aerospike.predexp — Query Predicate Expressions

The following methods allow a user to define a predicate expression filter. Predicate expression filters are applied on the query results on the server. Predicate expression filters may occur on any bin in the record.

aerospike.predexp.predexp_and(nexpr)

Create an AND logical predicate expression.

Parameters:nexprint Number of expressions to combine with “and” . The value of nexpr must be between 1 and 65535.
Returns:tuple() to be used in aerospike.Query.predexp().

For example, the following sequence of predicate expressions selects records where the value of bin “c” is between 11 and 20 inclusive:

from aerospike import predexp as predexp
predexps =  [
    predexp.integer_bin("c"),
    predexp.integer_value(11),
    predexp.integer_greatereq(),
    predexp.integer_bin("c"),
    predexp.integer_value(20),
    predexp.integer_lesseq(),
    predexp.predexp_and(2)
]
aerospike.predexp.predexp_or(nexpr)

Create an Or logical predicate expression.

Parameters:nexprint Number of expressions to combine with “or”. The value of nexpr must be between 1 and 65535.
Returns:tuple() to be used in aerospike.Query.predexp().

For example, the following sequence of predicate expressions selects records where the value of bin “pet” is “dog” or “cat”

from aerospike import predexp as predexp
predexps =  [
    predexp.string_bin("pet"),
    predexp.string_value("cat"),
    predexp.string_equal(),
    predexp.string_bin("pet"),
    predexp.string_value("dog"),
    predexp.string_equal(),
    predexp.predexp_or(2)
]
aerospike.predexp.predexp_not()

Create a not logical predicate expression which negates the previouse predicate expression on the stack.

Returns:tuple() to be used in aerospike.Query.predexp().

For example, the following sequence of predicate expressions selects records where the value of bin “pet” is not “cat”

from aerospike import predexp as predexp
predexps =  [
    predexp.string_bin("pet"),
    predexp.string_value("cat"),
    predexp.string_equal(),
    predexp.predexp_not()
]
aerospike.predexp.integer_bin(bin_name)

Create an integer bin value predicate expression.

Parameters:bin_namestr The name of the bin containing an integer.
Returns:tuple() to be used in aerospike.Query.predexp().

For example, the following sequence of predicate expressions selects records where the value of bin “age” is 42

from aerospike import predexp as predexp
predexps =  [
    predexp.integer_bin("age"),
    predexp.integer_value(42),
    predexp.integer_equal()
]
aerospike.predexp.string_bin(bin_name)

Create a string bin value predicate expression.

Parameters:bin_namestr The name of the bin containing a string.
Returns:tuple() to be used in aerospike.Query.predexp().

For example, the following sequence of predicate expressions selects records where the value of bin “name” is “Bob”.

from aerospike import predexp as predexp
predexps =  [
    predexp.string_bin("name"),
    predexp.string_value("Bob"),
    predexp.string_equal()
]
aerospike.predexp.geojson_bin(bin_name)

Create a GeoJSON bin value predicate expression.

Parameters:bin_namestr The name of the bin containing a GeoJSON value.
Returns:tuple() to be used in aerospike.Query.predexp().

For example, the following sequence of predicate expressions selects records where the value of bin “location” is within a specified region.

from aerospike import predexp as predexp
geo_region = aerospike.GeoJSON(
    {"type": "AeroCircle", "coordinates": [[-122.0, 37.5], 1000]}).dumps()
predexps =  [
    predexp.geojson_bin("location"),
    predexp.geojson_value(geo_region),
    predexp.geojson_within()
]
aerospike.predexp.list_bin(bin_name)

Create a list bin value predicate expression.

Parameters:bin_namestr The name of the bin containing a list.
Returns:tuple() to be used in aerospike.Query.predexp().

For example, the following sequence of predicate expressions selects records where the list in bin “names” contains an entry equal to “Alice”

from aerospike import predexp as predexp
predexps =  [
    predexp.string_var("list_entry"),
    predexp.string_value("Alice"),
    predexp.string_equal(),
    predexp.list_bin("names"),
    predexp.list_iterate_or("list_entry")
]
aerospike.predexp.map_bin(bin_name)

Create a map bin value predicate expression.

