Advanced Search Overview
A search filter is a tree structure, where each node is either a group or a constraint.
A constraint node takes the form:
{
type: 'constraint',
id: string,
operator: string,
inverted: boolean,
value: mixed,
}A group node takes the form:
{
type: 'group',
operator: 'and'|'or',
inverted: boolean,
conditions: [...node],
}The condition nodes in a group can be either constraints or other group nodes.
Data Types and Operators
The search system recognizes a handful of data types for search criteria, and the operators that can be used are specitic to the
data type. Additionally, the form of the value depends on the data type and operator.
text
This table shows the operators and value shapes allowed on text-type criteria
| Operator | Value | Description |
|---|---|---|
| contains | string | Matches if the value is a substring of the field. |
| contains_like | string | Matches if the field contains the value, where space characters are interpreted as wild cards. |
| does_not_contain | string | Matches if the value is not a substring of the field. |
| does_not_contain_like | string | Matches if the field does not contain the value, where space characters are interpreted as wild cards. |
| ends_with | string | Matches if the field ends with the value. |
| equal | string | Matches if the field and the value are exactly equal. |
| in | [string] | Matches if the field is exactly equal to one or more of the items in the value array. |
| is_not_set | none | Matches if the field does not have a value. |
| is_set | none | Matches if the field has a value. |
| like | string | Matches if the field is like the value, where '%' characters are interpreted as wild cards. |
| not_equal | string | Matches if the field and the value are not exactly equal. |
| not_in | [string] | Matches if the field is not exactly equal to any of the items in the value array. |
| not_like | string | Matches if the field is not like the value, where '%' characters are interpreted as wild cards. |
| starts_with | string | Matches if the field starts with the value. |
| word_boundary | string | Matches if the field contains the value at a word boundary (beginning of the field or a non-space character after a space). |
date
Value Types
A date string is a string in the format yyyy-mm-dd
A relative range object has the shape:
{
period: "day"\|"week"\|"month"\|"quarter\|"year",
units: integer,
anniversary: boolean,
}A range object has the shape:
{
lbound: date string,
ubound: date string,
}If anniversary is true, rather than comparing the actual date, only the month and day of the date will be used in the
comparison.
This table shows the operators and value shapes allowed on date-type criteria
| Operator | Value | Description |
|---|---|---|
| between | range | Matches if the field is in the range [lbound, ubound]. |
| equal | date string | Matches if the field and the value are exactly equal. |
| greater_than | date string | Matches if the value is greater than the field. |
| greater_than_or_equal | date string | Matches if the value is greater than or equal to the field. |
| in | [date string] | Matches if the field is equal to one or more of the items in the value array. |
| in_the_last | relative range | Matches if the field is in the previous relative range. |
| in_the_next | relative range | Matches if the field is in the upcoming relative range. |
| is_not_set | none | Matches if the field is empty. |
| is_set | none | Matches if the field is not empty. |
| less_than | date string | Matches if the value is less than the field. |
| less_than_or_equal | date string | Matches if the value is less than or equal to the field. |
| not_equal | date string | Matches if the field and the value are not equal. |
| not_in | [date string] | Matches if the field is not equal to any of the items in the value array. |
| not_in_the_last | relative range | Matches if the field is not in the previous relative range. |
| not_in_the_next | relative range | Matches if the field is not in the upcoming relative range. |
date_parts
Date parts is like the date type, however you can do comparisons on the parts of a date, year, month, and day, for the following operators:
- equal
- not_equal
- less_than
- less_than_or_equal
- greater_than
- greater_than_or_equal
The value should take the form:
{
year: number,
month: number,
day: number
}Each of which is optional
number
Value Types
A range object has the shape:
{
lbound: number,
ubound: number,
}This table shows the operators and value shapes allowed on number criteria
| Operator | Value | Description |
|---|---|---|
| equal | number | Matches if the field is exactly equal to the value. |
| not_equal | number | Matches if the field is not equal to the value. |
| less_than | number | Matches if the field is less than the value. |
| less_than_or_equal | number | Matches if the field is less than or equal to the value. |
| greater_than | number | Matches if the field is greater than the value. |
| greater_than_or_equal | number | Matches if the field is greater than or equal to the value. |
| between | range | Matches if the field is between the bounds of the range. |
| is_set | none | Matches if the field is not empty. |
| is_not_set | none | Matches if the field is empty. |
| in | [number] | Matches if the field is equal to one of the items in the value array. |
| not_in | [number] | Matches if the field is not equal to any of the items in the value array. |
currency
The currency type is like the number type, except that the number is in cents, so is multiplied by 100 before the comparison
takes place
time
This data type has all the same operators as number, except that it operates on the time portion of timestamps, rather than
numbers.
boolean
This table shows the operators and value shapes allowed on boolean criteria
| Operator | Value | Description |
|---|---|---|
| is_set | none | Matches if the field is exactly '1'. |
| is_not_set | none | Matches if the field is not '1'. |
boolean_strict
The boolean-strict type is like boolean, except that a field will be '1' if it is true, and '0' if it is false. Compared to the boolean field, where '1' means true and anything else means false.
| Operator | Value | Description |
|---|---|---|
| is_set | none | matches if the field is exactly 1 |
| is_not_set | none | matches if the field is exactly '0' |
| unknown | none | matches if the field is not '1' or '0' |
Examples
Here are a few examples of filters and their meaning:
A simple comparison
// All individuals with the first name "Tom"
{
"type": "constraint",
"id": "first_name",
"operator": "equal",
"value: "Tom",
"inverted": false,
}A grouped comparison
// All individuals who are male and are over 20
{
"type": "group",
"operator": "and",
"inverted": false,
"conditions": [
{
"type": "constraint",
"id": "gender",
"operator": "equal",
"value": "m",
"inverted": false,
},
{
"type": "constraint",
"id": "age",
"operator": "greater_than"
"value": 20,
"inverted": false,
},
],
}A more complex grouped comparison
// All individuals who are male and over 20, or who are named Tom
{
"type": "group",
"operator": "or",
"inverted": false,
"conditions": [
{
"type": "constraint",
"id": "name_first",
"operator": "equal",
"value": "Tom",
"inverted": false,
},
{
"type": "group",
"operator": "and",
"inverted": false,
"conditions": [
{
"type": "constraint",
"id": "gender",
"operator": "equal",
"value": "m",
"inverted": false,
},
{
"type": "constraint",
"id": "age",
"operator": "greater_than"
"value": 20,
"inverted": false,
},
],
}
],
}