HyperLogLog bin operations

For the complete documentation index see: llms.txt

All documentation pages available in markdown.

HyperLogLog (HLL) bin expressions run the same read and modify operations as the HLL data type (estimated cardinality, union, intersection, similarity, describe, may-contain), but embedded in the expression tree for filters, read/write operation expressions, and policies.

Read expressions (hll_get_count, hll_get_union, …) return integers, floats, lists, or HLL values; wrap them in comparison or logic when you need a Boolean filter. Modify expressions (hll_add, hll_update, …) evaluate to an HLL value for the pipeline; they do not replace normal HLL write operations unless you use them in an operation policy that applies the result.

HLL operations that read stored data can evaluate to unknown when the underlying bin or key is missing, the type does not match, or the value is not yet available during the metadata-only phase of filter evaluation. See Record storage and the expressions overview execution model.

For typed bin operands, start from Record storage hll_bin. Nested results (for example hll_describe returning a two-element list) often pair with list bin read helpers such as ListExp.getByIndex.

Composing expressions

The hll_add reference includes an example that wraps HLLExp.add in HLLExp.getCount—a modify-then-read pattern on the HLL value. Many other operations show similar composition: their examples nest another expression as the HLL operand (hll_bin_expr in the arguments table), including union and other read chains.

Modify

`hll_add`

hll_add(policy, values, index_bit_count, bin)

Description

Invokes the add operation.

Arguments

Name	Type
`policy`	`library_specific`
`values`	`list_expr`
`index_bit_count`	`integer_expr`
`bin`	`hll_bin_expr`

Returns

hll_bin

Introduced

5.2.0.4

Example

Add string ids from list bin new_user_ids into visitors, creating the HLL with index_bit_count 10 if missing; then require a non-zero estimated count.

import com.aerospike.client.operation.HLLPolicy;
import com.aerospike.client.exp.Exp;
import com.aerospike.client.exp.HLLExp;

Expression exp = Exp.build(
  Exp.gt(
    HLLExp.getCount(
      HLLExp.add(
        HLLPolicy.Default,
        Exp.listBin("new_user_ids"),
        Exp.val(10),
        Exp.hllBin("visitors"))),
    Exp.val(0)));

from aerospike_helpers.expressions import GT, HLLBin
from aerospike_helpers.expressions.hll import HLLAdd, HLLGetCount

added = HLLAdd(None, ["user1", "user2"], 10, None, HLLBin("visitors"))
exp = GT(HLLGetCount(added), 0).compile()

as_exp_build(predexp,
  as_exp_cmp_gt(
    as_exp_hll_get_count(
      as_exp_hll_add(
        NULL,
        as_exp_bin_list("new_user_ids"),
        10,
        as_exp_bin_hll("visitors"))),
    as_exp_int(0)));

// Requires: import as "github.com/aerospike/aerospike-client-go/v6"
added := as.ExpHLLAddWithIndex(
  as.DefaultHLLPolicy(),
  as.ExpListBin("new_user_ids"),
  as.ExpIntVal(10),
  as.ExpHLLBin("visitors"),
)
_ = as.ExpGreater(as.ExpHLLGetCount(added), as.ExpIntVal(0))

Expression exp = Exp.Build(
  Exp.GT(
    HLLExp.GetCount(
      HLLExp.Add(
        HLLPolicy.Default,
        Exp.ListBin("new_user_ids"),
        Exp.Val(10),
        Exp.HLLBin("visitors"))),
    Exp.Val(0)));

const exp = Aerospike.exp

const added = exp.hll.add(
  exp.binHll('visitors'),
  10,
  exp.list(['user1', 'user2']),
  null,
)
const filterExp = exp.gt(exp.hll.getCount(added), exp.int(0))

`hll_add_mh`

hll_add_mh(policy, values, index_bit_count, minhash_bit_count, bin)

Description

Invokes the add_mh operation.

Arguments

Name	Type
`policy`	`library_specific`
`values`	`list_expr`
`index_bit_count`	`integer_expr`
`minhash_bit_count`	`integer_expr`
`bin`	`hll_bin_expr`

Returns

hll_bin

Introduced

5.2.0.4

Example

Same as hll_add but supplies both index and minhash bit counts when the HLL must be created.

import com.aerospike.client.operation.HLLPolicy;
import com.aerospike.client.exp.Exp;
import com.aerospike.client.exp.HLLExp;

