Expressions

Aerospike expressions are a specialized, strictly typed, functional language. They are designed specifically for manipulating and comparing data fields (bins) and record metadata.

Because they are intentionally non-Turing complete, meaning they cannot perform all possible computations that a universal Turing machine could, they can’t handle complex features like iteration or recursion, which ensures their execution remains fast and predictable.

Expressions are used for several key purposes:

• Filter records: Select which records to read or process.
• Control operations: Determine if a record operation (like a write) should proceed.
• XDR filtering: Filter which data gets replicated to remote datacenters (DCs).
• Extend transactions: Add custom logic and functionality to database transactions.

For working with nested collection data, see:

• Working with nested collection data types (CDTs): access elements within nested maps and lists using composed expressions.
• Path expressions: select, filter, and retrieve multiple elements from nested structures in a single operation.

Types of expressions

Aerospike supports four types of expressions:

• Secondary index expressions introduced in Database 8.1.0
• Operation expressions introduced in Database 5.6.0
• XDR filter expressions introduced in Database 5.3.0
• Record filter expressions introduced in Database 5.2.0

Secondary index expression

A secondary index can index either the value of a specific bin or the computed value of an expression. When indexing very large data sets, you can create more memory-efficient secondary indexes by indexing on the computed value of an expression rather than bin data.

Use the Aerospike admin tool, asadm, to create secondary indexes. Queries can use an expression index either by matching the expression used by the index, or by referring to the index name in a predicate. For a hands-on walkthrough, see the expression index tutorial.

Operation expressions

Operation expressions are bin operations that atomically compute a value from data already in the record or supplied by the expression itself.

• Read expression: Evaluates the expression and returns the result under a name you provide, called a computed bin. The computed bin exists only in the response; nothing is written to storage. Read expressions work in single-record operate, batched operate, and query projection.
• Write expression: Evaluates the expression and persists the result into a named bin on the record. The bin name is a real, stored bin. Write expressions work in single-record operate and batched operate (not in query projection, which is read-only).

Operation expressions allow for atomic, cross-bin operations. This means they complete entirely or not at all across multiple data fields.

Operation expressions can be used in query projections as read expressions. A query’s projection accepts the same read operations and read expressions used in single-key and batched operate commands, enabling path expressions and computed values directly in the query result.

CDT operations vs. CDT expressions

CDT operations (ListOperation, MapOperation) and CDT expressions (ListExp, MapExp) both access list and map elements, but they work differently. Operations act in-place on the record’s bins and do not necessarily return a value. An operation can only affect a single named bin. Expressions evaluate to a typed result and can be composed, so the output of one expression can feed into another. Expressions can act across bins. For record filtering, the outermost expression must evaluate to boolean true or false; for operation expressions and secondary index expressions, the result can be any data type. CDT operations are used directly in operate() calls; CDT expressions must first be wrapped in a ExpOperation.read or ExpOperation.write. For a comparison of both approaches with worked examples, see Working with nested collection data types.

Record filtering with expressions

Record filtering selects only the records that satisfy a boolean expression, meaning the expression must evaluate to true.

Example: filter a single-record command

You attach a compiled boolean expression to the policy, and it acts as a conditional for the command. The server evaluates it if the record exists; see Execution timing below.

Java

import com.aerospike.client.AerospikeClient;
import com.aerospike.client.Key;
import com.aerospike.client.Record;
import com.aerospike.client.policy.Policy;
import com.aerospike.client.exp.Exp;

// Assume client and key are already configured.
Policy policy = new Policy();
policy.filterExp = Exp.build(Exp.gt(Exp.intBin("age"), Exp.val(18)));
Record record = client.get(policy, key);

Python

from aerospike_helpers.expressions import GT, IntBin

policy = {'expressions': GT(IntBin("age"), 18).compile()}
# Assume client and key_obj are already configured.
_, meta, bins = client.get(key_obj, policy=policy)

C

#include <aerospike/as_exp.h>
#include <aerospike/as_policy.h>

as_exp_build(read_filter,
    as_exp_cmp_gt(as_exp_bin_int("age"), as_exp_int(18)));

