Filtering

Filter expressions can be used by various parts of Boundary to provide useful functionality. This page describes the overall syntax; see the sub-pages for information on the specific values available for filtering for various features, including examples.

Each filter expression has matching operators composed with selectors and values.

Creating Expressions

A single expression is a matching operator with a selector and value. They are written in plain text format, and Boolean logic and parenthesization are supported. In general whitespace is ignored, except within literal strings.

Matching Operators

All matching operators use a selector or value to choose what data should be matched. Each endpoint that supports filtering accepts a potentially different list of selectors and is detailed in the API documentation for those endpoints.

  1. // Equality & Inequality checks
  2. <Selector> == "<Value>"
  3. <Selector> != "<Value>"
  5. // Emptiness checks
  6. <Selector> is empty
  7. <Selector> is not empty
  9. // Contains checks or Substring Matching
  10. "<Value>" in <Selector>
  11. "<Value>" not in <Selector>
  12. <Selector> contains "<Value>"
  13. <Selector> not contains "<Value>"
  15. // Regular Expression Matching
  16. <Selector> matches "<Value>"
  17. <Selector> not matches "<Value>"
  1. // Equality & Inequality checks<Selector> == "<Value>"<Selector> != "<Value>"
  2. // Emptiness checks<Selector> is empty<Selector> is not empty
  3. // Contains checks or Substring Matching"<Value>" in <Selector>"<Value>" not in <Selector><Selector> contains "<Value>"<Selector> not contains "<Value>"
  4. // Regular Expression Matching<Selector> matches "<Value>"<Selector> not matches "<Value>"

Selectors

Selectors are used by matching operators to create an expression. Inputs to filter expressions are JSON (or JSON-derived); selectors therefore use JSON Pointer to select values from the input. Each selector must be enclosed in quotes and contain a valid JSON Pointer path, including leading slash (/).

  1. // Selects the value `zipzap` from the input `{ "foo": { "bar": "zipzap" } }`
  2. "/foo/bar"
  1. // Selects the value `zipzap` from the input `{ "foo": { "bar": "zipzap" } }`"/foo/bar"

Values

Values are used by matching operators to create an expression. Values can be any valid selector, a number, or a string. It is best practice to quote values.

Numbers can be base 10 integers or floating point numbers.

When quoting strings, they may either be enclosed in double quotes or backticks. When enclosed in backticks they are treated as raw strings and escape sequences such as \n will not be expanded.

Connecting Expressions

There are several methods for connecting expressions, including

  • Logical or
  • Logical and
  • Logical not
  • Grouping with parenthesis
  • Matching expressions
  1. // Logical Or - evaluates to true if either sub-expression does
  2. <Expression 1> or <Expression 2>
  4. // Logical And - evaluates to true if both sub-expressions do
  5. <Expression 1 > and <Expression 2>
  7. // Logical Not - evaluates to true if the sub-expression does not
  8. not <Expression 1>
  10. // Grouping - Overrides normal precedence rules
  11. ( <Expression 1> )
  13. // Inspects data to check for a match
  14. <Matching Expression 1>
  1. // Logical Or - evaluates to true if either sub-expression does<Expression 1> or <Expression 2>
  2. // Logical And - evaluates to true if both sub-expressions do<Expression 1 > and <Expression 2>
  3. // Logical Not - evaluates to true if the sub-expression does notnot <Expression 1>
  4. // Grouping - Overrides normal precedence rules( <Expression 1> )
  5. // Inspects data to check for a match<Matching Expression 1>

Standard operator precedence can be expected for the various forms. For example, the following two expressions would be equivalent.

  1. <Expression 1> and not <Expression 2> or <Expression 3>
  3. ( <Expression 1> and (not <Expression 2> )) or <Expression 3>
  1. <Expression 1> and not <Expression 2> or <Expression 3>
  2. ( <Expression 1> and (not <Expression 2> )) or <Expression 3>

Performance

Filters are executed on the controllers and therefore will consume some amount of CPU time on the controller.