集群（Cluster）
- class elasticsearch.client.ClusterClient
To use this client, access
client.clusterfrom anElasticsearchclient. For example:from elasticsearch import Elasticsearch # Create the client instance client = Elasticsearch(...) # Use the cluster client client.cluster.<method>(...)
- allocation_explain(*, current_node=None, error_trace=None, filter_path=None, human=None, include_disk_info=None, include_yes_decisions=None, index=None, master_timeout=None, pretty=None, primary=None, shard=None, body=None)
解释分片分配情况。 获取集群中分片分配的解释说明。 此API接受请求体或查询参数中的current_node、index、primary和shard参数，但不能同时存在于两者中。 对于未分配的分片，提供其未被分配的原因解释。 对于已分配的分片，解释为何该分片保留在当前节点而未移动或重新平衡到其他节点。 当诊断分片为何未被分配或为何持续保留在当前节点（与预期不符）时，此API非常有用。 参考链接文档了解如何使用此API排查分配问题的示例。
https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-allocation-explain
- Parameters:
current_node (str | None) – 仅当分片当前位于指定节点名称或节点ID上时才进行解释。
include_disk_info (bool | None) – 如果为true，返回磁盘使用情况和分片大小的信息。
include_yes_decisions (bool | None) – 如果为true，在解释中包含YES决策。
index (str | None) – 需要获取解释的索引名称。
master_timeout (str | Literal[-1] | ~typing.Literal[0] | None) – 等待连接主节点的超时时间。
primary (bool | None) – 如果为true，返回指定分片ID的主分片解释。
shard (int | None) – 需要获取解释的分片标识符。
error_trace (bool | None)
human (bool | None)
pretty (bool | None)
- Return type:
- delete_component_template(*, name, error_trace=None, filter_path=None, human=None, master_timeout=None, pretty=None, timeout=None)
删除组件模板。 组件模板是构建索引模板的基础模块，用于指定索引映射、设置和别名。
https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-put-component-template
- delete_voting_config_exclusions(*, error_trace=None, filter_path=None, human=None, master_timeout=None, pretty=None, wait_for_removal=None)
清除集群投票配置排除项。 从投票配置排除列表中移除符合主节点资格的节点。
- Parameters:
- Return type:
- exists_component_template(*, name, error_trace=None, filter_path=None, human=None, local=None, master_timeout=None, pretty=None)
检查组件模板。 返回特定组件模板是否存在的信息。
https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-put-component-template
- Parameters:
- Return type:
- 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, settings_filter=None)
获取组件模板。 获取组件模板的相关信息。
https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-put-component-template
- Parameters:
name (str | None) – 用于限制请求的组件模板名称的逗号分隔列表。支持通配符(*)表达式。
flat_settings (bool | None) – 如果为`true`，以扁平格式返回设置。
include_defaults (bool | None) – 返回组件模板的所有默认配置(默认: false)
local (bool | None) – 如果为`true`，请求仅从本地节点获取信息。如果为`false`，则从主节点获取信息。
master_timeout (str | Literal[-1] | ~typing.Literal[0] | None) – 等待连接主节点的超时时间。如果在超时前未收到响应，请求将失败并返回错误。
settings_filter (str | Sequence[str] | None) – 过滤结果，例如过滤敏感信息。支持通配符或完整设置键
error_trace (bool | None)
human (bool | None)
pretty (bool | None)
- Return type:
- get_settings(*, error_trace=None, filter_path=None, flat_settings=None, human=None, include_defaults=None, master_timeout=None, pretty=None, timeout=None)
获取集群范围的设置。
默认情况下，仅返回已显式定义的设置。
https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-get-settings
- Parameters:
flat_settings (bool | None) – 如果为 true，则以扁平格式返回设置。
include_defaults (bool | None) – 如果为 true，则从本地节点返回默认集群设置。
master_timeout (str | Literal[-1] | ~typing.Literal[0] | None) – 等待连接到主节点的时间。如果在超时前未收到响应，请求将失败并返回错误。
timeout (str | Literal[-1] | ~typing.Literal[0] | None) – 等待响应的时间。如果在超时前未收到响应，请求将失败并返回错误。
error_trace (bool | None)
human (bool | None)
pretty (bool | None)
- Return type:
- 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)
获取集群健康状态。
也可使用该API获取指定数据流和索引的健康状态。对于数据流，API会检索其底层索引的健康状态。
集群健康状态分为：绿色、黄色或红色。 在分片级别，红色表示特定分片未在集群中分配。黄色表示主分片已分配但副本未分配。绿色表示所有分片均已分配。 索引级别状态由最差的分片状态决定。
该API的主要优势之一是能够等待集群达到特定的健康水位线。 集群状态由最差的索引状态控制。
https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-health
- Parameters:
index (str | Sequence[str] | None) – 用于限制请求的数据流、索引和索引别名的逗号分隔列表。支持通配符表达式(*)。若要针对集群中所有数据流和索引，可省略此参数或使用_all或`*`。
expand_wildcards (Sequence[str | Literal['all', 'closed', 'hidden', 'none', 'open']] | str | ~typing.Literal['all', 'closed', 'hidden', 'none', 'open'] | None) – 是否将通配符表达式展开为具体的打开、关闭或两者兼有的索引。
level (str | Literal['cluster', 'indices', 'shards'] | None) – 可以是cluster、indices或shards之一。控制返回健康信息的详细程度。
local (bool | None) – 如果为true，请求仅从本地节点检索信息。默认为false，表示从主节点检索信息。
master_timeout (str | Literal[-1] | ~typing.Literal[0] | None) – 等待连接到主节点的时间。如果在超时前未收到响应，请求将失败并返回错误。
timeout (str | Literal[-1] | ~typing.Literal[0] | None) – 等待响应的时间。如果在超时前未收到响应，请求将失败并返回错误。
wait_for_active_shards (int | str | Literal['all', 'index-setting'] | None) – 控制等待多少活动分片的数字，all表示等待集群中所有分片活动，0表示不等待。
wait_for_events (str | Literal['high', 'immediate', 'languid', 'low', 'normal', 'urgent'] | None) – 可以是immediate、urgent、high、normal、low、languid之一。等待直到所有当前具有给定优先级的事件被处理。
wait_for_no_initializing_shards (bool | None) – 布尔值，控制是否等待(直到提供的超时)集群没有分片初始化。默认为false，表示不等待初始化分片。
wait_for_no_relocating_shards (bool | None) – 布尔值，控制是否等待(直到提供的超时)集群没有分片重定位。默认为false，表示不等待重定位分片。
wait_for_nodes (int | str | None) – 请求等待直到指定数量的节点N可用。也接受>=N、<=N、>N和<N。或者可以使用ge(N)、le(N)、gt(N)和lt(N)表示法。
wait_for_status (str | Literal['green', 'red', 'unavailable', 'unknown', 'yellow'] | None) – green、yellow或red之一。将等待(直到提供的超时)直到集群状态变为提供的状态或更好，即green > yellow > red。默认不等待任何状态。
error_trace (bool | None)
human (bool | None)
pretty (bool | None)
- Return type:
- info(*, target, error_trace=None, filter_path=None, human=None, pretty=None)
获取集群信息。 返回关于集群的基本信息。
https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-info
- pending_tasks(*, error_trace=None, filter_path=None, human=None, local=None, master_timeout=None, pretty=None)
获取待处理的集群任务。 获取尚未生效的集群级别变更(如创建索引、更新映射、分配或失败分片)的信息。
注意：此API返回集群状态任何待处理更新的列表。 这些与任务管理API报告的任务不同，后者包括周期性任务和用户发起的任务，如节点统计、搜索查询或创建索引请求。 但是，如果用户发起的任务(如创建索引命令)导致集群状态更新，此任务的活动可能同时被任务API和待处理集群任务API报告。
https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-pending-tasks
- Parameters:
- Return type:
- post_voting_config_exclusions(*, error_trace=None, filter_path=None, human=None, master_timeout=None, node_ids=None, node_names=None, pretty=None, timeout=None)
更新投票配置排除项。 通过节点ID或节点名称更新集群投票配置排除项。 默认情况下，如果集群中有超过三个符合主节点条件的节点，并且一次性移除少于一半的符合主节点条件的节点，投票配置会自动收缩。 如果要将投票配置收缩到少于三个节点或一次性移除集群中一半或更多的符合主节点条件的节点，请使用此API手动从投票配置中移除离开的节点。 该API为每个指定节点向集群的投票配置排除列表添加一个条目。 然后等待直到集群重新配置其投票配置以排除指定节点。
正常运行的集群不应有投票配置排除项。 一旦被排除的节点停止，使用
DELETE /_cluster/voting_config_exclusions清除投票配置排除项。 此API在返回前等待节点完全从集群中移除。 如果集群中有不再打算移除的节点的投票配置排除项，使用DELETE /_cluster/voting_config_exclusions?wait_for_removal=false清除投票配置排除项而不等待节点离开集群。对
POST /_cluster/voting_config_exclusions的响应HTTP状态码为200 OK保证节点已从投票配置中移除，并且在调用DELETE /_cluster/voting_config_exclusions清除投票配置排除项之前不会被恢复。 如果对POST /_cluster/voting_config_exclusions的调用失败或返回HTTP状态码不是200 OK，则节点可能未被从投票配置中移除。 在这种情况下，可以安全地重试调用。注意：仅当在短时间内从集群中移除至少一半的符合主节点条件的节点时才需要投票排除。 移除不符合主节点条件的节点或移除少于一半的符合主节点条件的节点时不需要。
- Parameters:
master_timeout (str | Literal[-1] | ~typing.Literal[0] | None) – 等待连接到主节点的时间。
node_ids (str | Sequence[str] | None) – 要从投票配置中排除的节点的持久ID的逗号分隔列表。如果指定，则不能同时指定node_names。
node_names (str | Sequence[str] | None) – 要从投票配置中排除的节点名称的逗号分隔列表。如果指定，则不能同时指定node_ids。
timeout (str | Literal[-1] | ~typing.Literal[0] | None) – 添加投票配置排除项时，API在返回前等待指定节点被排除出投票配置。如果超时前未满足适当条件，请求将失败并返回错误。
error_trace (bool | None)
human (bool | None)
pretty (bool | None)
- Return type:
- put_component_template(*, name, template=None, cause=None, create=None, deprecated=None, error_trace=None, filter_path=None, human=None, master_timeout=None, meta=None, pretty=None, version=None, body=None)
创建或更新组件模板。 组件模板是构建索引模板的基础模块，用于指定索引映射、设置和别名。
一个索引模板可以由多个组件模板组成。 要使用组件模板，需在索引模板的
composed_of列表中指定它。 组件模板仅作为匹配索引模板的一部分应用于新的数据流和索引。直接在索引模板或创建索引请求中指定的设置和映射会覆盖组件模板中的任何设置或映射。
组件模板仅在索引创建期间使用。 对于数据流，这包括数据流创建和流后备索引的创建。 对组件模板的更改不会影响现有索引，包括流的后备索引。
可以在组件模板中使用C风格的
/* *\/块注释。 可以在请求体中的任何位置包含注释，除了左大括号之前。应用组件模板
不能直接将组件模板应用于数据流或索引。 要应用组件模板，必须将其包含在索引模板的
composed_of列表中。https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-put-component-template
- Parameters:
name (str) – 要创建的组件模板名称。Elasticsearch包含 以下内置组件模板：logs-mappings; logs-settings; metrics-mappings; metrics-settings;`synthetics-mapping`; synthetics-settings。 Elastic Agent使用这些模板为其数据流配置后备索引。 如果使用Elastic Agent并想覆盖其中一个模板， 请将替换模板的`version`设置为高于当前版本。 如果不使用Elastic Agent并想禁用所有内置组件 和索引模板，请使用集群更新设置API将`stack.templates.enabled`设置为`false`。
cause (str | None) – 用户定义的创建组件模板的原因。
create (bool | None) – 如果为`true`，此请求不能替换或更新现有组件模板。
deprecated (bool | None) – 将此索引模板标记为已弃用。当创建或 更新使用已弃用组件的非弃用索引模板时， Elasticsearch将发出弃用警告。
master_timeout (str | Literal[-1] | ~typing.Literal[0] | None) – 等待连接到主节点的时间。如果 在超时前未收到响应，请求将失败并返回错误。
meta (Mapping[str, Any] | None) – 关于组件模板的可选用户元数据。它可以包含 任何内容。此映射不是由Elasticsearch自动生成的。此 信息存储在集群状态中，因此最好保持简短。 要取消设置`_meta`，替换模板时不指定此信息。
version (int | None) – 用于外部管理组件模板的版本号。 此数字不是由Elasticsearch自动生成或递增的。 要取消设置版本，替换模板时不指定版本。
error_trace (bool | None)
human (bool | None)
pretty (bool | None)
- Return type:
- 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)
更新集群设置。
在运行中的集群上配置和更新动态设置。 也可以在未启动或关闭的节点上的
elasticsearch.yml中本地配置动态设置。使用此API进行的更新可以是持久的（跨集群重启应用），也可以是临时的（集群重启后重置）。 也可以通过为它们分配null值来重置临时或持久设置。
如果使用多种方法配置相同的设置，Elasticsearch按以下优先级顺序应用设置：1) 临时设置；2) 持久设置；3)
elasticsearch.yml设置；4) 默认设置值。 例如，可以应用临时设置来覆盖持久设置或elasticsearch.yml设置。 但是，对elasticsearch.yml设置的更改不会覆盖已定义的临时或持久设置。提示：在Elastic Cloud中，使用用户设置功能配置所有集群设置。此方法自动拒绝可能破坏集群的不安全设置。 如果在自己的硬件上运行Elasticsearch，请使用此API配置动态集群设置。 仅将
elasticsearch.yml用于静态集群设置和节点设置。 此API不需要重启，并确保所有节点上的设置值相同。警告：不再推荐使用临时集群设置。请改用持久集群设置。 如果集群变得不稳定，临时设置可能会意外清除，导致潜在的集群配置不符合预期。
https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-put-settings
- remote_info(*, error_trace=None, filter_path=None, human=None, pretty=None)
获取远程集群信息。
获取有关已配置远程集群的信息。 此API返回按配置的远程集群别名键控的连接和端点信息。
信息 此API返回反映本地集群当前状态的信息。
connected字段不一定反映远程集群是否宕机或不可用，仅反映当前是否有到它的开放连接。 Elasticsearch不会自发尝试重新连接到断开的远程集群。 要触发重新连接，尝试跨集群搜索、ES|QL跨集群搜索，或尝试解析集群端点。https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-remote-info
- 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)
重新路由集群。 手动更改集群中单个分片的分配。 例如，可以显式将分片从一个节点移动到另一个节点，可以取消分配，可以将未分配的分片显式分配到特定节点。
需要注意的是，在处理任何重新路由命令后，Elasticsearch将正常执行重新平衡（尊重
cluster.routing.rebalance.enable等设置的值）以保持平衡状态。 例如，如果请求的分配包括将分片从node1移动到node2，则可能导致分片从node2移回node1以平衡。可以使用
cluster.routing.allocation.enable设置禁用分配。 如果分配被禁用，则执行的唯一分配是使用重新路由命令给出的显式分配，以及由于重新平衡导致的后续分配。集群将尝试连续分配分片最多
index.allocation.max_retries次（默认为5），然后放弃并保留分片未分配。 这种情况可能是由结构性问题引起的，例如在所有节点上不存在的停用词文件的分析器。一旦问题得到纠正，可以通过调用带有
?retry_failedURI查询参数的重新路由API手动重试分配，这将尝试对这些分片进行单次重试。https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-reroute
- Parameters:
dry_run (bool | None) – 如果为true，则请求模拟操作。它将计算 将命令应用于当前集群状态的结果，并返回 应用命令（和重新平衡）后的结果集群状态； 实际上不会执行请求的更改。
explain (bool | None) – 如果为true，则响应包含命令可以或不能运行的解释。
master_timeout (str | Literal[-1] | ~typing.Literal[0] | None) – 等待连接到主节点的时间。如果 在超时前未收到响应，请求将失败并返回错误。
retry_failed (bool | None) – 如果为true，则重试由于后续分配失败过多而被阻止的分片分配。
timeout (str | Literal[-1] | ~typing.Literal[0] | None) – 等待响应的时间。如果在超时前未收到 响应，请求将失败并返回错误。
error_trace (bool | None)
human (bool | None)
pretty (bool | None)
- Return type:
- 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)
获取集群状态。 获取有关集群状态的全面信息。
集群状态是一个内部数据结构，用于跟踪每个节点所需的各种信息，包括集群中其他节点的身份和属性；集群范围的设置；索引元数据，包括每个索引的映射和设置；集群中每个分片副本的位置和状态。
当选的主节点确保集群中的每个节点都有相同的集群状态副本。 此API允许您检索此内部状态的表示以进行调试或诊断。 可能需要查阅Elasticsearch源代码以确定响应的确切含义。
默认情况下，API会将请求路由到当选的主节点，因为此节点是集群状态的权威来源。 也可以通过添加
?local=true查询参数来检索处理API请求的节点持有的集群状态。在较大的集群中，Elasticsearch可能需要花费大量精力计算此API的响应，并且响应可能包含大量数据。 如果重复使用此API，集群可能会变得不稳定。
警告：响应是内部数据结构的表示。 其格式不受与其他更稳定API相同的兼容性保证，并且可能因版本而异。 不要使用外部监控工具查询此API。 相反，使用其他更稳定的集群API获取所需信息。
https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-state
- Parameters:
index (str | Sequence[str] | None) – 逗号分隔的索引名称列表；使用`_all`或空字符串 对所有索引执行操作
allow_no_indices (bool | None) – 是否忽略通配符索引表达式解析为 无具体索引的情况。（这包括`_all`字符串或未指定 任何索引时）
expand_wildcards (Sequence[str | Literal['all', 'closed', 'hidden', 'none', 'open']] | str | ~typing.Literal['all', 'closed', 'hidden', 'none', 'open'] | None) – 是否将通配符表达式扩展为开放、关闭或两者兼有的具体索引。
flat_settings (bool | None) – 以扁平格式返回设置（默认：false）
ignore_unavailable (bool | None) – 是否在不可用时忽略指定的具体索引 （缺失或关闭）
local (bool | None) – 返回本地信息，不从主节点检索状态 （默认：false）
master_timeout (str | Literal[-1] | ~typing.Literal[0] | None) – 在集群状态被阻塞时等待新集群状态的超时
wait_for_metadata_version (int | None) – 等待元数据版本等于或 大于指定的元数据版本
wait_for_timeout (str | Literal[-1] | ~typing.Literal[0] | None) – 在超时前等待wait_for_metadata_version 的最长时间
error_trace (bool | None)
human (bool | None)
pretty (bool | None)
- Return type:
- stats(*, node_id=None, error_trace=None, filter_path=None, human=None, include_remotes=None, pretty=None, timeout=None)
获取集群统计信息。 获取基本索引指标（分片数量、存储大小、内存使用情况）以及构成集群的当前节点信息（数量、角色、操作系统、JVM版本、内存使用情况、CPU和已安装插件）。
https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-stats
- Parameters:
node_id (str | Sequence[str] | None) – 用于限制返回信息的节点过滤器逗号分隔列表。 默认为集群中的所有节点。
include_remotes (bool | None) – 在响应中包含远程集群数据
timeout (str | Literal[-1] | ~typing.Literal[0] | None) – 等待每个节点响应的超时时间。如果一个节点在超时到期前未响应， 则响应中不包含其统计信息。但超时的节点会被包含在响应的`_nodes.failed`属性中。 默认为无超时。
error_trace (bool | None)
human (bool | None)
pretty (bool | None)
- Return type: