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)ilike(case-insensitive pattern match; array expressions only)regex(regular expression match)contains(substring match)icontains(case-insensitive substring match; array expressions only)starts_with(prefix match)istarts_with(case-insensitive prefix match; array expressions only)ends_with(suffix match)iends_with(case-insensitive suffix match; array expressions only)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 unless a case-insensitive operator is used
(see below). 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.
like, regex, contains, starts_with, ends_with, and their
case-insensitive variants require string operands: a literal, a property
reference, or a function that returns a string. A literal number or boolean, or
a numeric function such as length, is rejected when the query is parsed.
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", "%"]}]
ilike, icontains, istarts_with, and iends_with are
case-insensitive versions of like, contains, starts_with, and
ends_with. Both operands are compared after Unicode full case folding, so
"Straße" matches "STRASSE" and "Café" matches "CAFÉ". This is
more thorough than comparing lower or upper results, which do not fold
characters such as ß to ss. In ilike, % and _ apply to the
folded text, so a pattern wildcard may match a different number of code points
than appear in the stored value. The right operand may be a literal, a
property reference, or a function; a null operand never matches. These
operators are available only in array expressions:
[{
"FindEntity": {
"with_class": "living",
"constraints": ["$name", "ilike", "CREATURE1%"],
"results": {
"list": ["name"],
"sort": "name"
}
}
}]
Successful response:
[{
"FindEntity": {
"entities": [{
"name": "creature1"
}, {
"name": "creature10"
}],
"returned": 2,
"status": 0
}
}]
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.