Filtering
Filter expressions refine data queries for some API listing endpoints, as notated in the individual API documentation.
To create a filter expression, you will write one or more expressions. Each expression has a matching operators composed with selectors and values.
Filtering is executed on the Consul server, before data is returned, reducing the network load. To pass a
filter expression to Consul, use the filter
query parameter when sending requests to HTTP API endpoints that support it.
Creating Expressions
A single expression is a matching operator with a selector and value. They are written in plain text format, 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.
Selectors
Selectors are used by matching operators to create an expression. They are
defined by a .
separated list of names. Each name must start with
a an ASCII letter and can contain ASCII letters, numbers, and underscores. When
part of the selector references a map value it may be expressed using the form
["<map key name>"]
instead of .<map key name>
. This allows the possibility
of using map keys that are not valid selectors in and of themselves.
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
Standard operator precedence can be expected for the various forms. For example, the following two expressions would be equivalent.
Filter Utilization
Generally, only the main object is filtered. When filtering for
an item within an array that is not at the top level, the entire array that contains the item
will be returned. This is usually the outermost object of a response,
but in some cases such the /catalog/node/:node
endpoint the filtering is performed on a object embedded within the results.
Performance
Filters are executed on the servers and therefore will consume some amount of CPU time on the server. For non-stale queries this means that the filter is executed on the leader.
Filtering Examples
Agent API
Command - Unfiltered
Response - Unfiltered
Command - Filtered
Response - Filtered
Catalog API
Command - Unfiltered
Response - Unfiltered
Command - Filtered
Response - Filtered
Health API
Command - Unfiltered
Response - Unfiltered
Command - Filtered
Response - Filtered