Record metadata

Record metadata expressions read Aerospike-managed fields: TTL and void time, digest sampling, set name, stored key flag, record size, last-update and time-since-update, and tombstone state (where applicable). Use them in secondary index filters, query predicates, record policies, and XDR shipping filters—anywhere the client accepts a boolean or typed expression over record metadata.

Wrap metadata values in comparison or logic expressions when you need a boolean filter (true / false / unknown). For how metadata-only evaluation interacts with the rest of an expression, see the expressions overview execution model.

memory_size and device_size are deprecated with warnings in Database 8.1 and later. Use record_size, introduced in 7.0, instead. It returns a consistent value regardless of storage engine.

The Developer SDK’s AEL text syntax exposes the same metadata as path functions on $, for example $.ttl() < 3600.

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

device_size

deprecated

device_size()

Description

Returns the record’s storage size in bytes, or 0 when the namespace is configured storage-engine memory. Superseded by record_size in Database 8.1.

Returns

integer

Introduced

5.2.0.4

Example

(Deprecated.) When still using device-size metadata on disk-backed namespaces, find records over 128 KiB. Prefer record_size on Database 7.0 and later.

Java SDK

String exp = "$.deviceSize() > 128 * 1024";

Python SDK

exp = "$.deviceSize() > 128 * 1024"

Rust

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

let exp = gt(device_size(), int_val(128 * 1024));

C#

Expression exp = Exp.Build(
  Exp.GT(Exp.DeviceSize(), Exp.Val(128 * 1024)));

Go

// Requires: import as "github.com/aerospike/aerospike-client-go/v8"
exp := as.ExpGreater(as.ExpDeviceSize(), as.ExpIntVal(128*1024))

Node.js

const exp = Aerospike.exp

const filterExp = exp.gt(exp.deviceSize(), exp.int(128 * 1024))

C

as_exp_build(predexp,
  as_exp_cmp_gt(as_exp_device_size(), as_exp_int(128 * 1024)));

Java

Expression exp = Exp.build(
  Exp.gt(Exp.deviceSize(), Exp.val(128 * 1024)));

Python

from aerospike_helpers.expressions import DeviceSize, GT

exp = GT(DeviceSize(), 128 * 1024).compile()

digest_modulo

digest_modulo(mod)

Description

Returns a record digest modulo as an integer.

Arguments

Name	Type	Description
mod	integer literal	Divisor applied to the record digest. The expression returns the remainder, so a mod of 3 yields 0, 1 or 2 — enough to sample a fixed fraction of records.

Returns

integer

Introduced

5.2.0.4

Example

Sample roughly one third of records (digest modulo 3 equals 0).

Java SDK

String exp = "$.digestModulo(3) == 0";

Python SDK

exp = "$.digestModulo(3) == 0"

Rust

use aerospike::expressions::{digest_modulo, eq, int_val};

let exp = eq(digest_modulo(3), int_val(0));

C#

Expression exp = Exp.Build(
  Exp.EQ(Exp.DigestModulo(3), Exp.Val(0)));

Go

// Requires: import as "github.com/aerospike/aerospike-client-go/v8"
exp := as.ExpEq(as.ExpDigestModulo(3), as.ExpIntVal(0))

Node.js

// The Node.js client's exp.digestModulo drops its divisor, so the server rejects
// the expression and this example has no Node.js form.

C

as_exp_build(predexp,
  as_exp_cmp_eq(as_exp_digest_modulo(3), as_exp_int(0)));

Java

Expression exp = Exp.build(
  Exp.eq(Exp.digestModulo(3), Exp.val(0)));

Python

from aerospike_helpers.expressions import DigestMod, Eq

exp = Eq(DigestMod(3), 0).compile()

is_tombstone

is_tombstone()

Description

Returns true if the record is a tombstone, otherwise false. Note: Applies to XDR filters and to write requests using read/write expressions.

Returns

boolean

Introduced

5.2.0.4

Example

XDR shipping filter — select tombstone records only.

