156 lines
4.9 KiB
Plaintext
156 lines
4.9 KiB
Plaintext
[[cluster-state]]
|
|
=== Cluster state API
|
|
++++
|
|
<titleabbrev>Cluster state</titleabbrev>
|
|
++++
|
|
|
|
Returns metadata about the state of the cluster.
|
|
|
|
[[cluster-state-api-request]]
|
|
==== {api-request-title}
|
|
|
|
`GET /_cluster/state/<metrics>/<target>`
|
|
|
|
[[cluster-state-api-desc]]
|
|
==== {api-description-title}
|
|
|
|
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.
|
|
|
|
NOTE: 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>>.
|
|
|
|
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]
|
|
|
|
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.
|
|
|
|
[[cluster-state-api-path-params]]
|
|
==== {api-path-parms-title}
|
|
|
|
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:
|
|
|
|
`<metrics>`::
|
|
(Optional, string) A comma-separated list of the following options:
|
|
+
|
|
--
|
|
`_all`::
|
|
Shows all metrics.
|
|
|
|
`blocks`::
|
|
Shows the `blocks` part of the response.
|
|
|
|
`master_node`::
|
|
Shows the elected `master_node` part of the response.
|
|
|
|
`metadata`::
|
|
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.
|
|
|
|
`nodes`::
|
|
Shows the `nodes` part of the response.
|
|
|
|
`routing_nodes`::
|
|
Shows the `routing_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
|
|
routing table for these indices.
|
|
|
|
`version`::
|
|
Shows the cluster state version.
|
|
--
|
|
|
|
`<target>`::
|
|
(Optional, string)
|
|
Comma-separated list of data streams, indices, and index aliases used to limit
|
|
the request. Wildcard expressions (`*`) are supported.
|
|
+
|
|
To target all data streams and indices in a cluster, omit this parameter or use
|
|
`_all` or `*`.
|
|
|
|
|
|
[[cluster-state-api-query-params]]
|
|
==== {api-query-parms-title}
|
|
|
|
`allow_no_indices`::
|
|
(Optional, Boolean) If `true`, the wildcard indices expression that resolves
|
|
into no concrete indices will be ignored. (This includes `_all` string or
|
|
when no indices have been specified).
|
|
+
|
|
Defaults to `true`.
|
|
|
|
`expand_wildcards`::
|
|
(Optional, string) Whether to expand wildcard expression to concrete indices
|
|
that are open, closed or both. Available options: `open`, `closed`, `none`,
|
|
`all`.
|
|
|
|
include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=flat-settings]
|
|
|
|
`ignore_unavailable`::
|
|
(Optional, Boolean) If `true`, unavailable indices (missing or closed) will
|
|
be ignored.
|
|
|
|
include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=local]
|
|
|
|
include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=master-timeout]
|
|
|
|
`wait_for_metadata_version`::
|
|
(Optional, integer) Waits for the metadata version to be equal or greater
|
|
than the specified metadata version.
|
|
|
|
`wait_for_timeout`::
|
|
(Optional, <<time-units, time units>>) Specifies the maximum time to wait
|
|
for wait_for_metadata_version before timing out.
|
|
|
|
|
|
[[cluster-state-api-example]]
|
|
==== {api-examples-title}
|
|
|
|
The following example returns only `metadata` and `routing_table` data for the
|
|
`foo` and `bar` data streams or indices:
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
GET /_cluster/state/metadata,routing_table/foo,bar
|
|
--------------------------------------------------
|
|
|
|
The next example returns all available metadata for `foo` and `bar`:
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
GET /_cluster/state/_all/foo,bar
|
|
--------------------------------------------------
|
|
|
|
This example returns only the `blocks` metadata:
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
GET /_cluster/state/blocks
|
|
--------------------------------------------------
|