cat APIs

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.

Each of the commands accepts a query string parameter v to turn on verbose output.

% curl 'localhost:9200/_cat/master?v'
id                     ip        node
EGtKWZlWQYWDmX29fUnp3Q 127.0.0.1 Grey, Sara

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

% curl 'localhost:9200/_cat/master?help'
id   | node id
ip   | node transport ip address
node | node name

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

% curl 'n1:9200/_cat/nodes?h=ip,port,heapPercent,name'
192.168.56.40 9300 40.3 Captain Universe
192.168.56.20 9300 15.3 Kaluu
192.168.56.50 9300 17.0 Yellowjacket
192.168.56.10 9300 12.3 Remy LeBeau
192.168.56.30 9300 43.9 Ramsey, Doug

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..

Many commands provide a few types of numeric output, either a byte value 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.

% 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