mirror of
https://github.com/elastic/elasticsearch.git
synced 2025-04-24 23:27:25 -04:00
166 lines
5.4 KiB
Text
166 lines
5.4 KiB
Text
[[cluster-state]]
|
|
=== Cluster state API
|
|
++++
|
|
<titleabbrev>Cluster state</titleabbrev>
|
|
++++
|
|
|
|
..New API reference
|
|
[sidebar]
|
|
--
|
|
For the most up-to-date API details, refer to {api-es}/group/endpoint-cluster[Cluster APIs].
|
|
--
|
|
|
|
Returns an internal representation of the cluster state for debugging or
|
|
diagnostic purposes.
|
|
|
|
[[cluster-state-api-request]]
|
|
==== {api-request-title}
|
|
|
|
`GET /_cluster/state/<metrics>/<target>`
|
|
|
|
[[cluster-state-api-prereqs]]
|
|
==== {api-prereq-title}
|
|
|
|
* If the {es} {security-features} are enabled, you must have the `monitor` or
|
|
`manage` <<privileges-list-cluster,cluster privilege>> to use this API.
|
|
|
|
[[cluster-state-api-desc]]
|
|
==== {api-description-title}
|
|
|
|
The _cluster state_ is an internal data structure which keeps track of a
|
|
variety of information needed by every node, including:
|
|
|
|
* The identity and attributes of the other nodes in the cluster
|
|
|
|
* Cluster-wide settings
|
|
|
|
* Index metadata, including the mapping and settings for each index
|
|
|
|
* The location and status of every shard copy in the cluster
|
|
|
|
The elected master node ensures that every node in the cluster has a copy of
|
|
the same cluster state. The cluster state API lets you retrieve a
|
|
representation of this internal state for debugging or diagnostic purposes. You
|
|
may need to consult the {es} source code to determine the precise meaning of
|
|
the response.
|
|
|
|
By default the cluster state API will route requests to the elected master node
|
|
since this node is the authoritative source of cluster states. You can also
|
|
retrieve the cluster state held on the node handling the API request by adding
|
|
the query parameter `?local=true`.
|
|
|
|
{es} may need to expend significant effort to compute a response to this API in
|
|
larger clusters, and the response may comprise a very large quantity of data.
|
|
If you use this API repeatedly, your cluster may become unstable.
|
|
|
|
[[cluster-state-api-unstable-warning]]
|
|
WARNING: The response is a representation of an internal data structure. Its
|
|
format is not subject to the same compatibility guarantees as other more stable
|
|
APIs and may change from version to version. **Do not query this API using
|
|
external monitoring tools.** Instead, obtain the information you require using
|
|
other more stable <<cluster,cluster APIs>>.
|
|
|
|
[[cluster-state-api-path-params]]
|
|
==== {api-path-parms-title}
|
|
|
|
The cluster state can sometimes be very large, and {es} may consume significant
|
|
resources while computing a response to this API. To reduce the size of the
|
|
response, you can request only the part of the cluster state in which you are
|
|
interested:
|
|
|
|
`<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 `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 aliases
|
|
used to limit the request. Supports wildcards (`*`). To target all data streams
|
|
and indices, omit this parameter or use `*` or `_all`.
|
|
|
|
[[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-ref-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-ref-dir}/rest-api/common-parms.asciidoc[tag=local]
|
|
|
|
include::{es-ref-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
|
|
--------------------------------------------------
|