255 lines
7.2 KiB
Plaintext
255 lines
7.2 KiB
Plaintext
[[cat]]
|
|
== cat APIs
|
|
|
|
["float",id="intro"]
|
|
=== Introduction
|
|
|
|
JSON is great... for computers. Even if it's pretty-printed, trying
|
|
to find relationships in the data is tedious. Human eyes, especially
|
|
when looking at a terminal, need compact and aligned text. The cat API
|
|
aims to meet this need.
|
|
|
|
All the cat commands accept a query string parameter `help` to see all
|
|
the headers and info they provide, and the `/_cat` command alone lists all
|
|
the available commands.
|
|
|
|
[float]
|
|
[[common-parameters]]
|
|
=== Common parameters
|
|
|
|
[float]
|
|
[[verbose]]
|
|
==== Verbose
|
|
|
|
Each of the commands accepts a query string parameter `v` to turn on
|
|
verbose output. For example:
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
GET /_cat/master?v
|
|
--------------------------------------------------
|
|
|
|
Might respond with:
|
|
|
|
[source,txt]
|
|
--------------------------------------------------
|
|
id host ip node
|
|
u_n93zwxThWHi1PDBJAGAg 127.0.0.1 127.0.0.1 u_n93zw
|
|
--------------------------------------------------
|
|
// TESTRESPONSE[s/u_n93zw(xThWHi1PDBJAGAg)?/.+/ non_json]
|
|
|
|
[float]
|
|
[[help]]
|
|
==== Help
|
|
|
|
Each of the commands accepts a query string parameter `help` which will
|
|
output its available columns. For example:
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
GET /_cat/master?help
|
|
--------------------------------------------------
|
|
|
|
Might respond with:
|
|
|
|
[source,txt]
|
|
--------------------------------------------------
|
|
id | | node id
|
|
host | h | host name
|
|
ip | | ip address
|
|
node | n | node name
|
|
--------------------------------------------------
|
|
// TESTRESPONSE[s/[|]/[|]/ non_json]
|
|
|
|
NOTE: `help` is not supported if any optional url parameter is used.
|
|
For example `GET _cat/shards/twitter?help` or `GET _cat/indices/twi*?help`
|
|
results in an error. Use `GET _cat/shards?help` or `GET _cat/indices?help`
|
|
instead.
|
|
|
|
[float]
|
|
[[headers]]
|
|
==== Headers
|
|
|
|
Each of the commands accepts a query string parameter `h` which forces
|
|
only those columns to appear. For example:
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
GET /_cat/nodes?h=ip,port,heapPercent,name
|
|
--------------------------------------------------
|
|
|
|
Responds with:
|
|
|
|
[source,txt]
|
|
--------------------------------------------------
|
|
127.0.0.1 9300 27 sLBaIGK
|
|
--------------------------------------------------
|
|
// TESTRESPONSE[s/9300 27 sLBaIGK/\\d+ \\d+ .+/ non_json]
|
|
|
|
You can also request multiple columns using simple wildcards like
|
|
`/_cat/thread_pool?h=ip,queue*` to get all headers (or aliases) starting
|
|
with `queue`.
|
|
|
|
[float]
|
|
[[numeric-formats]]
|
|
==== Numeric formats
|
|
|
|
Many commands provide a few types of numeric output, either a byte, size
|
|
or a time value. By default, these types are human-formatted,
|
|
for example, `3.5mb` instead of `3763212`. The human values are not
|
|
sortable numerically, so in order to operate on these values where
|
|
order is important, you can change it.
|
|
|
|
Say you want to find the largest index in your cluster (storage used
|
|
by all the shards, not number of documents). The `/_cat/indices` API
|
|
is ideal. You only need to add three things to the API request:
|
|
|
|
. The `bytes` query string parameter with a value of `b` to get byte-level resolution.
|
|
. The `s` (sort) parameter with a value of `store.size:desc` to sort the output
|
|
by shard storage in descending order.
|
|
. The `v` (verbose) parameter to include column headings in the response.
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
GET /_cat/indices?bytes=b&s=store.size:desc&v
|
|
--------------------------------------------------
|
|
// TEST[setup:huge_twitter]
|
|
// TEST[s/^/PUT twitter2\n{"settings": {"number_of_replicas": 0}}\n/]
|
|
|
|
The API returns the following response:
|
|
|
|
[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 72171 72171
|
|
green open twitter2 nYFWZEO7TUiOjLQXBaYJpA 1 0 0 0 230 230
|
|
--------------------------------------------------
|
|
// TESTRESPONSE[s/72171|230/\\d+/]
|
|
// TESTRESPONSE[s/u8FNjxh8Rfy_awN11oDKYQ|nYFWZEO7TUiOjLQXBaYJpA/.+/ non_json]
|
|
|
|
If you want to change the <<time-units,time units>>, use `time` parameter.
|
|
|
|
If you want to change the <<size-units,size units>>, use `size` parameter.
|
|
|
|
If you want to change the <<byte-units,byte units>>, use `bytes` parameter.
|
|
|
|
[float]
|
|
==== Response as text, json, smile, yaml or cbor
|
|
|
|
[source,sh]
|
|
--------------------------------------------------
|
|
% curl 'localhost:9200/_cat/indices?format=json&pretty'
|
|
[
|
|
{
|
|
"pri.store.size": "650b",
|
|
"health": "yellow",
|
|
"status": "open",
|
|
"index": "twitter",
|
|
"pri": "5",
|
|
"rep": "1",
|
|
"docs.count": "0",
|
|
"docs.deleted": "0",
|
|
"store.size": "650b"
|
|
}
|
|
]
|
|
--------------------------------------------------
|
|
// NOTCONSOLE
|
|
|
|
Currently supported formats (for the `?format=` parameter):
|
|
- text (default)
|
|
- json
|
|
- smile
|
|
- yaml
|
|
- cbor
|
|
|
|
Alternatively you can set the "Accept" HTTP header to the appropriate media format.
|
|
All formats above are supported, the GET parameter takes precedence over the header.
|
|
For example:
|
|
|
|
[source,sh]
|
|
--------------------------------------------------
|
|
% curl '192.168.56.10:9200/_cat/indices?pretty' -H "Accept: application/json"
|
|
[
|
|
{
|
|
"pri.store.size": "650b",
|
|
"health": "yellow",
|
|
"status": "open",
|
|
"index": "twitter",
|
|
"pri": "5",
|
|
"rep": "1",
|
|
"docs.count": "0",
|
|
"docs.deleted": "0",
|
|
"store.size": "650b"
|
|
}
|
|
]
|
|
--------------------------------------------------
|
|
// NOTCONSOLE
|
|
|
|
[float]
|
|
[[sort]]
|
|
==== Sort
|
|
|
|
Each of the commands accepts a query string parameter `s` which sorts the table by
|
|
the columns specified as the parameter value. Columns are specified either by name or by
|
|
alias, and are provided as a comma separated string. By default, sorting is done in
|
|
ascending fashion. Appending `:desc` to a column will invert the ordering for
|
|
that column. `:asc` is also accepted but exhibits the same behavior as the default sort order.
|
|
|
|
For example, with a sort string `s=column1,column2:desc,column3`, the table will be
|
|
sorted in ascending order by column1, in descending order by column2, and in ascending
|
|
order by column3.
|
|
|
|
[source,sh]
|
|
--------------------------------------------------
|
|
GET _cat/templates?v&s=order:desc,index_patterns
|
|
--------------------------------------------------
|
|
//CONSOLE
|
|
|
|
returns:
|
|
|
|
[source,txt]
|
|
--------------------------------------------------
|
|
name index_patterns order version
|
|
pizza_pepperoni [*pepperoni*] 2
|
|
sushi_california_roll [*avocado*] 1 1
|
|
pizza_hawaiian [*pineapples*] 1
|
|
--------------------------------------------------
|
|
|
|
include::cat/alias.asciidoc[]
|
|
|
|
include::cat/allocation.asciidoc[]
|
|
|
|
include::cat/count.asciidoc[]
|
|
|
|
include::cat/fielddata.asciidoc[]
|
|
|
|
include::cat/health.asciidoc[]
|
|
|
|
include::cat/indices.asciidoc[]
|
|
|
|
include::cat/master.asciidoc[]
|
|
|
|
include::cat/nodeattrs.asciidoc[]
|
|
|
|
include::cat/nodes.asciidoc[]
|
|
|
|
include::cat/pending_tasks.asciidoc[]
|
|
|
|
include::cat/plugins.asciidoc[]
|
|
|
|
include::cat/recovery.asciidoc[]
|
|
|
|
include::cat/repositories.asciidoc[]
|
|
|
|
include::cat/tasks.asciidoc[]
|
|
|
|
include::cat/thread_pool.asciidoc[]
|
|
|
|
include::cat/shards.asciidoc[]
|
|
|
|
include::cat/segments.asciidoc[]
|
|
|
|
include::cat/snapshots.asciidoc[]
|
|
|
|
include::cat/templates.asciidoc[]
|