2013-11-14 20:14:39 -05:00
|
|
|
[[cat-indices]]
|
2019-08-13 08:35:08 -04:00
|
|
|
=== cat indices API
|
|
|
|
|
++++
|
|
|
|
|
<titleabbrev>cat indices</titleabbrev>
|
|
|
|
|
++++
|
2013-11-14 20:14:39 -05:00
|
|
|
|
2020-06-30 15:52:48 -04:00
|
|
|
Returns high-level information about indices in a cluster, including backing
|
|
|
|
|
indices for data streams.
|
2013-11-14 20:14:39 -05:00
|
|
|
|
2016-10-11 08:46:59 -04:00
|
|
|
|
2019-08-07 09:08:09 -04:00
|
|
|
[[cat-indices-api-request]]
|
|
|
|
|
==== {api-request-title}
|
2016-10-11 08:46:59 -04:00
|
|
|
|
2020-06-30 15:52:48 -04:00
|
|
|
`GET /_cat/indices/<target>`
|
2013-11-14 20:14:39 -05:00
|
|
|
|
2019-10-10 09:48:40 -04:00
|
|
|
`GET /_cat/indices`
|
|
|
|
|
|
2013-11-14 20:14:39 -05:00
|
|
|
|
2019-08-07 09:08:09 -04:00
|
|
|
[[cat-indices-api-desc]]
|
|
|
|
|
==== {api-description-title}
|
2017-04-17 21:52:29 -04:00
|
|
|
|
2019-08-07 09:08:09 -04:00
|
|
|
Use the cat indices API to get the following information for each index in a
|
|
|
|
|
cluster:
|
2017-04-17 21:52:29 -04:00
|
|
|
|
2019-08-07 09:08:09 -04:00
|
|
|
* Shard count
|
|
|
|
|
* Document count
|
|
|
|
|
* Deleted document count
|
|
|
|
|
* Primary store size
|
|
|
|
|
* Total store size of all shards, including shard replicas
|
2017-04-17 21:52:29 -04:00
|
|
|
|
2019-08-07 09:08:09 -04:00
|
|
|
These metrics are retrieved directly from
|
|
|
|
|
https://lucene.apache.org/core/[Lucene], which {es} uses internally to power
|
|
|
|
|
indexing and search. As a result, all document counts include hidden
|
|
|
|
|
<<nested,nested>> documents.
|
2014-01-13 15:18:14 -05:00
|
|
|
|
2019-08-07 09:08:09 -04:00
|
|
|
To get an accurate count of {es} documents, use the <<cat-count,cat count>> or
|
|
|
|
|
<<search-count,count>> APIs.
|
2014-01-13 15:18:14 -05:00
|
|
|
|
2013-11-14 20:14:39 -05:00
|
|
|
|
2019-08-07 09:08:09 -04:00
|
|
|
[[cat-indices-api-path-params]]
|
|
|
|
|
==== {api-path-parms-title}
|
2013-11-14 20:14:39 -05:00
|
|
|
|
2020-06-30 15:52:48 -04:00
|
|
|
`<target>`::
|
|
|
|
|
(Optional, string)
|
2020-06-30 15:55:37 -04:00
|
|
|
Comma-separated list of data streams, indices, and index aliases used to limit
|
|
|
|
|
the request. Wildcard expressions (`*`) are supported.
|
2020-06-30 15:52:48 -04:00
|
|
|
+
|
|
|
|
|
To target all data streams and indices in a cluster, omit this parameter or use
|
|
|
|
|
`_all` or `*`.
|
2016-10-11 08:46:59 -04:00
|
|
|
|
2019-08-07 09:08:09 -04:00
|
|
|
[[cat-indices-api-query-params]]
|
|
|
|
|
==== {api-query-parms-title}
|
2013-11-14 20:14:39 -05:00
|
|
|
|
2020-06-01 19:42:53 -04:00
|
|
|
include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=bytes]
|
2013-11-14 20:14:39 -05:00
|
|
|
|
2020-06-01 19:42:53 -04:00
|
|
|
include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=http-format]
|
2016-10-11 08:46:59 -04:00
|
|
|
|
2020-06-01 19:42:53 -04:00
|
|
|
include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=cat-h]
|
2016-10-11 08:46:59 -04:00
|
|
|
|
2019-08-07 09:08:09 -04:00
|
|
|
`health`::
|
|
|
|
|
+
|
|
|
|
|
--
|
|
|
|
|
(Optional, string) Health status used to limit returned indices. Valid values
|
|
|
|
|
are:
|
2016-10-11 08:46:59 -04:00
|
|
|
|
2019-08-07 09:08:09 -04:00
|
|
|
* `green`
|
|
|
|
|
* `yellow`
|
|
|
|
|
* `red`
|
2016-10-11 08:46:59 -04:00
|
|
|
|
2019-08-07 09:08:09 -04:00
|
|
|
By default, the response includes indices of any health status.
|
|
|
|
|
--
|
2014-01-13 15:18:14 -05:00
|
|
|
|
2020-06-01 19:42:53 -04:00
|
|
|
include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=help]
|
2014-01-13 15:18:14 -05:00
|
|
|
|
2020-06-01 19:42:53 -04:00
|
|
|
include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=include-unloaded-segments]
|
2014-09-22 16:03:50 -04:00
|
|
|
|
2020-06-01 19:42:53 -04:00
|
|
|
include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=local]
|
2014-09-22 16:03:50 -04:00
|
|
|
|
2020-06-01 19:42:53 -04:00
|
|
|
include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=master-timeout]
|
2019-08-07 09:08:09 -04:00
|
|
|
|
|
|
|
|
[[pri-flag]]
|
|
|
|
|
`pri` (primary shards)::
|
|
|
|
|
(Optional, boolean) If `true`, the response only includes information from
|
|
|
|
|
primary shards. Defaults to `false`.
|
|
|
|
|
|
2020-06-01 19:42:53 -04:00
|
|
|
include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=cat-s]
|
2019-08-07 09:08:09 -04:00
|
|
|
|
2020-06-01 19:42:53 -04:00
|
|
|
include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=time]
|
2019-10-10 09:48:40 -04:00
|
|
|
|
2020-06-01 19:42:53 -04:00
|
|
|
include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=cat-v]
|
2019-08-07 09:08:09 -04:00
|
|
|
|
2020-06-01 19:42:53 -04:00
|
|
|
include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=expand-wildcards]
|
2020-05-29 13:01:53 -04:00
|
|
|
|
2019-08-07 09:08:09 -04:00
|
|
|
|
|
|
|
|
[[cat-indices-api-example]]
|
|
|
|
|
==== {api-examples-title}
|
|
|
|
|
|
|
|
|
|
[[examples]]
|
2019-09-09 13:38:14 -04:00
|
|
|
[source,console]
|
2016-10-11 08:46:59 -04:00
|
|
|
--------------------------------------------------
|
2020-08-03 10:22:36 -04:00
|
|
|
GET /_cat/indices/my-index-*?v&s=index
|
2016-10-11 08:46:59 -04:00
|
|
|
--------------------------------------------------
|
2020-08-03 10:22:36 -04:00
|
|
|
// TEST[setup:my_index_huge]
|
|
|
|
|
// TEST[s/^/PUT my-index-000002\n{"settings": {"number_of_replicas": 0}}\n/]
|
2016-10-11 08:46:59 -04:00
|
|
|
|
2019-08-07 09:08:09 -04:00
|
|
|
The API returns the following response:
|
2016-10-11 08:46:59 -04:00
|
|
|
|
Enforce that responses in docs are valid json (#26249)
All of the snippets in our docs marked with `// TESTRESPONSE` are
checked against the response from Elasticsearch but, due to the
way they are implemented they are actually parsed as YAML instead
of JSON. Luckilly, all valid JSON is valid YAML! Unfurtunately
that means that invalid JSON has snuck into the exmples!
This adds a step during the build to parse them as JSON and fail
the build if they don't parse.
But no! It isn't quite that simple. The displayed text of some of
these responses looks like:
```
{
...
"aggregations": {
"range": {
"buckets": [
{
"to": 1.4436576E12,
"to_as_string": "10-2015",
"doc_count": 7,
"key": "*-10-2015"
},
{
"from": 1.4436576E12,
"from_as_string": "10-2015",
"doc_count": 0,
"key": "10-2015-*"
}
]
}
}
}
```
Note the `...` which isn't valid json but we like it anyway and want
it in the output. We use substitution rules to convert the `...`
into the response we expect. That yields a response that looks like:
```
{
"took": $body.took,"timed_out": false,"_shards": $body._shards,"hits": $body.hits,
"aggregations": {
"range": {
"buckets": [
{
"to": 1.4436576E12,
"to_as_string": "10-2015",
"doc_count": 7,
"key": "*-10-2015"
},
{
"from": 1.4436576E12,
"from_as_string": "10-2015",
"doc_count": 0,
"key": "10-2015-*"
}
]
}
}
}
```
That is what the tests consume but it isn't valid JSON! Oh no! We don't
want to go update all the substitution rules because that'd be huge and,
ultimately, wouldn't buy much. So we quote the `$body.took` bits before
parsing the JSON.
Note the responses that we use for the `_cat` APIs are all converted into
regexes and there is no expectation that they are valid JSON.
Closes #26233
2017-08-17 09:02:10 -04:00
|
|
|
[source,txt]
|
2014-09-22 16:03:50 -04:00
|
|
|
--------------------------------------------------
|
2020-08-03 10:22:36 -04:00
|
|
|
health status index uuid pri rep docs.count docs.deleted store.size pri.store.size
|
|
|
|
|
yellow open my-index-000001 u8FNjxh8Rfy_awN11oDKYQ 1 1 1200 0 88.1kb 88.1kb
|
|
|
|
|
green open my-index-000002 nYFWZEO7TUiOjLQXBaYJpA 1 0 0 0 260b 260b
|
2014-09-22 16:03:50 -04:00
|
|
|
--------------------------------------------------
|
2016-10-11 08:46:59 -04:00
|
|
|
// TESTRESPONSE[s/\d+(\.\d+)?[tgmk]?b/\\d+(\\.\\d+)?[tgmk]?b/]
|
2019-08-07 09:08:09 -04:00
|
|
|
// TESTRESPONSE[s/u8FNjxh8Rfy_awN11oDKYQ|nYFWZEO7TUiOjLQXBaYJpA/.+/ non_json]
|
