Auto-generated API code (#2692)

elasticsearch/_async/client/__init__.py

@@ -743,7 +743,8 @@ async def clear_scroll(
         body: t.Optional[t.Dict[str, t.Any]] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Clears the search context and results for a scrolling search.
+        Clear a scrolling search. Clear the search context and results for a scrolling
+        search.
 
         `<https://www.elastic.co/guide/en/elasticsearch/reference/8.16/clear-scroll-api.html>`_
 
@@ -793,7 +794,11 @@ async def close_point_in_time(
         body: t.Optional[t.Dict[str, t.Any]] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Closes a point-in-time.
+        Close a point in time. A point in time must be opened explicitly before being
+        used in search requests. The `keep_alive` parameter tells Elasticsearch how long
+        it should persist. A point in time is automatically closed when the `keep_alive`
+        period has elapsed. However, keeping points in time has a cost; close them as
+        soon as they are no longer required for search requests.
 
         `<https://www.elastic.co/guide/en/elasticsearch/reference/8.16/point-in-time-api.html>`_
 
@@ -1844,10 +1849,11 @@ async def field_caps(
         body: t.Optional[t.Dict[str, t.Any]] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        The field capabilities API returns the information about the capabilities of
-        fields among multiple indices. The field capabilities API returns runtime fields
-        like any other field. For example, a runtime field with a type of keyword is
-        returned as any other field that belongs to the `keyword` family.
+        Get the field capabilities. Get information about the capabilities of fields
+        among multiple indices. For data streams, the API returns field capabilities
+        among the stream’s backing indices. It returns runtime fields like any other
+        field. For example, a runtime field with a type of keyword is returned the same
+        as any other field that belongs to the `keyword` family.
 
         `<https://www.elastic.co/guide/en/elasticsearch/reference/8.16/search-field-caps.html>`_
 
@@ -2490,6 +2496,7 @@ async def info(
         ),
         parameter_aliases={"_source": "source"},
     )
+    @_stability_warning(Stability.EXPERIMENTAL)
     async def knn_search(
         self,
         *,
@@ -2510,7 +2517,15 @@ async def knn_search(
         body: t.Optional[t.Dict[str, t.Any]] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Performs a kNN search.
+        Run a knn search. NOTE: The kNN search API has been replaced by the `knn` option
+        in the search API. Perform a k-nearest neighbor (kNN) search on a dense_vector
+        field and return the matching documents. Given a query vector, the API finds
+        the k closest vectors and returns those documents as search hits. Elasticsearch
+        uses the HNSW algorithm to support efficient kNN search. Like most kNN algorithms,
+        HNSW is an approximate method that sacrifices result accuracy for improved search
+        speed. This means the results returned are not always the true k closest neighbors.
+        The kNN search API supports restricting the search using a filter. The search
+        will return the top k documents that also match the filter query.
 
         `<https://www.elastic.co/guide/en/elasticsearch/reference/8.16/search-search.html>`_
 
@@ -2873,7 +2888,7 @@ async def msearch_template(
         typed_keys: t.Optional[bool] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Runs multiple templated searches with a single request.
+        Run multiple templated searches.
 
         `<https://www.elastic.co/guide/en/elasticsearch/reference/8.16/search-multi-search.html>`_
 
@@ -3083,13 +3098,15 @@ async def open_point_in_time(
         body: t.Optional[t.Dict[str, t.Any]] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        A search request by default executes against the most recent visible data of
-        the target indices, which is called point in time. Elasticsearch pit (point in
-        time) is a lightweight view into the state of the data as it existed when initiated.
-        In some cases, it’s preferred to perform multiple search requests using the same
-        point in time. For example, if refreshes happen between `search_after` requests,
-        then the results of those requests might not be consistent as changes happening
-        between searches are only visible to the more recent point in time.
+        Open a point in time. A search request by default runs against the most recent
+        visible data of the target indices, which is called point in time. Elasticsearch
+        pit (point in time) is a lightweight view into the state of the data as it existed
+        when initiated. In some cases, it’s preferred to perform multiple search requests
+        using the same point in time. For example, if refreshes happen between `search_after`
+        requests, then the results of those requests might not be consistent as changes
+        happening between searches are only visible to the more recent point in time.
+        A point in time must be opened explicitly before being used in search requests.
+        The `keep_alive` parameter tells Elasticsearch how long it should persist.
 
         `<https://www.elastic.co/guide/en/elasticsearch/reference/8.16/point-in-time-api.html>`_
 
@@ -3256,8 +3273,8 @@ async def rank_eval(
         body: t.Optional[t.Dict[str, t.Any]] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Enables you to evaluate the quality of ranked search results over a set of typical
-        search queries.
+        Evaluate ranked search results. Evaluate the quality of ranked search results
+        over a set of typical search queries.
 
         `<https://www.elastic.co/guide/en/elasticsearch/reference/8.16/search-rank-eval.html>`_
 
@@ -3501,7 +3518,7 @@ async def render_search_template(
         body: t.Optional[t.Dict[str, t.Any]] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Renders a search template as a search request body.
+        Render a search template. Render a search template as a search request body.
 
         `<https://www.elastic.co/guide/en/elasticsearch/reference/8.16/render-search-template-api.html>`_
 
@@ -3833,9 +3850,9 @@ async def search(
         body: t.Optional[t.Dict[str, t.Any]] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Returns search hits that match the query defined in the request. You can provide
-        search queries using the `q` query string parameter or the request body. If both
-        are specified, only the query parameter is used.
+        Run a search. Get search hits that match the query defined in the request. You
+        can provide search queries using the `q` query string parameter or the request
+        body. If both are specified, only the query parameter is used.
 
         `<https://www.elastic.co/guide/en/elasticsearch/reference/8.16/search-search.html>`_
 
@@ -4265,7 +4282,7 @@ async def search_mvt(
         body: t.Optional[t.Dict[str, t.Any]] = None,
     ) -> BinaryApiResponse:
         """
-        Search a vector tile. Searches a vector tile for geospatial values.
+        Search a vector tile. Search a vector tile for geospatial values.
 
         `<https://www.elastic.co/guide/en/elasticsearch/reference/8.16/search-vector-tile-api.html>`_
 
@@ -4419,8 +4436,10 @@ async def search_shards(
         routing: t.Optional[str] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Returns information about the indices and shards that a search request would
-        be executed against.
+        Get the search shards. Get the indices and shards that a search request would
+        be run against. This information can be useful for working out issues or planning
+        optimizations with routing and shard preferences. When filtered aliases are used,
+        the filter is returned as part of the indices section.
 
         `<https://www.elastic.co/guide/en/elasticsearch/reference/8.16/search-shards.html>`_
 
@@ -4521,7 +4540,7 @@ async def search_template(
         body: t.Optional[t.Dict[str, t.Any]] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Runs a search with a search template.
+        Run a search with a search template.
 
         `<https://www.elastic.co/guide/en/elasticsearch/reference/8.16/search-template.html>`_
 
@@ -4759,8 +4778,8 @@ async def termvectors(
         body: t.Optional[t.Dict[str, t.Any]] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Get term vector information. Returns information and statistics about terms in
-        the fields of a particular document.
+        Get term vector information. Get information and statistics about terms in the
+        fields of a particular document.
 
         `<https://www.elastic.co/guide/en/elasticsearch/reference/8.16/docs-termvectors.html>`_
 

elasticsearch/_async/client/async_search.py

@@ -148,10 +148,10 @@ async def status(
         pretty: t.Optional[bool] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Get async search status. Retrieve the status of a previously submitted async
-        search request given its identifier, without retrieving search results. If the
-        Elasticsearch security features are enabled, use of this API is restricted to
-        the `monitoring_user` role.
+        Get the async search status. Get the status of a previously submitted async search
+        request given its identifier, without retrieving search results. If the Elasticsearch
+        security features are enabled, use of this API is restricted to the `monitoring_user`
+        role.
 
         `<https://www.elastic.co/guide/en/elasticsearch/reference/8.16/async-search.html>`_
 

elasticsearch/_async/client/autoscaling.py

@@ -36,7 +36,8 @@ async def delete_autoscaling_policy(
         pretty: t.Optional[bool] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Deletes an autoscaling policy. Designed for indirect use by ECE/ESS and ECK.
+        Delete an autoscaling policy. NOTE: This feature is designed for indirect use
+        by Elasticsearch Service, Elastic Cloud Enterprise, and Elastic Cloud on Kubernetes.
         Direct use is not supported.
 
         `<https://www.elastic.co/guide/en/elasticsearch/reference/8.16/autoscaling-delete-autoscaling-policy.html>`_
@@ -76,8 +77,18 @@ async def get_autoscaling_capacity(
         pretty: t.Optional[bool] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Gets the current autoscaling capacity based on the configured autoscaling policy.
-        Designed for indirect use by ECE/ESS and ECK. Direct use is not supported.
+        Get the autoscaling capacity. NOTE: This feature is designed for indirect use
+        by Elasticsearch Service, Elastic Cloud Enterprise, and Elastic Cloud on Kubernetes.
+        Direct use is not supported. This API gets the current autoscaling capacity based
+        on the configured autoscaling policy. It will return information to size the
+        cluster appropriately to the current workload. The `required_capacity` is calculated
+        as the maximum of the `required_capacity` result of all individual deciders that
+        are enabled for the policy. The operator should verify that the `current_nodes`
+        match the operator’s knowledge of the cluster to avoid making autoscaling decisions
+        based on stale or incomplete information. The response contains decider-specific
+        information you can use to diagnose how and why autoscaling determined a certain
+        capacity was required. This information is provided for diagnosis only. Do not
+        use this information to make autoscaling decisions.
 
         `<https://www.elastic.co/guide/en/elasticsearch/reference/8.16/autoscaling-get-autoscaling-capacity.html>`_
         """
@@ -113,7 +124,8 @@ async def get_autoscaling_policy(
         pretty: t.Optional[bool] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Retrieves an autoscaling policy. Designed for indirect use by ECE/ESS and ECK.
+        Get an autoscaling policy. NOTE: This feature is designed for indirect use by
+        Elasticsearch Service, Elastic Cloud Enterprise, and Elastic Cloud on Kubernetes.
         Direct use is not supported.
 
         `<https://www.elastic.co/guide/en/elasticsearch/reference/8.16/autoscaling-get-autoscaling-capacity.html>`_
@@ -158,8 +170,9 @@ async def put_autoscaling_policy(
         pretty: t.Optional[bool] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Creates a new autoscaling policy. Designed for indirect use by ECE/ESS and ECK.
-        Direct use is not supported.
+        Create or update an autoscaling policy. NOTE: This feature is designed for indirect
+        use by Elasticsearch Service, Elastic Cloud Enterprise, and Elastic Cloud on
+        Kubernetes. Direct use is not supported.
 
         `<https://www.elastic.co/guide/en/elasticsearch/reference/8.16/autoscaling-put-autoscaling-policy.html>`_