Some API end-points allow you to specify a filter for the data returned. This helps you limit the data you request to exactly what you need.
The filter expression language is based around the SCIM filtering specification. Despite the name, it also applies to some non-SCIM Trelica API end-points such as the audit log, which we will use in our examples on this page.
Filters consist of one or more expressions, where an expression contains an attribute name, followed by an attribute operator and an optional value. Multiple expressions can be combined using logical operators like "and", "or", "not" etc. Finally, parentheses can be used as grouping operators to control precedence.
Attribute names are attributes in the JSON structure returned. Attributes can use "dot" notation to denote child attributes, e.g. in the following example from the audit log, published
would be the attribute name for the date the log entry occurred, and client.ipAddress
would be the attribute name for the associated IP address:
{
"id": "1732bc2d72394452cad708d89c875b10",
"published": "2020-12-10T01:01:50.3043104",
"eventType": "user_created",
"client": {
"ipAddress": "152.212.154.123"
}
}
Operators are described in more detail below, but are short, text representations of the common symbols, so "eq" means equals, "ne" means "not equals" etc.
Values are either:
- Strings (wrapped in double quotes)
- Integer numbers
- Dates (strings, so wrapped in double quotes, formatted to RFC 3339 which is essentially ISO 8601 format, e.g. 2020-12-25T10:50:00)
- Boolean (true or false)
Examples
Filters are passed using the filter
query string parameter, and should be URL encoded. For the purposes of clarity, we won't encode the strings in our examples.
Filter parameter | Result |
---|---|
eventType eq "user_created" |
Just "User created" events |
client.ipAddress pr |
Events with an IP addresses |
|
Events triggered by john.doe during November 2020 |
filter=teams[name co "Sub-contractors"] |
All people in teams with 'Sub-contractors' in the name |
Operators
Operator | Description | Behavior |
---|---|---|
eq | equal | The attribute value is identical to the operator value |
ne | not equal | The attribute value and the operator value are not identical |
co | contains | The attribute value contains the operator value text |
sw | starts with | The attribute value starts with the operator value text |
ew | ends with | The attribute value ends with the operator value text |
pr | present (has value) | The attribute has a non-empty or non-null value, or it contains a non-empty node |
gt | greater than | The attribute value is greater than the operator value |
lt | less than | The attribute value is less than the operator value. |
ge | greater than or equal to | The attribute value is greater than or equal to the operator value |
le | less than or equal to | The attribute value is less than or equal to the operator value |
For greater than / less than type operators (i.e. gt
, lt
, ge
, le
), the comparison depends on the attribute type: for strings, there is a lexicographical comparison (i.e. B is greater than A); for date/time types it is chronological; for integer attribute values it is by numeric value.
Comments
0 comments
Please sign in to leave a comment.