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

elasticsearch/_async/client/sql.py

@@ -39,9 +39,9 @@ class SqlClient(NamespacedClient):
         body: t.Optional[t.Dict[str, t.Any]] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Clears the SQL cursor
+        Clear an SQL search cursor.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.16/clear-sql-cursor-api.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/clear-sql-cursor-api.html>`_
 
         :param cursor: Cursor to clear.
         """
@@ -84,12 +84,15 @@ class SqlClient(NamespacedClient):
         pretty: t.Optional[bool] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Deletes an async SQL search or a stored synchronous SQL search. If the search
-        is still running, the API cancels it.
+        Delete an async SQL search. Delete an async SQL search or a stored synchronous
+        SQL search. If the search is still running, the API cancels it. If the Elasticsearch
+        security features are enabled, only the following users can use this API to delete
+        a search: * Users with the `cancel_task` cluster privilege. * The user who first
+        submitted the search.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.16/delete-async-sql-search-api.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/delete-async-sql-search-api.html>`_
 
-        :param id: Identifier for the search.
+        :param id: The identifier for the search.
         """
         if id in SKIP_IN_PATH:
             raise ValueError("Empty value passed for parameter 'id'")
@@ -131,21 +134,24 @@ class SqlClient(NamespacedClient):
         ] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Returns the current status and available results for an async SQL search or stored
-        synchronous SQL search
+        Get async SQL search results. Get the current status and available results for
+        an async SQL search or stored synchronous SQL search. If the Elasticsearch security
+        features are enabled, only the user who first submitted the SQL search can retrieve
+        the search using this API.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.16/get-async-sql-search-api.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/get-async-sql-search-api.html>`_
 
-        :param id: Identifier for the search.
-        :param delimiter: Separator for CSV results. The API only supports this parameter
-            for CSV responses.
-        :param format: Format for the response. You must specify a format using this
-            parameter or the Accept HTTP header. If you specify both, the API uses this
-            parameter.
-        :param keep_alive: Retention period for the search and its results. Defaults
+        :param id: The identifier for the search.
+        :param delimiter: The separator for CSV results. The API supports this parameter
+            only for CSV responses.
+        :param format: The format for the response. You must specify a format using this
+            parameter or the `Accept` HTTP header. If you specify both, the API uses
+            this parameter.
+        :param keep_alive: The retention period for the search and its results. It defaults
             to the `keep_alive` period for the original SQL search.
-        :param wait_for_completion_timeout: Period to wait for complete results. Defaults
-            to no timeout, meaning the request waits for complete search results.
+        :param wait_for_completion_timeout: The period to wait for complete results.
+            It defaults to no timeout, meaning the request waits for complete search
+            results.
         """
         if id in SKIP_IN_PATH:
             raise ValueError("Empty value passed for parameter 'id'")
@@ -189,12 +195,12 @@ class SqlClient(NamespacedClient):
         pretty: t.Optional[bool] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Returns the current status of an async SQL search or a stored synchronous SQL
-        search
+        Get the async SQL search status. Get the current status of an async SQL search
+        or a stored synchronous SQL search.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.16/get-async-sql-search-status-api.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/get-async-sql-search-status-api.html>`_
 
-        :param id: Identifier for the search.
+        :param id: The identifier for the search.
         """
         if id in SKIP_IN_PATH:
             raise ValueError("Empty value passed for parameter 'id'")
@@ -221,6 +227,7 @@ class SqlClient(NamespacedClient):
 
     @_rewrite_parameters(
         body_fields=(
+            "allow_partial_search_results",
             "catalog",
             "columnar",
             "cursor",
@@ -243,6 +250,7 @@ class SqlClient(NamespacedClient):
     async def query(
         self,
         *,
+        allow_partial_search_results: t.Optional[bool] = None,
         catalog: t.Optional[str] = None,
         columnar: t.Optional[bool] = None,
         cursor: t.Optional[str] = None,
@@ -273,40 +281,49 @@ class SqlClient(NamespacedClient):
         body: t.Optional[t.Dict[str, t.Any]] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Executes a SQL request
+        Get SQL search results. Run an SQL request.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.16/sql-search-api.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/sql-search-api.html>`_
 
