Record storage

Record storage expressions read user data from bins and from the primary key as typed values: integers, floats, strings, blobs, GeoJSON, lists, maps, HyperLogLogs, and particle types. They are the building blocks for comparison and logic filters, for list, map, and HLL CDT expressions (where you pass a typed bin into ListExp / MapExp / HLLExp), and for path-based filters on nested data.

If the bin is missing or the type does not match, the expression evaluates to unknown (see the expressions overview execution model). For record keys, use the key-type expression that matches how the key was written (integer, string, or blob).

Typed bin readers (bin_int, bin_list, …) pair naturally with the same naming and scenarios as the bookstore / catalog examples elsewhere in this guide.

Ops

bin_blob

bin_blob(name)

Description

Retrieve the bin with the name indicated by name as a blob_bin. Return unknown if the bin does not exist or the bin is a different type.

Arguments

Name	Type
name	string_value

Returns

blob_bin

Introduced

5.2.0.4

Example

Records where blob bin checksum matches a 3-byte prefix (example digest bytes).

Java

Expression exp = Exp.build(
  Exp.eq(
    Exp.blobBin("checksum"),
    Exp.val(new byte[] { 0x01, 0x02, 0x03 })));

Python

from aerospike_helpers.expressions import BlobBin, Eq

exp = Eq(BlobBin("checksum"), bytearray([0x01, 0x02, 0x03])).compile()

C

uint8_t chk[] = { 0x01, 0x02, 0x03 };
as_exp_build(predexp,
  as_exp_cmp_eq(
    as_exp_bin_blob("checksum"),
    as_exp_bytes(chk, sizeof(chk))));

Go

// Requires: import as "github.com/aerospike/aerospike-client-go/v6"
_ = as.ExpEq(
  as.ExpBlobBin("checksum"),
  as.ExpBlobVal([]byte{0x01, 0x02, 0x03}),
)

C#

Expression exp = Exp.Build(
  Exp.EQ(Exp.BlobBin("checksum"), Exp.Val(new byte[] { 0x01, 0x02, 0x03 })));

Node.js

const exp = Aerospike.exp

const filterExp = exp.eq(
  exp.binBlob('checksum'),
  exp.bytes(Buffer.from([0x01, 0x02, 0x03])),
)

bin_exists

bin_exists(name)

Description

Returns true if a bin exists on the record with the name indicated by name, otherwise returns unknown.

Arguments

Name	Type
name	string_value

Returns

boolean_value

Introduced

5.2.0.4

Example

Filter to records that have a quantity bin (any type).

Java

Expression exp = Exp.build(Exp.binExists("quantity"));

Python

from aerospike_helpers.expressions import BinExists

exp = BinExists("quantity").compile()

C

as_exp_build(predexp, as_exp_bin_exists("quantity"));

Go

// Requires: import as "github.com/aerospike/aerospike-client-go/v6"
_ = as.ExpBinExists("quantity")

C#

Expression exp = Exp.Build(Exp.BinExists("quantity"));

Node.js

const exp = Aerospike.exp

const filterExp = exp.binExists('quantity')

bin_float

bin_float(name)

Description

Retrieve the bin with the name indicated by name as a float_bin. Return unknown if the bin does not exist or the bin is a different type.

Arguments

Name	Type
name	string_value

Returns

float_bin

Introduced

5.2.0.4

Example

Records where float bin list_price is under 15 (bookstore-style pricing).

Java

Expression exp = Exp.build(
  Exp.lt(Exp.floatBin("list_price"), Exp.val(15.0)));

Python

from aerospike_helpers.expressions import FloatBin, LT

exp = LT(FloatBin("list_price"), 15.0).compile()

C

as_exp_build(predexp,
  as_exp_cmp_lt(as_exp_bin_float("list_price"), as_exp_float(15.0)));

Go

// Requires: import as "github.com/aerospike/aerospike-client-go/v6"
_ = as.ExpLess(as.ExpFloatBin("list_price"), as.ExpFloatVal(15.0))

C#

Expression exp = Exp.Build(
  Exp.LT(Exp.FloatBin("list_price"), Exp.Val(15.0)));

Node.js

const exp = Aerospike.exp

const filterExp = exp.lt(exp.binFloat('list_price'), exp.float(15.0))

bin_geo

bin_geo(name)

Description

Retrieve the bin with the name indicated by name as a geojson_bin. Return unknown if the bin does not exist or the bin is a different type.

Arguments

Name	Type
name	string_value

Returns

geojson_bin

Introduced

5.2.0.4

Example

Records whose GeoJSON bin region contains the given point (same pattern as cmp_geo).

Java

String point = "{\"type\":\"Point\",\"coordinates\":[-122.4,37.8]}";
Expression exp = Exp.build(
  Exp.geoCompare(Exp.geo(point), Exp.geoBin("region")));

Python

import aerospike
from aerospike_helpers.expressions import CmpGeo, GeoBin

point = aerospike.GeoJSON(
    '{"type":"Point","coordinates":[-122.4,37.8]}')
exp = CmpGeo(point, GeoBin("region")).compile()

C

as_exp_build(predexp,
  as_exp_cmp_geo(
    as_exp_geo("{\"type\":\"Point\",\"coordinates\":[-122.4,37.8]}"),
    as_exp_bin_geo("region")));

Go

// Requires: import as "github.com/aerospike/aerospike-client-go/v6"
point := "{\"type\":\"Point\",\"coordinates\":[-122.4,37.8]}"
_ = as.ExpGeoCompare(as.ExpGeoVal(point), as.ExpGeoBin("region"))

C#

string point = "{\"type\":\"Point\",\"coordinates\":[-122.4,37.8]}";
Expression exp = Exp.Build(
  Exp.GeoCompare(Exp.Geo(point), Exp.GeoBin("region")));

Node.js

const exp = Aerospike.exp

const filterExp = exp.cmpGeo(
  exp.geo({ type: 'Point', coordinates: [-122.4, 37.8] }),
  exp.binGeo('region'),
)

bin_hll

bin_hll(name)

Description

Retrieve the bin with the name indicated by name as a hll_bin. Return unknown if the bin does not exist or the bin is a different type.

Arguments

Name	Type
name	string_value

Returns

hll_bin

Introduced

5.2.0.4

Example

Records where HLL bin visitors has a non-zero estimated cardinality, using HLLExp.getCount on the typed HLL bin.

Java

import com.aerospike.client.exp.HLLExp;

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

Python

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

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

C

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

Go

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

C#

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

Node.js

const exp = Aerospike.exp

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

bin_int

bin_int(name)

Description

Retrieve the bin with the name indicated by name as a integer_bin. Return unknown if the bin does not exist or the bin is a different type.

Arguments

Name	Type
name	string_value

Returns

integer_bin

Introduced

5.2.0.4

Example

Records where integer bin quantity is in stock (greater than zero).

Java

Expression exp = Exp.build(
  Exp.gt(Exp.intBin("quantity"), Exp.val(0)));

Python

from aerospike_helpers.expressions import GT, IntBin

exp = GT(IntBin("quantity"), 0).compile()

C

as_exp_build(predexp,
  as_exp_cmp_gt(as_exp_bin_int("quantity"), as_exp_int(0)));

Go

// Requires: import as "github.com/aerospike/aerospike-client-go/v6"
_ = as.ExpGreater(as.ExpIntBin("quantity"), as.ExpIntVal(0))

C#

Expression exp = Exp.Build(
  Exp.GT(Exp.IntBin("quantity"), Exp.Val(0)));

Node.js

const exp = Aerospike.exp

const filterExp = exp.gt(exp.binInt('quantity'), exp.int(0))

bin_list

bin_list(name)

Description

Retrieve the bin with the name indicated by name as a list_bin. Return unknown if the bin does not exist or the bin is a different type.

Arguments

Name	Type
name	string_value

Returns

list_bin

Introduced

5.2.0.4

Example

Records where list bin tags is non-empty, using the list bin value with a list read expression (size).

Java

import com.aerospike.client.exp.ListExp;

Expression exp = Exp.build(
  Exp.gt(ListExp.size(Exp.listBin("tags")), Exp.val(0)));

Python

from aerospike_helpers.expressions import GT, ListBin
from aerospike_helpers.expressions.list import ListSize

exp = GT(ListSize(None, ListBin("tags")), 0).compile()

C

as_exp_build(predexp,
  as_exp_cmp_gt(
    as_exp_list_size(NULL, as_exp_bin_list("tags")),
    as_exp_int(0)));

Go

// Requires: import as "github.com/aerospike/aerospike-client-go/v6"
_ = as.ExpGreater(
  as.ExpListSize(as.ExpListBin("tags")),
  as.ExpIntVal(0),
)

C#

Expression exp = Exp.Build(
  Exp.GT(ListExp.Size(Exp.ListBin("tags")), Exp.Val(0)));

Node.js

const exp = Aerospike.exp

const filterExp = exp.gt(
  exp.lists.size(exp.binList('tags')),
  exp.int(0),
)

bin_map

bin_map(name)

Description

Retrieve the bin with the name indicated by name as a map_bin. Return unknown if the bin does not exist or the bin is a different type.

Arguments

Name	Type
name	string_value

Returns

map_bin

Introduced

5.2.0.4

Example

Records where map bin attrs has at least one entry, using MapExp.size on the typed map bin.

Java

import com.aerospike.client.exp.MapExp;

Expression exp = Exp.build(
  Exp.gt(MapExp.size(Exp.mapBin("attrs")), Exp.val(0)));

Python

from aerospike_helpers.expressions import GT, MapBin
from aerospike_helpers.expressions.map import MapSize

exp = GT(MapSize(None, MapBin("attrs")), 0).compile()

C

as_exp_build(predexp,
  as_exp_cmp_gt(
    as_exp_map_size(NULL, as_exp_bin_map("attrs")),
    as_exp_int(0)));

Go

// Requires: import as "github.com/aerospike/aerospike-client-go/v6"
_ = as.ExpGreater(
  as.ExpMapSize(as.ExpMapBin("attrs")),
  as.ExpIntVal(0),
)

C#

Expression exp = Exp.Build(
  Exp.GT(MapExp.Size(Exp.MapBin("attrs")), Exp.Val(0)));

Node.js

const exp = Aerospike.exp

const filterExp = exp.gt(
  exp.maps.size(exp.binMap('attrs')),
  exp.int(0),
)

bin_str

bin_str(name)

Description

Retrieve the bin with the name indicated by name as a string_bin. Return unknown if the bin does not exist or the bin is a different type.

Arguments

Name	Type
name	string_value

Returns

string_bin

Introduced

5.2.0.4

Example

Records in the fiction category (string bin category).

Java

Expression exp = Exp.build(
  Exp.eq(Exp.stringBin("category"), Exp.val("fiction")));

Python

from aerospike_helpers.expressions import Eq, StrBin

exp = Eq(StrBin("category"), "fiction").compile()

C

as_exp_build(predexp,
  as_exp_cmp_eq(as_exp_bin_str("category"), as_exp_str("fiction")));

Go

// Requires: import as "github.com/aerospike/aerospike-client-go/v6"
_ = as.ExpEq(as.ExpStringBin("category"), as.ExpStringVal("fiction"))

C#

Expression exp = Exp.Build(
  Exp.EQ(Exp.StringBin("category"), Exp.Val("fiction")));

Node.js

const exp = Aerospike.exp

const filterExp = exp.eq(exp.binStr('category'), exp.str('fiction'))

bin_type

bin_type(name)

Description

Retrieve the data type of the bin with the name indicated by name in ParticleType format. Return unknown if the bin does not exist.

The following list shows each bin ParticleType and its associated integer value:

NULL: 0

INTEGER: 1

DOUBLE: 2

STRING: 3

BLOB: 4

JBLOB: 7

BOOL: 17

HLL: 18

MAP: 19

LIST: 20

GEOJSON: 23

Arguments

Name	Type
name	string_value

Returns

ParticleType

Introduced

5.2.0.4

Example

Filter to records whose sku bin is stored as a string (see ParticleType).

Java

import com.aerospike.client.command.ParticleType;

Expression exp = Exp.build(
  Exp.eq(Exp.binType("sku"), Exp.val(ParticleType.STRING)));

Python

import aerospike
from aerospike_helpers.expressions import BinType, Eq

exp = Eq(BinType("sku"), aerospike.AS_BYTES_STRING).compile()

