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 or equal than)
- "==" (equal to)
- "!=" (different than)
- ">" (greater than)
- ">=" (greater or equal than)
- "in" (is in)
- "not in" (is not in)
NOTE: Only the "==", "in", and "not in" operators are supported for "_uniqueid".
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), as follows:
[{
"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 {"creature3", "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
}
}]
Tip: Given our current lack of query optimizer and as the constraints are specified as a JSON object instead of array (which leaves ordering unknown when parsing), we have introduced a way to attach monotonically increasing order from 0-n to the constraints based on user's knowledge of which property can reduce the result set the most (see example below). When using the option of giving order to constraints, please choose the first property constraint carefully in order to restrict the most number of entity/connection returns since that one is potentially applied on an existing index. The other constraints are applied sequentially on the returned result set. If no ordering is specified, the property constraints are applied in an undetermined order.
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
}
}]