Parameters:bin_namestr The name of the bin containing a map value.
Returns:tuple() to be used in aerospike.Query.predexp().

For example, the following sequence of predicate expressions selects records where the map in bin “pet_count” has an entry with a key equal to “Cat”

from aerospike import predexp as predexp
predexps =  [
    predexp.string_var("map_key"),
    predexp.string_value("Cat"),
    predexp.string_equal(),
    predexp.map_bin("pet_count"),
    predexp.mapkey_iterate_or("map_key")
]
aerospike.predexp.geojson_value(geo_value)

Create a GeoJSON value predicate expression.

Parameters:bin_namestr The geojson string.
Returns:tuple() to be used in aerospike.Query.predexp().

For example, the following sequence of predicate expressions selects records where the value of bin “location” is within a specified region.

from aerospike import predexp as predexp
geo_region = aerospike.GeoJSON(
    {"type": "AeroCircle", "coordinates": [[-122.0, 37.5], 1000]}).dumps()
predexps =  [
    predexp.geojson_bin("location"),
    predexp.geojson_value(geo_region),
    predexp.geojson_within()
]
aerospike.predexp.integer_value(int_value)

Create an integer value predicate expression.

Parameters:bin_nameint The integer value
Returns:tuple() to be used in aerospike.Query.predexp().

For example, the following sequence of predicate expressions selects records where the value of bin “age” is 42

from aerospike import predexp as predexp
predexps =  [
    predexp.integer_bin("age"),
    predexp.integer_value(42),
    predexp.integer_equal()
]
aerospike.predexp.string_value(string_value)

Create a string value predicate expression.

Parameters:bin_namestr The string value.
Returns:tuple() to be used in aerospike.Query.predexp().

For example, the following sequence of predicate expressions selects records where the value of bin “name” is “Bob”.

from aerospike import predexp as predexp
predexps =  [
    predexp.string_bin("name"),
    predexp.string_value("Bob"),
    predexp.string_equal()
]
aerospike.predexp.integer_var(var_name)

Create an integer iteration variable predicate expression.

Parameters:var_namestr The name of the variable. This should match a value used when specifying the iteration.
Returns:tuple() to be used in aerospike.Query.predexp().

For example the following selects a record where the list in bin “numbers” contains an entry equal to 42

from aerospike import predexp as predexp
predexps =  [
    predexp.integer_var("item"),
    predexp.integer_value(42),
    predexp.integer_equal(),
    predexp.list_bin("numbers"),
    predexp.list_iterate_or("item")
]
aerospike.predexp.string_var(var_name)

Create an string iteration variable predicate expression.

Parameters:var_namestr The name of the variable. This should match a value used when specifying the iteration.
Returns:tuple() to be used in aerospike.Query.predexp().

For example the following selects a record where the list in bin “languages” contains an entry equal to "Python"

from aerospike import predexp as predexp
predexps =  [
    predexp.string_var("item"),
    predexp.string_value("Python"),
    predexp.string_equal(),
    predexp.list_bin("languages"),
    predexp.list_iterate_or("item")
]
aerospike.predexp.geojson_var(var_name)

Create an GeoJSON iteration variable predicate expression.

Parameters:var_namestr The name of the variable. This should match a value used when specifying the iteration.
Returns:tuple() to be used in aerospike.Query.predexp().
aerospike.predexp.list_iterate_or(var_name)

Create an list iteration OR logical predicate expression.

Parameters:bin_namestr The name of the iteration variable
Returns:tuple() to be used in aerospike.Query.predexp().

The list iteration expression pops two children off the expression stack. The left child (pushed earlier) must contain a logical subexpression containing one or more matching iteration variable expressions. The right child (pushed later) must specify a list bin. The list iteration traverses the list and repeatedly evaluates the subexpression substituting each list element’s value into the matching iteration variable. The result of the iteration expression is a logical OR of all of the individual element evaluations.

If the list bin contains zero elements list_iterate_or() will evaluate to false.

For example, the following sequence of predicate expressions selects records where the list in bin “names” contains an entry equal to “Alice”

from aerospike import predexp as predexp
predexps =  [
    predexp.string_var("list_entry"),
    predexp.string_value("Alice"),
    predexp.string_equal(),
    predexp.list_bin("names"),
    predexp.list_iterate_or("list_entry")
]
aerospike.predexp.list_iterate_and(var_name)

