status-im
/
consul
mirror of https://github.com/status-im/consul.git
2
0
Fork 0
Code Issues Projects Releases Wiki Activity

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 <blake@covarrubi.as>

* Apply suggestions from code review

Co-authored-by: Freddy <freddygv@users.noreply.github.com>

Co-authored-by: Blake Covarrubias <blake@covarrubi.as>
Co-authored-by: Freddy <freddygv@users.noreply.github.com>
This commit is contained in:
kaitlincarter-hc 2020-12-09 15:03:44 -08:00 committed by hashicorp-ci
parent aa03e9979e
commit a042b748f1
1 changed files with 67 additions and 63 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

130
website/pages/api-docs/features/filtering.mdx
View File

@ -9,23 +9,80 @@ description: |-
# Filtering # Filtering
A filter expression is used to refine a data query for some API listing endpoints as notated in the individual API documentation. Filter expressions refine data queries 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. To create a filter expression, you will write one or more expressions. Each expression has a matching operators composed with selectors and values.
```shell ```shell
curl -G <path> --data-urlencode 'filter=<filter expression>' curl --get <path> --data-urlencode 'filter="<filter expression>"'
``` ```
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 supported. In general whitespace is ignored, except within literal
strings. 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
<Selector> == "<Value>"
<Selector> != "<Value>"
// Emptiness checks
<Selector> is empty
<Selector> is not empty
// Contains checks or Substring Matching
"<Value>" in <Selector>
"<Value>" not in <Selector>
<Selector> contains "<Value>"
<Selector> not contains "<Value>"
// Regular Expression Matching
<Selector> matches "<Value>"
<Selector> not matches "<Value>"
```
### 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.
```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 There are several methods for connecting expressions, including
@ -61,59 +118,6 @@ example, the following two expressions would be equivalent.
( <Expression 1> and (not <Expression 2> )) or <Expression 3> ( <Expression 1> and (not <Expression 2> )) or <Expression 3>
``` ```
### 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
<Selector> == <Value>
<Selector> != <Value>
// Emptiness checks
<Selector> is empty
<Selector> is not empty
// Contains checks or Substring Matching
<Value> in <Selector>
<Value> not in <Selector>
<Selector> contains <Value>
<Selector> not contains <Value>
// Regular Expression Matching
<Selector> matches <Value>
<Selector> not matches <Value>
```
### 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.
```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 ## Filter Utilization
Generally, only the main object is filtered. When filtering for Generally, only the main object is filtered. When filtering for
@ -195,7 +199,7 @@ curl -X GET localhost:8500/v1/agent/services
**Command - Filtered** **Command - Filtered**
```shell ```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** **Response - Filtered**
@ -326,7 +330,7 @@ curl -X GET localhost:8500/v1/catalog/service/api-internal
**Command - Filtered** **Command - Filtered**
```shell ```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** **Response - Filtered**