Skip to content

Commit 4063f3c

Browse files
committed
Rework the selector docs to be less abstract
1 parent 758b78d commit 4063f3c

File tree

1 file changed

+7
-8
lines changed

1 file changed

+7
-8
lines changed

docs/reference/elasticsearch/rest-apis/api-conventions.md

Lines changed: 7 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -421,24 +421,24 @@ GET /_nodes/ra*:2
421421
GET /_nodes/ra*:2*
422422
```
423423

424-
### Index Component Selectors [api-component-selectors]
424+
### Component Selectors [api-component-selectors]
425425

426-
Some APIs that accept a `<data-stream>`, `<index>`, or `<target>` request path parameter also support *selector syntax*.
426+
A data stream component is a logical grouping of indices that help organize data inside a data stream. All data streams contain a `data` component by default. The `data` component comprises the data stream's backing indices. When searching, managing, or indexing into a data stream, the `data` component is what you are interacting with by default.
427427

428-
Some indices and data streams are made of multiple components besides their default data. These other components store additional data which can be queried separately like regular index data. Some APIs may operate on subsets of these index components which can be specified by using a selector suffix.
428+
Some data stream features are exposed as additional components alongside its `data` component. These other components are comprised of separate sets of backing indices. These additional components store supplemental data independent of the data stream's regular backing indices. An example of another component is the `failures` component exposed by the data stream [failure store](docs-content://manage-data/data-store/data-streams/failure-store.md) feature, which captures documents that fail to be ingested in a separate set of backing indices on the data stream.
429+
430+
Some APIs that accept a `<data-stream>`, `<index>`, or `<target>` request path parameter also support *selector syntax* which defines which component on a data stream the API should operate on. To use a selector, it is appended to the index or data stream name. Selectors can be combined with other index pattern syntax like [date math](#api-date-math-index-names) and wildcards.
429431

430432
There are currently two selector suffixes supported by {{es}} APIs:
431433

432434
`::data`
433-
: (Indices, data streams) This selector references the default component present on all indices and data streams which holds the regular data contained therein.
435+
: Refers to a data stream's backing indices containing regular data. Data streams always contain a data component.
434436

435437
`::failures`
436-
: (Data streams only) This component references data stored in a data stream's [failure store](docs-content://manage-data/data-store/data-streams/failure-store.md). This component is only present on data streams.
438+
: This component refers to the internal indices used for a data stream's [failure store](docs-content://manage-data/data-store/data-streams/failure-store.md).
437439

438440
As an example, [search]({{es-apis}}group/endpoint-search), [field capabilities]({{es-apis}}operation/operation-field-caps), and [index stats]({{es-apis}}operation/operation-indices-stats) APIs can all report results from a different component rather than from the default data.
439441

440-
Selectors are applied to an index pattern at the end and can be combined with other index pattern syntax like [date math](#api-date-math-index-names) and wildcards.
441-
442442
```console
443443
# Search for regular data on a data stream
444444
GET my-data-stream/_search
@@ -454,7 +454,6 @@ GET <logs-{now/d}>::failures/_search
454454
```
455455

456456

457-
458457
## Parameters [api-conventions-parameters]
459458

460459
Rest parameters (when using HTTP, map to HTTP URL parameters) follow the convention of using underscore casing.

0 commit comments

Comments
 (0)