as_policy_read policy;
as_policy_read_init(&policy);
policy.base.filter_exp = read_filter;

/* aerospike_key_get(&as, &err, &policy, &key, &rec); */
/* as_exp_destroy(read_filter); */

Go

// Requires: import aerospike "github.com/aerospike/aerospike-client-go/v6"
policy := aerospike.NewPolicy()
policy.FilterExpression = aerospike.ExpGreater(
    aerospike.ExpIntBin("age"),
    aerospike.ExpIntVal(18))

record, err := client.Get(policy, key)

C#

using Aerospike.Client;

Policy policy = new Policy();
policy.filterExp = Exp.Build(
    Exp.GT(Exp.IntBin("age"), Exp.Val(18)));

Record record = client.Get(policy, key);

Node.js

const Aerospike = await import("aerospike");

const exp = Aerospike.exp

const readPolicy = new Aerospike.ReadPolicy({
  filterExpression: exp.gt(exp.binInt('age'), exp.int(18)),
})

const record = await client.get(key_obj, readPolicy)

In a query, setting QueryPolicy.filterExp filters records out of the query.

Execution timing

Filter expressions are only executed when the record already exists in the database. They will not execute if a read operation fails to find the record, which surfaces a missing-record signal to the client, usually the RecordNotFound error; the exact behavior of exists() is client-specific, so consult your client reference.

If a write operation is creating a new record the filter expression will not execute. To veto record creation, combine the filter expression with a WritePolicy.recordExistsAction set to UPDATE_ONLY.

Behavior when the filter does not evaluate to true

A record is accepted only when its filter expression evaluates to true. An explicit false, or an unknown that survives the two-phase Execution model is treated identically: the record is rejected. How that rejection reaches the caller depends on the command class.

Command class	Commands	Rejection surface
Single-record	get, put, operate, remove, touch	Differentiates “record missing” (RecordNotFound) vs. “record present but rejected by filter” (FilteredOut).
Single-record existence	exists	Most clients return false, as if the record was absent. Consult your client’s API reference.
Batch	batch_read, batch_write, batch_operate, batch_remove	The top-level call does not raise. Each per-record result carries the rejection as a status code (FILTERED_OUT, 27) in the batch result array. Callers must inspect each entry.
Queries	query.results / query.foreach, scan_all, background variants	Rejected records are silently omitted from the result stream.
Transactions	Any of the above, inside the transaction (strong-consistency true namespaces)	Per-operation. FilteredOut on any command does not roll back the transaction.
XDR ship filters	Configured via namespace config, not client API	Filtered-out records are not shipped. No application-level signal.

Two practical consequences:

• Single-record callers can try/except FilteredOut (or equivalent). Batch callers cannot — the exception would short-circuit the rest of the batch. Inspect each BatchRecord’s result code instead.
• Query and scan callers get a filtered view, not a rejection report. If you need to distinguish “this key was filtered” from “this key doesn’t match”, do the filter as a single-record command per key rather than as part of the query.

Filter XDR records with expressions

You can filter records before they are sent to remote destinations using XDR (Cross-Datacenter Replication).

These XDR filters are dynamic and must be defined uniquely for each namespace going to a specific destination datacenter (DC).

You have two main ways to set these filter expressions:

Using the info command: Execute the command xdr-set-filter.

Programmatically: Use the appropriate client API in your application code.

XDR filtering reduces the volume of data that you replicate. When you reduce the volume of replicated data, you also:

• Reduce network traffic.
• Reduce storage and processing requirements at destination datacenters, which avoids the costs of overprovisioning, most significantly in hub-and-spoke XDR topologies.
• Reduce the cost of moving data across or from public clouds.

For configuration details, see XDR filters.

Syntax and behavior

Aerospike expressions use Polish Notation (PN) syntax and have strict typing, which broadens the criteria you can use to select specific records.

Key rules

• Immutability: All data within an expression is immutable (cannot be changed).

• Bin modifications: If an expression performs modifications to a bin, those changes operate on a temporary copy and are not saved to the actual bin once the expression finishes.