-        :param catalog: Default catalog (cluster) for queries. If unspecified, the queries
-            execute on the data in the local cluster only.
-        :param columnar: If true, the results in a columnar fashion: one row represents
-            all the values of a certain column from the current page of results.
-        :param cursor: Cursor used to retrieve a set of paginated results. If you specify
-            a cursor, the API only uses the `columnar` and `time_zone` request body parameters.
-            It ignores other request body parameters.
-        :param fetch_size: The maximum number of rows (or entries) to return in one response
-        :param field_multi_value_leniency: Throw an exception when encountering multiple
-            values for a field (default) or be lenient and return the first value from
-            the list (without any guarantees of what that will be - typically the first
-            in natural ascending order).
-        :param filter: Elasticsearch query DSL for additional filtering.
-        :param format: Format for the response.
-        :param index_using_frozen: If true, the search can run on frozen indices. Defaults
-            to false.
-        :param keep_alive: Retention period for an async or saved synchronous search.
-        :param keep_on_completion: If true, Elasticsearch stores synchronous searches
-            if you also specify the wait_for_completion_timeout parameter. If false,
-            Elasticsearch only stores async searches that don’t finish before the wait_for_completion_timeout.
-        :param page_timeout: The timeout before a pagination request fails.
-        :param params: Values for parameters in the query.
-        :param query: SQL query to run.
+        :param allow_partial_search_results: If `true`, the response has partial results
+            when there are shard request timeouts or shard failures. If `false`, the
+            API returns an error with no partial results.
+        :param catalog: The default catalog (cluster) for queries. If unspecified, the
+            queries execute on the data in the local cluster only.
+        :param columnar: If `true`, the results are in a columnar fashion: one row represents
+            all the values of a certain column from the current page of results. The
+            API supports this parameter only for CBOR, JSON, SMILE, and YAML responses.
+        :param cursor: The cursor used to retrieve a set of paginated results. If you
+            specify a cursor, the API only uses the `columnar` and `time_zone` request
+            body parameters. It ignores other request body parameters.
+        :param fetch_size: The maximum number of rows (or entries) to return in one response.
+        :param field_multi_value_leniency: If `false`, the API returns an exception when
+            encountering multiple values for a field. If `true`, the API is lenient and
+            returns the first value from the array with no guarantee of consistent results.
+        :param filter: The Elasticsearch query DSL for additional filtering.
+        :param format: The format for the response. You can also specify a format using
+            the `Accept` HTTP header. If you specify both this parameter and the `Accept`
+            HTTP header, this parameter takes precedence.
+        :param index_using_frozen: If `true`, the search can run on frozen indices.
+        :param keep_alive: The retention period for an async or saved synchronous search.
+        :param keep_on_completion: If `true`, Elasticsearch stores synchronous searches
+            if you also specify the `wait_for_completion_timeout` parameter. If `false`,
+            Elasticsearch only stores async searches that don't finish before the `wait_for_completion_timeout`.
+        :param page_timeout: The minimum retention period for the scroll cursor. After
+            this time period, a pagination request might fail because the scroll cursor
+            is no longer available. Subsequent scroll requests prolong the lifetime of
+            the scroll cursor by the duration of `page_timeout` in the scroll request.
+        :param params: The values for parameters in the query.
+        :param query: The SQL query to run.
         :param request_timeout: The timeout before the request fails.
-        :param runtime_mappings: Defines one or more runtime fields in the search request.
-            These fields take precedence over mapped fields with the same name.
-        :param time_zone: ISO-8601 time zone ID for the search.
-        :param wait_for_completion_timeout: Period to wait for complete results. Defaults
-            to no timeout, meaning the request waits for complete search results. If
-            the search doesn’t finish within this period, the search becomes async.
+        :param runtime_mappings: One or more runtime fields for the search request. These
+            fields take precedence over mapped fields with the same name.
+        :param time_zone: The ISO-8601 time zone ID for the search.
+        :param wait_for_completion_timeout: The period to wait for complete results.
+            It defaults to no timeout, meaning the request waits for complete search
+            results. If the search doesn't finish within this period, the search becomes
+            async. To save a synchronous search, you must specify this parameter and
+            the `keep_on_completion` parameter.
         """
         __path_parts: t.Dict[str, str] = {}
         __path = "/_sql"
@@ -323,6 +340,8 @@ class SqlClient(NamespacedClient):
         if pretty is not None:
             __query["pretty"] = pretty
         if not __body:
+            if allow_partial_search_results is not None:
+                __body["allow_partial_search_results"] = allow_partial_search_results
             if catalog is not None:
                 __body["catalog"] = catalog
             if columnar is not None:
@@ -383,14 +402,16 @@ class SqlClient(NamespacedClient):
         body: t.Optional[t.Dict[str, t.Any]] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Translates SQL into Elasticsearch queries
+        Translate SQL into Elasticsearch queries. Translate an SQL search into a search
+        API request containing Query DSL. It accepts the same request body parameters
+        as the SQL search API, excluding `cursor`.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.16/sql-translate-api.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/sql-translate-api.html>`_
 
-        :param query: SQL query to run.
+        :param query: The SQL query to run.
         :param fetch_size: The maximum number of rows (or entries) to return in one response.
-        :param filter: Elasticsearch query DSL for additional filtering.
-        :param time_zone: ISO-8601 time zone ID for the search.
+        :param filter: The Elasticsearch query DSL for additional filtering.
+        :param time_zone: The ISO-8601 time zone ID for the search.
         """
         if query is None and body is None:
             raise ValueError("Empty value passed for parameter 'query'")

