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 "john.doe@example.com" and
(published ge "2020-11-01" and
published lt "2020-12-01")

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.

Was this article helpful?

1 out of 1 found this helpful

Comments

0 comments

Please sign in to leave a comment.