[DOCS] Reformats cat indices API (#45239)

Author: jrodewig

docs/reference/cat/indices.asciidoc

@@ -1,125 +1,101 @@
 [[cat-indices]]
 === cat indices
 
-The `indices` command provides a cross-section of each index.  This
-information *spans nodes*. For example:
+Returns high-level information about indices in a cluster.
 
-[source,js]
---------------------------------------------------
-GET /_cat/indices/twi*?v&s=index
---------------------------------------------------
-// CONSOLE
-// TEST[setup:huge_twitter]
-// TEST[s/^/PUT twitter2\n{"settings": {"number_of_replicas": 0}}\n/]
 
-Might respond with:
+[[cat-indices-api-request]]
+==== {api-request-title}
 
-[source,txt]
---------------------------------------------------
-health status index    uuid                   pri rep docs.count docs.deleted store.size pri.store.size
-yellow open   twitter  u8FNjxh8Rfy_awN11oDKYQ   1   1       1200            0     88.1kb         88.1kb
-green  open   twitter2 nYFWZEO7TUiOjLQXBaYJpA   1   0          0            0       260b           260b
---------------------------------------------------
-// TESTRESPONSE[s/\d+(\.\d+)?[tgmk]?b/\\d+(\\.\\d+)?[tgmk]?b/]
-// TESTRESPONSE[s/u8FNjxh8Rfy_awN11oDKYQ|nYFWZEO7TUiOjLQXBaYJpA/.+/ non_json]
+`GET /_cat/indices/{index}`
 
-We can tell quickly how many shards make up an index, the number of
-docs, deleted docs, primary store size, and total store size (all shards including replicas).
-All these exposed metrics come directly from Lucene APIs.
 
-*Notes:*
+[[cat-indices-api-desc]]
+==== {api-description-title}
 
-1. As the number of documents and deleted documents shown in this are at the lucene level,
-it includes all the hidden documents (e.g. from nested documents) as well.
+Use the cat indices API to get the following information for each index in a
+cluster:
 
-2. To get actual count of documents at the Elasticsearch level, the recommended way
-is to use either the <<cat-count>> or the <<search-count>>
+* Shard count
+* Document count
+* Deleted document count
+* Primary store size
+* Total store size of all shards, including shard replicas
 
-[float]
-[[pri-flag]]
-==== Primaries
+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.
 
-The index stats by default will show them for all of an index's
-shards, including replicas.  A `pri` flag can be supplied to enable
-the view of relevant stats in the context of only the primaries.
+To get an accurate count of {es} documents, use the <<cat-count,cat count>> or
+<<search-count,count>> APIs.
 
-[float]
-[[examples]]
-==== Examples
 
-Which indices are yellow?
+[[cat-indices-api-path-params]]
+==== {api-path-parms-title}
 
-[source,js]
---------------------------------------------------
-GET /_cat/indices?v&health=yellow
---------------------------------------------------
-// CONSOLE
-// TEST[continued]
+include::{docdir}/rest-api/common-parms.asciidoc[tag=index]
 
-Which looks like:
 
-[source,txt]
---------------------------------------------------
-health status index    uuid                   pri rep docs.count docs.deleted store.size pri.store.size
-yellow open   twitter  u8FNjxh8Rfy_awN11oDKYQ   1   1       1200            0     88.1kb         88.1kb
---------------------------------------------------
-// TESTRESPONSE[s/\d+(\.\d+)?[tgmk]?b/\\d+(\\.\\d+)?[tgmk]?b/]
-// TESTRESPONSE[s/u8FNjxh8Rfy_awN11oDKYQ/.+/ non_json]
+[[cat-indices-api-query-params]]
+==== {api-query-parms-title}
 
-Which index has the largest number of documents?
+include::{docdir}/rest-api/common-parms.asciidoc[tag=bytes]
 
-[source,js]
---------------------------------------------------
-GET /_cat/indices?v&s=docs.count:desc
---------------------------------------------------
-// CONSOLE
-// TEST[continued]
+include::{docdir}/rest-api/common-parms.asciidoc[tag=http-format]
 
-Which looks like:
+include::{docdir}/rest-api/common-parms.asciidoc[tag=cat-h]
 
-[source,txt]
---------------------------------------------------
-health status index    uuid                   pri rep docs.count docs.deleted store.size pri.store.size
-yellow open   twitter  u8FNjxh8Rfy_awN11oDKYQ   1   1       1200            0     88.1kb         88.1kb
-green  open   twitter2 nYFWZEO7TUiOjLQXBaYJpA   1   0          0            0       260b           260b
---------------------------------------------------
-// TESTRESPONSE[s/\d+(\.\d+)?[tgmk]?b/\\d+(\\.\\d+)?[tgmk]?b/]
-// TESTRESPONSE[s/u8FNjxh8Rfy_awN11oDKYQ|nYFWZEO7TUiOjLQXBaYJpA/.+/ non_json]
+`health`::
++
+--
+(Optional, string) Health status used to limit returned indices. Valid values
+are:
 
-How many merge operations have the shards for the `twitter` completed?
+* `green`
+* `yellow`
+* `red`
 
-[source,js]
---------------------------------------------------
-GET /_cat/indices/twitter?pri&v&h=health,index,pri,rep,docs.count,mt
---------------------------------------------------
-// CONSOLE
-// TEST[continued]
+By default, the response includes indices of any health status.
+--
 
-Might look like:
+include::{docdir}/rest-api/common-parms.asciidoc[tag=help]
 
-[source,txt]
---------------------------------------------------
-health index   pri rep docs.count mt pri.mt
-yellow twitter   1   1 1200       16     16
---------------------------------------------------
-// TESTRESPONSE[s/16/\\d+/ non_json]
+include::{docdir}/rest-api/common-parms.asciidoc[tag=include-unloaded-segments]
 
-How much memory is used per index?
+include::{docdir}/rest-api/common-parms.asciidoc[tag=local]
 
+include::{docdir}/rest-api/common-parms.asciidoc[tag=master-timeout]
+
+[[pri-flag]]
+`pri` (primary shards)::
+(Optional, boolean) If `true`, the response only includes information from
+primary shards. Defaults to `false`.
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=cat-s]
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=cat-v]
+
+
+[[cat-indices-api-example]]
+==== {api-examples-title}
+
+[[examples]]
 [source,js]
 --------------------------------------------------
