Some of the ROAD Service's REST APIs allow filtering at queries being sent via GET command's parameter fields. Currently the described filtering is supported by these interfaces: categories, jobs, schedules, templates. The actual fields being supported for each interface is described there or in the related Data Types documentation.

This new syntax is supported from ROAD version 1.0.238.0 (May 2020).

The REST GET interface (and some others where this is documented) supports the parameter filter with the following specification.

Syntax specification

General

The syntax is similar to the one in usual programming languages like C++. As the '&' character is reserved for the REST parameter command line, we replace it by 'AND' and to be consistent replace '|' by 'OR' and '!' by 'NOT'.

A query term must describe at least one data field, comparator and value to be compared. So it is a condition consisting of one or several connected comparisons.

Examples

filter = name == "Recording Studio 21"
filter = field1 < 77 OR NOT(field2 == "my job" AND field3 <= "2020-02-20T16:11:48")
filter = name ==~ "MY JOB" OR template.name ~ "([A-Z])\w+"

Expression terms

General

Expression part separation: Each part of an expression must be separated from the ones before and after. This separation is either the beginning and end of the whole expression, a whitespace (outside string) or another separation character (all non-alphanumeric characters except . - ). Operators end by such a separator, which may not be another operator to allow operators like <=.

Quotes enclose a part, even if it contains separators. This doesn't necessarily mean a string, it can also enclose a weird field name or a non-string value.

(Not implemented yet: Escaping characters is supported as usual with a leading backslash.)

Description

The full content of the REST parameter 'filter' must be an expression term, which meets this specification.

  • It is a condition.
  • A condition is a tree described by sub-conditions, which are combined by 'AND', 'OR', 'NOT' and reasonably placed and nested round braces.
    • Where there are no brackets, the conditions are evaluated left to right.
    • The inversion operator 'NOT' can be before an opening brace or it refers to the subsequent comparison.
    • Functions are followed by a bracket pair, which contains comma-separated parameters. Depending on the function there's an expected count of parameters.
  • On bottom level a condition consists of
    • field name (fields of sub-objects are specified by the dot syntax)
    • comparison operator
    • for binary operators, a second operand

Comparison Operators

  • Binary standard comparators
    • <, <=, ==, !=, >=, > Usual comparison, independent from field type
  • Binary operators for case-insensitive comparison of text fields
    • ==~  A text field's content must match with the given value case-insensitively
    • !=~  A text field's content must not match with the given value case-insensitively
  • Binary operators for regular expression
    • ~  A text field's content must match with the given regular expression (see below)
    • !~  A text field's content must not match with the given regular expression (see below)

Functions

  • regex(field, expression): Evaluates a regular expression on the specified field confirming the syntax of the Perl Compatible Regular Expression (PCRE) library, which is used by the MongoDB database engine.
  • (Not implemented yet: unary: 'exists' to check if a field is existing)

Operands

  • Operands are fix values. (Special values like @now may be added later.)
  • They are either a complete word (so not containing any separator) or enclosed in quotes.
  • Recommendation: Put all operands into quotes, so any value will be interpreted correctly, regardless of containing spaces, colons (as a DateTime) or other reserved characters.
  • They are type-less, meaning they are interpreted as the requested type. If this fails, an error will be returned.
  • DateTime values are always interpreted as UTC values (as DateTimes are also returned to queries in UTC). Out of query expressions one exception to this principle is the schedules' pending interface, where the clientTimeZone parameter is interpreted in the schedule's specific time zone.
  • (Not implemented yet, but later this could mean special interpretations depending on context (e.g. "startTime < 2020-04-17" would mean 0:00 time and "startTime > 2020-04-17" would mean 23:59:59))

Legacy Syntax Support Dropped

Old syntax (like field1:blabla, field2:blubb) is not supported any more.