Create an list iteration And logical predicate expression.

Parameters:var_namestr The name of the iteration variable
Returns:tuple() to be used in aerospike.Query.predexp().

The list iteration expression pops two children off the expression stack. The left child (pushed earlier) must contain a logical subexpression containing one or more matching iteration variable expressions. The right child (pushed later) must specify a list bin. The list iteration traverses the list and repeatedly evaluates the subexpression substituting each list element’s value into the matching iteration variable. The result of the iteration expression is a logical AND of all of the individual element evaluations.

If the list bin contains zero elements list_iterate_and() will evaluate to true. This is useful when testing for exclusion (see example).

For example, the following sequence of predicate expressions selects records where the list in bin “names” contains no entries equal to “Bob”.

from aerospike import predexp as predexp
predexps =  [
    predexp.string_var("list_entry"),
    predexp.string_value("Bob"),
    predexp.string_equal(),
    predexp.predexp_not(),
    predexp.list_bin("names"),
    predexp.list_iterate_and("list_entry")
]
aerospike.predexp.mapkey_iterate_or(var_name)

Create an map key iteration Or logical predicate expression.

Parameters:var_namestr The name of the iteration variable
Returns:tuple() to be used in aerospike.Query.predexp().

The mapkey iteration expression pops two children off the expression stack. The left child (pushed earlier) must contain a logical subexpression containing one or more matching iteration variable expressions. The right child (pushed later) must specify a map bin. The mapkey iteration traverses the map and repeatedly evaluates the subexpression substituting each map key value into The matching iteration variable. The result of the iteration expression is a logical OR of all of the individual element evaluations.

If the map bin contains zero elements mapkey_iterate_or() will return false. For example, the following sequence of predicate expressions selects records where the map in bin “pet_count” has an entry with a key equal to “Cat”

from aerospike import predexp as predexp
predexps =  [
    predexp.string_var("map_key"),
    predexp.string_value("Cat"),
    predexp.string_equal(),
    predexp.map_bin("pet_count"),
    predexp.mapkey_iterate_or("map_key")
]
aerospike.predexp.mapkey_iterate_and(var_name)

Create an map key iteration AND logical predicate expression.

Parameters:var_namestr The name of the iteration variable
Returns:tuple() to be used in aerospike.Query.predexp().

The mapkey iteration expression pops two children off the expression stack. The left child (pushed earlier) must contain a logical subexpression containing one or more matching iteration variable expressions. The right child (pushed later) must specify a map bin. The mapkey iteration traverses the map and repeatedly evaluates the subexpression substituting each map key value into The matching iteration variable. The result of the iteration expression is a logical AND of all of the individual element evaluations.

If the map bin contains zero elements mapkey_iterate_and() will return true. This is useful when testing for exclusion (see example).

For example, the following sequence of predicate expressions selects records where the map in bin “pet_count” does not contain an entry with a key equal to “Cat”.

from aerospike import predexp as predexp
predexps =  [
    predexp.string_var("map_key"),
    predexp.string_value("Cat"),
    predexp.string_equal(),
    predexp.predexp_not(),
    predexp.map_bin("pet_count"),
    predexp.mapkey_iterate_and("map_key")
]
aerospike.predexp.mapval_iterate_or(var_name)

Create an map value iteration Or logical predicate expression.

Parameters:var_namestr The name of the iteration variable
Returns:tuple() to be used in aerospike.Query.predexp().

The mapval iteration expression pops two children off the expression stack. The left child (pushed earlier) must contain a logical subexpression containing one or more matching iteration variable expressions. The right child (pushed later) must specify a map bin. The mapval iteration traverses the map and repeatedly evaluates the subexpression substituting each map value into the matching iteration variable. The result of the iteration expression is a logical OR of all of the individual element evaluations.

If the map bin contains zero elements mapval_iterate_or() will return false.

For example, the following sequence of predicate expressions selects records where at least one of the values in the map in bin “pet_count” is 0

from aerospike import predexp as predexp
predexps =  [
    predexp.string_var("map_key"),
    predexp.integer_value(0),
    predexp.integer_equal(),
    predexp.map_bin("pet_count"),
    predexp.mapval_iterate_or("map_key")
]
aerospike.predexp.mapval_iterate_and(var_name)