Java SDK

String exp = "$.isTombstone()";

Python SDK

exp = "$.isTombstone()"

Rust

use aerospike::expressions::is_tombstone;

let exp = is_tombstone();

C#

Expression exp = Exp.Build(Exp.IsTombstone());

Go

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

Node.js

const exp = Aerospike.exp

const filterExp = exp.isTombstone()

C

as_exp_build(predexp, as_exp_is_tombstone());

Java

Expression exp = Exp.build(Exp.isTombstone());

Python

from aerospike_helpers.expressions import IsTombstone

exp = IsTombstone().compile()

key_exists

key_exists()

Description

Returns true if the record has a stored key (written with the write policy’s send-key option), otherwise false. Once stored, the key persists with the record until the record is deleted.

Returns

boolean

Introduced

5.2.0.4

Example

Return records that have a stored primary key in the record metadata.

Java SDK

String exp = "$.keyExists()";

Python SDK

exp = "$.keyExists()"

Rust

use aerospike::expressions::key_exists;

let exp = key_exists();

C#

Expression exp = Exp.Build(Exp.KeyExists());

Go

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

Node.js

const exp = Aerospike.exp

const filterExp = exp.keyExist()

C

as_exp_build(predexp, as_exp_key_exist());

Java

Expression exp = Exp.build(Exp.keyExists());

Python

from aerospike_helpers.expressions import KeyExists

exp = KeyExists().compile()

last_update

last_update()

Description

Returns the record’s last-update-time (LUT) in nanoseconds (millisecond resolution) from Unix Epoch (1/1/1970) as an integer.

Returns

integer

Introduced

5.2.0.4

Example

Return records whose server last-update time (LUT, nanoseconds since epoch) is less than integer bin updated_at (for example, an application timestamp in the same units).

Java SDK

String exp = "$.lastUpdateTime() < $.updated_at";

Python SDK

exp = "$.lastUpdateTime() < $.updated_at"

Rust

use aerospike::expressions::{int_bin, last_update, lt};

let exp = lt(last_update(), int_bin("updated_at".into()));

C#

Expression exp = Exp.Build(
  Exp.LT(Exp.LastUpdate(), Exp.IntBin("updated_at")));

Go

// Requires: import as "github.com/aerospike/aerospike-client-go/v8"
exp := as.ExpLess(as.ExpLastUpdate(), as.ExpIntBin("updated_at"))

Node.js

const exp = Aerospike.exp

const filterExp = exp.lt(exp.lastUpdate(), exp.binInt('updated_at'))

C

as_exp_build(predexp,
  as_exp_cmp_lt(
    as_exp_last_update(), as_exp_bin_int("updated_at")));

Java

Expression exp = Exp.build(
  Exp.lt(Exp.lastUpdate(), Exp.intBin("updated_at")));

Python

from aerospike_helpers.expressions import IntBin, LastUpdateTime, LT

exp = LT(LastUpdateTime(), IntBin("updated_at")).compile()

memory_size

deprecated

memory_size()

Description

Returns the record’s size in bytes when the namespace is configured storage-engine memory, otherwise 0. Before Database 7.0 it also returned a size when the namespace was configured data-in-memory true; since 7.0 the data size and memory size are the same. Superseded by record_size in Database 8.1.

Returns

integer

Introduced

5.3.0

Example

(Deprecated.) When still using legacy memory-size metadata, find records over 128 KiB. Prefer record_size on Database 7.0 and later.

Java SDK

String exp = "$.memorySize() > 128 * 1024";

Python SDK

exp = "$.memorySize() > 128 * 1024"

Rust

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

let exp = gt(memory_size(), int_val(128 * 1024));

C#

Expression exp = Exp.Build(
  Exp.GT(Exp.MemorySize(), Exp.Val(128 * 1024)));

Go

// Requires: import as "github.com/aerospike/aerospike-client-go/v8"
exp := as.ExpGreater(as.ExpMemorySize(), as.ExpIntVal(128*1024))

