elasticsearch/docs/reference/cat.asciidoc

[[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[]