elasticsearch 8.15.1__py3-none-any.whl → 8.17.0__py3-none-any.whl

elasticsearch/_async/client/cluster.py

@@ -44,9 +44,15 @@ class ClusterClient(NamespacedClient):
         body: t.Optional[t.Dict[str, t.Any]] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Provides explanations for shard allocations in the cluster.
+        Explain the shard allocations. Get explanations for shard allocations in the
+        cluster. For unassigned shards, it provides an explanation for why the shard
+        is unassigned. For assigned shards, it provides an explanation for why the shard
+        is remaining on its current node and has not moved or rebalanced to another node.
+        This API can be very useful when attempting to diagnose why a shard is unassigned
+        or why a shard continues to remain on its current node when you might expect
+        otherwise.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.15/cluster-allocation-explain.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/cluster-allocation-explain.html>`_
 
         :param current_node: Specifies the node ID or the name of the node to only explain
             a shard that is currently located on the specified node.
@@ -113,10 +119,11 @@ class ClusterClient(NamespacedClient):
         timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Deletes component templates. Component templates are building blocks for constructing
-        index templates that specify index mappings, settings, and aliases.
+        Delete component templates. Deletes component templates. Component templates
+        are building blocks for constructing index templates that specify index mappings,
+        settings, and aliases.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.15/indices-component-template.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/indices-component-template.html>`_
 
         :param name: Comma-separated list or wildcard expression of component template
             names used to limit the request.
@@ -164,9 +171,10 @@ class ClusterClient(NamespacedClient):
         wait_for_removal: t.Optional[bool] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Clears cluster voting config exclusions.
+        Clear cluster voting config exclusions. Remove master-eligible nodes from the
+        voting configuration exclusion list.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.15/voting-config-exclusions.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/voting-config-exclusions.html>`_
 
         :param wait_for_removal: Specifies whether to wait for all excluded nodes to
             be removed from the cluster before clearing the voting configuration exclusions
@@ -211,9 +219,10 @@ class ClusterClient(NamespacedClient):
         pretty: t.Optional[bool] = None,
     ) -> HeadApiResponse:
         """
-        Returns information about whether a particular component template exist
+        Check component templates. Returns information about whether a particular component
+        template exists.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.15/indices-component-template.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/indices-component-template.html>`_
 
         :param name: Comma-separated list of component template names used to limit the
             request. Wildcard (*) expressions are supported.
@@ -266,9 +275,9 @@ class ClusterClient(NamespacedClient):
         pretty: t.Optional[bool] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Retrieves information about component templates.
+        Get component templates. Retrieves information about component templates.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.15/indices-component-template.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/indices-component-template.html>`_
 
         :param name: Comma-separated list of component template names used to limit the
             request. Wildcard (`*`) expressions are supported.
@@ -329,10 +338,10 @@ class ClusterClient(NamespacedClient):
         timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Returns cluster-wide settings. By default, it returns only settings that have
-        been explicitly defined.
+        Get cluster-wide settings. By default, it returns only settings that have been
+        explicitly defined.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.15/cluster-get-settings.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/cluster-get-settings.html>`_
 
         :param flat_settings: If `true`, returns settings in flat format.
         :param include_defaults: If `true`, returns default cluster settings from the
@@ -412,17 +421,18 @@ class ClusterClient(NamespacedClient):
         ] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        The cluster health API returns a simple status on the health of the cluster.
-        You can also use the API to get the health status of only specified data streams
-        and indices. For data streams, the API retrieves the health status of the stream’s
-        backing indices. The cluster health status is: green, yellow or red. On the shard
-        level, a red status indicates that the specific shard is not allocated in the
-        cluster, yellow means that the primary shard is allocated but replicas are not,
-        and green means that all shards are allocated. The index level status is controlled
-        by the worst shard status. The cluster status is controlled by the worst index
+        Get the cluster health status. You can also use the API to get the health status
+        of only specified data streams and indices. For data streams, the API retrieves
+        the health status of the stream’s backing indices. The cluster health status
+        is: green, yellow or red. On the shard level, a red status indicates that the
+        specific shard is not allocated in the cluster. Yellow means that the primary
+        shard is allocated but replicas are not. Green means that all shards are allocated.
+        The index level status is controlled by the worst shard status. One of the main
+        benefits of the API is the ability to wait until the cluster reaches a certain
+        high watermark health level. The cluster status is controlled by the worst index
         status.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.15/cluster-health.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/cluster-health.html>`_
 
         :param index: Comma-separated list of data streams, indices, and index aliases
             used to limit the request. Wildcard expressions (`*`) are supported. To target
@@ -524,9 +534,9 @@ class ClusterClient(NamespacedClient):
         pretty: t.Optional[bool] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Returns different information about the cluster.
+        Get cluster info. Returns basic information about the cluster.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.15/cluster-info.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/cluster-info.html>`_
 
         :param target: Limits the information returned to the specific target. Supports
             a comma-separated list, such as http,ingest.
