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 on newer servers; prefer record_size on database 7.0+ (and 8.1+ guidance in each operation).

Ops

device_size

device_size()

Description

Deprecated in Database 8.1. Use record_size instead. Returns the record’s storage size in bytes as an integer. Value is 0 when namespace is configured storage-engine memory.

Returns

integer_value

Introduced

5.2.0.4

Example

(Deprecated.) When still using device-size metadata on disk-backed namespaces, find records over 1 MiB. Prefer record_size on server 7.0+.

Java

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

Python

from aerospike_helpers.expressions import DeviceSize, GT

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

C

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

Go

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

C#

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

Node.js

const exp = Aerospike.exp

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

digest_modulo

digest_modulo(mod)

Description

Returns a record digest modulo as an integer.

Arguments

Name	Type
mod	integer_value

Returns

integer_value

Introduced

5.2.0.4

Example

Sample roughly one third of records (digest modulo 3 equals 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()

C

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

Go

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

C#

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

Node.js

const exp = Aerospike.exp

const filterExp = exp.eq(exp.digestModulo(3), exp.int(0))

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_value

Introduced

5.2.0.4

Example

XDR shipping filter — select tombstone records only.

Java

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

Python

from aerospike_helpers.expressions import IsTombstone

exp = IsTombstone().compile()

C

as_exp_build(predexp, as_exp_is_tombstone());

Go

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

C#

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

Node.js

const exp = Aerospike.exp

const filterExp = exp.isTombstone()

key_exists

key_exists()

Description

Returns true if the record has a stored key (written with send_key / POLICY_KEY_SEND), otherwise false. Once stored, the key persists with the record until the record is deleted.

Returns

boolean_value

Introduced

5.2.0.4

Example

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

Java

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

Python

from aerospike_helpers.expressions import KeyExists

exp = KeyExists().compile()

C

as_exp_build(predexp, as_exp_key_exist());

Go

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

C#

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

Node.js

const exp = Aerospike.exp

const filterExp = exp.keyExist()

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_value

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

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

C

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

Go

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

C#

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

Node.js

const exp = Aerospike.exp

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

memory_size

memory_size()

Description

Deprecated in Database 8.1. Use record_size instead. Returns the record’s size in bytes as an integer when the namespace is configured storage-engine memory, otherwise returns 0.

Prior to Database 7.0: Returns the record’s memory size in bytes as an integer when either the namespace is configured data-in-memory true or storage-engine memory, otherwise returns 0.

Note: deprecated as of Database 7.0.0 since the data-size and memory-size are now the same size. Use record_size instead.

Returns

integer_value

Introduced

5.3.0

Example

(Deprecated.) When still using legacy memory-size metadata, find records over 1 MiB. Prefer record_size on server 7.0+.

Java

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

Python

from aerospike_helpers.expressions import GT, MemorySize

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

C

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

Go

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

C#

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

Node.js

const exp = Aerospike.exp

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

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_value

Introduced

7.0.0

Example

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

Java

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

Python

from aerospike_helpers.expressions import GT, RecordSize

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

C

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

Go

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

C#

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

Node.js

const exp = Aerospike.exp

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

set_name

set_name()

Description

Returns the record’s set_name as a string.

Returns

string_value

Introduced

5.2.0.4

Example

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

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

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

Go

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

C#

Expression exp = Exp.Build(Exp.Or(
  Exp.EQ(Exp.SetName(), Exp.Val("books")),
  Exp.EQ(Exp.SetName(), Exp.Val("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')),
)

since_update

since_update()

Description

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

Returns

integer_value

Introduced

5.2.0.4

Example

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

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

C

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

Go

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

C#

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

Node.js

const exp = Aerospike.exp

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

ttl

ttl()

Description

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

Returns

integer_value

Introduced

5.2.0.4

Example

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

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

C

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

Go

// Import path matches the Go client examples elsewhere on this doc site (/v6).
// If you use the latest client line, switch to .../aerospike-client-go/v8 (API names unchanged).
// Requires: import as "github.com/aerospike/aerospike-client-go/v6"
_ = as.ExpLessEq(as.ExpTTL(), as.ExpIntVal(24*60*60))

C#

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

Node.js

const exp = Aerospike.exp

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

void_time

void_time()

Description

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

Returns

integer_value

Introduced

5.2.0.4

Example

Return records that never expire (void time -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()

C

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

Go

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

C#

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

Node.js

const exp = Aerospike.exp

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