iSharkFly-Docs
/
opensearch-docs-cn
mirror of https://github.com/iSharkFly-Docs/opensearch-docs-cn
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #58 from opensearch-project/cat_api 

added cat apis to rest api reference
This commit is contained in:
Andrew Etter 2021-06-22 11:56:49 -07:00 committed by GitHub
parent cfd782d857 c38f9f9905
commit df471fb310
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
21 changed files with 1037 additions and 256 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

256
_opensearch/catapis.md
View File

@ -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/<operation_name>?v
```
To see all the available headers, use the `?help` parameter:
```
GET _cat/<operation_name>?help
```
To limit the output to a subset of headers, use the `?h` parameter:
```
GET _cat/<operation_name>?h=<header_name_1>,<header_name_2>&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/<alias>?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/<index>?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/<fields>?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/<index>?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/<index>?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/<index>?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/<index>?v
```
## Snapshots
Lists all snapshots for a repository.
```
GET _cat/snapshots/<repository>?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/<thread_pool>?v
```

61
_opensearch/rest-api/cat/cat-aliases.md Normal file
View File

@ -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/<alias>?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/<alias>
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).

61
_opensearch/rest-api/cat/cat-allocation.md Normal file
View File

@ -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/<node_name>
```
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/<node_name>
```
## 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
```

51
_opensearch/rest-api/cat/cat-count.md Normal file
View File

@ -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/<index_or_alias>?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/<index>?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
```

57
_opensearch/rest-api/cat/cat-field-data.md Normal file
View File

@ -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/<field_name>?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/<field_name>?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
```

42
_opensearch/rest-api/cat/cat-health.md Normal file
View File

@ -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%
```

61
_opensearch/rest-api/cat/cat-indices.md Normal file
View File

@ -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/<index>?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/<index>
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
```

42
_opensearch/rest-api/cat/cat-master.md Normal file
View File

@ -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
```

43
_opensearch/rest-api/cat/cat-nodeattrs.md Normal file
View File

@ -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
```

50
_opensearch/rest-api/cat/cat-nodes.md Normal file
View File

@ -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
```

44
_opensearch/rest-api/cat/cat-pending-tasks.md Normal file
View File

@ -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
```

62
_opensearch/rest-api/cat/cat-plugins.md Normal file
View File

@ -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
```

57
_opensearch/rest-api/cat/cat-recovery.md Normal file
View File

@ -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/<index>?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%
```

44
_opensearch/rest-api/cat/cat-repositories.md Normal file
View File

@ -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
```

55
_opensearch/rest-api/cat/cat-segments.md Normal file
View File

@ -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/<index>?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
```

58
_opensearch/rest-api/cat/cat-shards.md Normal file
View File

@ -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/<index>?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
```

44
_opensearch/rest-api/cat/cat-snapshots.md Normal file
View File

@ -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
```

45
_opensearch/rest-api/cat/cat-tasks.md Normal file
View File

@ -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
```

51
_opensearch/rest-api/cat/cat-templates.md Normal file
View File

@ -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).

51
_opensearch/rest-api/cat/cat-thread-pool.md Normal file
View File

@ -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
```

58
_opensearch/rest-api/cat/index.md Normal file
View File

@ -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/<operation_name>?v
```
To see all the available headers, use the `?help` parameter:
```
GET _cat/<operation_name>?help
```
To limit the output to a subset of headers, use the `?h` parameter:
```
GET _cat/<operation_name>?h=<header_name_1>,<header_name_2>&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 }