• Conditional logic but no iteration: Expressions do support conditional branching via the cond operator. However, the expression system does not support loops, iteration, or recursion, and therefore cannot perform general control-flow constructs such as repeated evaluation. If performed as an expression write operation, the final result of the expression is stored to the target bin.

This means expressions are designed for fast, single-pass evaluation without persistent state changes or complex control flow within the evaluation logic itself.

Types

Expressions are strictly typed. Each expression evaluates to a value of one of the supported data types: nil, boolean, integer (64-bit signed), float (64-bit), string, blob, list, map, GeoJSON, or HyperLogLog. The type must match what the operation expects; for example, a comparison expression requires both operands to be the same type. See the client API reference for your language for the specific type signatures.

Execution model

Metadata resolution is critical for the performance of Aerospike expressions. Since metadata is stored in the primary index and doesn’t require loading data from disk for namespaces with data on disk, expressions that can be entirely processed using only this metadata can avoid disk access.

This ability to forgo disk operations yields a significant performance improvement—an order of magnitude gain. Aerospike expressions achieve this efficiency using a two-phase execution model. When an expression’s logic for a specific operation can be satisfied only with metadata, the system executes it that way, resulting in major speed enhancements.

Phase 1: Metadata check (fast path)

This phase starts by trying to resolve the expression using only the metadata stored in the primary index, which is very fast and avoids disk access.

Storage Data is unknown: During this phase, any expression that tries to read the actual stored data evaluates as unknown.

Trilean Logic: Most expressions output unknown if their input is unknown, except for logical expressions which use trilean logic (true, false, or unknown) and can sometimes return a definite answer.

Outcomes:

• If the result is false, the record is immediately filtered out, and no storage is accessed.
• If the result is true, the operation proceeds, but storage is only accessed if absolutely necessary for the ongoing operation.
• If the result is unknown, the system moves to Phase 2.

Phase 2: Storage-data access

This phase is executed only if the first phase failed to produce a definite true or false answer.

• Data Load: The system loads the full record, incurring physical I/O if the data resides on disk.
• Re-execution: The expression is executed a second time.
• Definitive result: This phase always resolves the expression to a definite true or false answer.

This two-phase approach ensures that expressions only proceed to the slower disk-access phase when the outcome absolutely depends on the actual stored data.

Example: metadata first, trilean short-circuit

The since_update() expression reads milliseconds since the record was last updated from metadata (see Record metadata). It is a practical predicate for the two-phase model: unlike matching on set_name, which often duplicates what the client already chose when issuing the operation. since_update always reflects the record in storage.

Use a recent window in milliseconds (here, two hours), aligned with the since_update reference examples.

Conjunction (and)

Require both a recent update and a positive integer bin priority.

Here is how a conjunction (AND) behaves during evaluation:

Scenario A: The record is stale

• Phase 1 (Metadata): The since_update check returns false.
• Short-circuit: Since false AND (anything) is always false, the entire expression fails immediately.
• Result: The server skips Phase 2 and does not touch the disk.

Scenario B: The record is recent

• Phase 1 (Metadata): The since_update check returns true.
• The conflict: The system doesn’t know the priority bin value yet (it’s on disk), so that part is unknown.
• Result: true AND unknown equals unknown. The system proceeds to Phase 2, loads the record from storage, and re-evaluates to get a final answer.

Java

import com.aerospike.client.exp.Expression;
import com.aerospike.client.exp.Exp;

long recentMs = 2L * 60 * 60 * 1000;

Expression recentAndHighPriority = Exp.build(
    Exp.and(
        Exp.lt(Exp.sinceUpdate(), Exp.val(recentMs)),
        Exp.gt(Exp.intBin("priority"), Exp.val(0))));

Python

from aerospike_helpers.expressions import And, GT, IntBin, LT, SinceUpdateTime

recent_ms = 2 * 60 * 60 * 1000

recent_and_high_priority = And(
    LT(SinceUpdateTime(), recent_ms),
    GT(IntBin("priority"), 0),
).compile()

C