elasticsearch/_async/client/ssl.py

@@ -53,7 +53,7 @@ class SslClient(NamespacedClient):
         the API output includes all certificates in that store, even though some of the
         certificates might not be in active use within the cluster.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.16/security-api-ssl.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/security-api-ssl.html>`_
         """
         __path_parts: t.Dict[str, str] = {}
         __path = "/_ssl/certificates"

elasticsearch/_async/client/synonyms.py

@@ -36,11 +36,25 @@ class SynonymsClient(NamespacedClient):
         pretty: t.Optional[bool] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Deletes a synonym set
+        Delete a synonym set. You can only delete a synonyms set that is not in use by
+        any index analyzer. Synonyms sets can be used in synonym graph token filters
+        and synonym token filters. These synonym filters can be used as part of search
+        analyzers. Analyzers need to be loaded when an index is restored (such as when
+        a node starts, or the index becomes open). Even if the analyzer is not used on
+        any field mapping, it still needs to be loaded on the index recovery phase. If
+        any analyzers cannot be loaded, the index becomes unavailable and the cluster
+        status becomes red or yellow as index shards are not available. To prevent that,
+        synonyms sets that are used in analyzers can't be deleted. A delete request in
+        this case will return a 400 response code. To remove a synonyms set, you must
+        first remove all indices that contain analyzers using it. You can migrate an
+        index by creating a new index that does not contain the token filter with the
+        synonyms set, and use the reindex API in order to copy over the index data. Once
+        finished, you can delete the index. When the synonyms set is not used in analyzers,
+        you will be able to delete it.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.16/delete-synonyms-set.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/delete-synonyms-set.html>`_
 
-        :param id: The id of the synonyms set to be deleted
+        :param id: The synonyms set identifier to delete.
         """
         if id in SKIP_IN_PATH:
             raise ValueError("Empty value passed for parameter 'id'")
@@ -77,12 +91,12 @@ class SynonymsClient(NamespacedClient):
         pretty: t.Optional[bool] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Deletes a synonym rule in a synonym set
+        Delete a synonym rule. Delete a synonym rule from a synonym set.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.16/delete-synonym-rule.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/delete-synonym-rule.html>`_
 
-        :param set_id: The id of the synonym set to be updated
-        :param rule_id: The id of the synonym rule to be deleted
+        :param set_id: The ID of the synonym set to update.
+        :param rule_id: The ID of the synonym rule to delete.
         """
         if set_id in SKIP_IN_PATH:
             raise ValueError("Empty value passed for parameter 'set_id'")
@@ -127,13 +141,13 @@ class SynonymsClient(NamespacedClient):
         size: t.Optional[int] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Retrieves a synonym set
+        Get a synonym set.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.16/get-synonyms-set.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/get-synonyms-set.html>`_
 
-        :param id: "The id of the synonyms set to be retrieved
-        :param from_: Starting offset for query rules to be retrieved
-        :param size: specifies a max number of query rules to retrieve
+        :param id: The synonyms set identifier to retrieve.
+        :param from_: The starting offset for query rules to retrieve.
+        :param size: The max number of query rules to retrieve.
         """
         if id in SKIP_IN_PATH:
             raise ValueError("Empty value passed for parameter 'id'")
@@ -174,12 +188,12 @@ class SynonymsClient(NamespacedClient):
         pretty: t.Optional[bool] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Retrieves a synonym rule from a synonym set
+        Get a synonym rule. Get a synonym rule from a synonym set.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.16/get-synonym-rule.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/get-synonym-rule.html>`_
 
