From a042b748f12d8b2c899f04056486665986a6182f Mon Sep 17 00:00:00 2001 From: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> Date: Wed, 9 Dec 2020 15:03:44 -0800 Subject: [PATCH] Filter API Docs (#9202) * reorganize for clarity and update for value syntax * fix quotes around value * Apply suggestions from code review Co-authored-by: Blake Covarrubias * Apply suggestions from code review Co-authored-by: Freddy Co-authored-by: Blake Covarrubias Co-authored-by: Freddy --- website/pages/api-docs/features/filtering.mdx | 130 +++++++++--------- 1 file changed, 67 insertions(+), 63 deletions(-) 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,23 +9,80 @@ 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 +### 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. + +```text +// Equality & Inequality checks + == "" + != "" + +// Emptiness checks + is empty + is not empty + +// Contains checks or Substring Matching +"" in +"" not in + contains "" + not contains "" + +// Regular Expression Matching + matches "" + not matches "" +``` + +### 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 +`[""]` instead of `.`. This allows the possibility +of using map keys that are not valid selectors in and of themselves. + +```text +// selects the foo key within the ServiceMeta mapping for the +// /catalog/service/:service endpoint +ServiceMeta.foo + +// Also selects the foo key for the same endpoint +ServiceMeta["foo"] +``` + +### 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 @@ -61,59 +118,6 @@ example, the following two expressions would be equivalent. ( 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 -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 - -// Regular Expression Matching - matches - not matches -``` - -### 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 -`[""]` instead of `.`. This allows the possibility -of using map keys that are not valid selectors in and of themselves. - -```text -// selects the foo key within the ServiceMeta mapping for the -// /catalog/service/:service endpoint -ServiceMeta.foo - -// Also selects the foo key for the same endpoint -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, -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. - ## 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**