[[cat]]
= cat APIs

[partintro]
--

["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 an ssh 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.

[source,sh]
--------------------------------------------------
% curl 'localhost:9200/_cat/master?v'
id                     ip        node
EGtKWZlWQYWDmX29fUnp3Q 127.0.0.1 Grey, Sara
--------------------------------------------------

[float]
[[help]]
=== Help

Each of the commands accepts a query string parameter `help` which will
output its available columns.

[source,sh]
--------------------------------------------------
% curl 'localhost:9200/_cat/master?help'
id   | node id
ip   | node transport ip address
node | node name
--------------------------------------------------

[float]
[[headers]]
=== Headers

Each of the commands accepts a query string parameter `h` which forces
only those columns to appear.

[source,sh]
--------------------------------------------------
% curl 'n1:9200/_cat/nodes?h=ip,port,heapPercent,name'
192.168.56.40 9300 40.3 bGG90GE
192.168.56.20 9300 15.3 H5dfFeA
192.168.56.50 9300 17.0 I8hydUG
192.168.56.10 9300 12.3 DKDM97B
192.168.56.30 9300 43.9 6-bjhwl
--------------------------------------------------

You can also request multiple columns using simple wildcards like
`/_cat/thread_pool?h=ip,bulk.*` to get all headers (or aliases) starting
with `bulk.`.

[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.  We only need to tweak two things.  First, we want to turn
off human mode.  We'll use a byte-level resolution.  Then we'll pipe
our output into `sort` using the appropriate column, which in this
case is the eight one.

[source,sh]
--------------------------------------------------
% curl '192.168.56.10:9200/_cat/indices?bytes=b' | sort -rnk8
green wiki2 3 0 10000   0 105274918 105274918
green wiki1 3 0 10000 413 103776272 103776272
green foo   1 0   227   0   2065131   2065131
--------------------------------------------------

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 '192.168.56.10:9200/_cat/indices?format=json' | jq .
[
  {
    "pri.store.size": "650b",
    "health": "yellow",
    "status": "open",
    "index": "twitter",
    "pri": "5",
    "rep": "1",
    "docs.count": "0",
    "docs.deleted": "0",
    "store.size": "650b"
  }
]
--------------------------------------------------

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' -H "Accept: application/json" | jq .
[
  {
    "pri.store.size": "650b",
    "health": "yellow",
    "status": "open",
    "index": "twitter",
    "pri": "5",
    "rep": "1",
    "docs.count": "0",
    "docs.deleted": "0",
    "store.size": "650b"
  }
]
--------------------------------------------------

--

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/thread_pool.asciidoc[]

include::cat/shards.asciidoc[]

include::cat/segments.asciidoc[]

include::cat/snapshots.asciidoc[]

include::cat/templates.asciidoc[]