-        :param set_id: The id of the synonym set to retrieve the synonym rule from
-        :param rule_id: The id of the synonym rule to retrieve
+        :param set_id: The ID of the synonym set to retrieve the synonym rule from.
+        :param rule_id: The ID of the synonym rule to retrieve.
         """
         if set_id in SKIP_IN_PATH:
             raise ValueError("Empty value passed for parameter 'set_id'")
@@ -223,12 +237,12 @@ class SynonymsClient(NamespacedClient):
         size: t.Optional[int] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Retrieves a summary of all defined synonym sets
+        Get all synonym sets. Get a summary of all defined synonym sets.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.16/list-synonyms-sets.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/get-synonyms-set.html>`_
 
-        :param from_: Starting offset
-        :param size: specifies a max number of results to get
+        :param from_: The starting offset for synonyms sets to retrieve.
+        :param size: The maximum number of synonyms sets to retrieve.
         """
         __path_parts: t.Dict[str, str] = {}
         __path = "/_synonyms"
@@ -272,12 +286,17 @@ class SynonymsClient(NamespacedClient):
         body: t.Optional[t.Dict[str, t.Any]] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Creates or updates a synonym set.
+        Create or update a synonym set. Synonyms sets are limited to a maximum of 10,000
+        synonym rules per set. If you need to manage more synonym rules, you can create
+        multiple synonym sets. When an existing synonyms set is updated, the search analyzers
+        that use the synonyms set are reloaded automatically for all indices. This is
+        equivalent to invoking the reload search analyzers API for all indices that use
+        the synonyms set.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.16/put-synonyms-set.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/put-synonyms-set.html>`_
 
-        :param id: The id of the synonyms set to be created or updated
-        :param synonyms_set: The synonym set information to update
+        :param id: The ID of the synonyms set to be created or updated.
+        :param synonyms_set: The synonym rules definitions for the synonyms set.
         """
         if id in SKIP_IN_PATH:
             raise ValueError("Empty value passed for parameter 'id'")
@@ -325,13 +344,17 @@ class SynonymsClient(NamespacedClient):
         body: t.Optional[t.Dict[str, t.Any]] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Creates or updates a synonym rule in a synonym set
+        Create or update a synonym rule. Create or update a synonym rule in a synonym
+        set. If any of the synonym rules included is invalid, the API returns an error.
+        When you update a synonym rule, all analyzers using the synonyms set will be
+        reloaded automatically to reflect the new rule.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.16/put-synonym-rule.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/put-synonym-rule.html>`_
 
-        :param set_id: The id of the synonym set to be updated with the synonym rule
-        :param rule_id: The id of the synonym rule to be updated or created
-        :param synonyms:
+        :param set_id: The ID of the synonym set.
+        :param rule_id: The ID of the synonym rule to be updated or created.
+        :param synonyms: The synonym rule information definition, which must be in Solr
+            format.
         """
         if set_id in SKIP_IN_PATH:
             raise ValueError("Empty value passed for parameter 'set_id'")

elasticsearch/_async/client/tasks.py

@@ -47,17 +47,30 @@ class TasksClient(NamespacedClient):
         wait_for_completion: t.Optional[bool] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Cancels a task, if it can be cancelled through an API.
+        Cancel a task. WARNING: The task management API is new and should still be considered
+        a beta feature. The API may change in ways that are not backwards compatible.
+        A task may continue to run for some time after it has been cancelled because
+        it may not be able to safely stop its current activity straight away. It is also
+        possible that Elasticsearch must complete its work on other tasks before it can
+        process the cancellation. The get task information API will continue to list
+        these cancelled tasks until they complete. The cancelled flag in the response
+        indicates that the cancellation command has been processed and the task will
+        stop as soon as possible. To troubleshoot why a cancelled task does not complete
+        promptly, use the get task information API with the `?detailed` parameter to
+        identify the other tasks the system is running. You can also use the node hot
+        threads API to obtain detailed information about the work the system is doing
+        instead of completing the cancelled task.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.16/tasks.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/tasks.html>`_
 
-        :param task_id: ID of the task.
-        :param actions: Comma-separated list or wildcard expression of actions used to
-            limit the request.
-        :param nodes: Comma-separated list of node IDs or names used to limit the request.
-        :param parent_task_id: Parent task ID used to limit the tasks.
-        :param wait_for_completion: Should the request block until the cancellation of
-            the task and its descendant tasks is completed. Defaults to false
+        :param task_id: The task identifier.
+        :param actions: A comma-separated list or wildcard expression of actions that
+            is used to limit the request.
+        :param nodes: A comma-separated list of node IDs or names that is used to limit
+            the request.
+        :param parent_task_id: A parent task ID that is used to limit the tasks.
+        :param wait_for_completion: If true, the request blocks until all found tasks
+            are complete.
         """
         __path_parts: t.Dict[str, str]
         if task_id not in SKIP_IN_PATH:
