Imported Upstream version 1.0.3upstream/1.0.3

1 files changed, 67 insertions, 0 deletions

diff --git a/docs/reference/cluster/state.asciidoc b/docs/reference/cluster/state.asciidoc
new file mode 100644
index 0000000..3a18be2
--- /dev/null
+++ b/docs/reference/cluster/state.asciidoc
@@ -0,0 +1,67 @@
+[[cluster-state]]
+== Cluster State
+
+The cluster state API allows to get a comprehensive state information of
+the whole cluster.
+
+[source,js]
+--------------------------------------------------
+$ curl -XGET 'http://localhost:9200/_cluster/state'
+--------------------------------------------------
+
+By default, the cluster state request is routed to the master node, to
+ensure that the latest cluster state is returned.   
+For debugging purposes, you can retrieve the cluster state local to a
+particular node by adding `local=true` to the  query string.
+
+[float]
+=== Response Filters
+
+As the cluster state can grow (depending on the number of shards and indices, your mapping, templates),
+it is possible to filter the cluster state response specifying the parts in the URL.
+
+[source,js]
+--------------------------------------------------
+$ curl -XGET 'http://localhost:9200/_cluster/state/{metrics}/{indices}'
+--------------------------------------------------
+
+`metrics` can be a comma-separated list of
+
+`version`::
+    Shows the cluster state version.
+
+`master_node`::
+    Shows the elected `master_node` part of the response
+
+`nodes`::
+    Shows the `nodes` part of the response
+
+`routing_table`::
+    Shows the `routing_table` part of the response. If you supply a comma separated list of indices, the returned output will only contain the indices listed.
+
+`metadata`::
+    Shows the `metadata` part of the response. If you supply a comma separated list of indices, the returned output will only contain the indices listed.
+
+`blocks`::
+    Shows the `blocks` part of the response
+
+In addition the `index_templates` parameter can be specified, which returns the specified index templates only. This works only if the `metadata` is asked to be returned.
+
+A couple of example calls:
+
+[source,js]
+--------------------------------------------------
+# return only metadata and routing_table data for specified indices
+$ curl -XGET 'http://localhost:9200/_cluster/state/metadata,routing_table/foo,bar'
+
+# return everything for these two indices
+$ curl -XGET 'http://localhost:9200/_cluster/state/_all/foo,bar'
+
+# Return only blocks data
+$ curl -XGET 'http://localhost:9200/_cluster/state/blocks'
+
+# Return only metadata and a specific index_template
+# You should use the dedicated template endpoint for this
+$ curl -XGET 'http://localhost:9200/_cluster/state/metadata?index_templates=template_1'
+--------------------------------------------------
+