Add docs for index component selector api convention #128786
Conversation
jbaiera
added
>docs
elasticsearchmachine
added
Team:Data Management
|
Pinging @elastic/es-docs (Team:Docs) |
|
Pinging @elastic/es-data-management (Team:Data Management) |
| There are currently two selector suffixes supported by {{es}} APIs: | ||
|
|
||
| `::data` | ||
| : (Indices, data streams) This selector references the default component present on all indices and data streams which holds the regular data contained therein. |
There was a problem hiding this comment.
I think this sentence could be clearer, I think we can simplify it (e.g.: ::data refers to backing indices containing regular data, not failures.)
| : (Indices, data streams) This selector references the default component present on all indices and data streams which holds the regular data contained therein. | ||
|
|
||
| `::failures` | ||
| : (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. |
There was a problem hiding this comment.
I don't think we can say it references "data", because that doesn't work for non-data APIs. For example GET /myds::failures/_settings returns the settings for the failure store indices, and not the data stored in those failure store indices.
|
|
||
| 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. | ||
|
|
||
| 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. |
There was a problem hiding this comment.
Selectors are applied … at the end …
applied at the end of what? Is it that they're the last thing resolved, or at the end of the name pattern itself?
| 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. | ||
|
|
||
| ```console | ||
| # Search for regular data on a data stream |
There was a problem hiding this comment.
I think "regular" may mislead here (and the word "failures" is hard also, because a user could be indexing failures successfully). Perhaps something like
| # Search for regular data on a data stream | |
| # Search the data (non-failure) backing indices of a data stream |
Maybe that's too specific though? (I think the one two lines below this suffers from the same problem)
There was a problem hiding this comment.
| # Search for regular data on a data stream | |
| # Search for non-failure data in a data stream |
Would this work? I'd probably avoid mentioning the backing indices, just to keep things simple.
|
|
||
| There are currently two selector suffixes supported by {{es}} APIs: | ||
|
|
||
| `::data` |
There was a problem hiding this comment.
| `::data` | |
| `data` |
I think the :: should be removed from here and the failures entry below. Without them it renders nicely:
There was a problem hiding this comment.
One concern I have is that we need the :: because it is part of the selector itself. For example: my-data-stream::data. If we remove the :: we risk a user not understanding they are delimited by the double-colon.
There was a problem hiding this comment.
Oh, sorry! I was reading those as a docs formatting thing, rather than the parameter.
This is why I shouldn't review PRs first thing in the AM. :-)
|
|
||
| Some APIs that accept a `<data-stream>`, `<index>`, or `<target>` request path parameter also support *selector syntax*. | ||
|
|
||
| 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 a regular index. Some APIs may operate on subsets of these index components which can be specified by using a selector suffix. |
There was a problem hiding this comment.
| 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 a regular index. Some APIs may operate on subsets of these index components which can be specified by using a selector suffix. | |
| 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. |
Maybe this is a bit more clear.
| ```console | ||
| # Search for regular data on a data stream | ||
| GET my-data-stream/_search | ||
| # Search for failure data on a data stream |
There was a problem hiding this comment.
| # Search for failure data on a data stream | |
| # Search for failure data in a data stream |
I'd use "in" when talking about the contents of the index / data stream (as opposed to performing operations on an index).
Adds documentation for index component selectors to the reference docs.
This documentation references and will be referenced by new docs located at elastic/docs-content#1368