Filtering
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
actor.alternateId eq "[email protected]" and (published ge "2020-11-01" and published lt "2020-12-01")
Events triggered by john.doe during November 2020

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.
​
Last modified 28d ago
Copy link
Outline
Examples
Operators