Node.js

const exp = Aerospike.exp

const filterExp = exp.gt(exp.memorySize(), exp.int(128 * 1024))

C

as_exp_build(predexp,
  as_exp_cmp_gt(as_exp_memory_size(), as_exp_int(128 * 1024)));

Java

Expression exp = Exp.build(
  Exp.gt(Exp.memorySize(), Exp.val(128 * 1024)));

Python

from aerospike_helpers.expressions import GT, MemorySize

exp = GT(MemorySize(), 128 * 1024).compile()

record_size

record_size()

Description

Returns the record’s size in bytes as an integer. This is the physical size of the record in the namespace storage device. If compression is turned on, the record size reflects the compressed size of the record, not the logical uncompressed size.

Returns

integer

Introduced

7.0.0

Example

Find records larger than 128 KiB on the storage device (compressed size when compression is enabled).

Java SDK

String exp = "$.recordSize() > 128 * 1024";

Python SDK

exp = "$.recordSize() > 128 * 1024"

Rust

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

let exp = gt(record_size(), int_val(128 * 1024));

C#

Expression exp = Exp.Build(
  Exp.GT(Exp.RecordSize(), Exp.Val(128 * 1024)));

Go

// Requires: import as "github.com/aerospike/aerospike-client-go/v8"
exp := as.ExpGreater(as.ExpRecordSize(), as.ExpIntVal(128*1024))

Node.js

const exp = Aerospike.exp

const filterExp = exp.gt(exp.recordSize(), exp.int(128 * 1024))

C

as_exp_build(predexp,
  as_exp_cmp_gt(as_exp_record_size(), as_exp_int(128 * 1024)));

Java

Expression exp = Exp.build(
  Exp.gt(Exp.recordSize(), Exp.val(128 * 1024)));

Python

from aerospike_helpers.expressions import GT, RecordSize

exp = GT(RecordSize(), 128 * 1024).compile()

set_name

set_name()

Description

Returns the record’s set_name as a string.

Returns

string

Introduced

5.2.0.4

Example

Return records in Aerospike sets books or bundles (aligned with catalog-style examples elsewhere).

Java SDK

String exp = "$.setName() == 'books' or $.setName() == 'bundles'";

Python SDK

exp = "$.setName() == 'books' or $.setName() == 'bundles'"

Rust

use aerospike::expressions::{eq, or, set_name, string_val};

let exp = or(vec![
    eq(set_name(), string_val("books".into())),
    eq(set_name(), string_val("bundles".into())),
]);

C#

Expression exp = Exp.Build(Exp.Or(
  Exp.EQ(Exp.SetName(), Exp.Val("books")),
  Exp.EQ(Exp.SetName(), Exp.Val("bundles"))));

Go

// Requires: import as "github.com/aerospike/aerospike-client-go/v8"
exp := as.ExpOr(
  as.ExpEq(as.ExpSetName(), as.ExpStringVal("books")),
  as.ExpEq(as.ExpSetName(), as.ExpStringVal("bundles")),
)

Node.js

const exp = Aerospike.exp

const filterExp = exp.or(
  exp.eq(exp.setName(), exp.str('books')),
  exp.eq(exp.setName(), exp.str('bundles')),
)

C

as_exp_build(predexp, as_exp_or(
  as_exp_cmp_eq(as_exp_set_name(), as_exp_str("books")),
  as_exp_cmp_eq(as_exp_set_name(), as_exp_str("bundles"))));

Java

Expression exp = Exp.build(Exp.or(
  Exp.eq(Exp.setName(), Exp.val("books")),
  Exp.eq(Exp.setName(), Exp.val("bundles"))));

Python

from aerospike_helpers.expressions import Eq, Or, SetName

exp = Or(Eq(SetName(), "books"), Eq(SetName(), "bundles")).compile()

since_update

since_update()

Description

Returns the time (in milliseconds) since the record was last updated.

Returns

integer

Introduced

5.2.0.4

Example

