Filtering
Utilize filters to query your data on supported endpoints.
Preface
On endpoints where filtering is supported, we use a restricted subset of the AIP-160 Filtering syntax, and each endpoint must document what it does and does not support.
The filters used in these examples are for illustration purposes only and may not represent the actual supported filters or comparators.
Search syntax
The following table describes the syntax tokens used to construct filter queries.
| Token | Usage | Description | Examples |
|---|---|---|---|
“” | “string” | A string literal; can contain whitespace and special characters. To include a " character inside the string, escape using \. | "#1 Rated Tax App”, "Made it on the \"Inc 500\" list of fastest-growing startups!" |
| Any text excluding whitespace and other tokens used in the syntax | text | When used as a comparand, represents the field being compared. When used as an argument, it will be parsed to the comparand’s data type. | status, CLAIMED |
Numbers. Use . for decimals. | 123 | A numeric value. | 1337, 399.99 |
AND (case sensitive) | field1=value1 AND field2=value2 | The query returns records that match both clauses. | status="CLAIMED" AND total_amount > 500 |
OR (case sensitive) | field=value1 OR field=value2 | The query returns records that match either of the clauses. | status="CLAIMED" OR status="CLOSED" |
(, ) | (a AND b) OR c | Grouping delimiters. They are used to group logical expressions together and can be used to manually set the logical operator precedence. | (modified_time > "2020-01-01" AND last_login_time > "2020-01-01") OR inactive = true — the () are used to group the AND clauses together. |
. (dot/period) | composite.scalar | Traversal operator, used for traversing into structures and lists. | user.email, members.user.id |
=, !=, >, >=, <, <=, : | field=value | Comparators; see the next section for details. | See next section |
Comparators (a.k.a comparison operators)
The following table describes all comparators supported by the filtering syntax. Surrounding whitespace is optional. Note that not every field in every API supports every comparator. The documentation for each endpoint should enumerate the fields that can be filtered as well as their supported comparators.
| Comparator | Usage | Description | Examples |
|---|---|---|---|
= | field=value | Equality. | user.email = "john@example.com" |
!= | field!=value | Inequality. | status != CLAIMED |
> | field > value | Greater than. | total_amount > 100 |
>= | field >= value | Greater than or equal. | create_time >= "2022-01-01" |
< | field < value | Less than. | total_amount < 100 |
<= | field <= value | Less than or equal. | create_time <= "2022-01-01" |
: | field:value | “Has”. Special operator used for lists. See the section on the Has Operator for details. | members.type:CLIENT |
Comparisons
The simplest form of a filter is a single comparison. A comparison takes a comparand (a field), a comparator, and an argument (what the comparand is being compared against).
Example 1
List records where the email field equals john@test.com.
Copied1email = "john@test.com"
The comparand is email, using the equality comparator (=) and a string argument of "john@test.com".
Logical operators (AND/ OR)
Some endpoints may support combining comparisons using the logical operators AND / OR and will document which they support if any at all.
To match common patterns of speech, the OR operator has higher precedence than AND, unlike what is found in most programming languages. The expression a AND b OR c evaluates to a AND (b OR c).
You can use ( and ) to specify the grouping yourself.
Example 1
List inactive members in the Workspace with id 9.
Copied1inactive = true AND workspace_id = 9
We are using an AND to combine two comparisons; both of these must be satisfied.
Example 2
List jobs that are either CLAIMED or CLOSED:
Copied1status = "CLAIMED" OR status = CLOSED
We are using an OR to check for either status. The quotation marks are optional as long as there are no whitespace or special characters in the comparison argument.
Example 3
List jobs that are either CLAIMED or CLOSED with a total amount greater than or equal to 299.99 that was created before or on new years in 2022 (newlines for brevity):
Copied1total_amount >= 299.992AND status = "CLAIMED" OR status = "CLOSED"3AND create_time <= "2022-12-31"
This example illustrates the precedence of the OR operator. With explicit () groupings, the example would have looked like this:
Copied1total_amount >= 299.992AND (status = "CLAIMED" OR status = "CLOSED")3AND create_time <= "2022-12-31"
Traversal Operator
The . operator, called the traversal operator, is used to traverse nested fields.
Example 1
Lists members where the user object’s email field is john@test.com
Copied1user.email = "john@test.com"
Has Operator
The Has operator is a special operator used for checking whether a list contains an element and must not be used for non-list elements.
The AIP prescribes the Has operator for checking the presence of fields in a structure. As of this time, we only implement the Has operator for checking for items in lists.
Example
List jobs where the user with ID b8cce4be-b6ee-4198-9d56-174b217671b8 is a collaborator.
Copied1members.user_id:"b8cce4be-b6ee-4198-9d56-174b217671b8"
We are using the . (traversal) operator to enter the members list and check if any of the members’ user_id equals the given value. In other words, the filter will return true for a job if members contains an element e such that e.user_id = "b8cce4be-b6ee-4198-9d56-174b217671b8"