Filter events

Required capabilities: eventsAcl:READ

Retrieve a list of events in the same project. This operation supports pagination by cursor. Apply Filtering and Advanced filtering criteria to select a subset of events.

Advanced filtering

Advanced filter lets you create complex filtering expressions that combine simple operations, such as equals, prefix, exists, etc., using boolean operators and, or, and not. It applies to basic fields as well as metadata.

See the advancedFilter attribute in the example.

See more information about filtering DSL here.

Supported leaf filters

Search

The search leaf filter provides functional parity with the /events/search endpoint. It’s available only for the ["description"] field. When specifying only this filter with no explicit ordering, behavior is the same as of the /events/search/ endpoint without specifying filters. Explicit sorting overrides the default ordering by relevance. It’s possible to use the search leaf filter as any other leaf filter for creating complex queries.

See the search filter in the advancedFilter attribute in the example.

advancedFilter attribute limits

• filter query max depth: 10
• filter query max number of clauses: 100
• filter by metadata is case-insensitive, and it supports filtering on keys and values up to 256 characters
• and and or clauses must have at least one element
• property array of each leaf filter has the following limitations:
  • number of elements in the array is in the range [1, 2]
  • elements must not be blank
  • each element max length is 128 symbols
  • property array must match one of the existing properties (static or dynamic metadata)
• containsAll, containsAny, and in filter values array size must be in the range [1, 100]
• containsAll, containsAny, and in filter values array must contain elements of a primitive type (number, string)
• range filter must have at least one of gt, gte, lt, lte attributes. But gt is mutually exclusive to gte, while lt is mutually exclusive to lte. For metadata, both upper and lower bounds must be specified.
• gt, gte, lt, lte in the range filter must be a primitive value
• search filter value must not be blank and the length must be in the range [1, 128]
• filter query may have maximum 2 search leaf filters
• maximum leaf filter string value length is different depending on the property the filter is using:
  • externalId - 255
  • description - 128 for the search filter and 255 for other filters
  • type - 64
  • subtype - 64
  • source - 128
  • any metadata key - 128

Sorting

By default, events are sorted by their creation time in the ascending order. Use the search leaf filter to sort the results by relevance. Sorting by other fields can be explicitly requested. The order field is optional and defaults to desc for _score_ and asc for all other fields. The nulls field is optional and defaults to auto. auto is translated to last for the asc order and to first for the desc order by the service. Partitions are done independently of sorting: there’s no guarantee of the sort order between elements from different partitions.

See the sort attribute in the example.

Null values

In case the nulls attribute has the auto value or the attribute isn’t specified, null (missing) values are considered to be bigger than any other values. They are placed last when sorting in the asc order and first when sorting in desc. Otherwise, missing values are placed according to the nulls attribute (last or first), and their placement doesn’t depend on the order value. Values, such as empty strings, aren’t considered as nulls.

Sorting by score

Use a special sort property _score_ when sorting by relevance. The more filters a particular event matches, the higher its score is. This can be useful, for example, when building UIs. Let’s assume we want exact matches to be be displayed above matches by prefix as in the request below. An event with the type fire will match both equals and prefix filters and, therefore, have higher score than events with names like fire training that match only the prefix filter.

"advancedFilter" : {
  "or" : [
    {
      "equals": {
        "property": ["type"],
        "value": "fire"
      }
    },
    {
      "prefix": {
        "property": ["type"],
        "value": "fire"
      }
    }
  ]
},
"sort": [
  {
    "property" : ["_score_"]
  }
]

Request throttling

This endpoint is meant for data analytics/exploration usage and is not suitable for high load data retrieval usage. It is a subject of the new throttling schema (limited request rate and concurrency). Please check Events resource description for more information.