@@ -566,16 +576,16 @@ class ClusterClient(NamespacedClient):
         pretty: t.Optional[bool] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Returns cluster-level changes (such as create index, update mapping, allocate
-        or fail shard) that have not yet been executed. NOTE: This API returns a list
-        of any pending updates to the cluster state. These are distinct from the tasks
-        reported by the Task Management API which include periodic tasks and tasks initiated
-        by the user, such as node stats, search queries, or create index requests. However,
-        if a user-initiated task such as a create index command causes a cluster state
-        update, the activity of this task might be reported by both task api and pending
-        cluster tasks API.
+        Get the pending cluster tasks. Get information about cluster-level changes (such
+        as create index, update mapping, allocate or fail shard) that have not yet taken
+        effect. NOTE: This API returns a list of any pending updates to the cluster state.
+        These are distinct from the tasks reported by the task management API which include
+        periodic tasks and tasks initiated by the user, such as node stats, search queries,
+        or create index requests. However, if a user-initiated task such as a create
+        index command causes a cluster state update, the activity of this task might
+        be reported by both task api and pending cluster tasks API.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.15/cluster-pending.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/cluster-pending.html>`_
 
         :param local: If `true`, the request retrieves information from the local node
             only. If `false`, information is retrieved from the master node.
@@ -621,9 +631,35 @@ class ClusterClient(NamespacedClient):
         timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Updates the cluster voting config exclusions by node ids or node names.
+        Update voting configuration exclusions. Update the cluster voting config exclusions
+        by node IDs or node names. By default, if there are more than three master-eligible
+        nodes in the cluster and you remove fewer than half of the master-eligible nodes
+        in the cluster at once, the voting configuration automatically shrinks. If you
+        want to shrink the voting configuration to contain fewer than three nodes or
+        to remove half or more of the master-eligible nodes in the cluster at once, use
+        this API to remove departing nodes from the voting configuration manually. The
+        API adds an entry for each specified node to the cluster’s voting configuration
+        exclusions list. It then waits until the cluster has reconfigured its voting
+        configuration to exclude the specified nodes. Clusters should have no voting
+        configuration exclusions in normal operation. Once the excluded nodes have stopped,
+        clear the voting configuration exclusions with `DELETE /_cluster/voting_config_exclusions`.
+        This API waits for the nodes to be fully removed from the cluster before it returns.
+        If your cluster has voting configuration exclusions for nodes that you no longer
+        intend to remove, use `DELETE /_cluster/voting_config_exclusions?wait_for_removal=false`
+        to clear the voting configuration exclusions without waiting for the nodes to
+        leave the cluster. A response to `POST /_cluster/voting_config_exclusions` with
+        an HTTP status code of 200 OK guarantees that the node has been removed from
+        the voting configuration and will not be reinstated until the voting configuration
+        exclusions are cleared by calling `DELETE /_cluster/voting_config_exclusions`.
+        If the call to `POST /_cluster/voting_config_exclusions` fails or returns a response
+        with an HTTP status code other than 200 OK then the node may not have been removed
+        from the voting configuration. In that case, you may safely retry the call. NOTE:
+        Voting exclusions are required only when you remove at least half of the master-eligible
+        nodes from a cluster in a short time period. They are not required when removing
+        master-ineligible nodes or when removing fewer than half of the master-eligible
+        nodes.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.15/voting-config-exclusions.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/voting-config-exclusions.html>`_
 
         :param node_ids: A comma-separated list of the persistent ids of the nodes to
             exclude from the voting configuration. If specified, you may not also specify
