Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Note that GET /_cluster/state is unstable #40104

Merged
merged 2 commits into from
Mar 18, 2019
Merged

Note that GET /_cluster/state is unstable #40104

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c3a5c33
Note that GET /_cluster/state is unstable
DaveCTurner Mar 14, 2019
e2b8fad
Whitespace
DaveCTurner Mar 15, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
64 changes: 44 additions & 20 deletions docs/reference/cluster/state.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,44 +1,59 @@
[[cluster-state]]
== Cluster State

The cluster state API allows to get a comprehensive state information of
the whole cluster.
The cluster state API allows access to metadata representing the state of the
whole cluster. This includes information such as

* the set of nodes in the cluster

* all cluster-level settings

* information about the indices in the cluster, including their mappings and
settings

* the locations of all the shards in the cluster

The response is an internal representation of the cluster state and its format
may change from version to version. If possible, you should obtain any
information from the cluster state using the other, more stable,
<<cluster,cluster APIs>>.

[source,js]
--------------------------------------------------
GET /_cluster/state
--------------------------------------------------
// CONSOLE

The response provides the cluster name, the total compressed size
of the cluster state (its size when serialized for transmission over
the network), and the cluster state itself, which can be filtered to
only retrieve the parts of interest, as described below.
The response provides the cluster state itself, which can be filtered to only
retrieve the parts of interest as described below.

The cluster's `cluster_uuid` is also returned as part of the top-level
response, in addition to the `metadata` section. added[6.4.0]
The cluster's `cluster_uuid` is also returned as part of the top-level response,
in addition to the `metadata` section. added[6.4.0]

NOTE: While the cluster is still forming, it is possible for the `cluster_uuid`
to be `_na_` as well as the cluster state's version to be `-1`.

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.
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.
The cluster state contains information about all the indices in the cluster,
including their mappings, as well as templates and other metadata. This means it
can sometimes be quite large. To avoid the need to process all this information
you can request only the part of the cluster state that you need:

[source,js]
--------------------------------------------------
GET /_cluster/state/{metrics}
GET /_cluster/state/{metrics}/{indices}
--------------------------------------------------
// CONSOLE

`metrics` can be a comma-separated list of
`{metrics}` is a comma-separated list of the following options.

`version`::
Shows the cluster state version.
Expand All @@ -50,15 +65,23 @@ GET /_cluster/state/{metrics}/{indices}
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.
Shows the `routing_table` part of the response. If you supply a comma
separated list of indices, the returned output will only contain the routing
table for these indices.

`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.
Shows the `metadata` part of the response. If you supply a comma separated
list of indices, the returned output will only contain metadata for these
indices.

`blocks`::
Shows the `blocks` part of the response
Shows the `blocks` part of the response.

`_all`::
Shows all metrics.

The following example returns only `metadata` and `routing_table` data for the `foo` and `bar` indices:
The following example returns only `metadata` and `routing_table` data for the
`foo` and `bar` indices:

[source,js]
--------------------------------------------------
Expand All @@ -74,7 +97,8 @@ GET /_cluster/state/_all/foo,bar
--------------------------------------------------
// CONSOLE

And this example return only `blocks` data:
Finally, this example return only the `blocks` metadata:

[source,js]
--------------------------------------------------
GET /_cluster/state/blocks
Expand Down