Record storage

Record storage expressions read a record’s own data as typed values: its bins, its primary key, and whether a bin exists. Together with record metadata, they are the leaves of an expression tree — every other expression in this reference takes its operands from one of these, or from another expression built on them.

Use a typed reader as the operand of a comparison or logic filter, as the collection operand of a list, map, or HLL expression, as the string operand of a string expression, or as the root of a path filter over nested data.

A typed reader evaluates to unknown when the bin is absent or holds a different type; see Unknown results. The key readers follow the same rule, so read a key with the reader matching how it was written — key_int, key_str, or key_blob.

bin_type is the exception to the pattern. It evaluates to an integer code naming the bin’s data type rather than to the bin’s value, which makes it the way to branch on what a bin holds before reading it.

The Developer SDK’s AEL text syntax infers most of these types from paths and literals, so an explicit typed reader is rarely needed.

Each operation’s Example shows the code in nine tabs: Aerospike Expression Language (AEL) text on the Java SDK and Python SDK tabs, and the Exp builder on the other seven. See the AEL reference for AEL grammar.

Ops

bin_blob

bin_blob(name)

Description

Returns the bin named by name as a blob, or unknown if the bin does not exist or holds a different type.

Arguments

Name	Type	Description
name	string literal	Name of the bin.

Returns

blob

Introduced

5.2.0.4

Example

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

Java SDK

String exp = "$.checksum:BLOB == x'010203'";

Python SDK

exp = "$.checksum:BLOB == x'010203'"

Rust

use aerospike::expressions::{blob_bin, blob_val, eq};

let exp = eq(blob_bin("checksum".into()), blob_val(vec![0x01, 0x02, 0x03]));

C#

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

Go

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

Node.js

const exp = Aerospike.exp

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

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

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

bin_exists

bin_exists(name)

Description

Returns true if the record has a bin named name, otherwise false.

Arguments

Name	Type	Description
name	string literal	Name of the bin.

Returns

boolean

Introduced

5.2.0.4

Example

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

Java SDK

String exp = "$.quantity.exists()";

Python SDK

exp = "$.quantity.exists()"

Rust

use aerospike::expressions::bin_exists;

let exp = bin_exists("quantity".into());

C#

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

Go

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

Node.js

const exp = Aerospike.exp

const filterExp = exp.binExists('quantity')

C

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

Java

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

Python

from aerospike_helpers.expressions import BinExists

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

bin_float

bin_float(name)

Description

Returns the bin named by name as a float, or unknown if the bin does not exist or holds a different type.

Arguments

Name	Type	Description
name	string literal	Name of the bin.

Returns

float

Introduced

5.2.0.4

Example

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

Java SDK

String exp = "$.list_price:FLOAT < 15.0";

Python SDK

exp = "$.list_price:FLOAT < 15.0"

Rust

use aerospike::expressions::{float_bin, float_val, lt};

let exp = lt(float_bin("list_price".into()), float_val(15.0));

C#

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

Go

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

Node.js

const exp = Aerospike.exp

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

C

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

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

bin_geo

bin_geo(name)

Description

Returns the bin named by name as a GeoJSON value, or unknown if the bin does not exist or holds a different type.

Arguments

Name	Type	Description
name	string literal	Name of the bin.

Returns

geojson

Introduced

5.2.0.4

Example

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

Java SDK

String exp = "geoCompare("
    + "geoJson('{\"type\":\"Point\",\"coordinates\":[-122.4,37.8]}'), $.region:GEO)";

Python SDK

exp = ("geoCompare("
       "geoJson('{\"type\":\"Point\",\"coordinates\":[-122.4,37.8]}'), $.region:GEO)")

Rust

use aerospike::expressions::{geo_bin, geo_compare, geo_val};

let point = "{\"type\":\"Point\",\"coordinates\":[-122.4,37.8]}";
let exp = geo_compare(geo_val(point.into()), geo_bin("region".into()));

C#

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

Go

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

Node.js

const exp = Aerospike.exp

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

C

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

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

bin_hll

bin_hll(name)

Description

Returns the bin named by name as an HLL, or unknown if the bin does not exist or holds a different type.

Arguments

Name	Type	Description
name	string literal	Name of the bin.

Returns

hll

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 SDK

String exp = "$.visitors:HLL.hllCount() > 0";

Python SDK

exp = "$.visitors:HLL.hllCount() > 0"

Rust

use aerospike::expressions::hll as hll_exp;
use aerospike::expressions::{gt, hll_bin, int_val};

let exp = gt(hll_exp::get_count(hll_bin("visitors".into())), int_val(0));

C#

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

Go

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

Node.js

const exp = Aerospike.exp

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

C

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

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

bin_int

bin_int(name)

Description

Returns the bin named by name as an integer, or unknown if the bin does not exist or holds a different type.

Arguments

Name	Type	Description
name	string literal	Name of the bin.

Returns

integer

Introduced

5.2.0.4

Example

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

Java SDK

String exp = "$.quantity:INT > 0";

Python SDK

exp = "$.quantity:INT > 0"

Rust

use aerospike::expressions::{gt, int_bin, int_val};

let exp = gt(int_bin("quantity".into()), int_val(0));

C#

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

Go

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