@@ -683,24 +719,25 @@ class ClusterClient(NamespacedClient):
         body: t.Optional[t.Dict[str, t.Any]] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Creates or updates a component template. Component templates are building blocks
-        for constructing index templates that specify index mappings, settings, and aliases.
-        An index template can be composed of multiple component templates. To use a component
-        template, specify it in an index template’s `composed_of` list. Component templates
-        are only applied to new data streams and indices as part of a matching index
-        template. Settings and mappings specified directly in the index template or the
-        create index request override any settings or mappings specified in a component
-        template. Component templates are only used during index creation. For data streams,
-        this includes data stream creation and the creation of a stream’s backing indices.
-        Changes to component templates do not affect existing indices, including a stream’s
-        backing indices. You can use C-style `/* *\\/` block comments in component templates.
+        Create or update a component template. Creates or updates a component template.
+        Component templates are building blocks for constructing index templates that
+        specify index mappings, settings, and aliases. An index template can be composed
+        of multiple component templates. To use a component template, specify it in an
+        index template’s `composed_of` list. Component templates are only applied to
+        new data streams and indices as part of a matching index template. Settings and
+        mappings specified directly in the index template or the create index request
+        override any settings or mappings specified in a component template. Component
+        templates are only used during index creation. For data streams, this includes
+        data stream creation and the creation of a stream’s backing indices. Changes
+        to component templates do not affect existing indices, including a stream’s backing
+        indices. You can use C-style `/* *\\/` block comments in component templates.
         You can include comments anywhere in the request body except before the opening
         curly bracket.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.15/indices-component-template.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/indices-component-template.html>`_
 
         :param name: Name of the component template to create. Elasticsearch includes
-            the following built-in component templates: `logs-mappings`; 'logs-settings`;
+            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,
@@ -784,9 +821,28 @@ class ClusterClient(NamespacedClient):
         body: t.Optional[t.Dict[str, t.Any]] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Updates the cluster settings.