@@ -107,14 +120,17 @@ class TasksClient(NamespacedClient):
         wait_for_completion: t.Optional[bool] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Get task information. Returns information about the tasks currently executing
-        in the cluster.
+        Get task information. Get information about a task currently running in the cluster.
+        WARNING: The task management API is new and should still be considered a beta
+        feature. The API may change in ways that are not backwards compatible. If the
+        task identifier is not found, a 404 response code indicates that there are no
+        resources that match the request.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.16/tasks.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/tasks.html>`_
 
-        :param task_id: ID of the task.
-        :param timeout: Period to wait for a response. If no response is received before
-            the timeout expires, the request fails and returns an error.
+        :param task_id: The task identifier.
+        :param timeout: The period to wait for a response. If no response is received
+            before the timeout expires, the request fails and returns an error.
         :param wait_for_completion: If `true`, the request blocks until the task has
             completed.
         """
@@ -166,25 +182,49 @@ class TasksClient(NamespacedClient):
         wait_for_completion: t.Optional[bool] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        The task management API returns information about tasks currently executing on
-        one or more nodes in the cluster.
+        Get all tasks. Get information about the tasks currently running on one or more
+        nodes in the cluster. WARNING: The task management API is new and should still
+        be considered a beta feature. The API may change in ways that are not backwards
+        compatible. **Identifying running tasks** The `X-Opaque-Id header`, when provided
+        on the HTTP request header, is going to be returned as a header in the response
+        as well as in the headers field for in the task information. This enables you
+        to track certain calls or associate certain tasks with the client that started
+        them. For example: ``` curl -i -H "X-Opaque-Id: 123456" "http://localhost:9200/_tasks?group_by=parents"
+        ``` The API returns the following result: ``` HTTP/1.1 200 OK X-Opaque-Id: 123456
+        content-type: application/json; charset=UTF-8 content-length: 831 { "tasks" :
+        { "u5lcZHqcQhu-rUoFaqDphA:45" : { "node" : "u5lcZHqcQhu-rUoFaqDphA", "id" : 45,
+        "type" : "transport", "action" : "cluster:monitor/tasks/lists", "start_time_in_millis"
+        : 1513823752749, "running_time_in_nanos" : 293139, "cancellable" : false, "headers"
+        : { "X-Opaque-Id" : "123456" }, "children" : [ { "node" : "u5lcZHqcQhu-rUoFaqDphA",
+        "id" : 46, "type" : "direct", "action" : "cluster:monitor/tasks/lists[n]", "start_time_in_millis"
+        : 1513823752750, "running_time_in_nanos" : 92133, "cancellable" : false, "parent_task_id"
+        : "u5lcZHqcQhu-rUoFaqDphA:45", "headers" : { "X-Opaque-Id" : "123456" } } ] }
+        } } ``` In this example, `X-Opaque-Id: 123456` is the ID as a part of the response
+        header. The `X-Opaque-Id` in the task `headers` is the ID for the task that was
+        initiated by the REST request. The `X-Opaque-Id` in the children `headers` is
+        the child task of the task that was initiated by the REST request.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.16/tasks.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/tasks.html>`_
 
-        :param actions: Comma-separated list or wildcard expression of actions used to
-            limit the request.
+        :param actions: A comma-separated list or wildcard expression of actions used
+            to limit the request. For example, you can use `cluser:*` to retrieve all
+            cluster-related tasks.
         :param detailed: If `true`, the response includes detailed information about
-            shard recoveries.
-        :param group_by: Key used to group tasks in the response.
-        :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.
-        :param nodes: Comma-separated list of node IDs or names used to limit returned
-            information.
-        :param parent_task_id: Parent task ID used to limit returned information. To
-            return all tasks, omit this parameter or use a value of `-1`.
-        :param timeout: Period to wait for a response. If no response is received before
-            the timeout expires, the request fails and returns an error.
+            the running tasks. This information is useful to distinguish tasks from each
+            other but is more costly to run.
+        :param group_by: A key that is used to group tasks in the response. The task
+            lists can be grouped either by nodes or by parent tasks.
+        :param master_timeout: The 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.
+        :param nodes: A comma-separated list of node IDs or names that is used to limit
+            the returned information.
+        :param parent_task_id: A parent task identifier that is used to limit returned
+            information. To return all tasks, omit this parameter or use a value of `-1`.
+            If the parent task is not found, the API does not return a 404 response code.
+        :param timeout: The period to wait for each node to respond. If a node does not
+            respond before its timeout expires, the response does not include its information.
+            However, timed out nodes are included in the `node_failures` property.
         :param wait_for_completion: If `true`, the request blocks until the operation
             is complete.
         """