constraints
constraints are used to specified search/filter criteria over the properties defined for objects (Entity, Image, Connection, etc).
Supported operators for properties are:
<(less than)<=(less than or equal to)==(equal to)!=(not equal to)>(greater than)>=(greater than or equal to)in(is in)not_in(is not in)like(pattern match)regex(regular expression match)contains(substring match)starts_with(prefix match)ends_with(suffix match)is_missing(missing property)is_finite(finite numeric value)
NOTE: The "_uniqueid" field supports only the "==", "in", and "not_in" operators.
Constraints for specific properties are defined as key-value pairs, where the key is the name of the property and the value is an array with operators and constraints values. Here is an example:
[{
"FindEntity": {
"with_class": "living",
"constraints": {
"age": [">=", 20, "<=", 90],
"score": ["<=", 75],
"area": ["==", 51]
},
"results": {
"list": ["age"]
}
}
}]
Successful response:
[{
"FindEntity": {
"entities": [{
"age": 20
}, {
"age": 40
}, {
"age": 60
}, {
"age": 80
}],
"returned": 4,
"status": 0
}
}]
The "in" operator expects an array of values to check a given property's value against to find match(es). Please note that the order of entities in the response may differ from the order of terms specified "in" the in clause.
[{
"FindEntity": {
"with_class": "living",
"constraints": {
"age": [">=", 20, "<=", 90],
"score": ["<=", 75],
"area": ["==", 51],
"name": [
"in",
["creature4", "creature6"]
]
},
"results": {
"list": ["name"]
}
}
}]
Successful response:
[{
"FindEntity": {
"entities": [{
"name": "creature4"
}, {
"name": "creature6"
}],
"returned": 2,
"status": 0
}
}]
The default conjunction is "AND".
For instance, in the first case, the constraints will express that the command will retrieve objects where "age" have values between [20,90], AND "score" have a value less or equal to 75, AND "area" have a value equal to 51, AND "name" is equal to either creature5.
An "OR" conjunction can be explicitly specified as follows:
[{
"FindEntity": {
"with_class": "living",
"constraints": {
"any": {
"age": [">=", 20, "<=", 90],
"score": ["<=", 75],
"area": ["==", 51],
"name": [
"in",
["creature3", "creature5"]
]
}
},
"results": {
"list": ["name"]
}
}
}]
Successful response:
[{
"FindEntity": {
"entities": [{
"name": "creature1"
}, {
"name": "creature2"
}, {
"name": "creature3"
}, {
"name": "creature4"
}, {
"name": "creature5"
}, {
"name": "creature6"
}, {
"name": "creature7"
}, {
"name": "creature8"
}, {
"name": "creature9"
}, {
"name": "creature10"
}],
"returned": 10,
"status": 0
}
}]
In a similar manner, and "AND" conjunction can be explicitly specified as follows:
[{
"FindEntity": {
"with_class": "living",
"constraints": {
"all": {
"age": [">=", 20, "<=", 90],
"score": ["<=", 75],
"area": ["==", 51],
"name": [
"in",
["creature2"]
]
}
},
"results": {
"list": ["name"]
}
}
}]
Successful response:
[{
"FindEntity": {
"entities": [{
"name": "creature2"
}],
"returned": 1,
"status": 0
}
}]
When querying for a time property, a "_date" keyword should be used following the syntax:
[{
"FindEntity": {
"with_class": "living",
"constraints": {
"all": {
"dob": [
"==",
{
"_date": "2018-02-27T13:45:12-08:00"
}
]
}
},
"results": {
"list": ["name"]
}
}
}]
Successful response:
[{
"FindEntity": {
"entities": [{
"name": "creature1"
}],
"returned": 1,
"status": 0
}
}]
Example
[{
"FindEntity": {
"with_class": "living",
"constraints": {
"age": [">=", 20, "<=", 90],
"name": [
"in",
["creature1", "creature2", "creature3"]
],
"dob": [
">",
{
"_date": "2018-02-27T13:45:12-08:00"
}
]
},
"results": {
"list": ["name"]
}
}
}]
Successful response:
[{
"FindEntity": {
"entities": [{
"name": "creature2"
}, {
"name": "creature3"
}],
"returned": 2,
"status": 0
}
}]
Array expressions
Constraints also accept expression arrays. all and any take one or
more child expressions directly; not takes exactly one:
["all",
["$status", "==", "active"],
["$usage", "<", "$limit"],
["not", ["$name", "regex", "^temp-"]]
]
$name references a property. To express a literal beginning with $,
add one extra dollar sign: $$USD means the literal $USD. Legacy object
constraint values and membership-list strings are always literal data.
Comparisons support ==, !=, <, <=, >, >=, in, and
not_in. Both operands may reference properties or call scalar functions.
Membership requires a literal candidate list; a null candidate matches a
missing property. ["$name", "is_missing"]
checks for an absent property. Date literals in array expressions use
{"date": "2026-09-13T00:00:00+00:00"}; _date is not accepted in array form.
Existing object constraints and property writes continue to use _date.
Missing values compare equal to null; both missing fields compare equal. Inequality with a non-null value can match a missing field. Ordered comparisons require matching number, string, or date types. Field-pair comparisons involving JSON/blob values do not match, including inequality. String equality and ordering use the existing query collator; string inequality and membership retain the existing binary comparison behavior.
Function calls use a single-key object. Unary functions take one argument; functions with multiple arguments take an array of arguments:
[{"length": {"trim": "$name"}}, ">", 3]
[{"coalesce": ["$usage", 0]}, "<", "$limit"]
["$name", "contains", "report"]
Boolean predicates such as contains, starts_with, ends_with, and
is_finite use operator syntax. Supported functions include length,
lower, upper, trim, ltrim, rtrim, concat, abs,
ceil, floor, add, subtract, multiply, divide, and
coalesce, to_number, to_string, and to_bool.
String and numeric functions operate on UTF-8 text and numeric values. Literal
text comparisons are case-sensitive. concat and coalesce require at
least two arguments. contains, starts_with, ends_with, add,
subtract, multiply, and divide take two arguments; the remaining
functions take one. coalesce returns the first non-null value.
Function arguments have positional types; variadic functions repeat their argument
type. A condition array can be used as a boolean argument to functions that accept
booleans, including coalesce and the converters. Conditions retain the same
comparison, missing-value, and short-circuit all/any/not semantics as
filtering. They are not implicitly converted to strings or numbers:
[{"to_number": ["$usage", "<", "$limit"]}, "==", 1]
[{"concat": ["eligible=", {"to_string": ["$usage", "<", "$limit"]}]}, "==", "eligible=true"]
[{"coalesce": [["$usage", "is_missing"], false]}, "==", true]
The unary converters accept strings, numbers, and booleans:
to_numbermapsfalseto 0 andtrueto 1, preserves numbers, and parses decimal strings with an optional leading minus and decimal exponent. The entire string must parse; whitespace, a leading plus, trailing characters, nonfinite values, and values outside the representable range are invalid.to_stringpreserves strings, formats finite numbers using a locale-independent shortest round-trip representation, and maps booleans to"true"or"false".to_boolpreserves booleans, maps zero to false and other finite numbers to true, and accepts exactly the case-sensitive strings"true"and"false".
All three propagate null or missing values. Dates, JSON objects, blobs, and lists
are not convertible. Invalid conversions produce an invalid value, so a comparison
using that value does not match (including !=); coalesce does not replace
invalid values with its fallback. No implicit scalar conversions are performed.
regex uses RE2 search semantics and is case-sensitive by default. RE2 inline
flags such as (?i) are supported; lookaround and backreferences are not.
like matches the whole string: % matches zero or more code points and
_ matches one. Backslash escapes %, _, or \. Both operators
accept values from literals, fields, or functions:
["$name", "regex", "$pattern"]
["$name", "like", {"concat": ["$prefix", "%"]}]
The expression language supports nested conditions and composition with
all, any, and not. Missing values compare equal to null when the
comparison is ==; not reverses the final result for that child
expression.
Node and connection filters share this language, including nested connection
constraints in is_connected_to and is_endpoint_of, and conditional-add
filters in if_not_found. Indexed property/literal comparisons
keep using native indexes; field pairs, functions, negation, and general
patterns may require evaluating candidate records.
Pattern compilation checks for server abort requests and client disconnections.