elasticsearch 8.16.0__py3-none-any.whl → 8.17.1__py3-none-any.whl

elasticsearch/_sync/client/snapshot.py

@@ -44,10 +44,10 @@ class SnapshotClient(NamespacedClient):
         timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Triggers the review of a snapshot repository’s contents and deletes any stale
-        data not referenced by existing snapshots.
+        Clean up the snapshot repository. Trigger the review of the contents of a snapshot
+        repository and delete any stale data not referenced by existing snapshots.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.16/clean-up-snapshot-repo-api.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/clean-up-snapshot-repo-api.html>`_
 
         :param name: Snapshot repository to clean up.
         :param master_timeout: Period to wait for a connection to the master node.
@@ -99,9 +99,10 @@ class SnapshotClient(NamespacedClient):
         body: t.Optional[t.Dict[str, t.Any]] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Clones indices from one snapshot into another snapshot in the same repository.
+        Clone a snapshot. Clone part of all of a snapshot into another snapshot in the
+        same repository.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.16/modules-snapshots.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/clone-snapshot-api.html>`_
 
         :param repository: A repository name
         :param snapshot: The name of the snapshot to clone from
@@ -182,9 +183,9 @@ class SnapshotClient(NamespacedClient):
         body: t.Optional[t.Dict[str, t.Any]] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Creates a snapshot in a repository.
+        Create a snapshot. Take a snapshot of a cluster or of data streams and indices.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.16/modules-snapshots.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/create-snapshot-api.html>`_
 
         :param repository: Repository for the snapshot.
         :param snapshot: Name of the snapshot. Must be unique in the repository.
@@ -286,9 +287,13 @@ class SnapshotClient(NamespacedClient):
         verify: t.Optional[bool] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Creates a repository.
+        Create or update a snapshot repository. IMPORTANT: If you are migrating searchable
+        snapshots, the repository name must be identical in the source and destination
+        clusters. To register a snapshot repository, the cluster's global metadata must
+        be writeable. Ensure there are no cluster blocks (for example, `cluster.blocks.read_only`
+        and `clsuter.blocks.read_only_allow_delete` settings) that prevent write access.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.16/modules-snapshots.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/modules-snapshots.html>`_
 
         :param name: A repository name
         :param repository:
@@ -346,9 +351,9 @@ class SnapshotClient(NamespacedClient):
         pretty: t.Optional[bool] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Deletes one or more snapshots.
+        Delete snapshots.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.16/modules-snapshots.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/delete-snapshot-api.html>`_
 
         :param repository: A repository name
         :param snapshot: A comma-separated list of snapshot names
@@ -397,9 +402,11 @@ class SnapshotClient(NamespacedClient):
         timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Deletes a repository.
+        Delete snapshot repositories. When a repository is unregistered, Elasticsearch
+        removes only the reference to the location where the repository is storing the
+        snapshots. The snapshots themselves are left untouched and in place.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.16/modules-snapshots.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/delete-snapshot-repo-api.html>`_
 
         :param name: Name of the snapshot repository to unregister. Wildcard (`*`) patterns
             are supported.
@@ -471,9 +478,9 @@ class SnapshotClient(NamespacedClient):
         verbose: t.Optional[bool] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Returns information about a snapshot.
+        Get snapshot information.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.16/modules-snapshots.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/get-snapshot-api.html>`_
 
         :param repository: Comma-separated list of snapshot repository names used to
             limit the request. Wildcard (*) expressions are supported.
@@ -583,9 +590,9 @@ class SnapshotClient(NamespacedClient):
         pretty: t.Optional[bool] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Returns information about a repository.
+        Get snapshot repository information.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.16/modules-snapshots.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/get-snapshot-repo-api.html>`_
 
         :param name: A comma-separated list of repository names
         :param local: Return local information, do not retrieve the state from master
@@ -622,6 +629,225 @@ class SnapshotClient(NamespacedClient):
             path_parts=__path_parts,
         )
 
