HyperLogLog bin operations

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.

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),
)