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

elasticsearch/_async/client/rollup.py

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

elasticsearch/_async/client/search_application.py

@@ -216,7 +216,7 @@ class SearchApplicationClient(NamespacedClient):
         size: t.Optional[int] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Returns the existing search applications.
+        Get search applications. Get information about search applications.
 
         `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/list-search-applications.html>`_
 
@@ -251,6 +251,71 @@ class SearchApplicationClient(NamespacedClient):
             path_parts=__path_parts,
         )
 
+    @_rewrite_parameters(
+        body_name="payload",
+    )
+    @_stability_warning(Stability.EXPERIMENTAL)
+    async def post_behavioral_analytics_event(
+        self,
+        *,
+        collection_name: str,
+        event_type: t.Union[str, t.Literal["page_view", "search", "search_click"]],
+        payload: t.Optional[t.Any] = None,
+        body: t.Optional[t.Any] = None,
+        debug: t.Optional[bool] = None,
+        error_trace: t.Optional[bool] = None,
+        filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None,
+        human: t.Optional[bool] = None,
+        pretty: t.Optional[bool] = None,
+    ) -> ObjectApiResponse[t.Any]:
+        """
+        Create a behavioral analytics collection event.
+
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/post-analytics-collection-event.html>`_
+
+        :param collection_name: The name of the behavioral analytics collection.
+        :param event_type: The analytics event type.
+        :param payload:
+        :param debug: Whether the response type has to include more details
+        """
+        if collection_name in SKIP_IN_PATH:
+            raise ValueError("Empty value passed for parameter 'collection_name'")
+        if event_type in SKIP_IN_PATH:
+            raise ValueError("Empty value passed for parameter 'event_type'")
+        if payload is None and body is None:
+            raise ValueError(
+                "Empty value passed for parameters 'payload' and 'body', one of them should be set."
+            )
+        elif payload is not None and body is not None:
+            raise ValueError("Cannot set both 'payload' and 'body'")
+        __path_parts: t.Dict[str, str] = {
+            "collection_name": _quote(collection_name),
+            "event_type": _quote(event_type),
+        }
+        __path = f'/_application/analytics/{__path_parts["collection_name"]}/event/{__path_parts["event_type"]}'
+        __query: t.Dict[str, t.Any] = {}
+        if debug is not None:
+            __query["debug"] = debug
+        if error_trace is not None:
+            __query["error_trace"] = error_trace
+        if filter_path is not None:
+            __query["filter_path"] = filter_path
+        if human is not None:
+            __query["human"] = human
+        if pretty is not None:
+            __query["pretty"] = pretty
+        __body = payload if payload is not None else body
+        __headers = {"accept": "application/json", "content-type": "application/json"}
+        return await self.perform_request(  # type: ignore[return-value]
+            "POST",
+            __path,
+            params=__query,
+            headers=__headers,
+            body=__body,
+            endpoint_id="search_application.post_behavioral_analytics_event",
+            path_parts=__path_parts,
+        )
+
     @_rewrite_parameters(
         body_name="search_application",
     )
@@ -351,6 +416,70 @@ class SearchApplicationClient(NamespacedClient):
             path_parts=__path_parts,
         )
 
