Cluster

class elasticsearch.client.ClusterClient(client)
Parameters:

client (BaseClient) –

allocation_explain(*, current_node=None, error_trace=None, filter_path=None, human=None, include_disk_info=None, include_yes_decisions=None, index=None, pretty=None, primary=None, shard=None, body=None)

Provides explanations for shard allocations in the cluster.

https://www.elastic.co/guide/en/elasticsearch/reference/8.13/cluster-allocation-explain.html

Parameters:

  • current_node (str | None) – Specifies the node ID or the name of the node to only explain a shard that is currently located on the specified node.

  • include_disk_info (bool | None) – If true, returns information about disk usage and shard sizes.

  • include_yes_decisions (bool | None) – If true, returns YES decisions in explanation.

  • index (str | None) – Specifies the name of the index that you would like an explanation for.

  • primary (bool | None) – If true, returns explanation for the primary shard for the given shard ID.

  • shard (int | None) – Specifies the ID of the shard that you would like an explanation for.

  • error_trace (bool | None) –

  • filter_path (str | Sequence[str] | None) –

  • human (bool | None) –

  • pretty (bool | None) –

  • body (Dict[str, Any] | None) –

Return type:

ObjectApiResponse[Any]

delete_component_template(*, name, error_trace=None, filter_path=None, human=None, master_timeout=None, pretty=None, timeout=None)

Deletes a component template

https://www.elastic.co/guide/en/elasticsearch/reference/8.13/indices-component-template.html

Parameters:

  • name (str | Sequence[str]) – Comma-separated list or wildcard expression of component template names used to limit the request.

  • master_timeout (Literal[-1] | ~typing.Literal[0] | str | None) – Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.

  • timeout (Literal[-1] | ~typing.Literal[0] | str | None) – Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.

  • error_trace (bool | None) –

  • filter_path (str | Sequence[str] | None) –

  • human (bool | None) –

  • pretty (bool | None) –

Return type:

ObjectApiResponse[Any]

delete_voting_config_exclusions(*, error_trace=None, filter_path=None, human=None, pretty=None, wait_for_removal=None)

Clears cluster voting config exclusions.

https://www.elastic.co/guide/en/elasticsearch/reference/8.13/voting-config-exclusions.html

Parameters:

  • wait_for_removal (bool | None) – Specifies whether to wait for all excluded nodes to be removed from the cluster before clearing the voting configuration exclusions list. Defaults to true, meaning that all excluded nodes must be removed from the cluster before this API takes any action. If set to false then the voting configuration exclusions list is cleared even if some excluded nodes are still in the cluster.

  • error_trace (bool | None) –

  • filter_path (str | Sequence[str] | None) –

  • human (bool | None) –

  • pretty (bool | None) –

Return type:

ObjectApiResponse[Any]

exists_component_template(*, name, error_trace=None, filter_path=None, human=None, local=None, master_timeout=None, pretty=None)

Returns information about whether a particular component template exist

https://www.elastic.co/guide/en/elasticsearch/reference/8.13/indices-component-template.html

Parameters:

  • name (str | Sequence[str]) – Comma-separated list of component template names used to limit the request. Wildcard (*) expressions are supported.

  • local (bool | None) – If true, the request retrieves information from the local node only. Defaults to false, which means information is retrieved from the master node.

  • master_timeout (Literal[-1] | ~typing.Literal[0] | str | None) – Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.

  • error_trace (bool | None) –

  • filter_path (str | Sequence[str] | None) –

  • human (bool | None) –

  • pretty (bool | None) –

Return type:

HeadApiResponse

get_component_template(*, name=None, error_trace=None, filter_path=None, flat_settings=None, human=None, include_defaults=None, local=None, master_timeout=None, pretty=None)

Returns one or more component templates

https://www.elastic.co/guide/en/elasticsearch/reference/8.13/indices-component-template.html

Parameters:

  • name (str | None) – Comma-separated list of component template names used to limit the request. Wildcard (*) expressions are supported.

  • flat_settings (bool | None) – If true, returns settings in flat format.

  • include_defaults (bool | None) – Return all default configurations for the component template (default: false)

  • local (bool | None) – If true, the request retrieves information from the local node only. If false, information is retrieved from the master node.

  • master_timeout (Literal[-1] | ~typing.Literal[0] | str | None) – Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.

  • error_trace (bool | None) –

  • filter_path (str | Sequence[str] | None) –

  • human (bool | None) –

  • pretty (bool | None) –

Return type:

ObjectApiResponse[Any]