Create an map value iteration AND logical predicate expression.

Parameters:var_namestr The name of the iteration variable
Returns:tuple() to be used in aerospike.Query.predexp().

The mapval iteration expression pops two children off the expression stack. The left child (pushed earlier) must contain a logical subexpression containing one or more matching iteration variable expressions. The right child (pushed later) must specify a map bin. The mapval iteration traverses the map and repeatedly evaluates the subexpression substituting each map value into the matching iteration variable. The result of the iteration expression is a logical AND of all of the individual element evaluations.

If the map bin contains zero elements mapval_iterate_and() will return true. This is useful when testing for exclusion (see example).

For example, the following sequence of predicate expressions selects records where none of the values in the map in bin “pet_count” is 0

from aerospike import predexp as predexp
predexps =  [
    predexp.string_var("map_key"),
    predexp.integer_value(0),
    predexp.integer_equal(),
    predexp.predexp_not(),
    predexp.map_bin("pet_count"),
    predexp.mapval_iterate_and("map_key")
]
aerospike.predexp.rec_digest_modulo(mod)

Create a digest modulo record metadata value predicate expression.

Parameters:modint The value of this expression assumes the value of 4 bytes of the digest modulo this argument.
Returns:tuple() to be used in aerospike.Query.predexp().

For example, the following sequence of predicate expressions selects records that have digest(key) % 3 == 1 :

from aerospike import predexp as predexp
predexps =  [
    predexp.rec_digest_modulo(3),
    predexp.integer_value(1),
    predexp.integer_equal()
]
aerospike.predexp.rec_last_update()

Create a last update record metadata value predicate expression. The record last update expression assumes the value of the number of nanoseconds since the unix epoch that the record was last updated.

Returns:tuple() to be used in aerospike.Query.predexp().

For example, the following sequence of predicate expressions selects records that have been updated after a timestamp:

from aerospike import predexp as predexp
predexps =  [
    predexp.rec_last_update(),
    predexp.integer_value(timestamp_ns),
    predexp.integer_greater()
]
aerospike.predexp.rec_void_time()

Create a void time record metadata value predicate expression. The record void time expression assumes the value of the number of nanoseconds since the unix epoch when the record will expire. The special value of 0 means the record will not expire.

Returns:tuple() to be used in aerospike.Query.predexp().

For example, the following sequence of predicate expressions selects records that have void time set to 0 (no expiration):

from aerospike import predexp as predexp
predexps =  [
    predexp.rec_void_time(),
    predexp.integer_value(0),
    predexp.integer_equal()
]
aerospike.predexp.rec_device_size()

Create a record device size metadata value predicate expression. The record device size expression assumes the value of the size in bytes that the record occupies on device storage. For non-persisted records, this value is 0.

Returns:tuple() to be used in aerospike.Query.predexp().

For example, the following sequence of predicate expressions selects records whose device storage size is larger than 65K:

from aerospike import predexp as predexp
predexps =  [
    predexp.rec_device_size(),
    predexp.integer_value(65 * 1024),
    predexp.integer_greater()
]
aerospike.predexp.integer_equal()

Create an integer comparison logical predicate expression. If the value of either of the child expressions is unknown because a specified bin does not exist or contains a value of the wrong type the result of the comparison is false. If a true outcome is desirable in this situation use the complimentary comparison and enclose in a logical NOT.

Returns:tuple() to be used in aerospike.Query.predexp().

For example, the following sequence of predicate expressions selects records that have bin “foo” equal to 42:

from aerospike import predexp as predexp
predexps =  [
    predexp.integer_bin("foo"),
    predexp.integer_value(42),
    predexp.integer_equal()
]
aerospike.predexp.integer_greater()

Create an integer comparison logical predicate expression.

Returns:tuple() to be used in aerospike.Query.predexp().

For example, the following sequence of predicate expressions selects records that have bin “foo” greater than 42:

from aerospike import predexp as predexp
predexps =  [
    predexp.integer_bin("foo"),
    predexp.integer_value(42),
    predexp.integer_greater()
]
aerospike.predexp.integer_greatereq()

