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

elasticsearch/_async/client/synonyms.py

@@ -36,11 +36,25 @@ class SynonymsClient(NamespacedClient):
         pretty: t.Optional[bool] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Delete 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.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'")
@@ -81,8 +95,8 @@ class SynonymsClient(NamespacedClient):
 
         `<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'")
@@ -131,9 +145,9 @@ class SynonymsClient(NamespacedClient):
 
         `<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'")
@@ -178,8 +192,8 @@ class SynonymsClient(NamespacedClient):
 
         `<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'")
@@ -225,10 +239,10 @@ class SynonymsClient(NamespacedClient):
         """
         Get all synonym sets. Get a summary of all defined synonym sets.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/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"
@@ -274,12 +288,15 @@ class SynonymsClient(NamespacedClient):
         """
         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.
+        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.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'")
@@ -328,13 +345,16 @@ class SynonymsClient(NamespacedClient):
     ) -> ObjectApiResponse[t.Any]:
         """
         Create or update a synonym rule. Create or update a synonym rule in a synonym
-        set.
+        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.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.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.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.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.
         """