get_settings(*, error_trace=None, filter_path=None, flat_settings=None, human=None, include_defaults=None, master_timeout=None, pretty=None, timeout=None)

Returns cluster settings.

https://www.elastic.co/guide/en/elasticsearch/reference/8.13/cluster-get-settings.html

Parameters:

  • flat_settings (bool | None) – If true, returns settings in flat format.

  • include_defaults (bool | None) – If true, returns default cluster settings from the local node.

  • master_timeout (Literal[-1] | ~typing.Literal[0] | str | None) – Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.

  • timeout (Literal[-1] | ~typing.Literal[0] | str | None) – Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.

  • error_trace (bool | None) –

  • filter_path (str | Sequence[str] | None) –

  • human (bool | None) –

  • pretty (bool | None) –

Return type:

ObjectApiResponse[Any]

health(*, index=None, error_trace=None, expand_wildcards=None, filter_path=None, human=None, level=None, local=None, master_timeout=None, pretty=None, timeout=None, wait_for_active_shards=None, wait_for_events=None, wait_for_no_initializing_shards=None, wait_for_no_relocating_shards=None, wait_for_nodes=None, wait_for_status=None)

Returns basic information about the health of the cluster.

https://www.elastic.co/guide/en/elasticsearch/reference/8.13/cluster-health.html

Parameters:

  • index (str | Sequence[str] | None) – 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 *.

  • expand_wildcards (Sequence[Literal['all', 'closed', 'hidden', 'none', 'open'] | str] | ~typing.Literal['all', 'closed', 'hidden', 'none', 'open'] | str | None) – Whether to expand wildcard expression to concrete indices that are open, closed or both.

  • level (Literal['cluster', 'indices', 'shards'] | str | None) – Can be one of cluster, indices or shards. Controls the details level of the health information returned.

  • local (bool | None) – If true, the request retrieves information from the local node only. Defaults to false, which means information is retrieved from the master node.

  • master_timeout (Literal[-1] | ~typing.Literal[0] | str | None) – Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.

  • timeout (Literal[-1] | ~typing.Literal[0] | str | None) – Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.

  • wait_for_active_shards (int | Literal['all', 'index-setting'] | str | None) – A number controlling to how many active shards to wait for, all to wait for all shards in the cluster to be active, or 0 to not wait.

  • wait_for_events (Literal['high', 'immediate', 'languid', 'low', 'normal', 'urgent'] | str | None) – Can be one of immediate, urgent, high, normal, low, languid. Wait until all currently queued events with the given priority are processed.

  • wait_for_no_initializing_shards (bool | None) – A boolean value which controls whether to wait (until the timeout provided) for the cluster to have no shard initializations. Defaults to false, which means it will not wait for initializing shards.

  • wait_for_no_relocating_shards (bool | None) – A boolean value which controls whether to wait (until the timeout provided) for the cluster to have no shard relocations. Defaults to false, which means it will not wait for relocating shards.

  • wait_for_nodes (int | str | None) – The request waits until the specified number N of nodes is available. It also accepts >=N, <=N, >N and <N. Alternatively, it is possible to use ge(N), le(N), gt(N) and lt(N) notation.

  • wait_for_status (Literal['green', 'red', 'yellow'] | str | None) – One of green, yellow or red. Will wait (until the timeout provided) until the status of the cluster changes to the one provided or better, i.e. green > yellow > red. By default, will not wait for any status.

  • error_trace (bool | None) –

  • filter_path (str | Sequence[str] | None) –

  • human (bool | None) –

  • pretty (bool | None) –

Return type:

ObjectApiResponse[Any]

info(*, target, error_trace=None, filter_path=None, human=None, pretty=None)

Returns different information about the cluster.

https://www.elastic.co/guide/en/elasticsearch/reference/8.13/cluster-info.html

Parameters:

  • target (Sequence[Literal['_all', 'http', 'ingest', 'script', 'thread_pool'] | str] | ~typing.Literal['_all', 'http', 'ingest', 'script', 'thread_pool'] | str) – Limits the information returned to the specific target. Supports a comma-separated list, such as http,ingest.

  • error_trace (bool | None) –

  • filter_path (str | Sequence[str] | None) –

  • human (bool | None) –

  • pretty (bool | None) –

Return type:

ObjectApiResponse[Any]

pending_tasks(*, error_trace=None, filter_path=None, human=None, local=None, master_timeout=None, pretty=None)

Returns a list of any cluster-level changes (e.g. create index, update mapping, allocate or fail shard) which have not yet been executed.

