Skip to content

Commit 94a9626

Browse files
dblockkolchfa-aws
dblock
and
kolchfa-aws
authored
Added documentation for cat?sort and format. (opensearch-project#7619)
* Added documentation for cat?sort and format. Signed-off-by: dblock <dblock@amazon.com> * Apply suggestions from code review Signed-off-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> --------- Signed-off-by: dblock <dblock@amazon.com> Signed-off-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> Co-authored-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com>
1 parent 786c74d commit 94a9626

File tree

1 file changed

+122
-4
lines changed

1 file changed

+122
-4
lines changed

‎_api-reference/cat/index.md

Lines changed: 122 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -24,17 +24,54 @@ GET _cat
2424
```
2525
{% include copy-curl.html %}
2626

27+
The response is an ASCII cat (`=^.^=`) and a list of operations:
28+
29+
```
30+
=^.^=
31+
/_cat/allocation
32+
/_cat/segment_replication
33+
/_cat/segment_replication/{index}
34+
/_cat/shards
35+
/_cat/shards/{index}
36+
/_cat/cluster_manager
37+
/_cat/nodes
38+
/_cat/tasks
39+
/_cat/indices
40+
/_cat/indices/{index}
41+
/_cat/segments
42+
/_cat/segments/{index}
43+
/_cat/count
44+
/_cat/count/{index}
45+
/_cat/recovery
46+
/_cat/recovery/{index}
47+
/_cat/health
48+
/_cat/pending_tasks
49+
/_cat/aliases
50+
/_cat/aliases/{alias}
51+
/_cat/thread_pool
52+
/_cat/thread_pool/{thread_pools}
53+
/_cat/plugins
54+
/_cat/fielddata
55+
/_cat/fielddata/{fields}
56+
/_cat/nodeattrs
57+
/_cat/repositories
58+
/_cat/snapshots/{repository}
59+
/_cat/templates
60+
/_cat/pit_segments
61+
/_cat/pit_segments/{pit_id}
62+
```
63+
2764
## Optional query parameters
2865

29-
You can use the following query parameters with any CAT API to filter your results.
66+
The root `_cat` API does not take any parameters, but individual APIs, such as `/_cat/nodes` accept the following query parameters.
3067

3168
Parameter | Description
3269
:--- | :--- |
3370
`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.
3471
`help` | Lists the default and other available headers for a given operation.
3572
`h` | Limits the output to specific headers.
36-
`format` | Returns the result in JSON, YAML, or CBOR formats.
37-
`sort` | Sorts the output by the specified columns.
73+
`format` | The format in which to return the result. Valid values are `json`, `yaml`, `cbor`, and `smile`.
74+
`s` | Sorts the output by the specified columns.
3875

3976
### Query parameter usage examples
4077

@@ -59,7 +96,6 @@ sample-alias1 sample-index-1 - - - -
5996
Without the verbose parameter, `v`, the response simply returns the alias names:
6097

6198
```
62-
6399
.kibana .kibana_1 - - - -
64100
sample-alias1 sample-index-1 - - - -
65101
```
@@ -72,6 +108,24 @@ To see all the available headers, use the `help` parameter:
72108
GET _cat/<operation_name>?help
73109
```
74110

111+
For example, to see the available headers for the CAT aliases operation, send the following request:
112+
113+
```json
114+
GET _cat/aliases?help
115+
```
116+
{% include copy-curl.html %}
117+
118+
The response contains the available headers:
119+
120+
```
121+
alias | a | alias name
122+
index | i,idx | index alias points to
123+
filter | f,fi | filter
124+
routing.index | ri,routingIndex | index routing
125+
routing.search | rs,routingSearch | search routing
126+
is_write_index | w,isWriteIndex | write index
127+
```
128+
75129
### Get a subset of headers
76130

77131
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:
80134
GET _cat/<operation_name>?h=<header_name_1>,<header_name_2>&v
81135
```
82136

137+
For example, to limit aliases to only the alias name and index, send the following request:
138+
139+
```json
140+
GET _cat/aliases?h=alias,index
141+
```
142+
{% include copy-curl.html %}
143+
144+
The response contains the requested information:
145+
146+
```
147+
.kibana .kibana_1
148+
sample-alias1 sample-index-1
149+
```
150+
83151
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.
84152

153+
### Sort by a header
154+
155+
To sort the output by a header, use the `s` parameter:
156+
157+
```json
158+
GET _cat/<operation_name>?s=<header_name_1>,<header_name_2>
159+
```
160+
161+
For example, to sort aliases by alias and then index, send the following request:
162+
163+
```json
164+
GET _cat/aliases?s=i,a
165+
```
166+
{% include copy-curl.html %}
167+
168+
The response contains the requested information:
169+
170+
```
171+
sample-alias2 sample-index-1
172+
sample-alias1 sample-index-2
173+
```
174+
175+
### Retrieve data in JSON format
176+
177+
By default, CAT APIs return data in `text/plain` format.
178+
179+
To retrieve data in JSON format, use the `format=json` parameter:
180+
181+
```json
182+
GET _cat/<operation_name>?format=json
183+
```
184+
185+
For example, to retrieve aliases in JSON format, send the following request:
186+
187+
```json
188+
GET _cat/aliases?format=json
189+
```
190+
{% include copy-curl.html %}
191+
192+
The response contains data in JSON format:
193+
194+
```json
195+
[
196+
{"alias":".kibana","index":".kibana_1","filter":"-","routing.index":"-","routing.search":"-","is_write_index":"-"},
197+
{"alias":"sample-alias-1","index":"sample-index-1","filter":"-","routing.index":"-","routing.search":"-","is_write_index":"-"}
198+
]
199+
```
200+
201+
Other supported formats are [YAML](https://yaml.org/), [CBOR](https://cbor.io/), and [Smile](https://github.com/FasterXML/smile-format-specification).
202+
85203
If you use the Security plugin, make sure you have the appropriate permissions.
86204
{: .note }

0 commit comments

Comments
 (0)