Return records updated within the last 2 hours (milliseconds since last update).

Java SDK

String exp = "$.timeSinceLastUpdate() < 2 * 60 * 60 * 1000";

Python SDK

exp = "$.timeSinceLastUpdate() < 2 * 60 * 60 * 1000"

Rust

use aerospike::expressions::{int_val, lt, since_update};

let exp = lt(since_update(), int_val(2 * 60 * 60 * 1000));

C#

Expression exp = Exp.Build(
  Exp.LT(Exp.SinceUpdate(), Exp.Val(2 * 60 * 60 * 1000)));

Go

// Requires: import as "github.com/aerospike/aerospike-client-go/v8"
exp := as.ExpLess(as.ExpSinceUpdate(), as.ExpIntVal(2*60*60*1000))

Node.js

const exp = Aerospike.exp

const filterExp = exp.lt(exp.sinceUpdate(), exp.int(2 * 60 * 60 * 1000))

C

as_exp_build(predexp,
  as_exp_cmp_lt(
    as_exp_since_update(), as_exp_int(2 * 60 * 60 * 1000)));

Java

Expression exp = Exp.build(
  Exp.lt(Exp.sinceUpdate(), Exp.val(2 * 60 * 60 * 1000)));

Python

from aerospike_helpers.expressions import LT, SinceUpdateTime

exp = LT(SinceUpdateTime(), 2 * 60 * 60 * 1000).compile()

ttl

ttl()

Description

Returns the record’s TTL (Time To Live) as an integer.

Returns

integer

Introduced

5.2.0.4

Example

Return records whose TTL is at most 24 hours (seconds remaining until expiration).

Java SDK

String exp = "$.ttl() <= 24 * 60 * 60";

Python SDK

exp = "$.ttl() <= 24 * 60 * 60"

Rust

use aerospike::expressions::{int_val, le, ttl};

let exp = le(ttl(), int_val(24 * 60 * 60));

C#

Expression exp = Exp.Build(
  Exp.LE(Exp.TTL(), Exp.Val(24 * 60 * 60)));

Go

// Requires: import as "github.com/aerospike/aerospike-client-go/v8"
exp := as.ExpLessEq(as.ExpTTL(), as.ExpIntVal(24*60*60))

Node.js

const exp = Aerospike.exp

const filterExp = exp.le(exp.ttl(), exp.int(24 * 60 * 60))

C

as_exp_build(predexp,
  as_exp_cmp_le(as_exp_ttl(), as_exp_int(24 * 60 * 60)));

Java

Expression exp = Exp.build(
  Exp.le(Exp.ttl(), Exp.val(24 * 60 * 60)));

Python

from aerospike_helpers.expressions import LE, TTL

exp = LE(TTL(), 24 * 60 * 60).compile()

void_time

void_time()

Description

Returns the record’s expiration time in nanoseconds (resolution in seconds) as an integer.

Returns

integer

Introduced

5.2.0.4

Example

Return records that never expire (void time -1).

Java SDK

String exp = "$.voidTime() == -1";

Python SDK

exp = "$.voidTime() == -1"

Rust

use aerospike::expressions::{eq, int_val, void_time};

let exp = eq(void_time(), int_val(-1));

C#

Expression exp = Exp.Build(Exp.EQ(Exp.VoidTime(), Exp.Val(-1)));

Go

// Requires: import as "github.com/aerospike/aerospike-client-go/v8"
exp := as.ExpEq(as.ExpVoidTime(), as.ExpIntVal(-1))

Node.js

const exp = Aerospike.exp

const filterExp = exp.eq(exp.voidTime(), exp.int(-1))

C

as_exp_build(predexp,
  as_exp_cmp_eq(as_exp_void_time(), as_exp_int(-1)));

Java

Expression exp = Exp.build(Exp.eq(Exp.voidTime(), Exp.val(-1)));

Python

from aerospike_helpers.expressions import Eq, VoidTime

exp = Eq(VoidTime(), -1).compile()