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.

Both operands must be the same type — two integers, or two strings, but never an integer and a float. A mismatch fails the command with error 4 (parameter error), rather than evaluating to false. A bin that holds a different type from the one its reader expects is another matter: the reader evaluates to unknown, so as a filter the record is rejected like any other non-match. GeoJSON and HLL cannot be compared at all; use cmp_geo for GeoJSON. See Types on the expressions overview.

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 (Database 8.1.2 and later). The examples use bins and thresholds aligned with the bookstore scenario on the path expressions page.

The Developer SDK’s AEL text syntax expresses the same comparisons inline, for example $.age >= 21.

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.

String values

eq, ne, gt, ge, lt, and le compare String values by UTF-8 bytes. The six String search operations in Database 8.2.0 treat canonically equivalent spellings as equal, so their results can differ from comparison operators. See Compare String values.

Map values

As of Database 8.2.0, eq, ne, gt, ge, lt, and le compare Maps by content, regardless of subtype. Two Maps with the same elements are equal whether they are Unordered, K-ordered, or KV-ordered, including Maps nested in a List or another Map. See Ordering for how one Map orders against another.

Before Database 8.2.0, a comparison evaluates to unknown when either operand is an Unordered Map or contains one, so a record filter built on it matches no records.

Ops

cmp_geo

cmp_geo(left, right)

Description

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

Arguments

Name	Type	Description
left	geojson	GeoJSON point or region. Any expression that evaluates to a GeoJSON value.
right	geojson	The GeoJSON value to test left against. One operand must be a point and the other a region; two points, or two regions, always return false.

Returns

boolean

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 SDK

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

Python SDK

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

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

cmp_regex

deprecated

cmp_regex(options_value, regex_string, string)

Description

Returns true if the regex_string matches the string, otherwise returns false. Uses POSIX regex and is not Unicode-compatible. Superseded by string_regex_compare.

Arguments

Name	Type	Description
options_value	integer literal	POSIX regcomp flags, combined with bitwise OR, or 0 for none: 1 extended syntax, 2 case-insensitive, 4 newline-sensitive matching, 8 no effect. Pass the numbers — most clients name 4 NOSUB and 8 NEWLINE, the reverse of what the server applies.
regex_string	string literal	POSIX regular expression to match. Compiled once when the expression is built, so it cannot be computed from a bin.
string	string	String bin to match against, or any expression that evaluates to a string.

Returns

boolean

Introduced

5.2.0.4

Example

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

Rust

use aerospike::expressions::{regex_compare, string_bin};
use aerospike::RegexFlag;

let exp = regex_compare(
    "^555.*".into(),
    RegexFlag::NONE as i64,
    string_bin("phone_num".into()));

C#

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

Go

// Requires: import as "github.com/aerospike/aerospike-client-go/v8"
exp := as.ExpRegexCompare("^555.*", as.ExpRegexFlagNONE, as.ExpStringBin("phone_num"))

Node.js

const exp = Aerospike.exp

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

C

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

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

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.

When both operands are strings, eq tests UTF-8 byte equality. A precomposed é (U+00E9) and an e followed by a combining acute accent (U+0301) are not equal. The string search operations treat those spellings as the same text. See Compare String values.

As of Database 8.2.0, eq compares Maps by content regardless of subtype. Two Maps with the same elements are equal whether they are Unordered, K-ordered, or KV-ordered, including Maps nested in a List or another Map. Before Database 8.2.0, eq returns unknown when either operand is an Unordered Map or contains one. See Map values.

Arguments

Name	Type	Description
left	any	Left operand. Any expression that evaluates to an integer, float, string, blob, boolean, list, or map. GeoJSON and HLL cannot be compared this way; for GeoJSON use cmp_geo.
right	any	Right operand. Must evaluate to the same type as left.

Returns

boolean

Introduced

5.2.0.4

Example

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

Java SDK

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

Python SDK

exp = "$.category == '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()

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	Description
left	any	Left operand. Any expression that evaluates to an integer, float, string, blob, boolean, list, or map. GeoJSON and HLL cannot be compared this way; for GeoJSON use cmp_geo.
right	any	Right operand. Must evaluate to the same type as left.

Returns

boolean

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 SDK

String exp = "$.quantity >= 1";