Create an integer comparison logical predicate expression.

Returns:tuple() to be used in aerospike.Query.predexp().

For example, the following sequence of predicate expressions selects records that have bin “foo” greater than or equal to 42:

from aerospike import predexp as predexp
predexps =  [
    predexp.integer_bin("foo"),
    predexp.integer_value(42),
    predexp.integer_greatereq()
]
aerospike.predexp.integer_less()

Create an integer comparison logical predicate expression.

Returns:tuple() to be used in aerospike.Query.predexp().

For example, the following sequence of predicate expressions selects records that have bin “foo” less than 42:

from aerospike import predexp as predexp
predexps =  [
    predexp.integer_bin("foo"),
    predexp.integer_value(42),
    predexp.integer_less()
]
aerospike.predexp.integer_lesseq()

Create an integer comparison logical predicate expression.

Returns:tuple() to be used in aerospike.Query.predexp().

For example, the following sequence of predicate expressions selects records that have bin “foo” less than or equal to 42:

from aerospike import predexp as predexp
predexps =  [
    predexp.integer_bin("foo"),
    predexp.integer_value(42),
    predexp.integer_lesseq()
]
aerospike.predexp.integer_unequal()

Create an integer comparison logical predicate expression.

Returns:tuple() to be used in aerospike.Query.predexp().

This expression will evaluate to true if, and only if, both children of the expression exist, and are of type integer, and are not equal to each other. If this is not desired, utilize aerospike.predexp.integer_equal() in conjunction with aerospike.predexp.predexp_not().

For example, the following sequence of predicate expressions selects records that have bin “foo” not equal to 42:

from aerospike import predexp as predexp
predexps =  [
    predexp.integer_bin("foo"),
    predexp.integer_value(42),
    predexp.integer_unequal()
]
aerospike.predexp.string_equal()

Create an integer comparison logical predicate expression. If the value of either of the child expressions is unknown because a specified bin does not exist or contains a value of the wrong type the result of the comparison is false. If a true outcome is desirable in this situation use the complimentary comparison and enclose in a logical NOT.

Returns:tuple() to be used in aerospike.Query.predexp().

For example, the following sequence of predicate expressions selects records that have bin “foo” equal to “bar”:

from aerospike import predexp as predexp
predexps =  [
    predexp.string_bin("foo"),
    predexp.string_value("bar"),
    predexp.string_equal()
]
aerospike.predexp.string_unequal()

Create an integer comparison logical predicate expression.

Returns:tuple() to be used in aerospike.Query.predexp().

This expression will evaluate to true if, and only if, both children of the expression exist, and are of type string, and are not equal to each other. If this is not desired, utilize aerospike.predexp.string_equal() in conjunction with aerospike.predexp.predexp_not().

For example, the following sequence of predicate expressions selects records that have bin “foo” not equal to “bar”:

from aerospike import predexp as predexp
predexps =  [
    predexp.string_bin("foo"),
    predexp.string_value("bar"),
    predexp.string_unequal()
]
aerospike.predexp.geojson_within()

Create a Geojson within predicate expression.

Returns:tuple() to be used in aerospike.Query.predexp().
from aerospike import predexp as predexp
predexps =  [
    predexp.geojson_bin("location"),
    predexp.geojson_value(my_geo_region),
    predexp.geojson_within()
]
aerospike.predexp.geojson_contains()

Create a Geojson contains predicate expression.

Returns:tuple() to be used in aerospike.Query.predexp().
from aerospike import predexp as predexp
predexps =  [
    predexp.geojson_bin("region"),
    predexp.geojson_value(my_geo_point),
    predexp.geojson_contains()
]
aerospike.predexp.string_regex(*flags)

Create a string regex predicate. May be called without any arguments to specify default behavior.

Parameters:flagsint Regex Flag Values Any, or none of the aerospike REGEX constants
Returns:tuple() to be used in aerospike.Query.predexp().

For example, the following sequence of predicate expressions selects records that have bin “hex” value ending in ‘1’ or ‘2’:

from aerospike import predexp as predexp
predexps = [
    predexp.string_bin('hex'),
    predexp.string_value('0x00.[12]'),
    predexp.string_regex(aerospike.REGEX_ICASE)
]