Expression exp = Exp.build(
  Exp.gt(
    HLLExp.getCount(
      HLLExp.add(
        HLLPolicy.Default,
        Exp.listBin("new_user_ids"),
        Exp.val(10),
        Exp.val(20),
        Exp.hllBin("visitors"))),
    Exp.val(0)));

from aerospike_helpers.expressions import GT, HLLBin
from aerospike_helpers.expressions.hll import HLLAdd, HLLGetCount

added = HLLAdd(None, ["user1", "user2"], 10, 20, HLLBin("visitors"))
exp = GT(HLLGetCount(added), 0).compile()

as_exp_build(predexp,
  as_exp_cmp_gt(
    as_exp_hll_get_count(
      as_exp_hll_add_mh(
        NULL,
        as_exp_bin_list("new_user_ids"),
        10,
        20,
        as_exp_bin_hll("visitors"))),
    as_exp_int(0)));

// Requires: import as "github.com/aerospike/aerospike-client-go/v6"
added := as.ExpHLLAddWithIndexAndMinHash(
  as.DefaultHLLPolicy(),
  as.ExpListBin("new_user_ids"),
  as.ExpIntVal(10),
  as.ExpIntVal(20),
  as.ExpHLLBin("visitors"),
)
_ = as.ExpGreater(as.ExpHLLGetCount(added), as.ExpIntVal(0))

Expression exp = Exp.Build(
  Exp.GT(
    HLLExp.GetCount(
      HLLExp.Add(
        HLLPolicy.Default,
        Exp.ListBin("new_user_ids"),
        Exp.Val(10),
        Exp.Val(20),
        Exp.HLLBin("visitors"))),
    Exp.Val(0)));

const exp = Aerospike.exp

const added = exp.hll.addMH(
  exp.binHll('visitors'),
  20,
  10,
  exp.list(['user1', 'user2']),
  null,
)
const filterExp = exp.gt(exp.hll.getCount(added), exp.int(0))

`hll_update`

hll_update(policy, values, bin)

Description

Invokes the update operation.

Arguments

Name	Type
`policy`	`library_specific`
`values`	`list_expr`
`bin`	`hll_bin_expr`

Returns

hll_bin

Introduced

5.2.0.4

Example

Add values from list bin new_user_ids to an existing HLL visitors (no index/minhash creation path).

import com.aerospike.client.operation.HLLPolicy;
import com.aerospike.client.exp.Exp;
import com.aerospike.client.exp.HLLExp;

Expression exp = Exp.build(
  Exp.gt(
    HLLExp.getCount(
      HLLExp.add(
        HLLPolicy.Default,
        Exp.listBin("new_user_ids"),
        Exp.val(-1),
        Exp.val(-1),
        Exp.hllBin("visitors"))),
    Exp.val(0)));

from aerospike_helpers.expressions import GT, HLLBin
from aerospike_helpers.expressions.hll import HLLAdd, HLLGetCount

updated = HLLAdd(None, ["user1", "user2"], None, None, HLLBin("visitors"))
exp = GT(HLLGetCount(updated), 0).compile()

as_exp_build(predexp,
  as_exp_cmp_gt(
    as_exp_hll_get_count(
      as_exp_hll_update(
        NULL,
        as_exp_bin_list("new_user_ids"),
        as_exp_bin_hll("visitors"))),
    as_exp_int(0)));

// Requires: import as "github.com/aerospike/aerospike-client-go/v6"
updated := as.ExpHLLAdd(
  as.DefaultHLLPolicy(),
  as.ExpListBin("new_user_ids"),
  as.ExpHLLBin("visitors"),
)
_ = as.ExpGreater(as.ExpHLLGetCount(updated), as.ExpIntVal(0))

Expression exp = Exp.Build(
  Exp.GT(
    HLLExp.GetCount(
      HLLExp.Add(
        HLLPolicy.Default,
        Exp.ListBin("new_user_ids"),
        Exp.Val(-1),
        Exp.Val(-1),
        Exp.HLLBin("visitors"))),
    Exp.Val(0)));

const exp = Aerospike.exp

const updated = exp.hll.update(
  exp.binHll('visitors'),
  exp.list(['user1', 'user2']),
  null,
)
const filterExp = exp.gt(exp.hll.getCount(updated), exp.int(0))

Read

`hll_describe`

hll_describe(bin)

Description

Invokes the describe operation.

Arguments

Name	Type
`bin`	`hll_bin_expr`

Returns

list_bin

Introduced

5.2.0.4

Example

