diff --git a/_opensearch/catapis.md b/_opensearch/catapis.md deleted file mode 100644 index a863f73d..00000000 --- a/_opensearch/catapis.md +++ /dev/null @@ -1,256 +0,0 @@ ---- -layout: default -title: CAT API -nav_order: 20 ---- - -# cat API - -You can get essential statistics about your cluster in an easy-to-understand, tabular format using the compact and aligned text (CAT) API. The cat API is a human-readable interface that returns plain text instead of traditional JSON. - -Using the cat API, you can answer questions like which node is the elected master, what state is the cluster in, how many documents are in each index, and so on. - -To see the available operations in the cat API, use the following command: - -``` -GET _cat -``` - -You can also use the following string parameters with your query. - -Parameter | Description -:--- | :--- | -`?v` | Makes the output more verbose by adding headers to the columns. It also adds some formatting to help align each of the columns together. All examples on this page include the `v` parameter. -`?help` | Lists the default and other available headers for a given operation. -`?h` | Limits the output to specific headers. -`?format` | Outputs the result in JSON, YAML, or CBOR formats. -`?sort` | Sorts the output by the specified columns. - -To see what each column represents, use the `?v` parameter: - -``` -GET _cat/?v -``` - -To see all the available headers, use the `?help` parameter: - -``` -GET _cat/?help -``` - -To limit the output to a subset of headers, use the `?h` parameter: - -``` -GET _cat/?h=,&v -``` - -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. - ---- - -#### Table of contents -1. TOC -{:toc} - ---- -## Aliases - -Lists the mapping of aliases to indices, plus routing and filtering information. - -``` -GET _cat/aliases?v -``` - -To limit the information to a specific alias, add the alias name after your query. - -``` -GET _cat/aliases/?v -``` - -## Allocation - -Lists the allocation of disk space for indices and the number of shards on each node. -Default request: -``` -GET _cat/allocation?v -``` - -## Count - -Lists the number of documents in your cluster. - -``` -GET _cat/count?v -``` - -To see the number of documents in a specific index, add the index name after your query. - -``` -GET _cat/count/?v -``` - -## Field data - -Lists the memory size used by each field per node. - -``` -GET _cat/fielddata?v -``` - -To limit the information to a specific field, add the field name after your query. - -``` -GET _cat/fielddata/?v -``` - -## Health - -Lists the status of the cluster, how long the cluster has been up, the number of nodes, and other useful information that helps you analyze the health of your cluster. - -``` -GET _cat/health?v -``` - -## Indices - -Lists information related to indices⁠—how much disk space they are using, how many shards they have, their health status, and so on. - -``` -GET _cat/indices?v -``` - -To limit the information to a specific index, add the index name after your query. - -``` -GET _cat/indices/?v -``` - -## Master - -Lists information that helps identify the elected master node. - -``` -GET _cat/master?v -``` - -## Node attributes - -Lists the attributes of custom nodes. - -``` -GET _cat/nodeattrs?v -``` - -## Nodes - -Lists node-level information, including node roles and load metrics. - -A few important node metrics are `pid`, `name`, `master`, `ip`, `port`, `version`, `build`, `jdk`, along with `disk`, `heap`, `ram`, and `file_desc`. - -``` -GET _cat/nodes?v -``` - -## Pending tasks - -Lists the progress of all pending tasks, including task priority and time in queue. - -``` -GET _cat/pending_tasks?v -``` - -## Plugins - -Lists the names, components, and versions of the installed plugins. - -``` -GET _cat/plugins?v -``` - -## Recovery - -Lists all completed and ongoing index and shard recoveries. - -``` -GET _cat/recovery?v -``` - -To see only the recoveries of a specific index, add the index name after your query. - -``` -GET _cat/recovery/?v -``` - -## Repositories - -Lists all snapshot repositories and their types. - -``` -GET _cat/repositories?v -``` - -## Segments - -Lists Lucene segment-level information for each index. - -``` -GET _cat/segments?v -``` - -To see only the information about segments of a specific index, add the index name after your query. - -``` -GET _cat/segments/?v -``` - -## Shards - -Lists the state of all primary and replica shards and how they are distributed. - -``` -GET _cat/shards?v -``` - -To see only the information about shards of a specific index, add the index name after your query. - -``` -GET _cat/shards/?v -``` - -## Snapshots - -Lists all snapshots for a repository. - -``` -GET _cat/snapshots/?v -``` - -## Tasks - -Lists the progress of all tasks currently running on your cluster. - -``` -GET _cat/tasks?v -``` - -## Templates - -Lists the names, patterns, order numbers, and version numbers of index templates. - -``` -GET _cat/templates?v -``` - -## Thread pool - -Lists the active, queued, and rejected threads of different thread pools on each node. - -``` -GET _cat/thread_pool?v -``` - -To limit the information to a specific thread pool, add the thread pool name after your query. - -``` -GET _cat/thread_pool/?v -``` diff --git a/_opensearch/rest-api/cat/cat-aliases.md b/_opensearch/rest-api/cat/cat-aliases.md new file mode 100644 index 00000000..833ad9a6 --- /dev/null +++ b/_opensearch/rest-api/cat/cat-aliases.md @@ -0,0 +1,61 @@ +--- +layout: default +title: cat aliases +parent: CAT +grand_parent: REST API reference +nav_order: 1 +has_children: false +--- + +# cat aliases + +The cat aliases operation lists the mapping of aliases to indices, plus routing and filtering information. + +## Example + +```json +GET _cat/aliases?v +``` + +To limit the information to a specific alias, add the alias name after your query: + +```json +GET _cat/aliases/?v +``` + +If you want to get information for more than one alias, separate the alias names with commas: + +```json +GET _cat/aliases/alias1,alias2,alias3 +``` + +## Path and HTTP methods + +``` +GET _cat/aliases/ +GET _cat/aliases +``` + + +## URL parameters + +All cat aliases URL parameters are optional. + +In addition to the [common URL parameters]({{site.url}}{{site.baseurl}}/opensearch/rest-api/cat/index#common-url-parameters), you can specify the following parameters: + +Parameter | Type | Description +:--- | :--- | :--- +local | Boolean | Whether to return information from the local node only instead of from the master node. Default is false. +expand_wildcards | Enum | Expands wildcard expressions to concrete indices. Combine multiple values with commas. Supported values are `all`, `open`, `closed`, `hidden`, and `none`. Default is `open`. + +## Response + +The following response shows that `alias1` refers to a `movies` index and has a configured filter: + +```json +alias | index | filter | routing.index | routing.search | is_write_index +alias1 | movies | * | - | - | - +.kibana | .kibana_1 | - | - | - | - +``` + +To learn more about index aliases, see [Index aliases]({{site.url}}{{site.baseurl}}/opensearch/index-alias). diff --git a/_opensearch/rest-api/cat/cat-allocation.md b/_opensearch/rest-api/cat/cat-allocation.md new file mode 100644 index 00000000..c7b14edc --- /dev/null +++ b/_opensearch/rest-api/cat/cat-allocation.md @@ -0,0 +1,61 @@ +--- +layout: default +title: cat allocation +parent: CAT +grand_parent: REST API reference +nav_order: 5 +has_children: false +--- + +# cat allocation + +The cat allocation operation lists the allocation of disk space for indices and the number of shards on each node. + +## Example + +```json +GET _cat/allocation?v +``` + +To limit the information to a specific node, add the node name after your query: + +```json +GET _cat/allocation/ +``` + +If you want to get information for more than one node, separate the node names with commas: + +```json +GET _cat/aliases/node_name_1,node_name_2,node_name_3 +``` + +## Path and HTTP methods + +``` +GET _cat/allocation?v +GET _cat/allocation/ +``` + +## URL parameters + +All cat allocation URL parameters are optional. + +In addition to the [common URL parameters]({{site.url}}{{site.baseurl}}/opensearch/rest-api/cat/index#common-url-parameters), you can specify the following parameters: + +Parameter | Type | Description +:--- | :--- | :--- +bytes | Byte size | Specify the units for byte size. For example, `7kb` or `6gb`. For more information, see [Supported units]({{site.url}}{{site.baseurl}}/opensearch/units/). +local | Boolean | Whether to return information from the local node only instead of from the master node. Default is false. +master_timeout | Time | The amount of time to wait for a connection to the master node. Default is 30 seconds. + + + +## Response + +The following response shows that 8 shards are allocated to each the two nodes available: + +```json +shards | disk.indices | disk.used | disk.avail | disk.total | disk.percent host | ip | node + 8 | 989.4kb | 25.9gb | 32.4gb | 58.4gb | 44 172.18.0.4 | 172.18.0.4 | odfe-node1 + 8 | 962.4kb | 25.9gb | 32.4gb | 58.4gb | 44 172.18.0.3 | 172.18.0.3 | odfe-node2 +``` diff --git a/_opensearch/rest-api/cat/cat-count.md b/_opensearch/rest-api/cat/cat-count.md new file mode 100644 index 00000000..44cc9d1b --- /dev/null +++ b/_opensearch/rest-api/cat/cat-count.md @@ -0,0 +1,51 @@ +--- +layout: default +title: cat count +parent: CAT +grand_parent: REST API reference +nav_order: 10 +has_children: false +--- + +# cat count + +The cat count operation lists the number of documents in your cluster. + +## Example + +```json +GET _cat/count?v +``` + +To see the number of documents in a specific index or alias, add the index or alias name after your query: + +```json +GET _cat/count/?v +``` + +If you want to get information for more than one index or alias, separate the index or alias names with commas: + +```json +GET _cat/aliases/index_or_alias_1,index_or_alias_2,index_or_alias_3 +``` + +## Path and HTTP methods + +``` +GET _cat/count?v +GET _cat/count/?v +``` + +## URL parameters + +All cat count URL parameters are optional. You can specify any of the [common URL parameters]({{site.url}}{{site.baseurl}}/opensearch/rest-api/cat/index#common-url-parameters). + + +## Response + +The following response shows the overall document count as 1625: + +```json +epoch | timestamp | count +1624237738 | 01:08:58 | 1625 +``` diff --git a/_opensearch/rest-api/cat/cat-field-data.md b/_opensearch/rest-api/cat/cat-field-data.md new file mode 100644 index 00000000..54c5a5bf --- /dev/null +++ b/_opensearch/rest-api/cat/cat-field-data.md @@ -0,0 +1,57 @@ +--- +layout: default +title: cat field data +parent: CAT +grand_parent: REST API reference +nav_order: 15 +has_children: false +--- + +# cat fielddata + +The cat fielddata operation lists the memory size used by each field per node. + +## Example + +```json +GET _cat/fielddata?v +``` + +To limit the information to a specific field, add the field name after your query: + +```json +GET _cat/fielddata/?v +``` + +If you want to get information for more than one field, separate the field names with commas: + +```json +GET _cat/aliases/field_name_1,field_name_2,field_name_3 +``` + +## Path and HTTP methods + +``` +GET _cat/fielddata?v +GET _cat/fielddata/?v +``` + +## URL parameters + +All cat fielddata URL parameters are optional. + +In addition to the [common URL parameters]({{site.url}}{{site.baseurl}}/opensearch/rest-api/cat/index#common-url-parameters), you can specify the following parameter: + +Parameter | Type | Description +:--- | :--- | :--- +bytes | Byte size | Specify the units for byte size. For example, `7kb` or `6gb`. For more information, see [Supported units]({{site.url}}{{site.baseurl}}/opensearch/units/). + +## Response + +The following response shows the memory size for all fields as 284 bytes: + +```json +id host ip node field size +1vo54NuxSxOrbPEYdkSF0w 172.18.0.4 172.18.0.4 odfe-node1 _id 284b +ZaIkkUd4TEiAihqJGkp5CA 172.18.0.3 172.18.0.3 odfe-node2 _id 284b +``` diff --git a/_opensearch/rest-api/cat/cat-health.md b/_opensearch/rest-api/cat/cat-health.md new file mode 100644 index 00000000..9e16abe7 --- /dev/null +++ b/_opensearch/rest-api/cat/cat-health.md @@ -0,0 +1,42 @@ +--- +layout: default +title: cat health +parent: CAT +grand_parent: REST API reference +nav_order: 20 +has_children: false +--- + +# cat health + +The cat health operation lists the status of the cluster, how long the cluster has been up, the number of nodes, and other useful information that helps you analyze the health of your cluster. + +## Example + +```json +GET _cat/health?v +``` + +## Path and HTTP methods + +``` +GET _cat/health?v +``` + +## URL parameters + +All cat health URL parameters are optional. + +Parameter | Type | Description +:--- | :--- | :--- +time | Time | Specify the units for time. For example, `5d` or `7h`. For more information, see [Supported units]({{site.url}}{{site.baseurl}}/opensearch/units/). +ts | Boolean | If true, returns HH:MM:SS and Unix epoch timestamps. Default is true. + +## Response + +```json +GET _cat/health?v&time=5d + +epoch | timestamp | cluster | status | node.total | node.data | shards | pri | relo | init | unassign | pending_tasks | max_task_wait_time | active_shards_percent +1624248112 | 04:01:52 | odfe-cluster | green | 2 | 2 | 16 | 8 | 0 | 0 | 0 | 0 | - | 100.0% +``` diff --git a/_opensearch/rest-api/cat/cat-indices.md b/_opensearch/rest-api/cat/cat-indices.md new file mode 100644 index 00000000..64affeee --- /dev/null +++ b/_opensearch/rest-api/cat/cat-indices.md @@ -0,0 +1,61 @@ +--- +layout: default +title: cat indices +parent: CAT +grand_parent: REST API reference +nav_order: 25 +has_children: false +--- + +# cat indices + +The cat indices operation lists information related to indices⁠—how much disk space they are using, how many shards they have, their health status, and so on. + +## Example + +``` +GET _cat/indices?v +``` + +To limit the information to a specific index, add the index name after your query. + +``` +GET _cat/indices/?v +``` + +If you want to get information for more than one index, separate the indices with commas: + +```json +GET _cat/aliases/index1,index2,index3 +``` + +## Path and HTTP methods + +``` +GET _cat/indices/ +GET _cat/indices +``` + +## URL parameters + +All cat indices URL parameters are optional. + +In addition to the [common URL parameters]({{site.url}}{{site.baseurl}}/opensearch/rest-api/cat/index#common-url-parameters), you can specify the following parameters: + +Parameter | Type | Description +:--- | :--- | :--- +bytes | Byte size | Specify the units for byte size. For example, `7kb` or `6gb`. For more information, see [Supported units]({{site.url}}{{site.baseurl}}/opensearch/units/). +health | String | Limit indices 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. +master_timeout | Time | The amount of time to wait for a connection to the master node. Default is 30 seconds. +pri | Boolean | Whether to return information only from the primary shards. Default is false. +time | Time | Specify the units for time. 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 indices. Combine multiple values with commas. Supported values are `all`, `open`, `closed`, `hidden`, and `none`. Default is `open`. + + +## Response + +```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 +``` diff --git a/_opensearch/rest-api/cat/cat-master.md b/_opensearch/rest-api/cat/cat-master.md new file mode 100644 index 00000000..266340d4 --- /dev/null +++ b/_opensearch/rest-api/cat/cat-master.md @@ -0,0 +1,42 @@ +--- +layout: default +title: cat master +parent: CAT +grand_parent: REST API reference +nav_order: 30 +has_children: false +--- + +# cat master + +The cat master operation lists information that helps identify the elected master node. + +## Example + +``` +GET _cat/master?v +``` + +## Path and HTTP methods + +``` +GET _cat/master +``` + +## URL parameters + +All cat master URL parameters are optional. + +In addition to the [common URL parameters]({{site.url}}{{site.baseurl}}/opensearch/rest-api/cat/index#common-url-parameters), you can specify the following parameters: + +Parameter | Type | Description +:--- | :--- | :--- +master_timeout | Time | The amount of time to wait for a connection to the master node. Default is 30 seconds. + + +## Response + +```json +id | host | ip | node +ZaIkkUd4TEiAihqJGkp5CA | 172.18.0.3 | 172.18.0.3 | odfe-node2 +``` diff --git a/_opensearch/rest-api/cat/cat-nodeattrs.md b/_opensearch/rest-api/cat/cat-nodeattrs.md new file mode 100644 index 00000000..0ed56e53 --- /dev/null +++ b/_opensearch/rest-api/cat/cat-nodeattrs.md @@ -0,0 +1,43 @@ +--- +layout: default +title: cat nodeattrs +parent: CAT +grand_parent: REST API reference +nav_order: 35 +has_children: false +--- + +# cat nodeattrs + +The cat nodeattrs operation lists the attributes of custom nodes. + +## Example + +``` +GET _cat/nodeattrs?v +``` + +## Path and HTTP methods + +``` +GET _cat/nodeattrs +``` + +## URL parameters + +All cat nodeattrs URL parameters are optional. + +In addition to the [common URL parameters]({{site.url}}{{site.baseurl}}/opensearch/rest-api/cat/index#common-url-parameters), you can specify the following parameters: + +Parameter | Type | Description +:--- | :--- | :--- +local | Boolean | Whether to return information from the local node only instead of from the master node. Default is false. +master_timeout | Time | The amount of time to wait for a connection to the master node. Default is 30 seconds. + + +## Response + +```json +node | host | ip | attr | value +odfe-node2 | 172.18.0.3 | 172.18.0.3 | testattr | test +``` diff --git a/_opensearch/rest-api/cat/cat-nodes.md b/_opensearch/rest-api/cat/cat-nodes.md new file mode 100644 index 00000000..8f3cdc84 --- /dev/null +++ b/_opensearch/rest-api/cat/cat-nodes.md @@ -0,0 +1,50 @@ +--- +layout: default +title: cat nodes +parent: CAT +grand_parent: REST API reference +nav_order: 40 +has_children: false +--- + +# cat nodes + +The cat nodes operation lists node-level information, including node roles and load metrics. + +A few important node metrics are `pid`, `name`, `master`, `ip`, `port`, `version`, `build`, `jdk`, along with `disk`, `heap`, `ram`, and `file_desc`. + +## Example + +``` +GET _cat/nodes?v +``` + +## Path and HTTP methods + +``` +GET _cat/nodes +``` + +## URL parameters + +All cat nodes URL parameters are optional. + +In addition to the [common URL parameters]({{site.url}}{{site.baseurl}}/opensearch/rest-api/cat/index#common-url-parameters), you can specify the following parameters: + +Parameter | Type | Description +:--- | :--- | :--- +bytes | Byte size | Specify the units for byte size. For example, `7kb` or `6gb`. For more information, see [Supported units]({{site.url}}{{site.baseurl}}/opensearch/units/). +full_id | Boolean | If true, return the full node ID. If false, return the shortened node ID. Defaults to false. +local | Boolean | Whether to return information from the local node only instead of from the master node. Default is false. +master_timeout | Time | The amount of time to wait for a connection to the master node. Default is 30 seconds. +time | Time | Specify the units for time. For example, `5d` or `7h`. For more information, see [Supported units]({{site.url}}{{site.baseurl}}/opensearch/units/). +include_unloaded_segments | Boolean | Whether to include information from segments not loaded into memory. Default is false. + + +## Response + +```json +ip | heap.percent | ram.percent | cpu load_1m | load_5m | load_15m | node.role | master | name +172.18.0.3 | 31 | 97 | 3 | 0.03 | 0.10 | 0.14 dimr | * | odfe-node2 +172.18.0.4 | 45 | 97 | 3 | 0.19 | 0.14 | 0.15 dimr | - | odfe-node1 +``` diff --git a/_opensearch/rest-api/cat/cat-pending-tasks.md b/_opensearch/rest-api/cat/cat-pending-tasks.md new file mode 100644 index 00000000..eb6f6a35 --- /dev/null +++ b/_opensearch/rest-api/cat/cat-pending-tasks.md @@ -0,0 +1,44 @@ +--- +layout: default +title: cat pending tasks +parent: CAT +grand_parent: REST API reference +nav_order: 45 +has_children: false +--- + +# cat pending tasks + +The cat pending tasks operation lists the progress of all pending tasks, including task priority and time in queue. + +## Example + +``` +GET _cat/pending_tasks?v +``` + +## Path and HTTP methods + +``` +GET _cat/pending_tasks +``` + +## URL parameters + +All cat nodes URL parameters are optional. + +In addition to the [common URL parameters]({{site.url}}{{site.baseurl}}/opensearch/rest-api/cat/index#common-url-parameters), you can specify the following parameters: + +Parameter | Type | Description +:--- | :--- | :--- +local | Boolean | Whether to return information from the local node only instead of from the master node. Default is false. +master_timeout | Time | The amount of time to wait for a connection to the master node. Default is 30 seconds. +time | Time | Specify the units for time. For example, `5d` or `7h`. For more information, see [Supported units]({{site.url}}{{site.baseurl}}/opensearch/units/). + + +## Response + +```json +insertOrder | timeInQueue | priority | source + 1786 | 1.8s | URGENT | shard-started +``` diff --git a/_opensearch/rest-api/cat/cat-plugins.md b/_opensearch/rest-api/cat/cat-plugins.md new file mode 100644 index 00000000..6f7f7c3e --- /dev/null +++ b/_opensearch/rest-api/cat/cat-plugins.md @@ -0,0 +1,62 @@ +--- +layout: default +title: cat plugins +parent: CAT +grand_parent: REST API reference +nav_order: 50 +has_children: false +--- + +# cat plugins + +The cat plugins operation lists the names, components, and versions of the installed plugins. + +## Example + +``` +GET _cat/plugins?v +``` + +## Path and HTTP methods + +``` +GET _cat/plugins +``` + +## URL parameters + +All cat plugins URL parameters are optional. + +In addition to the [common URL parameters]({{site.url}}{{site.baseurl}}/opensearch/rest-api/cat/index#common-url-parameters), you can specify the following parameters: + +Parameter | Type | Description +:--- | :--- | :--- +local | Boolean | Whether to return information from the local node only instead of from the master node. Default is false. +master_timeout | Time | The amount of time to wait for a connection to the master node. Default is 30 seconds. + + +## Response + +```json +name component version +odfe-node2 opendistro-alerting 1.13.1.0 +odfe-node2 opendistro-anomaly-detection 1.13.0.0 +odfe-node2 opendistro-asynchronous-search 1.13.0.1 +odfe-node2 opendistro-index-management 1.13.2.0 +odfe-node2 opendistro-job-scheduler 1.13.0.0 +odfe-node2 opendistro-knn 1.13.0.0 +odfe-node2 opendistro-performance-analyzer 1.13.0.0 +odfe-node2 opendistro-reports-scheduler 1.13.0.0 +odfe-node2 opendistro-sql 1.13.2.0 +odfe-node2 opendistro_security 1.13.1.0 +odfe-node1 opendistro-alerting 1.13.1.0 +odfe-node1 opendistro-anomaly-detection 1.13.0.0 +odfe-node1 opendistro-asynchronous-search 1.13.0.1 +odfe-node1 opendistro-index-management 1.13.2.0 +odfe-node1 opendistro-job-scheduler 1.13.0.0 +odfe-node1 opendistro-knn 1.13.0.0 +odfe-node1 opendistro-performance-analyzer 1.13.0.0 +odfe-node1 opendistro-reports-scheduler 1.13.0.0 +odfe-node1 opendistro-sql 1.13.2.0 +odfe-node1 opendistro_security 1.13.1.0 +``` diff --git a/_opensearch/rest-api/cat/cat-recovery.md b/_opensearch/rest-api/cat/cat-recovery.md new file mode 100644 index 00000000..b5aec967 --- /dev/null +++ b/_opensearch/rest-api/cat/cat-recovery.md @@ -0,0 +1,57 @@ +--- +layout: default +title: cat recovery +parent: CAT +grand_parent: REST API reference +nav_order: 50 +has_children: false +--- + +# cat recovery + +The cat recovery operation lists all completed and ongoing index and shard recoveries. + +## Example + +``` +GET _cat/recovery?v +``` + +To see only the recoveries of a specific index, add the index name after your query. + +``` +GET _cat/recovery/?v +``` + +If you want to get information for more than one index, separate the indices with commas: + +```json +GET _cat/aliases/index1,index2,index3 +``` + +## Path and HTTP methods + +``` +GET _cat/recovery +``` + +## URL parameters + +All cat recovery URL parameters are optional. + +In addition to the [common URL parameters]({{site.url}}{{site.baseurl}}/opensearch/rest-api/cat/index#common-url-parameters), you can specify the following parameters: + +Parameter | Type | Description +:--- | :--- | :--- +active_only | Boolean | Whether to only include ongoing shard recoveries. Default is false. +bytes | Byte size | Specify the units for byte size. For example, `7kb` or `6gb`. For more information, see [Supported units]({{site.url}}{{site.baseurl}}/opensearch/units/). +detailed | Boolean | Whether to include detailed information about shard recoveries. Default is false. +time | Time | Specify the units for time. For example, `5d` or `7h`. For more information, see [Supported units]({{site.url}}{{site.baseurl}}/opensearch/units/). + +## Response + +```json +index | shard | time | type | stage | source_host | source_node | target_host | target_node | repository | snapshot | files | files_recovered | files_percent | files_total | bytes | bytes_recovered | bytes_percent | bytes_total | translog_ops | translog_ops_recovered | translog_ops_percent +movies | 0 | 117ms | empty_store | done | n/a | n/a | 172.18.0.4 | odfe-node1 | n/a | n/a | 0 | 0 | 0.0% | 0 | 0 | 0 | 0.0% | 0 | 0 | 0 | 100.0% +movies | 0 | 382ms | peer | done | 172.18.0.4 | odfe-node1 | 172.18.0.3 | odfe-node2 | n/a | n/a | 1 | 1 | 100.0% | 1 | 208 | 208 | 100.0% | 208 | 1 | 1 | 100.0% +``` diff --git a/_opensearch/rest-api/cat/cat-repositories.md b/_opensearch/rest-api/cat/cat-repositories.md new file mode 100644 index 00000000..2b6129bd --- /dev/null +++ b/_opensearch/rest-api/cat/cat-repositories.md @@ -0,0 +1,44 @@ +--- +layout: default +title: cat repositories +parent: CAT +grand_parent: REST API reference +nav_order: 55 +has_children: false +--- + +# cat repositories + +The cat repositories operation lists all completed and ongoing index and shard recoveries. + +## Example + +``` +GET _cat/repositories?v +``` + +## Path and HTTP methods + +``` +GET _cat/repositories +``` + +## URL parameters + +All cat repositories URL parameters are optional. + +In addition to the [common URL parameters]({{site.url}}{{site.baseurl}}/opensearch/rest-api/cat/index#common-url-parameters), you can specify the following parameters: + +Parameter | Type | Description +:--- | :--- | :--- +local | Boolean | Whether to return information from the local node only instead of from the master node. Default is false. +master_timeout | Time | The amount of time to wait for a connection to the master node. Default is 30 seconds. + + +## Response + +```json +id type +repo1 fs +repo2 s3 +``` diff --git a/_opensearch/rest-api/cat/cat-segments.md b/_opensearch/rest-api/cat/cat-segments.md new file mode 100644 index 00000000..de4f0c7c --- /dev/null +++ b/_opensearch/rest-api/cat/cat-segments.md @@ -0,0 +1,55 @@ +--- +layout: default +title: cat segments +parent: CAT +grand_parent: REST API reference +nav_order: 55 +has_children: false +--- + +# cat segments + +The cat segments operation lists Lucene segment-level information for each index. + +## Example + +``` +GET _cat/segments?v +``` + +To see only the information about segments of a specific index, add the index name after your query. + +``` +GET _cat/segments/?v +``` + +If you want to get information for more than one index, separate the indices with commas: + +``` +GET _cat/segments/index1,index2,index3 +``` + +## Path and HTTP methods + +``` +GET _cat/segments +``` + +## URL parameters + +All cat segments URL parameters are optional. + +In addition to the [common URL parameters]({{site.url}}{{site.baseurl}}/opensearch/rest-api/cat/index#common-url-parameters), you can specify the following parameter: + +Parameter | Type | Description +:--- | :--- | :--- +bytes | Byte size | Specify the units for byte size. For example, `7kb` or `6gb`. For more information, see [Supported units]({{site.url}}{{site.baseurl}}/opensearch/units/).. + + +## Response + +```json +index | shard | prirep | ip | segment | generation | docs.count | docs.deleted | size | size.memory | committed | searchable | version | compound +movies | 0 | p | 172.18.0.4 | _0 | 0 | 1 | 0 | 3.5kb | 1364 | true | true | 8.7.0 | true +movies | 0 | r | 172.18.0.3 | _0 | 0 | 1 | 0 | 3.5kb | 1364 | true | true | 8.7.0 | true +``` diff --git a/_opensearch/rest-api/cat/cat-shards.md b/_opensearch/rest-api/cat/cat-shards.md new file mode 100644 index 00000000..b040ab6a --- /dev/null +++ b/_opensearch/rest-api/cat/cat-shards.md @@ -0,0 +1,58 @@ +--- +layout: default +title: cat shards +parent: CAT +grand_parent: REST API reference +nav_order: 60 +has_children: false +--- + +# cat shards + +The cat shards operation lists the state of all primary and replica shards and how they are distributed. + +## Example + +``` +GET _cat/shards?v +``` + +To see only the information about shards of a specific index, add the index name after your query. + +``` +GET _cat/shards/?v +``` + +If you want to get information for more than one index, separate the indices with commas: + +``` +GET _cat/shards/index1,index2,index3 +``` + +## Path and HTTP methods + +``` +GET _cat/shards +``` + +## URL parameters + +All cat shards URL parameters are optional. + +In addition to the [common URL parameters]({{site.url}}{{site.baseurl}}/opensearch/rest-api/cat/index#common-url-parameters), you can specify the following parameter: + +Parameter | Type | Description +:--- | :--- | :--- +bytes | Byte size | Specify the units for byte size. For example, `7kb` or `6gb`. For more information, see [Supported units]({{site.url}}{{site.baseurl}}/opensearch/units/). +local | Boolean | Whether to return information from the local node only instead of from the master node. Default is false. +master_timeout | Time | The amount of time to wait for a connection to the master node. Default is 30 seconds. +time | Time | Specify the units for time. For example, `5d` or `7h`. For more information, see [Supported units]({{site.url}}{{site.baseurl}}/opensearch/units/). + + +## Response + +```json +index | shard | prirep | state | docs | store | ip | | node +plugins | 0 | p | STARTED | 0 | 208b | 172.18.0.4 | odfe-node1 +plugins | 0 | r | STARTED | 0 | 208b | 172.18.0.3 | odfe-node2 +``` diff --git a/_opensearch/rest-api/cat/cat-snapshots.md b/_opensearch/rest-api/cat/cat-snapshots.md new file mode 100644 index 00000000..aafe9caa --- /dev/null +++ b/_opensearch/rest-api/cat/cat-snapshots.md @@ -0,0 +1,44 @@ +--- +layout: default +title: cat snapshots +parent: CAT +grand_parent: REST API reference +nav_order: 65 +has_children: false +--- + +# cat snapshots + +The cat snapshots operation lists all snapshots for a repository. + +## Example + +``` +GET _cat/snapshots?v +``` + +## Path and HTTP methods + +``` +GET _cat/snapshots +``` + +## URL parameters + +All cat snapshots URL parameters are optional. + +In addition to the [common URL parameters]({{site.url}}{{site.baseurl}}/opensearch/rest-api/cat/index#common-url-parameters), you can specify the following parameter: + +Parameter | Type | Description +:--- | :--- | :--- +master_timeout | Time | The amount of time to wait for a connection to the master node. Default is 30 seconds. +time | Time | Specify the units for time. For example, `5d` or `7h`. For more information, see [Supported units]({{site.url}}{{site.baseurl}}/opensearch/units/). + + +## Response + +```json +index | shard | prirep | state | docs | store | ip | | node +plugins | 0 | p | STARTED | 0 | 208b | 172.18.0.4 | odfe-node1 +plugins | 0 | r | STARTED | 0 | 208b | 172.18.0.3 | odfe-node2 +``` diff --git a/_opensearch/rest-api/cat/cat-tasks.md b/_opensearch/rest-api/cat/cat-tasks.md new file mode 100644 index 00000000..7dbccb73 --- /dev/null +++ b/_opensearch/rest-api/cat/cat-tasks.md @@ -0,0 +1,45 @@ +--- +layout: default +title: cat tasks +parent: CAT +grand_parent: REST API reference +nav_order: 70 +has_children: false +--- + +# cat tasks + +The cat tasks operation lists the progress of all tasks currently running on your cluster. + +## Example + +``` +GET _cat/tasks?v +``` + +## Path and HTTP methods + +``` +GET _cat/tasks +``` + +## URL parameters + +All cat tasks URL parameters are optional. + +In addition to the [common URL parameters]({{site.url}}{{site.baseurl}}/opensearch/rest-api/cat/index#common-url-parameters), you can specify the following parameter: + +Parameter | Type | Description +:--- | :--- | :--- +nodes | List | A comma-separated list of node IDs or names to limit the returned information. Use `_local` to return information from the node you're connecting to, specify the node name to get information from specific nodes, or keep the parameter empty to get information from all nodes. +detailed | Boolean | Returns detailed task information. (Default: false) +parent_task_id | String | Returns tasks with a specified parent task ID (node_id:task_number). Keep empty or set to -1 to return all. +time | Time | Specify the units for time. For example, `5d` or `7h`. For more information, see [Supported units]({{site.url}}{{site.baseurl}}/opensearch/units/). + + +## Response + +```json +action | task_id | parent_task_id | type | start_time | timestamp | running_time | ip | node +cluster:monitor/tasks/lists | 1vo54NuxSxOrbPEYdkSF0w:168062 | - | transport | 1624337809471 | 04:56:49 | 489.5ms | 172.18.0.4 | odfe-node1 +``` diff --git a/_opensearch/rest-api/cat/cat-templates.md b/_opensearch/rest-api/cat/cat-templates.md new file mode 100644 index 00000000..ff4035fb --- /dev/null +++ b/_opensearch/rest-api/cat/cat-templates.md @@ -0,0 +1,51 @@ +--- +layout: default +title: cat templates +parent: CAT +grand_parent: REST API reference +nav_order: 70 +has_children: false +--- + +# cat templates + +The cat templates operation lists the names, patterns, order numbers, and version numbers of index templates. + +## Example + +``` +GET _cat/templates?v +``` + +If you want to get information for more than one template, separate the template names with commas: + +``` +GET _cat/shards/template_name_1,template_name_2,template_name_3 +``` + +## Path and HTTP methods + +``` +GET _cat/templates +``` + +## URL parameters + +All cat templates URL parameters are optional. + +In addition to the [common URL parameters]({{site.url}}{{site.baseurl}}/opensearch/rest-api/cat/index#common-url-parameters), you can specify the following parameter: + +Parameter | Type | Description +:--- | :--- | :--- +local | Boolean | Whether to return information from the local node only instead of from the master node. Default is false. +master_timeout | Time | The amount of time to wait for a connection to the master node. Default is 30 seconds. + + +## Response + +``` +name | index_patterns order version composed_of +tenant_template | [kibana*] | 0 | +``` + +To learn more about index templates, see [Index templates]({{site.url}}{{site.baseurl}}/opensearch/index-templates). diff --git a/_opensearch/rest-api/cat/cat-thread-pool.md b/_opensearch/rest-api/cat/cat-thread-pool.md new file mode 100644 index 00000000..0f55d715 --- /dev/null +++ b/_opensearch/rest-api/cat/cat-thread-pool.md @@ -0,0 +1,51 @@ +--- +layout: default +title: cat thread pool +parent: CAT +grand_parent: REST API reference +nav_order: 75 +has_children: false +--- + +# cat thread pool + +The cat thread pool operation lists the active, queued, and rejected threads of different thread pools on each node. + +## Example + +``` +GET _cat/thread_pool?v +``` + +If you want to get information for more than one thread pool, separate the thread pool names with commas: + +``` +GET _cat/v/thread_pool_name_1,thread_pool_name_2,thread_pool_name_3 +``` + +## Path and HTTP methods + +``` +GET _cat/thread_pool +``` + +## URL parameters + +All cat thread pool URL parameters are optional. + +In addition to the [common URL parameters]({{site.url}}{{site.baseurl}}/opensearch/rest-api/cat/index#common-url-parameters), you can specify the following parameter: + +Parameter | Type | Description +:--- | :--- | :--- +local | Boolean | Whether to return information from the local node only instead of from the master node. Default is false. +master_timeout | Time | The amount of time to wait for a connection to the master node. Default is 30 seconds. + + +## Response + +```json +node_name name active queue rejected +odfe-node2 ad-batch-task-threadpool 0 0 0 +odfe-node2 ad-threadpool 0 0 0 +odfe-node2 analyze 0 0 0s +``` diff --git a/_opensearch/rest-api/cat/index.md b/_opensearch/rest-api/cat/index.md new file mode 100644 index 00000000..c5376636 --- /dev/null +++ b/_opensearch/rest-api/cat/index.md @@ -0,0 +1,58 @@ +--- +layout: default +title: CAT +parent: REST API reference +nav_order: 100 +has_children: true +redirect_from: + - /opensearch/catapis/ +--- + +# cat API + +You can get essential statistics about your cluster in an easy-to-understand, tabular format using the compact and aligned text (CAT) API. The cat API is a human-readable interface that returns plain text instead of traditional JSON. + +Using the cat API, you can answer questions like which node is the elected master, what state is the cluster in, how many documents are in each index, and so on. + +## Example + +To see the available operations in the cat API, use the following command: + +``` +GET _cat +``` + +## Common URL parameters + +You can use the following string parameters with your query. + +Parameter | Description +:--- | :--- | +`?v` | Makes the output more verbose 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` | Outputs the result in JSON, YAML, or CBOR formats. +`?sort` | Sorts the output by the specified columns. + +To see what each column represents, use the `?v` parameter: + +``` +GET _cat/?v +``` + +To see all the available headers, use the `?help` parameter: + +``` +GET _cat/?help +``` + +To limit the output to a subset of headers, use the `?h` parameter: + +``` +GET _cat/?h=,&v +``` + +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. + +If you use the security plugin, make sure you have the appropriate permissions. +{: .note }