https://www.elastic.co/guide/en/elasticsearch/reference/8.13/cluster-pending.html

Parameters:

  • local (bool | None) – If true, the request retrieves information from the local node only. If false, information is retrieved from the master node.

  • master_timeout (Literal[-1] | ~typing.Literal[0] | str | None) – Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.

  • error_trace (bool | None) –

  • filter_path (str | Sequence[str] | None) –

  • human (bool | None) –

  • pretty (bool | None) –

Return type:

ObjectApiResponse[Any]

post_voting_config_exclusions(*, error_trace=None, filter_path=None, human=None, node_ids=None, node_names=None, pretty=None, timeout=None)

Updates the cluster voting config exclusions by node ids or node names.

https://www.elastic.co/guide/en/elasticsearch/reference/8.13/voting-config-exclusions.html

Parameters:

  • node_ids (str | Sequence[str] | None) – A comma-separated list of the persistent ids of the nodes to exclude from the voting configuration. If specified, you may not also specify node_names.

  • node_names (str | Sequence[str] | None) – A comma-separated list of the names of the nodes to exclude from the voting configuration. If specified, you may not also specify node_ids.

  • timeout (Literal[-1] | ~typing.Literal[0] | str | None) – When adding a voting configuration exclusion, the API waits for the specified nodes to be excluded from the voting configuration before returning. If the timeout expires before the appropriate condition is satisfied, the request fails and returns an error.

  • error_trace (bool | None) –

  • filter_path (str | Sequence[str] | None) –

  • human (bool | None) –

  • pretty (bool | None) –

Return type:

ObjectApiResponse[Any]

put_component_template(*, name, template=None, allow_auto_create=None, create=None, error_trace=None, filter_path=None, human=None, master_timeout=None, meta=None, pretty=None, version=None, body=None)

Creates or updates a component template

https://www.elastic.co/guide/en/elasticsearch/reference/8.13/indices-component-template.html