The HLL’s index bit count (describe result index 0) is fewer than 16; uses a list read on the describe list.

import com.aerospike.client.cdt.ListReturnType;
import com.aerospike.client.exp.Exp;
import com.aerospike.client.exp.HLLExp;
import com.aerospike.client.exp.ListExp;

Expression exp = Exp.build(
  Exp.lt(
    ListExp.getByIndex(
      ListReturnType.VALUE,
      Exp.Type.INT,
      Exp.val(0),
      HLLExp.describe(Exp.hllBin("visitors"))),
    Exp.val(16)));

import aerospike
from aerospike_helpers.expressions import HLLBin, LT
from aerospike_helpers.expressions.hll import HLLDescribe
from aerospike_helpers.expressions.list import ListGetByIndex
from aerospike_helpers.expressions.resources import ResultType

desc = HLLDescribe(HLLBin("visitors"))
exp = LT(
    ListGetByIndex(
        None,
        aerospike.LIST_RETURN_VALUE,
        ResultType.INTEGER,
        0,
        desc,
    ),
    16,
).compile()

as_exp_build(predexp,
  as_exp_cmp_lt(
    as_exp_list_get_by_index(
      NULL,
      AS_LIST_RETURN_VALUE,
      AS_EXP_TYPE_INT,
      as_exp_int(0),
      as_exp_hll_describe(as_exp_bin_hll("visitors"))),
    as_exp_int(16)));

// Requires: import as "github.com/aerospike/aerospike-client-go/v6"
_ = as.ExpLess(
  as.ExpListGetByIndex(
    as.ListReturnTypeValue,
    as.ExpTypeINT,
    as.ExpIntVal(0),
    as.ExpHLLDescribe(as.ExpHLLBin("visitors")),
  ),
  as.ExpIntVal(16),
)

Expression exp = Exp.Build(
  Exp.LT(
    ListExp.GetByIndex(
      ListReturnType.VALUE,
      Exp.Type.INT,
      Exp.Val(0),
      HLLExp.Describe(Exp.HLLBin("visitors"))),
    Exp.Val(16)));

import Aerospike from 'aerospike'

const exp = Aerospike.exp
const lists = Aerospike.lists

const filterExp = exp.lt(
  exp.lists.getByIndex(
    exp.hll.describe(exp.binHll('visitors')),
    exp.int(0),
    exp.type.INT,
    lists.returnType.VALUE,
  ),
  exp.int(16),
)

`hll_get_count`

hll_get_count(bin)

Description

Invokes the get_count operation.

Arguments

Name	Type
`bin`	`hll_bin_expr`

Returns

integer_bin

Introduced

5.2.0.4

Example

Filter to records whose HLL visitors sketch estimates more than 100 unique ids.

import com.aerospike.client.exp.Exp;
import com.aerospike.client.exp.HLLExp;

Expression exp = Exp.build(
  Exp.gt(HLLExp.getCount(Exp.hllBin("visitors")), Exp.val(100)));

from aerospike_helpers.expressions import GT, HLLBin
from aerospike_helpers.expressions.hll import HLLGetCount

exp = GT(HLLGetCount(HLLBin("visitors")), 100).compile()

as_exp_build(predexp,
  as_exp_cmp_gt(
    as_exp_hll_get_count(as_exp_bin_hll("visitors")),
    as_exp_int(100)));

// Requires: import as "github.com/aerospike/aerospike-client-go/v6"
_ = as.ExpGreater(
  as.ExpHLLGetCount(as.ExpHLLBin("visitors")),
  as.ExpIntVal(100),
)

Expression exp = Exp.Build(
  Exp.GT(HLLExp.GetCount(Exp.HLLBin("visitors")), Exp.Val(100)));

const exp = Aerospike.exp

const filterExp = exp.gt(
  exp.hll.getCount(exp.binHll('visitors')),
  exp.int(100),
)

`hll_get_intersect_count`

hll_get_intersect_count(hll_list, bin)

Description

Invokes the get_intersect_count operation.

Arguments

Name	Type
`hll_list`	`list_expr`
`bin`	`hll_bin_expr`

Returns

integer_bin

Introduced

5.2.0.4

Example

Estimated intersection size between cohort_a and visitors is at least 50.

import com.aerospike.client.exp.Exp;
import com.aerospike.client.exp.HLLExp;

Expression exp = Exp.build(
  Exp.ge(
    HLLExp.getIntersectCount(Exp.hllBin("cohort_a"), Exp.hllBin("visitors")),
    Exp.val(50)));

