From 089f9dddf48dcf7958a669a98971b56c9e679a65 Mon Sep 17 00:00:00 2001 From: "Daniel (dB.) Doubrovkine" Date: Wed, 3 Jul 2024 10:16:00 -0400 Subject: [PATCH] Added documentation for cat?sort and format. (#7619) * Added documentation for cat?sort and format. Signed-off-by: dblock * Apply suggestions from code review Signed-off-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> --------- Signed-off-by: dblock Signed-off-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> Co-authored-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> Signed-off-by: Sander van de Geijn --- _api-reference/cat/index.md | 126 ++++++++++++++++++++++++++++++++++-- 1 file changed, 122 insertions(+), 4 deletions(-) diff --git a/_api-reference/cat/index.md b/_api-reference/cat/index.md index 0ddaf1e0a7..7454a4cf39 100644 --- a/_api-reference/cat/index.md +++ b/_api-reference/cat/index.md @@ -24,17 +24,54 @@ GET _cat ``` {% include copy-curl.html %} +The response is an ASCII cat (`=^.^=`) and a list of operations: + +``` +=^.^= +/_cat/allocation +/_cat/segment_replication +/_cat/segment_replication/{index} +/_cat/shards +/_cat/shards/{index} +/_cat/cluster_manager +/_cat/nodes +/_cat/tasks +/_cat/indices +/_cat/indices/{index} +/_cat/segments +/_cat/segments/{index} +/_cat/count +/_cat/count/{index} +/_cat/recovery +/_cat/recovery/{index} +/_cat/health +/_cat/pending_tasks +/_cat/aliases +/_cat/aliases/{alias} +/_cat/thread_pool +/_cat/thread_pool/{thread_pools} +/_cat/plugins +/_cat/fielddata +/_cat/fielddata/{fields} +/_cat/nodeattrs +/_cat/repositories +/_cat/snapshots/{repository} +/_cat/templates +/_cat/pit_segments +/_cat/pit_segments/{pit_id} +``` + ## Optional query parameters -You can use the following query parameters with any CAT API to filter your results. +The root `_cat` API does not take any parameters, but individual APIs, such as `/_cat/nodes` accept the following query parameters. Parameter | Description :--- | :--- | `v` | Provides verbose output by adding headers to the columns. It also adds some formatting to help align each of the columns together. All examples in this section include the `v` parameter. `help` | Lists the default and other available headers for a given operation. `h` | Limits the output to specific headers. -`format` | Returns the result in JSON, YAML, or CBOR formats. -`sort` | Sorts the output by the specified columns. +`format` | The format in which to return the result. Valid values are `json`, `yaml`, `cbor`, and `smile`. +`s` | Sorts the output by the specified columns. ### Query parameter usage examples @@ -59,7 +96,6 @@ sample-alias1 sample-index-1 - - - - Without the verbose parameter, `v`, the response simply returns the alias names: ``` - .kibana .kibana_1 - - - - sample-alias1 sample-index-1 - - - - ``` @@ -72,6 +108,24 @@ To see all the available headers, use the `help` parameter: GET _cat/?help ``` +For example, to see the available headers for the CAT aliases operation, send the following request: + +```json +GET _cat/aliases?help +``` +{% include copy-curl.html %} + +The response contains the available headers: + +``` +alias | a | alias name +index | i,idx | index alias points to +filter | f,fi | filter +routing.index | ri,routingIndex | index routing +routing.search | rs,routingSearch | search routing +is_write_index | w,isWriteIndex | write index +``` + ### Get a subset of headers To limit the output to a subset of headers, use the `h` parameter: @@ -80,7 +134,71 @@ To limit the output to a subset of headers, use the `h` parameter: GET _cat/?h=,&v ``` +For example, to limit aliases to only the alias name and index, send the following request: + +```json +GET _cat/aliases?h=alias,index +``` +{% include copy-curl.html %} + +The response contains the requested information: + +``` +.kibana .kibana_1 +sample-alias1 sample-index-1 +``` + Typically, for any operation you can find out what headers are available using the `help` parameter, and then use the `h` parameter to limit the output to only the headers that you care about. +### Sort by a header + +To sort the output by a header, use the `s` parameter: + +```json +GET _cat/?s=, +``` + +For example, to sort aliases by alias and then index, send the following request: + +```json +GET _cat/aliases?s=i,a +``` +{% include copy-curl.html %} + +The response contains the requested information: + +``` +sample-alias2 sample-index-1 +sample-alias1 sample-index-2 +``` + +### Retrieve data in JSON format + +By default, CAT APIs return data in `text/plain` format. + +To retrieve data in JSON format, use the `format=json` parameter: + +```json +GET _cat/?format=json +``` + +For example, to retrieve aliases in JSON format, send the following request: + +```json +GET _cat/aliases?format=json +``` +{% include copy-curl.html %} + +The response contains data in JSON format: + +```json +[ + {"alias":".kibana","index":".kibana_1","filter":"-","routing.index":"-","routing.search":"-","is_write_index":"-"}, + {"alias":"sample-alias-1","index":"sample-index-1","filter":"-","routing.index":"-","routing.search":"-","is_write_index":"-"} +] +``` + +Other supported formats are [YAML](https://yaml.org/), [CBOR](https://cbor.io/), and [Smile](https://github.com/FasterXML/smile-format-specification). + If you use the Security plugin, make sure you have the appropriate permissions. {: .note }