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

elasticsearch/_sync/client/sql.py

@@ -39,7 +39,10 @@ class SqlClient(NamespacedClient):
         body: t.Optional[t.Dict[str, t.Any]] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Clear an SQL search cursor.
+        .. raw:: html
+
+          <p>Clear an SQL search cursor.</p>
+
 
         `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/clear-sql-cursor-api.html>`_
 
@@ -84,12 +87,21 @@ class SqlClient(NamespacedClient):
         pretty: t.Optional[bool] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        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.
+        .. raw:: html
+
+          <p>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.</p>
+          <p>If the Elasticsearch security features are enabled, only the following users can use this API to delete a search:</p>
+          <ul>
+          <li>Users with the <code>cancel_task</code> cluster privilege.</li>
+          <li>The user who first submitted the search.</li>
+          </ul>
+
 
         `<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 +143,26 @@ class SqlClient(NamespacedClient):
         ] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Get async SQL search results. Get the current status and available results for
-        an async SQL search or stored synchronous SQL search.
+        .. raw:: html
+
+          <p>Get async SQL search results.
+          Get the current status and available results for an async SQL search or stored synchronous SQL search.</p>
+          <p>If the Elasticsearch security features are enabled, only the user who first submitted the SQL search can retrieve the search using this API.</p>
+
 
         `<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 +206,15 @@ class SqlClient(NamespacedClient):
         pretty: t.Optional[bool] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Get the async SQL search status. Get the current status of an async SQL search
-        or a stored synchronous SQL search.
+        .. raw:: html
+
+          <p>Get the async SQL search status.
+          Get the current status of an async SQL search or a stored synchronous SQL search.</p>
+
 
         `<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 +241,7 @@ class SqlClient(NamespacedClient):
 
     @_rewrite_parameters(
         body_fields=(
+            "allow_partial_search_results",
             "catalog",
             "columnar",
             "cursor",
@@ -243,6 +264,7 @@ class SqlClient(NamespacedClient):
     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 +295,53 @@ class SqlClient(NamespacedClient):
         body: t.Optional[t.Dict[str, t.Any]] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Get SQL search results. Run an SQL request.
+        .. raw:: html
+
+          <p>Get SQL search results.
+          Run an SQL request.</p>
+
 
         `<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 +358,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,15 +420,19 @@ class SqlClient(NamespacedClient):
         body: t.Optional[t.Dict[str, t.Any]] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Translate SQL into Elasticsearch queries. Translate an SQL search into a search
-        API request containing Query DSL.
+        .. raw:: html
+
+          <p>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 <code>cursor</code>.</p>
+
 
         `<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/_sync/client/ssl.py

@@ -35,23 +35,22 @@ class SslClient(NamespacedClient):
         pretty: t.Optional[bool] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Get SSL certificates. Get information about the X.509 certificates that are used
-        to encrypt communications in the cluster. The API returns a list that includes
-        certificates from all TLS contexts including: - Settings for transport and HTTP
-        interfaces - TLS settings that are used within authentication realms - TLS settings
-        for remote monitoring exporters The list includes certificates that are used
-        for configuring trust, such as those configured in the `xpack.security.transport.ssl.truststore`
-        and `xpack.security.transport.ssl.certificate_authorities` settings. It also
-        includes certificates that are used for configuring server identity, such as
-        `xpack.security.http.ssl.keystore` and `xpack.security.http.ssl.certificate settings`.
-        The list does not include certificates that are sourced from the default SSL
-        context of the Java Runtime Environment (JRE), even if those certificates are
-        in use within Elasticsearch. NOTE: When a PKCS#11 token is configured as the
-        truststore of the JRE, the API returns all the certificates that are included
-        in the PKCS#11 token irrespective of whether these are used in the Elasticsearch
-        TLS configuration. If Elasticsearch is configured to use a keystore or truststore,
-        the API output includes all certificates in that store, even though some of the
-        certificates might not be in active use within the cluster.
+        .. raw:: html
+
+          <p>Get SSL certificates.</p>
+          <p>Get information about the X.509 certificates that are used to encrypt communications in the cluster.
+          The API returns a list that includes certificates from all TLS contexts including:</p>
+          <ul>
+          <li>Settings for transport and HTTP interfaces</li>
+          <li>TLS settings that are used within authentication realms</li>
+          <li>TLS settings for remote monitoring exporters</li>
+          </ul>
+          <p>The list includes certificates that are used for configuring trust, such as those configured in the <code>xpack.security.transport.ssl.truststore</code> and <code>xpack.security.transport.ssl.certificate_authorities</code> settings.
+          It also includes certificates that are used for configuring server identity, such as <code>xpack.security.http.ssl.keystore</code> and <code>xpack.security.http.ssl.certificate settings</code>.</p>
+          <p>The list does not include certificates that are sourced from the default SSL context of the Java Runtime Environment (JRE), even if those certificates are in use within Elasticsearch.</p>
+          <p>NOTE: When a PKCS#11 token is configured as the truststore of the JRE, the API returns all the certificates that are included in the PKCS#11 token irrespective of whether these are used in the Elasticsearch TLS configuration.</p>
+          <p>If Elasticsearch is configured to use a keystore or truststore, the API output includes all certificates in that store, even though some of the certificates might not be in active use within the cluster.</p>
+
 
         `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/security-api-ssl.html>`_
         """

elasticsearch/_sync/client/synonyms.py

@@ -36,11 +36,26 @@ class SynonymsClient(NamespacedClient):
         pretty: t.Optional[bool] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Delete a synonym set.
+        .. raw:: html
+
+          <p>Delete a synonym set.</p>
+          <p>You can only delete a synonyms set that is not in use by any index analyzer.</p>
+          <p>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.</p>
+          <p>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.</p>
+          <p>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.</p>
+          <p>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.</p>
+
 
         `<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 +92,16 @@ class SynonymsClient(NamespacedClient):
         pretty: t.Optional[bool] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Delete a synonym rule. Delete a synonym rule from a synonym set.