Python SDK

exp = "$.quantity >= 1"

Rust

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

let exp = ge(int_bin("quantity".into()), int_val(1));

C#

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

Go

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

Node.js

const exp = Aerospike.exp

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

C

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

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

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	Description
left	any	Left operand. Any expression that evaluates to an integer, float, string, blob, boolean, list, or map. GeoJSON and HLL cannot be compared this way; for GeoJSON use cmp_geo.
right	any	Right operand. Must evaluate to the same type as left.

Returns

boolean

Introduced

5.2.0.4

Example

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

Java SDK

String exp = "$.ttl() > 365 * 24 * 3600";

Python SDK

exp = "$.ttl() > 365 * 24 * 3600"

Rust

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

let exp = gt(ttl(), int_val(365 * 24 * 3600));

C#

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

Go

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

Node.js

const exp = Aerospike.exp

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

C

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

Java

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

Python

from aerospike_helpers.expressions import GT, TTL

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

in_list

in_list(value, list)

Description

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

Arguments

Name	Type	Description
value	any	Value to look for. Matching is by type as well as by value, so an integer never matches a float and a boolean never matches an integer.
list	list	List to search. A list bin, a list literal, or any expression that evaluates to a list; its elements need not all be of one type.

Returns

boolean

Introduced

8.1.2

Example

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

Java SDK

String exp = "$.color in ['red', 'blue', 'green']";

Python SDK

exp = "$.color in ['red', 'blue', 'green']"

Rust

use aerospike::expressions::{in_list, list_val, string_bin};
use aerospike::Value;

let exp = in_list(
    string_bin("color".into()),
    list_val(vec![Value::from("red"), Value::from("blue"), Value::from("green")]));

C#

using System.Collections.Generic;

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

Go

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

Node.js

const exp = Aerospike.exp

const filterExp = exp.inList(
  exp.binStr('color'),
  exp.list(['red', 'blue', 'green']))

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

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, Val
from aerospike_helpers.expressions.list import InList

# The list operand must be an expression: a bare Python list is read as
# a bin name and fails when the operation is sent.
exp = InList(StrBin("color"), Val(["red", "blue", "green"])).compile()

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	Description
left	any	Left operand. Any expression that evaluates to an integer, float, string, blob, boolean, list, or map. GeoJSON and HLL cannot be compared this way; for GeoJSON use cmp_geo.
right	any	Right operand. Must evaluate to the same type as left.

Returns

boolean

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 SDK

String exp = "$.quantity <= 100";

Python SDK

exp = "$.quantity <= 100"

Rust

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

let exp = le(int_bin("quantity".into()), int_val(100));

C#

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

Go

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

Node.js

const exp = Aerospike.exp

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

C

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

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

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	Description
left	any	Left operand. Any expression that evaluates to an integer, float, string, blob, boolean, list, or map. GeoJSON and HLL cannot be compared this way; for GeoJSON use cmp_geo.
right	any	Right operand. Must evaluate to the same type as left.

Returns

boolean

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 SDK

String exp = "$.price < 10.0";

Python SDK

exp = "$.price < 10.0"

Rust

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

let exp = lt(float_bin("price".into()), float_val(10.0));

C#

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

Go

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

Node.js

const exp = Aerospike.exp

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

C

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

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

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	Description
left	any	Left operand. Any expression that evaluates to an integer, float, string, blob, boolean, list, or map. GeoJSON and HLL cannot be compared this way; for GeoJSON use cmp_geo.
right	any	Right operand. Must evaluate to the same type as left.

Returns

boolean

Introduced

5.2.0.4

Example

Find records where bin age does not hold an integer.

Java SDK

String exp = "$.age.type() != INT";

Python SDK

exp = "$.age.type() != INT"

Rust

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

let exp = ne(bin_type("age".into()), int_val(ParticleType::INTEGER as i64));

C#

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

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.ExpNotEq(as.ExpBinType("age"), as.ExpIntVal(particleType.INTEGER))

Node.js

const exp = Aerospike.exp

const filterExp = exp.ne(exp.binType('age'), exp.int(1))

C

as_exp_build(predexp,
  as_exp_cmp_ne(
    as_exp_bin_type("age"), as_exp_int(AS_BYTES_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()