Skip to content

Commit 60f74c4

Browse files
gargharsh3134Harsh GargNaarcha-AWSnatebower
authored
Adding documentation for _list APIs (#8594)
* Adding documentation for _list APIs Signed-off-by: Harsh Garg <gkharsh@amazon.com> * Add edits to index page. Signed-off-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> * Add edits to list indices Signed-off-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> * Update list-shards.md Signed-off-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> * Update index.md Signed-off-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> * Small grammar fixes Signed-off-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> * Apply suggestions from code review Signed-off-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> * Apply suggestions from code review Co-authored-by: Nathan Bower <nbower@amazon.com> Signed-off-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> * Update _api-reference/list/list-indices.md Signed-off-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> * Update _api-reference/list/list-shards.md Signed-off-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> * Correcting the examples and limits for size parameter Signed-off-by: Harsh Garg <gkharsh@amazon.com> * Apply suggestions from code review Signed-off-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> * Update list-indices.md Signed-off-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> * Update list-shards.md Signed-off-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> * Apply suggestions from code review Signed-off-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> --------- Signed-off-by: Harsh Garg <gkharsh@amazon.com> Signed-off-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> Co-authored-by: Harsh Garg <gkharsh@amazon.com> Co-authored-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> Co-authored-by: Nathan Bower <nbower@amazon.com>
1 parent 644ea06 commit 60f74c4

File tree

3 files changed

+336
-0
lines changed

3 files changed

+336
-0
lines changed

‎_api-reference/list/index.md‎

Lines changed: 175 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,175 @@
1+
---
2+
layout: default
3+
title: List API
4+
nav_order: 45
5+
has_children: true
6+
---
7+
8+
# List APIs
9+
**Introduced 2.18**
10+
{: .label .label-purple }
11+
12+
The List API retrieves statistics about indexes and shards in a paginated format. This streamlines the task of processing responses that include many indexes.
13+
14+
The List API supports two operations:
15+
16+
- [List indices]({{site.url}}{{site.baseurl}}/api-reference/list/list-indices/)
17+
- [List shards]({{site.url}}{{site.baseurl}}/api-reference/list/list-shards/)
18+
19+
## Shared query parameters
20+
21+
All List API operations support the following optional query parameters.
22+
23+
Parameter | Description
24+
:--- | :--- |
25+
`v` | Provides verbose output by adding headers to the columns. It also adds some formatting to help align each of the columns. All examples in this section include the `v` parameter.
26+
`help` | Lists the default and other available headers for a given operation.
27+
`h` | Limits the output to specific headers.
28+
`format` | The format in which to return the result. Valid values are `json`, `yaml`, `cbor`, and `smile`.
29+
`s` | Sorts the output by the specified columns.
30+
31+
## Examples
32+
33+
The following examples show how to use the optional query parameters to customize all List API responses.
34+
35+
36+
### Get verbose output
37+
38+
To query indexes and their statistics with a verbose output that includes all column headings in the response, use the `v` query parameter, as shown in the following example.
39+
40+
#### Request
41+
42+
```json
43+
GET _list/indices?v
44+
```
45+
{% include copy-curl.html %}
46+
47+
#### Response
48+
49+
```json
50+
health status index uuid pri rep docs.count docs.deleted
51+
green open .kibana_1 - - - -
52+
yellow open sample-index-1 - - - -
53+
next_token null
54+
```
55+
56+
57+
### Get all available headers
58+
59+
To see all the available headers, use the `help` parameter with the following syntax:
60+
61+
```json
62+
GET _list/<operation_name>?help
63+
```
64+
{% include copy-curl.html %}
65+
66+
#### Request
67+
68+
The following example list indices operation returns all the available headers:
69+
70+
```json
71+
GET _list/indices?help
72+
```
73+
{% include copy-curl.html %}
74+
75+
#### Response
76+
77+
The following example displays the indexes and their health status in a table:
78+
79+
```json
80+
health | h | current health status
81+
status | s | open/close status
82+
index | i,idx | index name
83+
uuid | id,uuid | index uuid
84+
pri | p,shards.primary,shardsPrimary | number of primary shards
85+
rep | r,shards.replica,shardsReplica | number of replica shards
86+
docs.count | dc,docsCount | available docs
87+
```
88+
89+
### Get a subset of headers
90+
91+
To limit the output to a subset of headers, use the `h` parameter with the following syntax:
92+
93+
```json
94+
GET _list/<operation_name>?h=<header_name_1>,<header_name_2>&v
95+
```
96+
{% include copy-curl.html %}
97+
98+
For any operation, you can determine which headers are available by using the `help` parameter and then using the `h` parameter to limit the output to only a subset of headers.
99+
100+
#### Request
101+
102+
The following example limits the indexes in the response to only the index name and health status headers:
103+
104+
```json
105+
GET _list/indices?h=health,index
106+
```
107+
{% include copy-curl.html %}
108+
109+
### Response
110+
111+
```json
112+
green .kibana_1
113+
yellow sample-index-1
114+
next_token null
115+
```
116+
117+
118+
### Sort by a header
119+
120+
To sort the output on a single page by a header, use the `s` parameter with the following syntax:
121+
122+
```json
123+
GET _list/<operation_name>?s=<header_name_1>,<header_name_2>
124+
```
125+
{% include copy-curl.html %}
126+
127+
#### Request
128+
129+
The following example request sorts indexes by index name:
130+
131+
```json
132+
GET _list/indices?s=h,i
133+
```
134+
{% include copy-curl.html %}
135+
136+
#### Response
137+
138+
```json
139+
green sample-index-2
140+
yellow sample-index-1
141+
next_token null
142+
```
143+
144+
### Retrieve data in JSON format
145+
146+
By default, List APIs return data in a `text/plain` format. Other supported formats are [YAML](https://yaml.org/), [CBOR](https://cbor.io/), and [Smile](https://github.com/FasterXML/smile-format-specification).
147+
148+
149+
To retrieve data in the JSON format, use the `format=json` parameter with the following syntax.
150+
151+
If you use the Security plugin, ensure you have the appropriate permissions.
152+
{: .note }
153+
154+
#### Request
155+
156+
```json
157+
GET _list/<operation_name>?format=json
158+
```
159+
{% include copy-curl.html %}
160+
161+
#### Request
162+
163+
```json
164+
GET _list/indices?format=json
165+
```
166+
{% include copy-curl.html %}
167+
168+
### Response
169+
170+
The response contains data in JSON format:
171+
172+
```json
173+
{"next_token":null,"indices":[{"health":"green","status":"-","index":".kibana_1","uuid":"-","pri":"-","rep":"-","docs.count":"-","docs.deleted":"-","store.size":"-","pri.store.size":"-"},{"health":"yellow","status":"-","index":"sample-index-1","uuid":"-","pri":"-","rep":"-","docs.count":"-","docs.deleted":"-","store.size":"-","pri.store.size":"-"}]}
174+
```
175+

‎_api-reference/list/list-indices.md‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
---
2+
layout: default
3+
title: List indices
4+
parent: List API
5+
nav_order: 25
6+
has_children: false
7+
---
8+
9+
# List indices
10+
**Introduced 2.18**
11+
{: .label .label-purple }
12+
13+
The list indices operation provides the following index information in a paginated format:
14+
15+
- The amount of disk space used by the index.
16+
- The number of shards contained in the index.
17+
- The index's health status.
18+
19+
## Path and HTTP methods
20+
21+
```json
22+
GET _list/indices
23+
GET _list/indices/<index>
24+
```
25+
26+
## Query parameters
27+
28+
Parameter | Type | Description
29+
:--- | :--- | :---
30+
`bytes` | Byte size | Specifies the units for the byte size, for example, `7kb` or `6gb`. For more information, see [Supported units]({{site.url}}{{site.baseurl}}/opensearch/units/).
31+
`health` | String | Limits indexes based on their health status. Supported values are `green`, `yellow`, and `red`.
32+
`include_unloaded_segments` | Boolean | Whether to include information from segments not loaded into memory. Default is `false`.
33+
`cluster_manager_timeout` | Time | The amount of time to wait for a connection to the cluster manager node. Default is `30s`.
34+
`pri` | Boolean | Whether to return information only from the primary shards. Default is `false`.
35+
`time` | Time | Specifies the time units, for example, `5d` or `7h`. For more information, see [Supported units]({{site.url}}{{site.baseurl}}/opensearch/units/).
36+
`expand_wildcards` | Enum | Expands wildcard expressions to concrete indexes. Combine multiple values with commas. Supported values are `all`, `open`, `closed`, `hidden`, and `none`. Default is `open`.
37+
`next_token` | String | Fetches the next page of indexes. When `null`, only provides the first page of indexes. Default is `null`.
38+
`size` | Integer | The maximum number of indexes to be displayed on a single page. The number of indexes on a single page of the response is not always equal to the specified `size`. Default is `500`. Minimum is `1` and maximum value is `5000`.
39+
`sort` | String | The order in which the indexes are displayed. If `desc`, then the most recently created indexes are displayed first. If `asc`, then the oldest indexes are displayed first. Default is `asc`.
40+
41+
When using the `next_token` path parameter, use the token produced by the response to see the next page of indexes. After the API returns `null`, all indexes contained in the API have been returned.
42+
{: .tip }
43+
44+
45+
## Example requests
46+
47+
To get information for all the indexes, use the following query and keep specifying the `next_token` as received from response until its `null`:
48+
49+
```json
50+
GET _list/indices/<index>?v&next_token=token
51+
```
52+
53+
54+
To limit the information to a specific index, add the index name after your query, as shown in the following example:
55+
56+
```json
57+
GET _list/indices/<index>?v
58+
```
59+
{% include copy-curl.html %}
60+
61+
To get information about more than one index, separate the indexes with commas, as shown in the following example:
62+
63+
```json
64+
GET _list/indices/index1,index2,index3?v&next_token=token
65+
```
66+
{% include copy-curl.html %}
67+
68+
69+
## Example response
70+
71+
**Plain text format**
72+
73+
```json
74+
health | status | index | uuid | pri | rep | docs.count | docs.deleted | store.size | pri.store.size
75+
green | open | movies | UZbpfERBQ1-3GSH2bnM3sg | 1 | 1 | 1 | 0 | 7.7kb | 3.8kb
76+
next_token MTcyOTE5NTQ5NjM5N3wub3BlbnNlYXJjaC1zYXAtbG9nLXR5cGVzLWNvbmZpZw==
77+
```
78+
79+
**JSON format**
80+
81+
```json
82+
{"next_token":"MTcyOTE5NTQ5NjM5N3wub3BlbnNlYXJjaC1zYXAtbG9nLXR5cGVzLWNvbmZpZw==","indices":[{"health":"green","status":"open","index":"movies","uuid":"UZbpfERBQ1-3GSH2bnM3sg","pri":"1","rep":"1","docs.count":"1","docs.deleted":"0","store.size":"7.7kb","pri.store.size":"3.8kb"}]}
83+
```

‎_api-reference/list/list-shards.md‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
---
2+
layout: default
3+
title: List shards
4+
parent: List API
5+
nav_order: 20
6+
---
7+
8+
# List shards
9+
**Introduced 2.18**
10+
{: .label .label-purple }
11+
12+
The list shards operation outputs, in a paginated format, the state of all primary and replica shards and how they are distributed.
13+
14+
## Path and HTTP methods
15+
16+
```json
17+
GET _list/shards
18+
GET _list/shards/<index>
19+
```
20+
21+
## Query parameters
22+
23+
All parameters are optional.
24+
25+
Parameter | Type | Description
26+
:--- | :--- | :---
27+
`bytes` | Byte size | Specifies the byte size units, for example, `7kb` or `6gb`. For more information, see [Supported units]({{site.url}}{{site.baseurl}}/opensearch/units/).
28+
`local` | Boolean | Whether to return information from the local node only instead of from the cluster manager node. Default is `false`.
29+
`cluster_manager_timeout` | Time | The amount of time to wait for a connection to the cluster manager node. Default is `30s`.
30+
`cancel_after_time_interval` | Time | The amount of time after which the shard request is canceled. Default is `-1` (no timeout).
31+
`time` | Time | Specifies the time units, for example, `5d` or `7h`. For more information, see [Supported units]({{site.url}}{{site.baseurl}}/opensearch/units/).
32+
`next_token` | String | Fetches the next page of indexes. When `null`, only provides the first page of indexes. Default is `null`.
33+
`size` | Integer | The maximum number of indexes to be displayed on a single page. The number of indexes on a single page of the response is not always equal to the specified `size`. Default and minimum value is `2000`. Maximum value is `20000`.
34+
`sort` | String | The order in which the indexes are displayed. If `desc`, then the most recently created indexes are displayed first. If `asc`, then the oldest indexes are displayed first. Default is `asc`.
35+
36+
When using the `next_token` path parameter, use the token produced by the response to see the next page of indexes. After the API returns `null`, all indexes contained in the API have been returned.
37+
{: .tip }
38+
39+
## Example requests
40+
41+
To get information for all the indexes and shards, use the following query and keep specifying the `next_token` as received from response until its `null`:
42+
43+
```json
44+
GET _list/shards/<index>?v&next_token=token
45+
```
46+
47+
To limit the information to a specific index, add the index name after your query, as shown in the following example and keep specifying the `next_token` as received from response until its `null`:
48+
49+
```json
50+
GET _list/shards/<index>?v&next_token=token
51+
```
52+
{% include copy-curl.html %}
53+
54+
If you want to get information for more than one index, separate the indexes with commas, as shown in the following example:
55+
56+
```json
57+
GET _list/shards/index1,index2,index3?v&next_token=token
58+
```
59+
{% include copy-curl.html %}
60+
61+
## Example response
62+
63+
**Plain text format**
64+
65+
```json
66+
index | shard | prirep | state | docs | store | ip | | node
67+
plugins | 0 | p | STARTED | 0 | 208b | 172.18.0.4 | odfe-node1
68+
plugins | 0 | r | STARTED | 0 | 208b | 172.18.0.3 | odfe-node2
69+
....
70+
....
71+
next_token MTcyOTE5NTQ5NjM5N3wub3BlbnNlYXJjaC1zYXAtbG9nLXR5cGVzLWNvbmZpZw==
72+
```
73+
74+
**JSON format**
75+
76+
```json
77+
{"next_token":"MTcyOTE5NTQ5NjM5N3wub3BlbnNlYXJjaC1zYXAtbG9nLXR5cGVzLWNvbmZpZw==","shards":[{"index":"plugins","shard":"0","prirep":"p","state":"STARTED","docs":"0","store":"208B","ip":"172.18.0.4","node":"odfe-node1"},{"index":"plugins","shard":"0","prirep":"r","state":"STARTED","docs":"0","store":"208B","ip":"172.18.0.3","node":"odfe-node2"}]}
78+
```

0 commit comments

Comments
 (0)