-GET /_cat/indices?v&h=i,tm&s=tm:desc
+GET /_cat/indices/twi*?v&s=index
 --------------------------------------------------
 // CONSOLE
-// TEST[continued]
+// TEST[setup:huge_twitter]
+// TEST[s/^/PUT twitter2\n{"settings": {"number_of_replicas": 0}}\n/]
 
-Might look like:
+The API returns the following response:
 
 [source,txt]
 --------------------------------------------------
-i         tm
-twitter   8.1gb
-twitter2  30.5kb
+health status index    uuid                   pri rep docs.count docs.deleted store.size pri.store.size
+yellow open   twitter  u8FNjxh8Rfy_awN11oDKYQ   1   1       1200            0     88.1kb         88.1kb
+green  open   twitter2 nYFWZEO7TUiOjLQXBaYJpA   1   0          0            0       260b           260b
 --------------------------------------------------
 // TESTRESPONSE[s/\d+(\.\d+)?[tgmk]?b/\\d+(\\.\\d+)?[tgmk]?b/]
-// TESTRESPONSE[non_json]
+// TESTRESPONSE[s/u8FNjxh8Rfy_awN11oDKYQ|nYFWZEO7TUiOjLQXBaYJpA/.+/ non_json]

docs/reference/rest-api/common-parms.asciidoc

@@ -22,10 +22,16 @@ https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html[HTTP accept header].
 Valid values include JSON, YAML, etc.
 end::http-format[]
 
+tag::include-unloaded-segments[]
+`include_unloaded_segments`::
+(Optional, boolean) If `true`, the response includes information from segments
+that are **not** loaded into memory. Defaults to `false`.
+end::include-unloaded-segments[]
+
 tag::index[]
 `{index}`::
-(Optional, string) Comma-separated list of index names used to limit returned
-information.
+(Optional, string) Comma-separated list or wildcard expression of index names
+used to limit the request.
 end::index[]
 
 tag::local[]