+    @_rewrite_parameters(
+        body_fields=("params",),
+        ignore_deprecated_options={"params"},
+    )
+    @_stability_warning(Stability.EXPERIMENTAL)
+    async def render_query(
+        self,
+        *,
+        name: str,
+        error_trace: t.Optional[bool] = None,
+        filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None,
+        human: t.Optional[bool] = None,
+        params: t.Optional[t.Mapping[str, t.Any]] = None,
+        pretty: t.Optional[bool] = None,
+        body: t.Optional[t.Dict[str, t.Any]] = None,
+    ) -> ObjectApiResponse[t.Any]:
+        """
+        Render a search application query. Generate an Elasticsearch query using the
+        specified query parameters and the search template associated with the search
+        application or a default template if none is specified. If a parameter used in
+        the search template is not specified in `params`, the parameter's default value
+        will be used. The API returns the specific Elasticsearch query that would be
+        generated and run by calling the search application search API. You must have
+        `read` privileges on the backing alias of the search application.
+
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/search-application-render-query.html>`_
+
+        :param name: The name of the search application to render teh query for.
+        :param params:
+        """
+        if name in SKIP_IN_PATH:
+            raise ValueError("Empty value passed for parameter 'name'")
+        __path_parts: t.Dict[str, str] = {"name": _quote(name)}
+        __path = (
+            f'/_application/search_application/{__path_parts["name"]}/_render_query'
+        )
+        __query: t.Dict[str, t.Any] = {}
+        __body: t.Dict[str, t.Any] = body if body is not None else {}
+        if error_trace is not None:
+            __query["error_trace"] = error_trace
+        if filter_path is not None:
+            __query["filter_path"] = filter_path
+        if human is not None:
+            __query["human"] = human
+        if pretty is not None:
+            __query["pretty"] = pretty
+        if not __body:
+            if params is not None:
+                __body["params"] = params
+        if not __body:
+            __body = None  # type: ignore[assignment]
+        __headers = {"accept": "application/json"}
+        if __body is not None:
+            __headers["content-type"] = "application/json"
+        return await self.perform_request(  # type: ignore[return-value]
+            "POST",
+            __path,
+            params=__query,
+            headers=__headers,
+            body=__body,
+            endpoint_id="search_application.render_query",
+            path_parts=__path_parts,
+        )
+
     @_rewrite_parameters(
         body_fields=("params",),
         ignore_deprecated_options={"params"},

elasticsearch/_async/client/searchable_snapshots.py

@@ -44,13 +44,12 @@ class SearchableSnapshotsClient(NamespacedClient):
         pretty: t.Optional[bool] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Retrieve node-level cache statistics about searchable snapshots.
+        Get cache statistics. Get statistics about the shared cache for partially mounted
+        indices.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/searchable-snapshots-apis.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/searchable-snapshots-api-cache-stats.html>`_
 
-        :param node_id: A comma-separated list of node IDs or names to limit the returned
-            information; use `_local` to return information from the node you're connecting
-            to, leave empty to get information from all nodes
+        :param node_id: The names of the nodes in the cluster to target.
         :param master_timeout:
         """
         __path_parts: t.Dict[str, str]
@@ -103,11 +102,13 @@ class SearchableSnapshotsClient(NamespacedClient):
         pretty: t.Optional[bool] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Clear the cache of searchable snapshots.
+        Clear the cache. Clear indices and data streams from the shared cache for partially
+        mounted indices.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/searchable-snapshots-apis.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/searchable-snapshots-api-clear-cache.html>`_
 
-        :param index: A comma-separated list of index names
+        :param index: A comma-separated list of data streams, indices, and aliases to
+            clear from the cache. It supports wildcards (`*`).
         :param allow_no_indices: Whether to ignore if a wildcard indices expression resolves
             into no concrete indices. (This includes `_all` string or when no indices
             have been specified)
@@ -175,22 +176,29 @@ class SearchableSnapshotsClient(NamespacedClient):
         body: t.Optional[t.Dict[str, t.Any]] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Mount a snapshot as a searchable index.
+        Mount a snapshot. Mount a snapshot as a searchable snapshot index. Do not use
+        this API for snapshots managed by index lifecycle management (ILM). Manually
+        mounting ILM-managed snapshots can interfere with ILM processes.
 
         `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/searchable-snapshots-api-mount-snapshot.html>`_
 
         :param repository: The name of the repository containing the snapshot of the
-            index to mount
-        :param snapshot: The name of the snapshot of the index to mount
-        :param index:
-        :param ignore_index_settings:
-        :param index_settings:
-        :param master_timeout: Explicit operation timeout for connection to master node
-        :param renamed_index:
-        :param storage: Selects the kind of local storage used to accelerate searches.
-            Experimental, and defaults to `full_copy`
-        :param wait_for_completion: Should this request wait until the operation has
-            completed before returning
+            index to mount.
+        :param snapshot: The name of the snapshot of the index to mount.
+        :param index: The name of the index contained in the snapshot whose data is to
+            be mounted. If no `renamed_index` is specified, this name will also be used
+            to create the new index.
+        :param ignore_index_settings: The names of settings that should be removed from
+            the index when it is mounted.
+        :param index_settings: The settings that should be added to the index when it
+            is mounted.
+        :param master_timeout: The period to wait for the master node. If the master
+            node is not available before the timeout expires, the request fails and returns
+            an error. To indicate that the request should never timeout, set it to `-1`.
+        :param renamed_index: The name of the index that will be created.
+        :param storage: The mount option for the searchable snapshot index.
+        :param wait_for_completion: If true, the request blocks until the operation is
+            complete.
         """
         if repository in SKIP_IN_PATH:
             raise ValueError("Empty value passed for parameter 'repository'")
@@ -255,11 +263,12 @@ class SearchableSnapshotsClient(NamespacedClient):
         pretty: t.Optional[bool] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Retrieve shard-level statistics about searchable snapshots.
+        Get searchable snapshot statistics.
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/searchable-snapshots-apis.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/searchable-snapshots-api-stats.html>`_
 
-        :param index: A comma-separated list of index names
+        :param index: A comma-separated list of data streams and indices to retrieve
+            statistics for.
         :param level: Return stats aggregated at cluster, index or shard level
         """
         __path_parts: t.Dict[str, str]