diff --git a/website/pages/api-docs/features/filtering.mdx b/website/pages/api-docs/features/filtering.mdx index 96344b7bf9..6b189b596a 100644 --- a/website/pages/api-docs/features/filtering.mdx +++ b/website/pages/api-docs/features/filtering.mdx @@ -9,83 +9,48 @@ description: |- # Filtering -A filter expression is used to refine a data query for some API listing endpoints as notated in the individual API documentation. -Filtering will be executed on the Consul server before data is returned, reducing the network load. To pass a -filter expression to Consul, with a data query, use the `filter` parameter. +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. ```shell -curl -G --data-urlencode 'filter=' +curl --get --data-urlencode 'filter=""' ``` -To create a filter expression, you will write one or more expressions using matching operators, 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. -## Expression Syntax +## Creating Expressions -Expressions are written in plain text format. Boolean logic and parenthesization are +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. -### Expressions - -There are several methods for connecting expressions, including - -- logical `or` -- logical `and` -- logical `not` -- grouping with parenthesis -- matching expressions - -```text -// Logical Or - evaluates to true if either sub-expression does - or - -// Logical And - evaluates to true if both sub-expressions do - and - -// Logical Not - evaluates to true if the sub-expression does not -not - -// Grouping - Overrides normal precedence rules -( ) - -// Inspects data to check for a match - -``` - -Standard operator precedence can be expected for the various forms. For -example, the following two expressions would be equivalent. - -```text - and not or - -( and (not )) or -``` - ### Matching Operators -Matching operators are used to create an expression. All matching operators use a selector or value to choose what data should be +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. ```text // Equality & Inequality checks - == - != + == "" + != "" // Emptiness checks is empty is not empty // Contains checks or Substring Matching - in - not in - contains - not contains +"" in +"" not in + contains "" + not contains "" // Regular Expression Matching - matches - not matches + matches "" + not matches "" ``` ### Selectors @@ -108,12 +73,51 @@ ServiceMeta["foo"] ### Values -Values are used by matching operators to create an expression. Values can be any valid selector, a number, or a quoted string. For numbers any -base 10 integers and floating point numbers are possible. For quoted strings, +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 + +```text +// Logical Or - evaluates to true if either sub-expression does + or + +// Logical And - evaluates to true if both sub-expressions do + and + +// Logical Not - evaluates to true if the sub-expression does not +not + +// Grouping - Overrides normal precedence rules +( ) + +// Inspects data to check for a match + +``` + +Standard operator precedence can be expected for the various forms. For +example, the following two expressions would be equivalent. + +```text + and not or + +( and (not )) or +``` + ## Filter Utilization Generally, only the main object is filtered. When filtering for @@ -195,7 +199,7 @@ curl -X GET localhost:8500/v1/agent/services **Command - Filtered** ```shell -curl -G localhost:8500/v1/agent/services --data-urlencode 'filter=Meta.env == qa' +curl --get localhost:8500/v1/agent/services --data-urlencode 'filter=Meta.env == "qa"' ``` **Response - Filtered** @@ -326,7 +330,7 @@ curl -X GET localhost:8500/v1/catalog/service/api-internal **Command - Filtered** ```shell -curl -G localhost:8500/v1/catalog/service/api-internal --data-urlencode 'filter=NodeMeta.os == linux' +curl --get localhost:8500/v1/catalog/service/api-internal --data-urlencode 'filter=NodeMeta.os == "linux"' ``` **Response - Filtered**