+        .. raw:: html
+
+          <p>Delete a synonym rule.
+          Delete a synonym rule from a synonym set.</p>
+
 
         `<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 +146,16 @@ class SynonymsClient(NamespacedClient):
         size: t.Optional[int] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Get a synonym set.
+        .. raw:: html
+
+          <p>Get a synonym set.</p>
+
 
         `<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 +196,16 @@ class SynonymsClient(NamespacedClient):
         pretty: t.Optional[bool] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Get a synonym rule. Get a synonym rule from a synonym set.
+        .. raw:: html
+
+          <p>Get a synonym rule.
+          Get a synonym rule from a synonym set.</p>
+
 
         `<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 +249,16 @@ class SynonymsClient(NamespacedClient):
         size: t.Optional[int] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Get all synonym sets. Get a summary of all defined synonym sets.
+        .. raw:: html
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/list-synonyms-sets.html>`_
+          <p>Get all synonym sets.
+          Get a summary of all defined synonym sets.</p>
 
-        :param from_: Starting offset
-        :param size: specifies a max number of results to get
+
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/get-synonyms-set.html>`_
+
+        :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,14 +302,19 @@ class SynonymsClient(NamespacedClient):
         body: t.Optional[t.Dict[str, t.Any]] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        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.
+        .. raw:: html
+
+          <p>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.</p>
+          <p>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.</p>
+
 
         `<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'")
@@ -327,14 +362,20 @@ class SynonymsClient(NamespacedClient):
         body: t.Optional[t.Dict[str, t.Any]] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Create or update a synonym rule. Create or update a synonym rule in a synonym
-        set.
+        .. raw:: html
+
+          <p>Create or update a synonym rule.
+          Create or update a synonym rule in a synonym set.</p>
+          <p>If any of the synonym rules included is invalid, the API returns an error.</p>
+          <p>When you update a synonym rule, all analyzers using the synonyms set will be reloaded automatically to reflect the new rule.</p>
+
 
         `<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/_sync/client/tasks.py

@@ -47,17 +47,29 @@ class TasksClient(NamespacedClient):
         wait_for_completion: t.Optional[bool] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Cancels a task, if it can be cancelled through an API.
+        .. raw:: html
+
+          <p>Cancel a task.</p>
+          <p>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.</p>
+          <p>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.</p>
+          <p>To troubleshoot why a cancelled task does not complete promptly, use the get task information API with the <code>?detailed</code> 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.</p>
+
 
         `<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 +119,20 @@ 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.
+        .. raw:: html
+
+          <p>Get task information.
+          Get information about a task currently running in the cluster.</p>
+          <p>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.</p>
+          <p>If the task identifier is not found, a 404 response code indicates that there are no resources that match the request.</p>
+
 
         `<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 +184,82 @@ 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.
+        .. raw:: html
+
+          <p>Get all tasks.
+          Get information about the tasks currently running on one or more nodes in the cluster.</p>
+          <p>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.</p>
+          <p><strong>Identifying running tasks</strong></p>
+          <p>The <code>X-Opaque-Id header</code>, 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:</p>
+          <pre><code>curl -i -H &quot;X-Opaque-Id: 123456&quot; &quot;http://localhost:9200/_tasks?group_by=parents&quot;
+          </code></pre>
+          <p>The API returns the following result:</p>
+          <pre><code>HTTP/1.1 200 OK
+          X-Opaque-Id: 123456
+          content-type: application/json; charset=UTF-8
+          content-length: 831
+
+          {
+            &quot;tasks&quot; : {
+              &quot;u5lcZHqcQhu-rUoFaqDphA:45&quot; : {
+                &quot;node&quot; : &quot;u5lcZHqcQhu-rUoFaqDphA&quot;,
+                &quot;id&quot; : 45,
+                &quot;type&quot; : &quot;transport&quot;,
+                &quot;action&quot; : &quot;cluster:monitor/tasks/lists&quot;,
+                &quot;start_time_in_millis&quot; : 1513823752749,
+                &quot;running_time_in_nanos&quot; : 293139,
+                &quot;cancellable&quot; : false,
+                &quot;headers&quot; : {
+                  &quot;X-Opaque-Id&quot; : &quot;123456&quot;
+                },
+                &quot;children&quot; : [
+                  {
+                    &quot;node&quot; : &quot;u5lcZHqcQhu-rUoFaqDphA&quot;,
+                    &quot;id&quot; : 46,
+                    &quot;type&quot; : &quot;direct&quot;,
+                    &quot;action&quot; : &quot;cluster:monitor/tasks/lists[n]&quot;,
+                    &quot;start_time_in_millis&quot; : 1513823752750,
+                    &quot;running_time_in_nanos&quot; : 92133,
+                    &quot;cancellable&quot; : false,
+                    &quot;parent_task_id&quot; : &quot;u5lcZHqcQhu-rUoFaqDphA:45&quot;,
+                    &quot;headers&quot; : {
+                      &quot;X-Opaque-Id&quot; : &quot;123456&quot;
+                    }
+                  }
+                ]
+              }
+            }
+           }
+          </code></pre>
+          <p>In this example, <code>X-Opaque-Id: 123456</code> is the ID as a part of the response header.
+          The <code>X-Opaque-Id</code> in the task <code>headers</code> is the ID for the task that was initiated by the REST request.
+          The <code>X-Opaque-Id</code> in the children <code>headers</code> is the child task of the task that was initiated by the REST request.</p>
+
 
         `<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.
         """