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

elasticsearch/_async/client/monitoring.py

@@ -42,9 +42,10 @@ class MonitoringClient(NamespacedClient):
         pretty: t.Optional[bool] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Used by the monitoring features to send monitoring data.
+        Send monitoring data. This API is used by the monitoring features to send monitoring
+        data.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.16/monitor-elasticsearch-cluster.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/monitor-elasticsearch-cluster.html>`_
 
         :param interval: Collection interval (e.g., '10s' or '10000ms') of the payload
         :param operations:

elasticsearch/_async/client/nodes.py

@@ -44,15 +44,15 @@ class NodesClient(NamespacedClient):
         pretty: t.Optional[bool] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        You can use this API to clear the archived repositories metering information
-        in the cluster.
+        Clear the archived repositories metering. Clear the archived repositories metering
+        information in the cluster.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.16/clear-repositories-metering-archive-api.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/clear-repositories-metering-archive-api.html>`_
 
         :param node_id: Comma-separated list of node IDs or names used to limit returned
-            information. All the nodes selective options are explained [here](https://www.elastic.co/guide/en/elasticsearch/reference/current/cluster.html#cluster-nodes).
-        :param max_archive_version: Specifies the maximum [archive_version](https://www.elastic.co/guide/en/elasticsearch/reference/current/get-repositories-metering-api.html#get-repositories-metering-api-response-body)
-            to be cleared from the archive.
+            information.
+        :param max_archive_version: Specifies the maximum `archive_version` to be cleared
+            from the archive.
         """
         if node_id in SKIP_IN_PATH:
             raise ValueError("Empty value passed for parameter 'node_id'")
@@ -94,13 +94,13 @@ class NodesClient(NamespacedClient):
         pretty: t.Optional[bool] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        You can use the cluster repositories metering API to retrieve repositories metering
-        information in a cluster. This API exposes monotonically non-decreasing counters
-        and it’s expected that clients would durably store the information needed to
-        compute aggregations over a period of time. Additionally, the information exposed
-        by this API is volatile, meaning that it won’t be present after node restarts.
+        Get cluster repositories metering. Get repositories metering information for
+        a cluster. This API exposes monotonically non-decreasing counters and it is expected
+        that clients would durably store the information needed to compute aggregations
+        over a period of time. Additionally, the information exposed by this API is volatile,
+        meaning that it will not be present after node restarts.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.16/get-repositories-metering-api.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/get-repositories-metering-api.html>`_
 
         :param node_id: Comma-separated list of node IDs or names used to limit returned
             information. All the nodes selective options are explained [here](https://www.elastic.co/guide/en/elasticsearch/reference/current/cluster.html#cluster-nodes).
@@ -151,10 +151,11 @@ class NodesClient(NamespacedClient):
         ] = None,
     ) -> TextApiResponse:
         """
-        This API yields a breakdown of the hot threads on each selected node in the cluster.
-        The output is plain text with a breakdown of each node’s top hot threads.
+        Get the hot threads for nodes. Get a breakdown of the hot threads on each selected
+        node in the cluster. The output is plain text with a breakdown of the top hot
+        threads for each node.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.16/cluster-nodes-hot-threads.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/cluster-nodes-hot-threads.html>`_
 
         :param node_id: List of node IDs or names used to limit returned information.
         :param ignore_idle_threads: If true, known idle threads (e.g. waiting in a socket
@@ -227,9 +228,10 @@ class NodesClient(NamespacedClient):
         timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Returns cluster nodes information.
+        Get node information. By default, the API returns all attributes and core settings
+        for cluster nodes.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.16/cluster-nodes-info.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/cluster-nodes-info.html>`_
 
         :param node_id: Comma-separated list of node IDs or names used to limit returned
             information.
@@ -296,9 +298,20 @@ class NodesClient(NamespacedClient):
         body: t.Optional[t.Dict[str, t.Any]] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Reloads the keystore on nodes in the cluster.
+        Reload the keystore on nodes in the cluster. Secure settings are stored in an
+        on-disk keystore. Certain of these settings are reloadable. That is, you can
+        change them on disk and reload them without restarting any nodes in the cluster.
+        When you have updated reloadable secure settings in your keystore, you can use
+        this API to reload those settings on each node. When the Elasticsearch keystore
+        is password protected and not simply obfuscated, you must provide the password
+        for the keystore when you reload the secure settings. Reloading the settings
+        for the whole cluster assumes that the keystores for all nodes are protected
+        with the same password; this method is allowed only when inter-node communications
+        are encrypted. Alternatively, you can reload the secure settings on each node
+        by locally accessing the API and passing the node-specific Elasticsearch keystore
+        password.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.16/secure-settings.html#reloadable-secure-settings>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/secure-settings.html#reloadable-secure-settings>`_
 
         :param node_id: The names of particular nodes in the cluster to target.
         :param secure_settings_password: The password for the Elasticsearch keystore.
@@ -367,9 +380,10 @@ class NodesClient(NamespacedClient):
         types: t.Optional[t.Sequence[str]] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Returns cluster nodes statistics.
+        Get node statistics. Get statistics for nodes in a cluster. By default, all stats
+        are returned. You can limit the returned information by using metrics.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.16/cluster-nodes-stats.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/cluster-nodes-stats.html>`_
 
         :param node_id: Comma-separated list of node IDs or names used to limit returned
             information.
@@ -484,9 +498,9 @@ class NodesClient(NamespacedClient):
         timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Returns information on the usage of features.
+        Get feature usage information.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.16/cluster-nodes-usage.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/cluster-nodes-usage.html>`_
 
         :param node_id: A comma-separated list of node IDs or names to limit the returned
             information; use `_local` to return information from the node you're connecting

elasticsearch/_async/client/query_rules.py

@@ -37,9 +37,11 @@ class QueryRulesClient(NamespacedClient):
         pretty: t.Optional[bool] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Deletes a query rule within a query ruleset.
+        Delete a query rule. Delete a query rule within a query ruleset. This is a destructive
+        action that is only recoverable by re-adding the same rule with the create or
+        update query rule API.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.16/delete-query-rule.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/delete-query-rule.html>`_
 
         :param ruleset_id: The unique identifier of the query ruleset containing the
             rule to delete
@@ -85,9 +87,10 @@ class QueryRulesClient(NamespacedClient):
         pretty: t.Optional[bool] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Deletes a query ruleset.
+        Delete a query ruleset. Remove a query ruleset and its associated data. This
+        is a destructive action that is not recoverable.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.16/delete-query-ruleset.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/delete-query-ruleset.html>`_
 
         :param ruleset_id: The unique identifier of the query ruleset to delete
         """
@@ -126,9 +129,9 @@ class QueryRulesClient(NamespacedClient):
         pretty: t.Optional[bool] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Returns the details about a query rule within a query ruleset
+        Get a query rule. Get details about a query rule within a query ruleset.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.16/get-query-rule.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/get-query-rule.html>`_
 
         :param ruleset_id: The unique identifier of the query ruleset containing the
             rule to retrieve
@@ -174,9 +177,9 @@ class QueryRulesClient(NamespacedClient):
         pretty: t.Optional[bool] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Returns the details about a query ruleset
+        Get a query ruleset. Get details about a query ruleset.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.16/get-query-ruleset.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/get-query-ruleset.html>`_
 
         :param ruleset_id: The unique identifier of the query ruleset
         """
@@ -217,12 +220,12 @@ class QueryRulesClient(NamespacedClient):
         size: t.Optional[int] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Returns summarized information about existing query rulesets.
+        Get all query rulesets. Get summarized information about the query rulesets.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.16/list-query-rulesets.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/list-query-rulesets.html>`_
 
-        :param from_: Starting offset (default: 0)
-        :param size: specifies a max number of results to get
+        :param from_: The offset from the first result to fetch.
+        :param size: The maximum number of results to retrieve.
         """
         __path_parts: t.Dict[str, str] = {}
         __path = "/_query_rules"
@@ -270,17 +273,26 @@ class QueryRulesClient(NamespacedClient):
         body: t.Optional[t.Dict[str, t.Any]] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Creates or updates a query rule within a query ruleset.
+        Create or update a query rule. Create or update a query rule within a query ruleset.
+        IMPORTANT: Due to limitations within pinned queries, you can only pin documents
+        using ids or docs, but cannot use both in single rule. It is advised to use one
+        or the other in query rulesets, to avoid errors. Additionally, pinned queries
+        have a maximum limit of 100 pinned hits. If multiple matching rules pin more
+        than 100 documents, only the first 100 documents are pinned in the order they
+        are specified in the ruleset.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.16/put-query-rule.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/put-query-rule.html>`_
 
         :param ruleset_id: The unique identifier of the query ruleset containing the
-            rule to be created or updated
+            rule to be created or updated.
         :param rule_id: The unique identifier of the query rule within the specified
-            ruleset to be created or updated
-        :param actions:
-        :param criteria:
-        :param type:
+            ruleset to be created or updated.
+        :param actions: The actions to take when the rule is matched. The format of this
+            action depends on the rule type.
+        :param criteria: The criteria that must be met for the rule to be applied. If
+            multiple criteria are specified for a rule, all criteria must be met for
+            the rule to be applied.
+        :param type: The type of rule.
         :param priority:
         """
         if ruleset_id in SKIP_IN_PATH:
@@ -345,12 +357,19 @@ class QueryRulesClient(NamespacedClient):
         body: t.Optional[t.Dict[str, t.Any]] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Creates or updates a query ruleset.
+        Create or update a query ruleset. There is a limit of 100 rules per ruleset.
+        This limit can be increased by using the `xpack.applications.rules.max_rules_per_ruleset`
+        cluster setting. IMPORTANT: Due to limitations within pinned queries, you can
+        only select documents using `ids` or `docs`, but cannot use both in single rule.
+        It is advised to use one or the other in query rulesets, to avoid errors. Additionally,
+        pinned queries have a maximum limit of 100 pinned hits. If multiple matching
+        rules pin more than 100 documents, only the first 100 documents are pinned in
+        the order they are specified in the ruleset.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.16/put-query-ruleset.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/put-query-ruleset.html>`_
 
         :param ruleset_id: The unique identifier of the query ruleset to be created or
-            updated
+            updated.
         :param rules:
         """
         if ruleset_id in SKIP_IN_PATH:
@@ -398,13 +417,16 @@ class QueryRulesClient(NamespacedClient):
         body: t.Optional[t.Dict[str, t.Any]] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Creates or updates a query ruleset.
+        Test a query ruleset. Evaluate match criteria against a query ruleset to identify
+        the rules that would match that criteria.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.16/test-query-ruleset.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/test-query-ruleset.html>`_
 
         :param ruleset_id: The unique identifier of the query ruleset to be created or
             updated
-        :param match_criteria:
+        :param match_criteria: The match criteria to apply to rules in the given query
+            ruleset. Match criteria should match the keys defined in the `criteria.metadata`
+            field of the rule.
         """
         if ruleset_id in SKIP_IN_PATH:
             raise ValueError("Empty value passed for parameter 'ruleset_id'")

elasticsearch/_async/client/rollup.py

@@ -43,9 +43,22 @@ class RollupClient(NamespacedClient):
         pretty: t.Optional[bool] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Deletes an existing rollup job.
+        Delete a rollup job. A job must be stopped before it can be deleted. If you attempt
+        to delete a started job, an error occurs. Similarly, if you attempt to delete
+        a nonexistent job, an exception occurs. IMPORTANT: When you delete a job, you
+        remove only the process that is actively monitoring and rolling up data. The
+        API does not delete any previously rolled up data. This is by design; a user
+        may wish to roll up a static data set. Because the data set is static, after
+        it has been fully rolled up there is no need to keep the indexing rollup job
+        around (as there will be no new data). Thus the job can be deleted, leaving behind
+        the rolled up data for analysis. If you wish to also remove the rollup data and
+        the rollup index contains the data for only a single job, you can delete the
+        whole rollup index. If the rollup index stores data from several jobs, you must
+        issue a delete-by-query that targets the rollup job's identifier in the rollup
+        index. For example: ``` POST my_rollup_index/_delete_by_query { "query": { "term":
+        { "_rollup.id": "the_rollup_job_id" } } } ```
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.16/rollup-delete-job.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/rollup-delete-job.html>`_
 
         :param id: Identifier for the job.
         """
@@ -84,9 +97,13 @@ class RollupClient(NamespacedClient):
         pretty: t.Optional[bool] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Retrieves the configuration, stats, and status of rollup jobs.
+        Get rollup job information. Get the configuration, stats, and status of rollup
+        jobs. NOTE: This API returns only active (both `STARTED` and `STOPPED`) jobs.
+        If a job was created, ran for a while, then was deleted, the API does not return
+        any details about it. For details about a historical rollup job, the rollup capabilities
+        API may be more useful.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.16/rollup-get-job.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/rollup-get-job.html>`_
 
         :param id: Identifier for the rollup job. If it is `_all` or omitted, the API
             returns all rollup jobs.
@@ -129,10 +146,17 @@ class RollupClient(NamespacedClient):
         pretty: t.Optional[bool] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Returns the capabilities of any rollup jobs that have been configured for a specific
-        index or index pattern.
+        Get the rollup job capabilities. Get the capabilities of any rollup jobs that
+        have been configured for a specific index or index pattern. This API is useful
+        because a rollup job is often configured to rollup only a subset of fields from
+        the source index. Furthermore, only certain aggregations can be configured for
+        various fields, leading to a limited subset of functionality depending on that
+        configuration. This API enables you to inspect an index and determine: 1. Does
+        this index have associated rollup data somewhere in the cluster? 2. If yes to
+        the first question, what fields were rolled up, what aggregations can be performed,
+        and where does the data live?
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.16/rollup-get-rollup-caps.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/rollup-get-rollup-caps.html>`_
 
         :param id: Index, indices or index-pattern to return rollup capabilities for.
             `_all` may be used to fetch rollup capabilities from all jobs.
@@ -175,10 +199,14 @@ class RollupClient(NamespacedClient):
         pretty: t.Optional[bool] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Returns the rollup capabilities of all jobs inside of a rollup index (for example,
-        the index where rollup data is stored).
+        Get the rollup index capabilities. Get the rollup capabilities of all jobs inside
+        of a rollup index. A single rollup index may store the data for multiple rollup
+        jobs and may have a variety of capabilities depending on those jobs. This API
+        enables you to determine: * What jobs are stored in an index (or indices specified
+        via a pattern)? * What target indices were rolled up, what fields were used in
+        those rollups, and what aggregations can be performed on each job?
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.16/rollup-get-rollup-index-caps.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/rollup-get-rollup-index-caps.html>`_
 
         :param index: Data stream or index to check for rollup capabilities. Wildcard
             (`*`) expressions are supported.
@@ -239,9 +267,18 @@ class RollupClient(NamespacedClient):
         body: t.Optional[t.Dict[str, t.Any]] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Creates a rollup job.
+        Create a rollup job. WARNING: From 8.15.0, calling this API in a cluster with
+        no rollup usage will fail with a message about the deprecation and planned removal
+        of rollup features. A cluster needs to contain either a rollup job or a rollup
+        index in order for this API to be allowed to run. The rollup job configuration
+        contains all the details about how the job should run, when it indexes documents,
+        and what future queries will be able to run against the rollup index. There are
+        three main sections to the job configuration: the logistical details about the
+        job (for example, the cron schedule), the fields that are used for grouping,
+        and what metrics to collect for each group. Jobs are created in a `STOPPED` state.
+        You can start them with the start rollup jobs API.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.16/rollup-put-job.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/rollup-put-job.html>`_
 
         :param id: Identifier for the rollup job. This can be any alphanumeric string
             and uniquely identifies the data that is associated with the rollup job.
@@ -356,14 +393,41 @@ class RollupClient(NamespacedClient):
         body: t.Optional[t.Dict[str, t.Any]] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Enables searching rolled-up data using the standard Query DSL.
+        Search rolled-up data. The rollup search endpoint is needed because, internally,
+        rolled-up documents utilize a different document structure than the original
+        data. It rewrites standard Query DSL into a format that matches the rollup documents
+        then takes the response and rewrites it back to what a client would expect given
+        the original query. The request body supports a subset of features from the regular
+        search API. The following functionality is not available: `size`: Because rollups
+        work on pre-aggregated data, no search hits can be returned and so size must
+        be set to zero or omitted entirely. `highlighter`, `suggestors`, `post_filter`,
+        `profile`, `explain`: These are similarly disallowed. **Searching both historical
+        rollup and non-rollup data** The rollup search API has the capability to search
+        across both "live" non-rollup data and the aggregated rollup data. This is done
+        by simply adding the live indices to the URI. For example: ``` GET sensor-1,sensor_rollup/_rollup_search
+        { "size": 0, "aggregations": { "max_temperature": { "max": { "field": "temperature"
+        } } } } ``` The rollup search endpoint does two things when the search runs:
+        * The original request is sent to the non-rollup index unaltered. * A rewritten
+        version of the original request is sent to the rollup index. When the two responses
+        are received, the endpoint rewrites the rollup response and merges the two together.
+        During the merging process, if there is any overlap in buckets between the two
+        responses, the buckets from the non-rollup index are used.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.16/rollup-search.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/rollup-search.html>`_
 
-        :param index: Enables searching rolled-up data using the standard Query DSL.
+        :param index: A comma-separated list of data streams and indices used to limit
+            the request. This parameter has the following rules: * At least one data
+            stream, index, or wildcard expression must be specified. This target can
+            include a rollup or non-rollup index. For data streams, the stream's backing
+            indices can only serve as non-rollup indices. Omitting the parameter or using
+            `_all` are not permitted. * Multiple non-rollup indices may be specified.
+            * Only one rollup index may be specified. If more than one are supplied,
+            an exception occurs. * Wildcard expressions (`*`) may be used. If they match
+            more than one rollup index, an exception occurs. However, you can use an
+            expression to match multiple non-rollup indices or data streams.
         :param aggregations: Specifies aggregations.
         :param aggs: Specifies aggregations.
-        :param query: Specifies a DSL query.
+        :param query: Specifies a DSL query that is subject to some limitations.
         :param rest_total_hits_as_int: Indicates whether hits.total should be rendered
             as an integer or an object in the rest search response
         :param size: Must be zero if set, as rollups work on pre-aggregated data.
@@ -420,9 +484,10 @@ class RollupClient(NamespacedClient):
         pretty: t.Optional[bool] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Starts an existing, stopped rollup job.
+        Start rollup jobs. If you try to start a job that does not exist, an exception
+        occurs. If you try to start a job that is already started, nothing happens.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.16/rollup-start-job.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/rollup-start-job.html>`_
 
         :param id: Identifier for the rollup job.
         """
@@ -463,14 +528,24 @@ class RollupClient(NamespacedClient):
         wait_for_completion: t.Optional[bool] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Stops an existing, started rollup job.
+        Stop rollup jobs. If you try to stop a job that does not exist, an exception
+        occurs. If you try to stop a job that is already stopped, nothing happens. Since
+        only a stopped job can be deleted, it can be useful to block the API until the
+        indexer has fully stopped. This is accomplished with the `wait_for_completion`
+        query parameter, and optionally a timeout. For example: ``` POST _rollup/job/sensor/_stop?wait_for_completion=true&timeout=10s
+        ``` The parameter blocks the API call from returning until either the job has
+        moved to STOPPED or the specified time has elapsed. If the specified time elapses
+        without the job moving to STOPPED, a timeout exception occurs.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.16/rollup-stop-job.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/rollup-stop-job.html>`_
 
         :param id: Identifier for the rollup job.
         :param timeout: If `wait_for_completion` is `true`, the API blocks for (at maximum)
             the specified duration while waiting for the job to stop. If more than `timeout`
-            time has passed, the API throws a timeout exception.
+            time has passed, the API throws a timeout exception. NOTE: Even if a timeout
+            occurs, the stop request is still processing and eventually moves the job
+            to STOPPED. The timeout simply means the API call itself timed out while
+            waiting for the status change.
         :param wait_for_completion: If set to `true`, causes the API to block until the
             indexer state completely stops. If set to `false`, the API returns immediately
             and the indexer is stopped asynchronously in the background.