The data item filter is a query string that is optionally available on the Get All Data Items endpoint. Its purpose is to allow you to limit which items you get from the Data API. This section covers its syntax and limitations.
The central component of the item filter expression is the comparison. By itself, a comparison is the simplest valid filter. All comparisons are strictly of the form fieldname -> operator -> constant. Note that the order is important; the field name must be on the left side and the constant must be on the right. A simple example of a comparison would be the filter name = "James", which will limit the results to only items where the field name has the value "James". If you wish to do a numeric comparison instead, you could use a filter like age > 21. Note that string constants are wrapped in quotes, while numeric constants are not.
Fields
If the name of the field you are filtering on contains spaces or other special characters, you can wrap the field name in any of the three simple quotation marks: " or ' or `. Thus the string "full name" = "John Smith" is a valid comparison for the field full name. If the field name includes quotes, you may either wrap the field name using one of the other quote characters (preferred) or you can escape the quote marks inside the field name by doubling them. For instance, you can represent the field name "I can't even" as either "I can't even" or 'I can''t even'.
Operators
There are 8 operators you can use in your comparisons:
| Operator | Valid Constant Type | Notes |
|---|---|---|
| = | String, Number | Equality works well with strings and with integer numbers. Floating-point numbers here and in general have difficulties with equality. This is a very involved problem, so if you are having trouble with it we suggest looking up specialized resources elsewhere. |
| != | String, Number | Note that = and != are only inverses over field values which are considered comparable to the constant, as outlined in the section below. |
| > | String, Number | |
| > = | String, Number | |
| < | String, Number | |
| <= | String, Number | |
| IN | String, Number, Array[String] | If the constant is either a string or number, it is treated as an array of strings or numbers that has a single element. |
| CONTAINS | String, Number | The data item will be split by comma seperator, and checked to see if any one of the children is the same as the constant. |
All string comparisons are case-insensitive.
Comparisons and Type Coercion
For all operators, the value of the field must be considered comparable with the constant in order for the result to be true. For instance, when the constant is a number, the fields are coerced to a number before the comparison is performed. If the field cannot be coerced to a number, the result of the comparison is false. This means, for instance, that a field with value "0.0" is equal to the numeric constant 0 but not the string constant "0". This also means that a field with value "a" will return false for both "a" = 0 and "a" != 0 because "a" cannot be coerced to a number. Similarly, if the constant is an array of strings, the comparison can evaluate to true only if the operator involved is IN; all other operators combined with an array constant are automatically false.
Constants
A constant can be either a quoted string, a number, or an array of strings.
A constant is a string if the constant is wrapped in any of the simple quotation marks (" or ' or `). As with field names, to include quotation marks inside a quoted string, you can either use a different quote symbol or escape the quotation marks by doubling them in every desired location inside the string.
A constant is a number if it is not quoted, not inside parentheses, and can be parsed as a valid floating point number in Java.
A constant is an array of strings if it is a comma-separated list of strings wrapped inside a pair of parentheses. Arrays only evaluate when using the IN operator; any other operator used with an array of strings automatically evaluates to false. An example of a comparison using an array of strings is "name IN ("Peter", "Paul", "Mary")"; this will evaluate to true only if the name is one of "Peter", "Paul", or "Mary".
Compound filters
Compound filters can be created from comparisons using the AND, OR and NOT operators, as outlined in the following table. You can use parentheses to group operations if the default precedence is not what you need.
| Operator | Precedence | Effect |
|---|---|---|
| NOT | Highest | Invert the result of the filter immediately after this operator |
| AND | Medium | The compound filter is only true if the filters before and after this operator are both true |
| OR | Lowest | True if either the filter before or after this operator is true |
For example, if you want a match for all items with names that are not "Thomas" or "Susan", you could use the compound filter NOT name IN ("Thomas", "Susan"). If you want people whose age is either less than 8 or greater than 10, you could use the compound filter age < 8 OR age > 10. If you only want people with first name "Chris" and whose last name is neither "Smith" nor "Wesson", you could use the compound filter first_name = "Chris" AND NOT last_name IN ("Smith", "Wesson").
For a more complex example of compound filters and their precedences, consider the following filter:
age > 21 AND NOT last_name in ("Smith", "Wesson") OR as_adult = "true"
This filter will return every item from the collection that has the field as_adult set to the value "true". It will also return every item which has an age greater than 21 and whose last_name is not either "Smith" or "Wesson". If there are any items which satisfy both of these conditions, they will be included in the results, but only once. This is equivalent to the filter:
((age > 21 AND (NOT last_name in ("Smith", "Wesson"))) OR as_adult = "true")
but different from the filter:
age > 21 AND (NOT last_name in ("Smith", "Wesson") OR as_adult = "true")
This last filter will only return items which have an age greater than 21, but only if they have as_adult equal to "true" or if their last_name is anything besides "Smith" or "Wesson".
Full filter syntax
filter = comparison | composite filter
comparison = fieldname operator constant
fieldname = identifier | quotedstring
identifier = a sequence of non-whitespace chars
quotedstring = ("|'|``)<Any string with escaped quotes>("|'|``) (both of the outer quotes must be the same symbol)
operator = '=' | '!=' | '>' | '>=' | '<' | '<=' | 'IN'
constant = stringconstant | numberconstant | stringarray
stringconstant = quotedstring
numberconstant = any non-quoted string (without whitespace) that Java parses as a valid double
stringarray = '(' stringconstant [, stringconstant... ] ')'
composite filter = notfilter | andfilter | orfilter
notfilter = 'NOT' filter
andfilter = filter 'AND' filter
orfilter = filter 'OR' filter