Imported Upstream version 1.0.3upstream/1.0.3

1 files changed, 117 insertions, 0 deletions

diff --git a/docs/reference/cat.asciidoc b/docs/reference/cat.asciidoc
new file mode 100644
index 0000000..0aa2d6f
--- /dev/null
+++ b/docs/reference/cat.asciidoc
@@ -0,0 +1,117 @@
+[[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,shell]
+--------------------------------------------------
+% 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,shell]
+--------------------------------------------------
+% 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,shell]
+--------------------------------------------------
+% 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
+--------------------------------------------------
+
+[float]
+[[numeric-formats]]
+=== Numeric formats
+
+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.
+
+[source,shell]
+--------------------------------------------------
+% 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
+--------------------------------------------------
+
+
+--
+
+include::cat/alias.asciidoc[]
+
+include::cat/allocation.asciidoc[]
+
+include::cat/count.asciidoc[]
+
+include::cat/health.asciidoc[]
+
+include::cat/indices.asciidoc[]
+
+include::cat/master.asciidoc[]
+
+include::cat/nodes.asciidoc[]
+
+include::cat/pending_tasks.asciidoc[]
+
+include::cat/recovery.asciidoc[]
+
+include::cat/thread_pool.asciidoc[]
+
+include::cat/shards.asciidoc[]