mirror of https://github.com/status-im/consul.git
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
hashicorp-ci
parent
9351400c2d
commit
4dae9b7224
|
|
@ -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 <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
|
||||
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
|
||||
|
||||
|
|
@ -61,59 +118,6 @@ example, the following two expressions would be equivalent.
|
|||
( <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
|
||||
|
||||
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**
|
||||
|
|
|
|||
Loading…
Reference in New Issue