from aerospike_helpers.expressions import GE, HLLBin
from aerospike_helpers.expressions.hll import HLLGetIntersectCount

exp = GE(
    HLLGetIntersectCount(HLLBin("cohort_a"), HLLBin("visitors")),
    50,
).compile()

as_exp_build(predexp,
  as_exp_cmp_ge(
    as_exp_hll_get_intersect_count(
      as_exp_bin_hll("cohort_a"),
      as_exp_bin_hll("visitors")),
    as_exp_int(50)));

// Requires: import as "github.com/aerospike/aerospike-client-go/v6"
_ = as.ExpGreaterEq(
  as.ExpHLLGetIntersectCount(as.ExpHLLBin("cohort_a"), as.ExpHLLBin("visitors")),
  as.ExpIntVal(50),
)

Expression exp = Exp.Build(
  Exp.GE(
    HLLExp.GetIntersectCount(Exp.HLLBin("cohort_a"), Exp.HLLBin("visitors")),
    Exp.Val(50)));

const exp = Aerospike.exp

const filterExp = exp.ge(
  exp.hll.getIntersectCount(
    exp.binHll('visitors'),
    exp.binHll('cohort_a'),
  ),
  exp.int(50),
)

`hll_get_similarity`

hll_get_similarity(hll_list, bin)

Description

Invokes the get_similarity operation.

Arguments

Name	Type
`hll_list`	`list_expr`
`bin`	`hll_bin_expr`

Returns

float_bin

Introduced

5.2.0.4

Example

Jaccard-style similarity between cohort_a and visitors is at least 0.5.

import com.aerospike.client.exp.Exp;
import com.aerospike.client.exp.HLLExp;

Expression exp = Exp.build(
  Exp.ge(
    HLLExp.getSimilarity(Exp.hllBin("cohort_a"), Exp.hllBin("visitors")),
    Exp.val(0.5)));

from aerospike_helpers.expressions import GE, HLLBin
from aerospike_helpers.expressions.hll import HLLGetSimilarity

exp = GE(
    HLLGetSimilarity(HLLBin("cohort_a"), HLLBin("visitors")),
    0.5,
).compile()

as_exp_build(predexp,
  as_exp_cmp_ge(
    as_exp_hll_get_similarity(
      as_exp_bin_hll("cohort_a"),
      as_exp_bin_hll("visitors")),
    as_exp_float(0.5)));

// Requires: import as "github.com/aerospike/aerospike-client-go/v6"
_ = as.ExpGreaterEq(
  as.ExpHLLGetSimilarity(as.ExpHLLBin("cohort_a"), as.ExpHLLBin("visitors")),
  as.ExpFloatVal(0.5),
)

Expression exp = Exp.Build(
  Exp.GE(
    HLLExp.GetSimilarity(Exp.HLLBin("cohort_a"), Exp.HLLBin("visitors")),
    Exp.Val(0.5)));

const exp = Aerospike.exp

const filterExp = exp.ge(
  exp.hll.getSimilarity(
    exp.binHll('visitors'),
    exp.binHll('cohort_a'),
  ),
  exp.float(0.5),
)

`hll_get_union`

hll_get_union(hll_list, bin)

Description

Invokes the get_union operation.

Arguments

Name	Type
`hll_list`	`list_expr`
`bin`	`hll_bin_expr`

Returns

hll_bin

Introduced

5.2.0.4

Example

Union of HLL cohort_a with visitors, then require a non-empty estimate (via hll_get_count on the union result).

import com.aerospike.client.exp.Exp;
import com.aerospike.client.exp.HLLExp;

Expression exp = Exp.build(
  Exp.gt(
    HLLExp.getCount(
      HLLExp.getUnion(Exp.hllBin("cohort_a"), Exp.hllBin("visitors"))),
    Exp.val(0)));

from aerospike_helpers.expressions import GT, HLLBin
from aerospike_helpers.expressions.hll import HLLGetCount, HLLGetUnion

u = HLLGetUnion(HLLBin("cohort_a"), HLLBin("visitors"))
exp = GT(HLLGetCount(u), 0).compile()

as_exp_build(predexp,
  as_exp_cmp_gt(
    as_exp_hll_get_count(
      as_exp_hll_get_union(
        as_exp_bin_hll("cohort_a"),
        as_exp_bin_hll("visitors"))),
    as_exp_int(0)));

