ElasticSearch 0.90.3 – cat API

Send to Kindle

textWith the incoming release of ElasticSearch 0.90.3 we will get a new maintenance API, a one that is able to return cluster and node related information in plain text format, not in JSON. It can come useful when working with your cluster from command line – for example when you don’t want to analyze the whole JSON output, but you are only interested in some of the information returned. Let’s have a look how this API looks like.

Available REST endpoints

The following REST endpoints were added to ElasticSearch:

  • /_cat/master
  • /_cat/nodes
  • /_cat/shards

Now let’s see what data we can expect in return when calling mentioned endpoints.


By calling the /_cat/master REST endpoint we can get information regarding the nodes and which one of them is currently being elected as a master. For example, this is how the response looks like for two nodes cluster that is running on my local PC:

$curl -XGET 'localhost:9200/_cat/master'

And the response:

id                     ip           node

As you can see, in return, we’ve got the information about which node is currently elected as the master. We can see it’s identifier, IP address and name.


The /_cat/nodes REST endpoint provides information about all the nodes in the cluster. Let’s see what ElasticSearch will return after running the following command:

$curl -XGET 'localhost:9200/_cat/nodes'

And the response:

id                     ip           port jdk      heapmax  memmax  uptime data/client master node     
D8jAvhjdQ5SRgF2VscS5Nw 9301 1.7.0_21 990.7mb   7.6gb    5.6m d           m      Ulik     
G3nG0tsKQDWpRTNKPgGWNQ 9300 1.7.0_21 990.7mb   7.6gb    5.8m d           *      Nocturne

As you can the /_cat/nodes REST endpoint provides generic information about the nodes in the cluster. You can see that we have the node identifier, node IP address with port on which it is running, Java version, maximum heap size that ElasticSearch is permitted to use, maximum physical memory available, ElasticSearch uptime, information whether a node is a data or client node, if the node is a master and finally node name.


Finally, the /_cat/shards REST endpoint provides us with the shard level information for the indices that are living in our cluster. Let’s check what kind of information is exactly returned by running the following command:

$curl -XGET 'localhost:9200/_cat/shards'

The response we’ve got was as follows:

index shard p/r state   docs store ip           node     
test  0     p   STARTED 0    99b Ulik     
test  0     r   STARTED 0    79b Nocturne 
test  1     r   STARTED 0    79b Ulik     
test  1     p   STARTED 0    99b Nocturne 
test  2     p   STARTED 1    1.6kb Ulik     
test  2     r   STARTED 1    1.6kb Nocturne 
test  3     r   STARTED 1    1.6kb Ulik     
test  3     p   STARTED 1    1.6kb Nocturne 
test  4     r   STARTED 1    1.6kb Ulik     
test  4     p   STARTED 1    1.6kb Nocturne

Just a quick comment – each line of the response describes a single shard from an index. We see the index name, the shard number, if it is a primary shard or a replica (p for primary, r for replica), the state of the given shards, number of documents it holds, shard size, the IP address of the node the shard is allocated to and the name of the node.

A quick summary

As you can see, you can get aggregated information regarding your cluster, in a simple, human readable format just by calling appropriate API call. This can be useful especially when your cluster is big and the JSON returned by different administration API tend to be big and finding relevant information can be a bit painful.

Leave a Reply