Parameters:

  • name (str) – Name of the component template to create. Elasticsearch includes the following built-in component templates: logs-mappings; ‘logs-settings`; metrics-mappings; metrics-settings;`synthetics-mapping`; synthetics-settings. Elastic Agent uses these templates to configure backing indices for its data streams. If you use Elastic Agent and want to overwrite one of these templates, set the version for your replacement template higher than the current version. If you don’t use Elastic Agent and want to disable all built-in component and index templates, set stack.templates.enabled to false using the cluster update settings API.

  • template (Mapping[str, Any] | None) – The template to be applied which includes mappings, settings, or aliases configuration.

  • allow_auto_create (bool | None) – This setting overrides the value of the action.auto_create_index cluster setting. If set to true in a template, then indices can be automatically created using that template even if auto-creation of indices is disabled via actions.auto_create_index. If set to false then data streams matching the template must always be explicitly created.

  • create (bool | None) – If true, this request cannot replace or update existing component templates.

  • master_timeout (Literal[-1] | ~typing.Literal[0] | str | None) – Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.

  • meta (Mapping[str, Any] | None) – Optional user metadata about the component template. May have any contents. This map is not automatically generated by Elasticsearch. This information is stored in the cluster state, so keeping it short is preferable. To unset _meta, replace the template without specifying this information.

  • version (int | None) – Version number used to manage component templates externally. This number isn’t automatically generated or incremented by Elasticsearch. To unset a version, replace the template without specifying a version.

  • error_trace (bool | None) –

  • filter_path (str | Sequence[str] | None) –

  • human (bool | None) –

  • pretty (bool | None) –

  • body (Dict[str, Any] | None) –

Return type:

ObjectApiResponse[Any]

put_settings(*, error_trace=None, filter_path=None, flat_settings=None, human=None, master_timeout=None, persistent=None, pretty=None, timeout=None, transient=None, body=None)

Updates the cluster settings.

https://www.elastic.co/guide/en/elasticsearch/reference/8.13/cluster-update-settings.html

Parameters:

  • flat_settings (bool | None) – Return settings in flat format (default: false)

  • master_timeout (Literal[-1] | ~typing.Literal[0] | str | None) – Explicit operation timeout for connection to master node

  • persistent (Mapping[str, Any] | None) –

  • timeout (Literal[-1] | ~typing.Literal[0] | str | None) – Explicit operation timeout

  • transient (Mapping[str, Any] | None) –

  • error_trace (bool | None) –

  • filter_path (str | Sequence[str] | None) –

  • human (bool | None) –

  • pretty (bool | None) –

  • body (Dict[str, Any] | None) –

Return type:

ObjectApiResponse[Any]

remote_info(*, error_trace=None, filter_path=None, human=None, pretty=None)

Returns the information about configured remote clusters.

https://www.elastic.co/guide/en/elasticsearch/reference/8.13/cluster-remote-info.html

Parameters:
Return type:

ObjectApiResponse[Any]

reroute(*, commands=None, dry_run=None, error_trace=None, explain=None, filter_path=None, human=None, master_timeout=None, metric=None, pretty=None, retry_failed=None, timeout=None, body=None)

Allows to manually change the allocation of individual shards in the cluster.

https://www.elastic.co/guide/en/elasticsearch/reference/8.13/cluster-reroute.html

Parameters:

  • commands (Sequence[Mapping[str, Any]] | None) – Defines the commands to perform.

  • dry_run (bool | None) – If true, then the request simulates the operation only and returns the resulting state.

  • explain (bool | None) – If true, then the response contains an explanation of why the commands can or cannot be executed.

  • master_timeout (Literal[-1] | ~typing.Literal[0] | str | None) – Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.

  • metric (str | Sequence[str] | None) – Limits the information returned to the specified metrics.

  • retry_failed (bool | None) – If true, then retries allocation of shards that are blocked due to too many subsequent allocation failures.

  • timeout (Literal[-1] | ~typing.Literal[0] | str | None) – Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.

  • error_trace (bool | None) –

  • filter_path (str | Sequence[str] | None) –

  • human (bool | None) –

  • pretty (bool | None) –

  • body (Dict[str, Any] | None) –

Return type:

ObjectApiResponse[Any]

state(*, metric=None, index=None, allow_no_indices=None, error_trace=None, expand_wildcards=None, filter_path=None, flat_settings=None, human=None, ignore_unavailable=None, local=None, master_timeout=None, pretty=None, wait_for_metadata_version=None, wait_for_timeout=None)

Returns a comprehensive information about the state of the cluster.

https://www.elastic.co/guide/en/elasticsearch/reference/8.13/cluster-state.html

Parameters:

  • metric (str | Sequence[str] | None) – Limit the information returned to the specified metrics

  • index (str | Sequence[str] | None) – A comma-separated list of index names; use _all or empty string to perform the operation on all indices

  • allow_no_indices (bool | None) – Whether to ignore if a wildcard indices expression resolves into no concrete indices. (This includes _all string or when no indices have been specified)

  • expand_wildcards (Sequence[Literal['all', 'closed', 'hidden', 'none', 'open'] | str] | ~typing.Literal['all', 'closed', 'hidden', 'none', 'open'] | str | None) – Whether to expand wildcard expression to concrete indices that are open, closed or both.

  • flat_settings (bool | None) – Return settings in flat format (default: false)

  • ignore_unavailable (bool | None) – Whether specified concrete indices should be ignored when unavailable (missing or closed)

  • local (bool | None) – Return local information, do not retrieve the state from master node (default: false)

  • master_timeout (Literal[-1] | ~typing.Literal[0] | str | None) – Specify timeout for connection to master

  • wait_for_metadata_version (int | None) – Wait for the metadata version to be equal or greater than the specified metadata version

  • wait_for_timeout (Literal[-1] | ~typing.Literal[0] | str | None) – The maximum time to wait for wait_for_metadata_version before timing out

  • error_trace (bool | None) –

  • filter_path (str | Sequence[str] | None) –

  • human (bool | None) –

  • pretty (bool | None) –

Return type:

ObjectApiResponse[Any]

stats(*, node_id=None, error_trace=None, filter_path=None, flat_settings=None, human=None, pretty=None, timeout=None)

Returns high-level overview of cluster statistics.

https://www.elastic.co/guide/en/elasticsearch/reference/8.13/cluster-stats.html

Parameters:

  • node_id (str | Sequence[str] | None) – Comma-separated list of node filters used to limit returned information. Defaults to all nodes in the cluster.

  • flat_settings (bool | None) – If true, returns settings in flat format.

  • timeout (Literal[-1] | ~typing.Literal[0] | str | None) – Period to wait for each node to respond. If a node does not respond before its timeout expires, the response does not include its stats. However, timed out nodes are included in the response’s _nodes.failed property. Defaults to no timeout.

  • error_trace (bool | None) –

  • filter_path (str | Sequence[str] | None) –

  • human (bool | None) –

  • pretty (bool | None) –

Return type:

ObjectApiResponse[Any]