Comparison

Comparison expressions evaluate to a boolean (true or false). You use them anywhere filter expressions are allowed—for example record filters on single-key, batch, scan, and query operations; FilterExpression on query and batch policies; XDR filters; and operation expressions (read/write expression ops) where the API expects a boolean.

Operands must have the same fundamental type (for example, both integers or both strings). If types do not match, behavior follows the expression type rules for your client; see the overview on expression types and strict typing.

Together with logical operators, comparisons drive most record selection. When a comparison (or its inputs) cannot be resolved in the metadata-only phase, the result may be unknown until storage is read; see the execution model on the expressions overview.

This reference covers the wire-level operators eq, ne, lt, gt, le, ge, cmp_regex, cmp_geo, and the in_list membership test (server 8.1.2+). The examples use bins and thresholds aligned with the bookstore scenario on the path expressions page where it helps readability.

Ops

cmp_geo

cmp_geo(left, right)

Description

Returns true if the left is either contained within or contains the right.

Arguments

Name	Type
left	geojson_expr
right	geojson_expr

Returns

boolean_value

Introduced

5.2.0.4

Example

Find records where GeoJSON bin region contains the given point (San Francisco Bay area). The point is standard GeoJSON; escape quotes as needed in your language.

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

// 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"
point := "{\"type\":\"Point\",\"coordinates\":[-122.4,37.8]}"
exp := 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'))

cmp_regex

cmp_regex(options_value, regex_string, string)

Description

Returns true if the regex_string matches the string, otherwise returns false.

Arguments

Name	Type
regex_string	string_value
options_value	integer_value
string	string_expr

Returns

boolean_value

Introduced

5.2.0.4

Example

Find records where string bin phone_num starts with area code 555.

Java

// import com.aerospike.client.query.RegexFlag;
Expression exp = Exp.build(
  Exp.regexCompare("^555.*", RegexFlag.NONE, Exp.stringBin("phone_num")));

Python

from aerospike_helpers.expressions import CmpRegex, StrBin

exp = CmpRegex(0, "^555.*", StrBin("phone_num")).compile()

C

as_exp_build(predexp,
  as_exp_cmp_regex(0, "^555.*", as_exp_bin_str("phone_num")));

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"
exp := as.ExpRegexCompare("^555.*", as.ExpRegexFlagNONE, as.ExpStringBin("phone_num"))

C#

Expression exp = Exp.Build(
  Exp.RegexCompare("^555.*", RegexFlag.NONE, Exp.StringBin("phone_num")));

Node.js

const exp = Aerospike.exp

const filterExp = exp.cmpRegex(0, '^555.*', exp.binStr('phone_num'))

eq

eq(left, right)

Description

Returns true if the left is equal to the right, otherwise returns false. left and right must result in the same fundamental type.

Note that an expression that uses the eq operator to compare two unordered maps, or an ordered map with an unordered map, returns false if the maps contain the same elements in different orders.

Arguments

Name	Type
left	expr
right	expr

Returns

boolean_value

Introduced

5.2.0.4

Example

Find records where string bin category equals fiction, matching the bookstore example on the path expressions overview.

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

// 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"
exp := 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'))

ge

ge(left, right)

Description

Returns true if the left is greater than or equal to the right, otherwise returns false. left and right must result in the same fundamental type.

Arguments

Name	Type
left	expr
right	expr

Returns

boolean_value

Introduced

5.2.0.4

Example

Find records where integer bin quantity is at least 1 (in-stock style), aligned with variant quantity fields in the path quickstart inventory example.

Java

Expression exp = Exp.build(
  Exp.ge(Exp.intBin("quantity"), Exp.val(1)));

Python

from aerospike_helpers.expressions import GE, IntBin

exp = GE(IntBin("quantity"), 1).compile()

C

as_exp_build(predexp,
  as_exp_cmp_ge(as_exp_bin_int("quantity"), as_exp_int(1)));

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"
exp := as.ExpGreaterEq(as.ExpIntBin("quantity"), as.ExpIntVal(1))

C#

Expression exp = Exp.Build(
  Exp.GE(Exp.IntBin("quantity"), Exp.Val(1)));

Node.js

const exp = Aerospike.exp

const filterExp = exp.ge(exp.binInt('quantity'), exp.int(1))

gt

gt(left, right)

Description

Returns true if the left is greater than the right, otherwise returns false. left and right must result in the same fundamental type.

Arguments

Name	Type
left	expr
right	expr

Returns

boolean_value

Introduced

5.2.0.4

Example

Find records where the time-to-live (TTL) is greater than one year (365 days in seconds).

Java

Expression exp = Exp.build(
  Exp.gt(Exp.ttl(), Exp.val(365 * 24 * 3600)));

Python

from aerospike_helpers.expressions import GT, TTL, Val

exp = GT(TTL(), 365 * 24 * 3600).compile()

C

as_exp_build(predexp,
  as_exp_cmp_gt(as_exp_ttl(), as_exp_int(365 * 24 * 3600)));

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"
exp := as.ExpGreater(as.ExpTTL(), as.ExpIntVal(365*24*3600))

C#

Expression exp = Exp.Build(
  Exp.GT(Exp.TTL(), Exp.Val(365 * 24 * 3600)));