as_exp_build(predexp,
    as_exp_and(
        as_exp_cmp_lt(
            as_exp_since_update(),
            as_exp_int(2 * 60 * 60 * 1000)),
        as_exp_cmp_gt(
            as_exp_bin_int("priority"),
            as_exp_int(0))));

Go

// Requires: import as "github.com/aerospike/aerospike-client-go/v6"
recentMs := int64(2 * 60 * 60 * 1000)
_ = as.ExpAnd(
    as.ExpLess(as.ExpSinceUpdate(), as.ExpIntVal(recentMs)),
    as.ExpGreater(as.ExpIntBin("priority"), as.ExpIntVal(0)))

C#

using Aerospike.Client;

long recentMs = 2L * 60 * 60 * 1000;

Expression recentAndHighPriority = Exp.Build(
    Exp.And(
        Exp.LT(Exp.SinceUpdate(), Exp.Val(recentMs)),
        Exp.GT(Exp.IntBin("priority"), Exp.Val(0))));

Node.js

const Aerospike = await import("aerospike");

const exp = Aerospike.exp

const recentMs = 2 * 60 * 60 * 1000
const recentAndHighPriority = exp.and(
  exp.lt(exp.sinceUpdate(), exp.int(recentMs)),
  exp.gt(exp.binInt('priority'), exp.int(0)),
)

Disjunction (or)

Keep records that are either recently updated or have priority greater than zero.

Here is how a conjunction (AND) behaves during evaluation:

Scenario A: The record is recent

• Phase 1 (Metadata): The since_update check returns true.
• Short-circuit: Since true AND (anything) is always true, the entire expression fails immediately.
• Result: The server skips Phase 2. It has already found a reason to include the record, so it doesn’t need to read the bin data from disk.

Scenario B: The record is recent

- Phase 1 (Metadata): The since_update check returns false. - The conflict: The system doesn’t know the priority bin value yet (unknown). Since false OR unknown is still unknown, the system cannot make a final decision. - Result: The system proceeds to Phase 2, loads the record from storage, and checks the actual bin value to reach a definitive true or false.

Java

import com.aerospike.client.exp.Expression;
import com.aerospike.client.exp.Exp;

long recentMs = 2L * 60 * 60 * 1000;

Expression recentOrHighPriority = Exp.build(
    Exp.or(
        Exp.lt(Exp.sinceUpdate(), Exp.val(recentMs)),
        Exp.gt(Exp.intBin("priority"), Exp.val(0))));

Python

from aerospike_helpers.expressions import GT, IntBin, LT, Or, SinceUpdateTime

recent_ms = 2 * 60 * 60 * 1000

recent_or_high_priority = Or(
    LT(SinceUpdateTime(), recent_ms),
    GT(IntBin("priority"), 0),
).compile()

C

as_exp_build(predexp,
    as_exp_or(
        as_exp_cmp_lt(
            as_exp_since_update(),
            as_exp_int(2 * 60 * 60 * 1000)),
        as_exp_cmp_gt(
            as_exp_bin_int("priority"),
            as_exp_int(0))));

Go

// Requires: import as "github.com/aerospike/aerospike-client-go/v6"
recentMs := int64(2 * 60 * 60 * 1000)
_ = as.ExpOr(
    as.ExpLess(as.ExpSinceUpdate(), as.ExpIntVal(recentMs)),
    as.ExpGreater(as.ExpIntBin("priority"), as.ExpIntVal(0)))

C#

using Aerospike.Client;

long recentMs = 2L * 60 * 60 * 1000;

Expression recentOrHighPriority = Exp.Build(
    Exp.Or(
        Exp.LT(Exp.SinceUpdate(), Exp.Val(recentMs)),
        Exp.GT(Exp.IntBin("priority"), Exp.Val(0))));

Node.js

const Aerospike = await import("aerospike");

const exp = Aerospike.exp

const recentMs = 2 * 60 * 60 * 1000
const recentOrHighPriority = exp.or(
  exp.lt(exp.sinceUpdate(), exp.int(recentMs)),
  exp.gt(exp.binInt('priority'), exp.int(0)),
)