+        Update the cluster settings. Configure and update dynamic settings on a running
+        cluster. You can also configure dynamic settings locally on an unstarted or shut
+        down node in `elasticsearch.yml`. Updates made with this API can be persistent,
+        which apply across cluster restarts, or transient, which reset after a cluster
+        restart. You can also reset transient or persistent settings by assigning them
+        a null value. If you configure the same setting using multiple methods, Elasticsearch
+        applies the settings in following order of precedence: 1) Transient setting;
+        2) Persistent setting; 3) `elasticsearch.yml` setting; 4) Default setting value.
+        For example, you can apply a transient setting to override a persistent setting
+        or `elasticsearch.yml` setting. However, a change to an `elasticsearch.yml` setting
+        will not override a defined transient or persistent setting. TIP: In Elastic
+        Cloud, use the user settings feature to configure all cluster settings. This
+        method automatically rejects unsafe settings that could break your cluster. If
+        you run Elasticsearch on your own hardware, use this API to configure dynamic
+        cluster settings. Only use `elasticsearch.yml` for static cluster settings and
+        node settings. The API doesn’t require a restart and ensures a setting’s value
+        is the same on all nodes. WARNING: Transient cluster settings are no longer recommended.
+        Use persistent cluster settings instead. If a cluster becomes unstable, transient
+        settings can clear unexpectedly, resulting in a potentially undesired cluster
+        configuration.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.15/cluster-update-settings.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/cluster-update-settings.html>`_
 
         :param flat_settings: Return settings in flat format (default: false)
         :param master_timeout: Explicit operation timeout for connection to master node
@@ -838,11 +894,11 @@ class ClusterClient(NamespacedClient):
         pretty: t.Optional[bool] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        The cluster remote info API allows you to retrieve all of the configured remote
-        cluster information. It returns connection and endpoint information keyed by
-        the configured remote cluster alias.
+        Get remote cluster information. Get all of the configured remote cluster information.
+        This API returns connection and endpoint information keyed by the configured
+        remote cluster alias.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.15/cluster-remote-info.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/cluster-remote-info.html>`_
         """
         __path_parts: t.Dict[str, str] = {}
         __path = "/_remote/info"
@@ -885,15 +941,35 @@ class ClusterClient(NamespacedClient):
         body: t.Optional[t.Dict[str, t.Any]] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Allows to manually change the allocation of individual shards in the cluster.
+        Reroute the cluster. Manually change the allocation of individual shards in the
+        cluster. For example, a shard can be moved from one node to another explicitly,
+        an allocation can be canceled, and an unassigned shard can be explicitly allocated
+        to a specific node. It is important to note that after processing any reroute
+        commands Elasticsearch will perform rebalancing as normal (respecting the values
+        of settings such as `cluster.routing.rebalance.enable`) in order to remain in
+        a balanced state. For example, if the requested allocation includes moving a
+        shard from node1 to node2 then this may cause a shard to be moved from node2
+        back to node1 to even things out. The cluster can be set to disable allocations
+        using the `cluster.routing.allocation.enable` setting. If allocations are disabled
+        then the only allocations that will be performed are explicit ones given using
+        the reroute command, and consequent allocations due to rebalancing. The cluster
+        will attempt to allocate a shard a maximum of `index.allocation.max_retries`
+        times in a row (defaults to `5`), before giving up and leaving the shard unallocated.
+        This scenario can be caused by structural problems such as having an analyzer
+        which refers to a stopwords file which doesn’t exist on all nodes. Once the problem
+        has been corrected, allocation can be manually retried by calling the reroute
+        API with the `?retry_failed` URI query parameter, which will attempt a single
+        retry round for these shards.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.15/cluster-reroute.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/cluster-reroute.html>`_
 
         :param commands: Defines the commands to perform.
-        :param dry_run: If true, then the request simulates the operation only and returns
-            the resulting state.
+        :param dry_run: If true, then the request simulates the operation. It will calculate
+            the result of applying the commands to the current cluster state and return
+            the resulting cluster state after the commands (and rebalancing) have been
+            applied; it will not actually perform the requested changes.
         :param explain: If true, then the response contains an explanation of why the
-            commands can or cannot be executed.
+            commands can or cannot run.
         :param master_timeout: 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.
@@ -972,9 +1048,28 @@ class ClusterClient(NamespacedClient):
         wait_for_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Returns a comprehensive information about the state of the cluster.
+        Get the cluster state. Get comprehensive information about the state of the cluster.
+        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. This API lets you retrieve a representation
+        of this internal state for debugging or diagnostic purposes. You may need to
+        consult the Elasticsearch source code to determine the precise meaning of the
+        response. By default the 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 `?local=true`
+        query parameter. Elasticsearch 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. 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 APIs.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.15/cluster-state.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/cluster-state.html>`_
 
         :param metric: Limit the information returned to the specified metrics
         :param index: A comma-separated list of index names; use `_all` or empty string
@@ -1050,21 +1145,21 @@ class ClusterClient(NamespacedClient):
         node_id: t.Optional[t.Union[str, t.Sequence[str]]] = None,
         error_trace: t.Optional[bool] = None,
         filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None,
-        flat_settings: t.Optional[bool] = None,
         human: t.Optional[bool] = None,
+        include_remotes: t.Optional[bool] = None,
         pretty: t.Optional[bool] = None,
         timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Returns cluster statistics. It returns basic index metrics (shard numbers, store
-        size, memory usage) and information about the current nodes that form the cluster
-        (number, roles, os, jvm versions, memory usage, cpu and installed plugins).
+        Get cluster statistics. Get basic index metrics (shard numbers, store size, memory
+        usage) and information about the current nodes that form the cluster (number,
+        roles, os, jvm versions, memory usage, cpu and installed plugins).
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.15/cluster-stats.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/cluster-stats.html>`_
 
         :param node_id: Comma-separated list of node filters used to limit returned information.
             Defaults to all nodes in the cluster.
-        :param flat_settings: If `true`, returns settings in flat format.
+        :param include_remotes: Include remote cluster data into the response
         :param timeout: 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.
@@ -1082,10 +1177,10 @@ class ClusterClient(NamespacedClient):
             __query["error_trace"] = error_trace
         if filter_path is not None:
             __query["filter_path"] = filter_path
-        if flat_settings is not None:
-            __query["flat_settings"] = flat_settings
         if human is not None:
             __query["human"] = human
+        if include_remotes is not None:
+            __query["include_remotes"] = include_remotes
         if pretty is not None:
             __query["pretty"] = pretty
         if timeout is not None: