forked from opensearch-project/documentation-website
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge branch 'main' into add-dashboards-assistant-doc
- Loading branch information
Showing
55 changed files
with
3,223 additions
and
45 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,175 @@ | ||
| --- | ||
| layout: default | ||
| title: List API | ||
| nav_order: 45 | ||
| has_children: true | ||
| --- | ||
|
|
||
| # List APIs | ||
| **Introduced 2.18** | ||
| {: .label .label-purple } | ||
|
|
||
| The List API retrieves statistics about indexes and shards in a paginated format. This streamlines the task of processing responses that include many indexes. | ||
|
|
||
| The List API supports two operations: | ||
|
|
||
| - [List indices]({{site.url}}{{site.baseurl}}/api-reference/list/list-indices/) | ||
| - [List shards]({{site.url}}{{site.baseurl}}/api-reference/list/list-shards/) | ||
|
|
||
| ## Shared query parameters | ||
|
|
||
| All List API operations support the following optional 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. 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` | The format in which to return the result. Valid values are `json`, `yaml`, `cbor`, and `smile`. | ||
| `s` | Sorts the output by the specified columns. | ||
|
|
||
| ## Examples | ||
|
|
||
| The following examples show how to use the optional query parameters to customize all List API responses. | ||
|
|
||
|
|
||
| ### Get verbose output | ||
|
|
||
| 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. | ||
|
|
||
| #### Request | ||
|
|
||
| ```json | ||
| GET _list/indices?v | ||
| ``` | ||
| {% include copy-curl.html %} | ||
|
|
||
| #### Response | ||
|
|
||
| ```json | ||
| health status index uuid pri rep docs.count docs.deleted | ||
| green open .kibana_1 - - - - | ||
| yellow open sample-index-1 - - - - | ||
| next_token null | ||
| ``` | ||
|
|
||
|
|
||
| ### Get all available headers | ||
|
|
||
| To see all the available headers, use the `help` parameter with the following syntax: | ||
|
|
||
| ```json | ||
| GET _list/<operation_name>?help | ||
| ``` | ||
| {% include copy-curl.html %} | ||
|
|
||
| #### Request | ||
|
|
||
| The following example list indices operation returns all the available headers: | ||
|
|
||
| ```json | ||
| GET _list/indices?help | ||
| ``` | ||
| {% include copy-curl.html %} | ||
|
|
||
| #### Response | ||
|
|
||
| The following example displays the indexes and their health status in a table: | ||
|
|
||
| ```json | ||
| health | h | current health status | ||
| status | s | open/close status | ||
| index | i,idx | index name | ||
| uuid | id,uuid | index uuid | ||
| pri | p,shards.primary,shardsPrimary | number of primary shards | ||
| rep | r,shards.replica,shardsReplica | number of replica shards | ||
| docs.count | dc,docsCount | available docs | ||
| ``` | ||
|
|
||
| ### Get a subset of headers | ||
|
|
||
| To limit the output to a subset of headers, use the `h` parameter with the following syntax: | ||
|
|
||
| ```json | ||
| GET _list/<operation_name>?h=<header_name_1>,<header_name_2>&v | ||
| ``` | ||
| {% include copy-curl.html %} | ||
|
|
||
| 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. | ||
|
|
||
| #### Request | ||
|
|
||
| The following example limits the indexes in the response to only the index name and health status headers: | ||
|
|
||
| ```json | ||
| GET _list/indices?h=health,index | ||
| ``` | ||
| {% include copy-curl.html %} | ||
|
|
||
| ### Response | ||
|
|
||
| ```json | ||
| green .kibana_1 | ||
| yellow sample-index-1 | ||
| next_token null | ||
| ``` | ||
|
|
||
|
|
||
| ### Sort by a header | ||
|
|
||
| To sort the output on a single page by a header, use the `s` parameter with the following syntax: | ||
|
|
||
| ```json | ||
| GET _list/<operation_name>?s=<header_name_1>,<header_name_2> | ||
| ``` | ||
| {% include copy-curl.html %} | ||
|
|
||
| #### Request | ||
|
|
||
| The following example request sorts indexes by index name: | ||
|
|
||
| ```json | ||
| GET _list/indices?s=h,i | ||
| ``` | ||
| {% include copy-curl.html %} | ||
|
|
||
| #### Response | ||
|
|
||
| ```json | ||
| green sample-index-2 | ||
| yellow sample-index-1 | ||
| next_token null | ||
| ``` | ||
|
|
||
| ### Retrieve data in JSON format | ||
|
|
||
| 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). | ||
|
|
||
|
|
||
| To retrieve data in the JSON format, use the `format=json` parameter with the following syntax. | ||
|
|
||
| If you use the Security plugin, ensure you have the appropriate permissions. | ||
| {: .note } | ||
|
|
||
| #### Request | ||
|
|
||
| ```json | ||
| GET _list/<operation_name>?format=json | ||
| ``` | ||
| {% include copy-curl.html %} | ||
|
|
||
| #### Request | ||
|
|
||
| ```json | ||
| GET _list/indices?format=json | ||
| ``` | ||
| {% include copy-curl.html %} | ||
|
|
||
| ### Response | ||
|
|
||
| The response contains data in JSON format: | ||
|
|
||
| ```json | ||
| {"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":"-"}]} | ||
| ``` | ||
|
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,83 @@ | ||
| --- | ||
| layout: default | ||
| title: List indices | ||
| parent: List API | ||
| nav_order: 25 | ||
| has_children: false | ||
| --- | ||
|
|
||
| # List indices | ||
| **Introduced 2.18** | ||
| {: .label .label-purple } | ||
|
|
||
| The list indices operation provides the following index information in a paginated format: | ||
|
|
||
| - The amount of disk space used by the index. | ||
| - The number of shards contained in the index. | ||
| - The index's health status. | ||
|
|
||
| ## Path and HTTP methods | ||
|
|
||
| ```json | ||
| GET _list/indices | ||
| GET _list/indices/<index> | ||
| ``` | ||
|
|
||
| ## Query parameters | ||
|
|
||
| Parameter | Type | Description | ||
| :--- | :--- | :--- | ||
| `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/). | ||
| `health` | String | Limits indexes based on their health status. Supported values are `green`, `yellow`, and `red`. | ||
| `include_unloaded_segments` | Boolean | Whether to include information from segments not loaded into memory. Default is `false`. | ||
| `cluster_manager_timeout` | Time | The amount of time to wait for a connection to the cluster manager node. Default is `30s`. | ||
| `pri` | Boolean | Whether to return information only from the primary shards. Default is `false`. | ||
| `time` | Time | Specifies the time units, for example, `5d` or `7h`. For more information, see [Supported units]({{site.url}}{{site.baseurl}}/opensearch/units/). | ||
| `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`. | ||
| `next_token` | String | Fetches the next page of indexes. When `null`, only provides the first page of indexes. Default is `null`. | ||
| `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`. | ||
| `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`. | ||
|
|
||
| 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. | ||
| {: .tip } | ||
|
|
||
|
|
||
| ## Example requests | ||
|
|
||
| To get information for all the indexes, use the following query and keep specifying the `next_token` as received from response until its `null`: | ||
|
|
||
| ```json | ||
| GET _list/indices/<index>?v&next_token=token | ||
| ``` | ||
|
|
||
|
|
||
| To limit the information to a specific index, add the index name after your query, as shown in the following example: | ||
|
|
||
| ```json | ||
| GET _list/indices/<index>?v | ||
| ``` | ||
| {% include copy-curl.html %} | ||
|
|
||
| To get information about more than one index, separate the indexes with commas, as shown in the following example: | ||
|
|
||
| ```json | ||
| GET _list/indices/index1,index2,index3?v&next_token=token | ||
| ``` | ||
| {% include copy-curl.html %} | ||
|
|
||
|
|
||
| ## Example response | ||
|
|
||
| **Plain text format** | ||
|
|
||
| ```json | ||
| health | status | index | uuid | pri | rep | docs.count | docs.deleted | store.size | pri.store.size | ||
| green | open | movies | UZbpfERBQ1-3GSH2bnM3sg | 1 | 1 | 1 | 0 | 7.7kb | 3.8kb | ||
| next_token MTcyOTE5NTQ5NjM5N3wub3BlbnNlYXJjaC1zYXAtbG9nLXR5cGVzLWNvbmZpZw== | ||
| ``` | ||
|
|
||
| **JSON format** | ||
|
|
||
| ```json | ||
| {"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"}]} | ||
| ``` |
Oops, something went wrong.