// Requires: import as "github.com/aerospike/aerospike-client-go/v6"
union := as.ExpHLLGetUnion(as.ExpHLLBin("cohort_a"), as.ExpHLLBin("visitors"))
_ = as.ExpGreater(as.ExpHLLGetCount(union), as.ExpIntVal(0))

Expression exp = Exp.Build(
  Exp.GT(
    HLLExp.GetCount(
      HLLExp.GetUnion(Exp.HLLBin("cohort_a"), Exp.HLLBin("visitors"))),
    Exp.Val(0)));

const exp = Aerospike.exp

const unionHll = exp.hll.getUnion(
  exp.binHll('visitors'),
  exp.binHll('cohort_a'),
)
const filterExp = exp.gt(exp.hll.getCount(unionHll), exp.int(0))

`hll_get_union_count`

hll_get_union_count(hlls, bin)

Description

Invokes the get_union_count operation.

Arguments

Name	Type
`hlls`	`list_expr`
`bin`	`hll_bin_expr`

Returns

integer_bin

Introduced

5.2.0.4

Example

Estimated cardinality of the union of cohort_a and visitors exceeds 500.

import com.aerospike.client.exp.Exp;
import com.aerospike.client.exp.HLLExp;

Expression exp = Exp.build(
  Exp.gt(
    HLLExp.getUnionCount(Exp.hllBin("cohort_a"), Exp.hllBin("visitors")),
    Exp.val(500)));

from aerospike_helpers.expressions import GT, HLLBin
from aerospike_helpers.expressions.hll import HLLGetUnionCount

exp = GT(
    HLLGetUnionCount(HLLBin("cohort_a"), HLLBin("visitors")),
    500,
).compile()

as_exp_build(predexp,
  as_exp_cmp_gt(
    as_exp_hll_get_union_count(
      as_exp_bin_hll("cohort_a"),
      as_exp_bin_hll("visitors")),
    as_exp_int(500)));

// Requires: import as "github.com/aerospike/aerospike-client-go/v6"
_ = as.ExpGreater(
  as.ExpHLLGetUnionCount(as.ExpHLLBin("cohort_a"), as.ExpHLLBin("visitors")),
  as.ExpIntVal(500),
)

Expression exp = Exp.Build(
  Exp.GT(
    HLLExp.GetUnionCount(Exp.HLLBin("cohort_a"), Exp.HLLBin("visitors")),
    Exp.Val(500)));

const exp = Aerospike.exp

const filterExp = exp.gt(
  exp.hll.getUnionCount(
    exp.binHll('visitors'),
    exp.binHll('cohort_a'),
  ),
  exp.int(500),
)

`hll_may_contain`

hll_may_contain(values, bin)

Description

Operation on bin that returns 1 if bin may contain all elements in the values list, otherwise returns 0.

Arguments

Name	Type
`values`	`list_expr`
`bin`	`hll_bin_expr`

Returns

integer_bin

Introduced

5.2.0.4

Example

The HLL may contain every candidate key listed in list bin candidate_keys (returns 1 when the check is positive).

import com.aerospike.client.exp.Exp;
import com.aerospike.client.exp.HLLExp;

Expression exp = Exp.build(
  Exp.eq(
    HLLExp.mayContain(Exp.listBin("candidate_keys"), Exp.hllBin("visitors")),
    Exp.val(1)));

from aerospike_helpers.expressions import Eq, HLLBin, ListBin
from aerospike_helpers.expressions.hll import HLLMayContain

exp = Eq(HLLMayContain(ListBin("candidate_keys"), HLLBin("visitors")), 1).compile()

as_exp_build(predexp,
  as_exp_cmp_eq(
    as_exp_hll_may_contain(
      as_exp_bin_list("candidate_keys"),
      as_exp_bin_hll("visitors")),
    as_exp_int(1)));

// Requires: import as "github.com/aerospike/aerospike-client-go/v6"
_ = as.ExpEq(
  as.ExpHLLMayContain(as.ExpListBin("candidate_keys"), as.ExpHLLBin("visitors")),
  as.ExpIntVal(1),
)

Expression exp = Exp.Build(
  Exp.EQ(
    HLLExp.MayContain(Exp.ListBin("candidate_keys"), Exp.HLLBin("visitors")),
    Exp.Val(1)));

const exp = Aerospike.exp

const filterExp = exp.eq(
  exp.hll.mayContain(
    exp.binHll('visitors'),
    exp.binList('candidate_keys'),
  ),
  exp.int(1),
)