+    @_rewrite_parameters()
+    def repository_analyze(
+        self,
+        *,
+        name: str,
+        blob_count: t.Optional[int] = None,
+        concurrency: t.Optional[int] = None,
+        detailed: t.Optional[bool] = None,
+        early_read_node_count: t.Optional[int] = None,
+        error_trace: t.Optional[bool] = None,
+        filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None,
+        human: t.Optional[bool] = None,
+        max_blob_size: t.Optional[t.Union[int, str]] = None,
+        max_total_data_size: t.Optional[t.Union[int, str]] = None,
+        pretty: t.Optional[bool] = None,
+        rare_action_probability: t.Optional[float] = None,
+        rarely_abort_writes: t.Optional[bool] = None,
+        read_node_count: t.Optional[int] = None,
+        register_operation_count: t.Optional[int] = None,
+        seed: t.Optional[int] = None,
+        timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None,
+    ) -> ObjectApiResponse[t.Any]:
+        """
+        Analyze a snapshot repository. Analyze the performance characteristics and any
+        incorrect behaviour found in a repository. The response exposes implementation
+        details of the analysis which may change from version to version. The response
+        body format is therefore not considered stable and may be different in newer
+        versions. There are a large number of third-party storage systems available,
+        not all of which are suitable for use as a snapshot repository by Elasticsearch.
+        Some storage systems behave incorrectly, or perform poorly, especially when accessed
+        concurrently by multiple clients as the nodes of an Elasticsearch cluster do.
+        This API performs a collection of read and write operations on your repository
+        which are designed to detect incorrect behaviour and to measure the performance
+        characteristics of your storage system. The default values for the parameters
+        are deliberately low to reduce the impact of running an analysis inadvertently
+        and to provide a sensible starting point for your investigations. Run your first
+        analysis with the default parameter values to check for simple problems. If successful,
+        run a sequence of increasingly large analyses until you encounter a failure or
+        you reach a `blob_count` of at least `2000`, a `max_blob_size` of at least `2gb`,
+        a `max_total_data_size` of at least `1tb`, and a `register_operation_count` of
+        at least `100`. Always specify a generous timeout, possibly `1h` or longer, to
+        allow time for each analysis to run to completion. Perform the analyses using
+        a multi-node cluster of a similar size to your production cluster so that it
+        can detect any problems that only arise when the repository is accessed by many
+        nodes at once. If the analysis fails, Elasticsearch detected that your repository
+        behaved unexpectedly. This usually means you are using a third-party storage
+        system with an incorrect or incompatible implementation of the API it claims
+        to support. If so, this storage system is not suitable for use as a snapshot
+        repository. You will need to work with the supplier of your storage system to
+        address the incompatibilities that Elasticsearch detects. If the analysis is
+        successful, the API returns details of the testing process, optionally including
+        how long each operation took. You can use this information to determine the performance
+        of your storage system. If any operation fails or returns an incorrect result,
+        the API returns an error. If the API returns an error, it may not have removed
+        all the data it wrote to the repository. The error will indicate the location
+        of any leftover data and this path is also recorded in the Elasticsearch logs.
+        You should verify that this location has been cleaned up correctly. If there
+        is still leftover data at the specified location, you should manually remove
+        it. If the connection from your client to Elasticsearch is closed while the client
+        is waiting for the result of the analysis, the test is cancelled. Some clients
+        are configured to close their connection if no response is received within a
+        certain timeout. An analysis takes a long time to complete so you might need
+        to relax any such client-side timeouts. On cancellation the analysis attempts
+        to clean up the data it was writing, but it may not be able to remove it all.
+        The path to the leftover data is recorded in the Elasticsearch logs. You should
+        verify that this location has been cleaned up correctly. If there is still leftover
+        data at the specified location, you should manually remove it. If the analysis
+        is successful then it detected no incorrect behaviour, but this does not mean
+        that correct behaviour is guaranteed. The analysis attempts to detect common
+        bugs but it does not offer 100% coverage. Additionally, it does not test the
+        following: * Your repository must perform durable writes. Once a blob has been
+        written it must remain in place until it is deleted, even after a power loss
+        or similar disaster. * Your repository must not suffer from silent data corruption.
+        Once a blob has been written, its contents must remain unchanged until it is
+        deliberately modified or deleted. * Your repository must behave correctly even
+        if connectivity from the cluster is disrupted. Reads and writes may fail in this
+        case, but they must not return incorrect results. IMPORTANT: An analysis writes
+        a substantial amount of data to your repository and then reads it back again.
+        This consumes bandwidth on the network between the cluster and the repository,
+        and storage space and I/O bandwidth on the repository itself. You must ensure
+        this load does not affect other users of these systems. Analyses respect the
+        repository settings `max_snapshot_bytes_per_sec` and `max_restore_bytes_per_sec`
+        if available and the cluster setting `indices.recovery.max_bytes_per_sec` which
+        you can use to limit the bandwidth they consume. NOTE: This API is intended for
+        exploratory use by humans. You should expect the request parameters and the response
+        format to vary in future versions. NOTE: Different versions of Elasticsearch
+        may perform different checks for repository compatibility, with newer versions
+        typically being stricter than older ones. A storage system that passes repository
+        analysis with one version of Elasticsearch may fail with a different version.
+        This indicates it behaves incorrectly in ways that the former version did not
+        detect. You must work with the supplier of your storage system to address the
+        incompatibilities detected by the repository analysis API in any version of Elasticsearch.
+        NOTE: This API may not work correctly in a mixed-version cluster. *Implementation
+        details* NOTE: This section of documentation describes how the repository analysis
+        API works in this version of Elasticsearch, but you should expect the implementation
+        to vary between versions. The request parameters and response format depend on
+        details of the implementation so may also be different in newer versions. The
+        analysis comprises a number of blob-level tasks, as set by the `blob_count` parameter
+        and a number of compare-and-exchange operations on linearizable registers, as
+        set by the `register_operation_count` parameter. These tasks are distributed
+        over the data and master-eligible nodes in the cluster for execution. For most
+        blob-level tasks, the executing node first writes a blob to the repository and
+        then instructs some of the other nodes in the cluster to attempt to read the
+        data it just wrote. The size of the blob is chosen randomly, according to the
+        `max_blob_size` and `max_total_data_size` parameters. If any of these reads fails
+        then the repository does not implement the necessary read-after-write semantics
+        that Elasticsearch requires. For some blob-level tasks, the executing node will
+        instruct some of its peers to attempt to read the data before the writing process
+        completes. These reads are permitted to fail, but must not return partial data.
+        If any read returns partial data then the repository does not implement the necessary
+        atomicity semantics that Elasticsearch requires. For some blob-level tasks, the
+        executing node will overwrite the blob while its peers are reading it. In this
+        case the data read may come from either the original or the overwritten blob,
+        but the read operation must not return partial data or a mix of data from the
+        two blobs. If any of these reads returns partial data or a mix of the two blobs
+        then the repository does not implement the necessary atomicity semantics that
+        Elasticsearch requires for overwrites. The executing node will use a variety
+        of different methods to write the blob. For instance, where applicable, it will
+        use both single-part and multi-part uploads. Similarly, the reading nodes will
+        use a variety of different methods to read the data back again. For instance
+        they may read the entire blob from start to end or may read only a subset of
+        the data. For some blob-level tasks, the executing node will cancel the write
+        before it is complete. In this case, it still instructs some of the other nodes
+        in the cluster to attempt to read the blob but all of these reads must fail to
+        find the blob. Linearizable registers are special blobs that Elasticsearch manipulates
+        using an atomic compare-and-exchange operation. This operation ensures correct
+        and strongly-consistent behavior even when the blob is accessed by multiple nodes
+        at the same time. The detailed implementation of the compare-and-exchange operation
+        on linearizable registers varies by repository type. Repository analysis verifies
+        that that uncontended compare-and-exchange operations on a linearizable register
+        blob always succeed. Repository analysis also verifies that contended operations
+        either succeed or report the contention but do not return incorrect results.
+        If an operation fails due to contention, Elasticsearch retries the operation
+        until it succeeds. Most of the compare-and-exchange operations performed by repository
+        analysis atomically increment a counter which is represented as an 8-byte blob.
+        Some operations also verify the behavior on small blobs with sizes other than
+        8 bytes.
+
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/repo-analysis-api.html>`_
+
+        :param name: The name of the repository.
+        :param blob_count: The total number of blobs to write to the repository during
+            the test. For realistic experiments, you should set it to at least `2000`.
+        :param concurrency: The number of operations to run concurrently during the test.
+        :param detailed: Indicates whether to return detailed results, including timing
+            information for every operation performed during the analysis. If false,
+            it returns only a summary of the analysis.
+        :param early_read_node_count: The number of nodes on which to perform an early
+            read operation while writing each blob. Early read operations are only rarely
+            performed.
+        :param max_blob_size: The maximum size of a blob to be written during the test.
+            For realistic experiments, you should set it to at least `2gb`.
+        :param max_total_data_size: An upper limit on the total size of all the blobs
+            written during the test. For realistic experiments, you should set it to
+            at least `1tb`.
+        :param rare_action_probability: The probability of performing a rare action such
+            as an early read, an overwrite, or an aborted write on each blob.
+        :param rarely_abort_writes: Indicates whether to rarely cancel writes before
+            they complete.
+        :param read_node_count: The number of nodes on which to read a blob after writing.
+        :param register_operation_count: The minimum number of linearizable register
+            operations to perform in total. For realistic experiments, you should set
+            it to at least `100`.
+        :param seed: The seed for the pseudo-random number generator used to generate
+            the list of operations performed during the test. To repeat the same set
+            of operations in multiple experiments, use the same seed in each experiment.
+            Note that the operations are performed concurrently so might not always happen
+            in the same order on each run.
+        :param timeout: The period of time to wait for the test to complete. If no response
+            is received before the timeout expires, the test is cancelled and returns
+            an error.
+        """
+        if name in SKIP_IN_PATH:
+            raise ValueError("Empty value passed for parameter 'name'")
+        __path_parts: t.Dict[str, str] = {"repository": _quote(name)}
+        __path = f'/_snapshot/{__path_parts["repository"]}/_analyze'
+        __query: t.Dict[str, t.Any] = {}
+        if blob_count is not None:
+            __query["blob_count"] = blob_count
+        if concurrency is not None:
+            __query["concurrency"] = concurrency
+        if detailed is not None:
+            __query["detailed"] = detailed
+        if early_read_node_count is not None:
+            __query["early_read_node_count"] = early_read_node_count
+        if error_trace is not None:
+            __query["error_trace"] = error_trace
+        if filter_path is not None:
+            __query["filter_path"] = filter_path
+        if human is not None:
+            __query["human"] = human
+        if max_blob_size is not None:
+            __query["max_blob_size"] = max_blob_size
+        if max_total_data_size is not None:
+            __query["max_total_data_size"] = max_total_data_size
+        if pretty is not None:
+            __query["pretty"] = pretty
+        if rare_action_probability is not None:
+            __query["rare_action_probability"] = rare_action_probability
+        if rarely_abort_writes is not None:
+            __query["rarely_abort_writes"] = rarely_abort_writes
+        if read_node_count is not None:
+            __query["read_node_count"] = read_node_count
+        if register_operation_count is not None:
+            __query["register_operation_count"] = register_operation_count
+        if seed is not None:
+            __query["seed"] = seed
+        if timeout is not None:
+            __query["timeout"] = timeout
+        __headers = {"accept": "application/json"}
+        return self.perform_request(  # type: ignore[return-value]
+            "POST",
+            __path,
+            params=__query,
+            headers=__headers,
+            endpoint_id="snapshot.repository_analyze",
+            path_parts=__path_parts,
+        )
+
     @_rewrite_parameters()
     @_stability_warning(Stability.EXPERIMENTAL)
     def repository_verify_integrity(
@@ -642,9 +868,42 @@ class SnapshotClient(NamespacedClient):
         verify_blob_contents: t.Optional[bool] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Verifies the integrity of the contents of a snapshot repository
+        Verify the repository integrity. Verify the integrity of the contents of a snapshot
+        repository. This API enables you to perform a comprehensive check of the contents
+        of a repository, looking for any anomalies in its data or metadata which might
+        prevent you from restoring snapshots from the repository or which might cause
+        future snapshot create or delete operations to fail. If you suspect the integrity
+        of the contents of one of your snapshot repositories, cease all write activity
+        to this repository immediately, set its `read_only` option to `true`, and use
+        this API to verify its integrity. Until you do so: * It may not be possible to
+        restore some snapshots from this repository. * Searchable snapshots may report
+        errors when searched or may have unassigned shards. * Taking snapshots into this
+        repository may fail or may appear to succeed but have created a snapshot which
+        cannot be restored. * Deleting snapshots from this repository may fail or may
+        appear to succeed but leave the underlying data on disk. * Continuing to write
+        to the repository while it is in an invalid state may causing additional damage
+        to its contents. If the API finds any problems with the integrity of the contents
+        of your repository, Elasticsearch will not be able to repair the damage. The
+        only way to bring the repository back into a fully working state after its contents
+        have been damaged is by restoring its contents from a repository backup which
+        was taken before the damage occurred. You must also identify what caused the
+        damage and take action to prevent it from happening again. If you cannot restore
+        a repository backup, register a new repository and use this for all future snapshot
+        operations. In some cases it may be possible to recover some of the contents
+        of a damaged repository, either by restoring as many of its snapshots as needed
+        and taking new snapshots of the restored data, or by using the reindex API to
+        copy data from any searchable snapshots mounted from the damaged repository.
+        Avoid all operations which write to the repository while the verify repository
+        integrity API is running. If something changes the repository contents while
+        an integrity verification is running then Elasticsearch may incorrectly report
+        having detected some anomalies in its contents due to the concurrent writes.
+        It may also incorrectly fail to report some anomalies that the concurrent writes
+        prevented it from detecting. NOTE: This API is intended for exploratory use by
+        humans. You should expect the request parameters and the response format to vary
+        in future versions. NOTE: This API may not work correctly in a mixed-version
+        cluster.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.16/modules-snapshots.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/verify-repo-integrity-api.html>`_
 
         :param name: A repository name
         :param blob_thread_pool_concurrency: Number of threads to use for reading blob
@@ -739,9 +998,22 @@ class SnapshotClient(NamespacedClient):
         body: t.Optional[t.Dict[str, t.Any]] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Restores a snapshot.
+        Restore a snapshot. Restore a snapshot of a cluster or data streams and indices.
+        You can restore a snapshot only to a running cluster with an elected master node.
+        The snapshot repository must be registered and available to the cluster. The
+        snapshot and cluster versions must be compatible. To restore a snapshot, the
+        cluster's global metadata must be writable. Ensure there are't any cluster blocks
+        that prevent writes. The restore operation ignores index blocks. Before you restore
+        a data stream, ensure the cluster contains a matching index template with data
+        streams enabled. To check, use the index management feature in Kibana or the
+        get index template API: ``` GET _index_template/*?filter_path=index_templates.name,index_templates.index_template.index_patterns,index_templates.index_template.data_stream
+        ``` If no such template exists, you can create one or restore a cluster state
+        that contains one. Without a matching index template, a data stream can't roll
+        over or create backing indices. If your snapshot contains data from App Search
+        or Workplace Search, you must restore the Enterprise Search encryption key before
+        you restore the snapshot.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.16/modules-snapshots.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/restore-snapshot-api.html>`_
 
         :param repository: A repository name
         :param snapshot: A snapshot name
@@ -832,9 +1104,20 @@ class SnapshotClient(NamespacedClient):
         pretty: t.Optional[bool] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Returns information about the status of a snapshot.
+        Get the snapshot status. Get a detailed description of the current state for
+        each shard participating in the snapshot. Note that this API should be used only
+        to obtain detailed shard-level information for ongoing snapshots. If this detail
+        is not needed or you want to obtain information about one or more existing snapshots,
+        use the get snapshot API. WARNING: Using the API to return the status of any
+        snapshots other than currently running snapshots can be expensive. The API requires
+        a read from the repository for each shard in each snapshot. For example, if you
+        have 100 snapshots with 1,000 shards each, an API request that includes all snapshots
+        will require 100,000 reads (100 snapshots x 1,000 shards). Depending on the latency
+        of your storage, such requests can take an extremely long time to return results.
+        These requests can also tax machine resources and, when using cloud storage,
+        incur high processing costs.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.16/modules-snapshots.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/get-snapshot-status-api.html>`_
 
         :param repository: A repository name
         :param snapshot: A comma-separated list of snapshot names
@@ -891,9 +1174,10 @@ class SnapshotClient(NamespacedClient):
         timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Verifies a repository.
+        Verify a snapshot repository. Check for common misconfigurations in a snapshot
+        repository.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.16/modules-snapshots.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/verify-snapshot-repo-api.html>`_
 
         :param name: A repository name
         :param master_timeout: Explicit operation timeout for connection to master node