C

as_exp_build(predexp,
  as_exp_cmp_eq(as_exp_bin_type("sku"), as_exp_int(AS_BYTES_STRING)));

Go

// Requires: import as "github.com/aerospike/aerospike-client-go/v6"
// ParticleType.STRING == 3 (see ExpBinType godoc).
_ = as.ExpEq(as.ExpBinType("sku"), as.ExpIntVal(3))

C#

Expression exp = Exp.Build(
  Exp.EQ(Exp.BinType("sku"), Exp.Val((long)ParticleType.STRING)));

Node.js

const exp = Aerospike.exp

const filterExp = exp.eq(exp.binType('sku'), exp.int(3))

key_blob

key_blob()

Description

Retrieve the key as a blob/bytes. Return unknown if the key does not exist or the key is a different type.

Returns

blob_value

Introduced

5.2.0.4

Example

Records whose blob user key matches a short byte sequence (for example a binary id).

Java

Expression exp = Exp.build(
  Exp.eq(Exp.key(Exp.Type.BLOB), Exp.val(new byte[] { 0x10, 0x20 })));

Python

from aerospike_helpers.expressions import Eq, KeyBlob

exp = Eq(KeyBlob(), bytearray([0x10, 0x20])).compile()

C

uint8_t id[] = { 0x10, 0x20 };
as_exp_build(predexp,
  as_exp_cmp_eq(as_exp_key_blob(), as_exp_bytes(id, sizeof(id))));

Go

// Requires: import as "github.com/aerospike/aerospike-client-go/v6"
_ = as.ExpEq(
  as.ExpKey(as.ExpTypeBLOB),
  as.ExpBlobVal([]byte{0x10, 0x20}),
)

C#

Expression exp = Exp.Build(
  Exp.EQ(Exp.Key(Exp.Type.BLOB), Exp.Val(new byte[] { 0x10, 0x20 })));

Node.js

const exp = Aerospike.exp

const filterExp = exp.eq(
  exp.keyBlob(),
  exp.bytes(Buffer.from([0x10, 0x20])),
)

key_int

key_int()

Description

Retrieve the key as a integer. Return unknown if the key does not exist or the key is a different type.

Returns

integer_value

Introduced

5.2.0.4

Example

Records whose integer user key is at least 1000 (same units as the key type).

Java

Expression exp = Exp.build(
  Exp.ge(Exp.key(Exp.Type.INT), Exp.val(1000)));

Python

from aerospike_helpers.expressions import GE, KeyInt

exp = GE(KeyInt(), 1000).compile()

C

as_exp_build(predexp,
  as_exp_cmp_ge(as_exp_key_int(), as_exp_int(1000)));

Go

// Requires: import as "github.com/aerospike/aerospike-client-go/v6"
_ = as.ExpGreaterEq(as.ExpKey(as.ExpTypeINT), as.ExpIntVal(1000))

C#

Expression exp = Exp.Build(
  Exp.GE(Exp.Key(Exp.Type.INT), Exp.Val(1000)));

Node.js

const exp = Aerospike.exp

const filterExp = exp.ge(exp.keyInt(), exp.int(1000))

key_str

key_str()

Description

Retrieve the key as a string. Return unknown if the key does not exist or the key is a different type.

Returns

string_value

Introduced

5.2.0.4

Example

Records whose string user key is order-42.

Java

Expression exp = Exp.build(
  Exp.eq(Exp.key(Exp.Type.STRING), Exp.val("order-42")));

Python

from aerospike_helpers.expressions import Eq, KeyStr

exp = Eq(KeyStr(), "order-42").compile()

C

as_exp_build(predexp,
  as_exp_cmp_eq(as_exp_key_str(), as_exp_str("order-42")));

Go

// Requires: import as "github.com/aerospike/aerospike-client-go/v6"
_ = as.ExpEq(as.ExpKey(as.ExpTypeSTRING), as.ExpStringVal("order-42"))

C#

Expression exp = Exp.Build(
  Exp.EQ(Exp.Key(Exp.Type.STRING), Exp.Val("order-42")));

Node.js

const exp = Aerospike.exp

const filterExp = exp.eq(exp.keyStr(), exp.str('order-42'))