Entity filter syntax

Overview

The document outlines the Entity filter syntax in the Gateway Hub REST API.

Filter Syntax

Entities represent something being monitored, and they possess attributes. Attributes are a collection of key / value pairs.

Attribute keys are:

  • Namespaced to avoid conflicts between:
    • ITRS defined attributes — itrs.* namespace.
    • User defined attributes — user.* namespace.
    • Integration defined attributes — namespace per integration, for example servicenow.*.
  • Case sensitive.

Entity information can be accessed using the /entities/... endpoint.

The GET /entities and GET /entities/summary endpoints can apply a filter on entity attributes based on the following syntax:

  • Values can be compared against a single value (using lexicographic comparison):
    OperatorDefinitionExample
    =Equalitrs.os-type = Linux
    !=Not equalitrs.os-type != Linux
    >Greater thanuser.yearCreated > 2018
    >=Greater than or equal touser.yearCreated >= 2018
    <Less thanuser.yearCreated < 2018
    <=Less than or equal touser.yearCreated <= 2018
  • Values can be compared against a set of values:
    OperatorDefinitionExample
    INIn

    user.department IN (eq, fx)

    NOT INNot In

    user.department NOT IN (eq, fx)

  • Attributes can be tested for existence (attributes containing empty strings are treated as if the attribute does not exist):
    OperatorDefinitionExample
    EXISTSExists

    user.department EXISTS

    NOT EXISTSDoes not exist

    user.department NOT EXISTS

  • Filters can be combined with boolean logic:
    OperatorDefinitionExample
    ANDX and Y

    itrs.os-type = Linux AND user.department = fx

    ORX or Y

    user.department = eq OR user.department = fx

    • Parentheses are also supported. For example, (user.department = eq OR user.department = fx) AND itrs.os-type = Linux.

When using the filter syntax, the following rules apply to attribute names and values:

  • Quotes (") or backslashes (\) must be escaped. For example, "user.department \"name\"" = "Equity \"Derivatives\"" and "user.department\\name" = "Equity\\Derivatives".
  • Characters other than 0-9, a-z, A-Z, or . must be surrounded by quotes. For example:
    • Names with spaces — "user.data centre" = "Telehouse Docklands".
    • Names with non-English characters — "user.数据中心" = "上海".