Node.js

const exp = Aerospike.exp

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

C

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

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

bin_list

bin_list(name)

Description

Returns the bin named by name as a list, or unknown if the bin does not exist or holds a different type.

Arguments

Name	Type	Description
name	string literal	Name of the bin.

Returns

list

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 SDK

String exp = "$.tags:LIST.count() > 0";

Python SDK

exp = "$.tags:LIST.count() > 0"

Rust

use aerospike::expressions::lists as list_exp;
use aerospike::expressions::{gt, int_val, list_bin};

let exp = gt(list_exp::size(list_bin("tags".into()), &[]), int_val(0));

C#

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

Go

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

Node.js

const exp = Aerospike.exp

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

C

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

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

bin_map

bin_map(name)

Description

Returns the bin named by name as a map, or unknown if the bin does not exist or holds a different type.

Arguments

Name	Type	Description
name	string literal	Name of the bin.

Returns

map

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 SDK

String exp = "$.attrs:MAP.count() > 0";

Python SDK

exp = "$.attrs:MAP.count() > 0"

Rust

use aerospike::expressions::maps as map_exp;
use aerospike::expressions::{gt, int_val, map_bin};

let exp = gt(map_exp::size(map_bin("attrs".into()), &[]), int_val(0));

C#

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

Go

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

Node.js

const exp = Aerospike.exp

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

C

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

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

bin_str

bin_str(name)

Description

Returns the bin named by name as a string, or unknown if the bin does not exist or holds a different type.

Arguments

Name	Type	Description
name	string literal	Name of the bin.

Returns

string

Introduced

5.2.0.4

Example

Records in the fiction category (string bin category).

Java SDK

String exp = "$.category:STRING == 'fiction'";

Python SDK

exp = "$.category:STRING == 'fiction'"

Rust

use aerospike::expressions::{eq, string_bin, string_val};

let exp = eq(string_bin("category".into()), string_val("fiction".into()));

C#

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

Go

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

Node.js

const exp = Aerospike.exp

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

C

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

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

bin_type

bin_type(name)

Description

Returns the data type of the bin named by name, as an integer code, or 0 if the bin does not exist.

Compare the result against your client’s bin-type constants rather than writing the number directly. The codes are:

Bin data type	Code
Integer	1
Double	2
String	3
Blob	4
Boolean	17
HyperLogLog	18
Map	19
List	20
GeoJSON	23

Arguments

Name	Type	Description
name	string literal	Name of the bin.

Returns

integer

Introduced

5.2.0.4

Example

Filter to records whose sku bin is stored as a string.

Java SDK

String exp = "$.sku.type() == STRING";

Python SDK

exp = "$.sku.type() == STRING"

Rust

use aerospike::expressions::{bin_type, eq, int_val};
use aerospike::ParticleType;

let exp = eq(bin_type("sku".into()), int_val(ParticleType::STRING as i64));

C#

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

Go

// Requires: import as "github.com/aerospike/aerospike-client-go/v8"
// Requires: import particleType "github.com/aerospike/aerospike-client-go/v8/types/particle_type"
exp := as.ExpEq(as.ExpBinType("sku"), as.ExpIntVal(particleType.STRING))

Node.js

const exp = Aerospike.exp

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

C

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

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

key_blob

key_blob()

Description

Returns the record’s user key as a blob, or unknown if the record has no stored key or the key is a different type.

Returns

blob

Introduced

5.2.0.4

Example

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

Java SDK

String exp = "$.key():BLOB == x'1020'";

Python SDK

exp = "$.key():BLOB == x'1020'"

Rust

use aerospike::expressions::{blob_val, eq, key, ExpType};

let exp = eq(key(ExpType::BLOB), blob_val(vec![0x10, 0x20]));

C#

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

Go

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

Node.js

const exp = Aerospike.exp

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

C

uint8_t id[] = { 0x10, 0x20 };
as_exp_build(predexp,
  as_exp_cmp_eq(as_exp_key_blob(), as_exp_bytes(id, sizeof(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()

key_int

key_int()

Description

Returns the record’s user key as an integer, or unknown if the record has no stored key or the key is a different type.

Returns

integer

Introduced

5.2.0.4

Example

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

Java SDK

String exp = "$.key():INT >= 1000";

Python SDK

exp = "$.key():INT >= 1000"

Rust

use aerospike::expressions::{ge, int_val, key, ExpType};

let exp = ge(key(ExpType::INT), int_val(1000));

C#

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

Go

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

Node.js

const exp = Aerospike.exp

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

C

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

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

key_str

key_str()

Description

Returns the record’s user key as a string, or unknown if the record has no stored key or the key is a different type.

Returns

string

Introduced

5.2.0.4

Example

Records whose string user key is order-42.

Java SDK

String exp = "$.key():STRING == 'order-42'";

Python SDK

exp = "$.key():STRING == 'order-42'"

Rust

use aerospike::expressions::{eq, key, string_val, ExpType};

let exp = eq(key(ExpType::STRING), string_val("order-42".into()));

C#

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

Go

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

Node.js

const exp = Aerospike.exp

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

C

as_exp_build(predexp,
  as_exp_cmp_eq(as_exp_key_str(), as_exp_str("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()