Node.js

const exp = Aerospike.exp

const filterExp = exp.gt(exp.ttl(), exp.int(365 * 24 * 3600))

in_list

in_list(value, list)

Description

Returns true if value is contained in list, otherwise returns false.

Arguments

Name	Type
value	expr
list	list_expr

Returns

boolean_value

Introduced

8.1.2

Example

Filter records where string bin color is one of “red”, “blue”, or “green”.

Java

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

import java.util.List;

Expression exp = Exp.build(
  Exp.inList(
    Exp.stringBin("color"),
    Exp.val(List.of("red", "blue", "green"))));

Python

from aerospike_helpers.expressions import StrBin
from aerospike_helpers.expressions.list import InList

exp = InList(StrBin("color"), ["red", "blue", "green"]).compile()

C

as_arraylist colors;
as_arraylist_init(&colors, 3, 0);
as_arraylist_append_str(&colors, "red");
as_arraylist_append_str(&colors, "blue");
as_arraylist_append_str(&colors, "green");
as_exp_build(predexp,
  as_exp_in_list(
    as_exp_bin_str("color"),
    as_exp_val(&colors)));
as_arraylist_destroy(&colors);

Go

// Requires: import as "github.com/aerospike/aerospike-client-go/v6"
_ = as.ExpInList(
  as.ExpStringBin("color"),
  as.ExpListVal(
    as.NewValue("red"),
    as.NewValue("blue"),
    as.NewValue("green"),
  ),
)

C#

using System.Collections.Generic;

Expression exp = Exp.Build(
  Exp.InList(
    Exp.StringBin("color"),
    Exp.Val(new List<string> { "red", "blue", "green" })));

le

le(left, right)

Description

Returns true if the left is less than or equal to the right, otherwise returns false. left and right must result in the same fundamental type.

Arguments

Name	Type
left	expr
right	expr

Returns

boolean_value

Introduced

5.2.0.4

Example

Find records where integer bin quantity is at most 100 (cap on on-hand units), consistent with inventory-style bins in the path documentation.

Java

Expression exp = Exp.build(
  Exp.le(Exp.intBin("quantity"), Exp.val(100)));

Python

from aerospike_helpers.expressions import IntBin, LE

exp = LE(IntBin("quantity"), 100).compile()

C

as_exp_build(predexp,
  as_exp_cmp_le(as_exp_bin_int("quantity"), as_exp_int(100)));

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"
exp := as.ExpLessEq(as.ExpIntBin("quantity"), as.ExpIntVal(100))

C#

Expression exp = Exp.Build(
  Exp.LE(Exp.IntBin("quantity"), Exp.Val(100)));

Node.js

const exp = Aerospike.exp

const filterExp = exp.le(exp.binInt('quantity'), exp.int(100))

lt

lt(left, right)

Description

Returns true if the left is less than the right, otherwise returns false. left and right must result in the same fundamental type.

Arguments

Name	Type
left	expr
right	expr

Returns

boolean_value

Introduced

5.2.0.4

Example

Find records where float bin price is strictly below 10—the same “cheap book” threshold used in the bookstore example on the path expressions overview.

Java

Expression exp = Exp.build(
  Exp.lt(Exp.floatBin("price"), Exp.val(10.0)));

Python

from aerospike_helpers.expressions import FloatBin, LT

exp = LT(FloatBin("price"), 10.0).compile()

C

as_exp_build(predexp,
  as_exp_cmp_lt(as_exp_bin_float("price"), as_exp_float(10.0)));

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"
exp := as.ExpLess(as.ExpFloatBin("price"), as.ExpFloatVal(10.0))

C#

Expression exp = Exp.Build(
  Exp.LT(Exp.FloatBin("price"), Exp.Val(10.0)));

Node.js

const exp = Aerospike.exp

const filterExp = exp.lt(exp.binFloat('price'), exp.float(10.0))

ne

ne(left, right)

Description

Returns true if the left is not equal to the right, otherwise returns false. left and right must result in the same fundamental type.

Arguments

Name	Type
left	expr
right	expr

Returns

boolean_value

Introduced

5.2.0.4

Example

Find records where bin age is not stored as an integer (bin type differs from AS_BYTES_INTEGER / ParticleType.INTEGER).

Java

// import com.aerospike.client.command.ParticleType;
Expression exp = Exp.build(
  Exp.ne(Exp.binType("age"), Exp.val(ParticleType.INTEGER)));

Python

import aerospike
from aerospike_helpers.expressions import BinType, NE

exp = NE(BinType("age"), aerospike.AS_BYTES_INTEGER).compile()

C

as_exp_build(predexp,
  as_exp_cmp_ne(
    as_exp_bin_type("age"), as_exp_int(AS_BYTES_INTEGER)));

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"
exp := as.ExpNotEq(as.ExpBinType("age"), as.ExpIntVal(1))

C#

Expression exp = Exp.Build(
  Exp.NE(Exp.BinType("age"), Exp.Val((long)ParticleType.INTEGER)));

Node.js

const exp = Aerospike.exp

// ParticleType.INTEGER is 1 in the Java/C# API; same wire value as AS_BYTES_INTEGER.
const filterExp = exp.ne(exp.binType('age'), exp.int(1))