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

elasticsearch/_sync/client/monitoring.py

@@ -42,7 +42,11 @@ class MonitoringClient(NamespacedClient):
         pretty: t.Optional[bool] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Used by the monitoring features to send monitoring data.
+        .. raw:: html
+
+          <p>Send monitoring data.
+          This API is used by the monitoring features to send monitoring data.</p>
+
 
         `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/monitor-elasticsearch-cluster.html>`_
 

elasticsearch/_sync/client/nodes.py

@@ -44,15 +44,18 @@ class NodesClient(NamespacedClient):
         pretty: t.Optional[bool] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Clear the archived repositories metering. Clear the archived repositories metering
-        information in the cluster.
+        .. raw:: html
+
+          <p>Clear the archived repositories metering.
+          Clear the archived repositories metering information in the cluster.</p>
+
 
         `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/clear-repositories-metering-archive-api.html>`_
 
         :param node_id: Comma-separated list of node IDs or names used to limit returned
-            information. All the nodes selective options are explained [here](https://www.elastic.co/guide/en/elasticsearch/reference/current/cluster.html#cluster-nodes).
-        :param max_archive_version: Specifies the maximum [archive_version](https://www.elastic.co/guide/en/elasticsearch/reference/current/get-repositories-metering-api.html#get-repositories-metering-api-response-body)
-            to be cleared from the archive.
+            information.
+        :param max_archive_version: Specifies the maximum `archive_version` to be cleared
+            from the archive.
         """
         if node_id in SKIP_IN_PATH:
             raise ValueError("Empty value passed for parameter 'node_id'")
@@ -94,11 +97,13 @@ class NodesClient(NamespacedClient):
         pretty: t.Optional[bool] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Get cluster repositories metering. Get repositories metering information for
-        a cluster. This API exposes monotonically non-decreasing counters and it is expected
-        that clients would durably store the information needed to compute aggregations
-        over a period of time. Additionally, the information exposed by this API is volatile,
-        meaning that it will not be present after node restarts.
+        .. raw:: html
+
+          <p>Get cluster repositories metering.
+          Get repositories metering information for a cluster.
+          This API exposes monotonically non-decreasing counters and it is expected that clients would durably store the information needed to compute aggregations over a period of time.
+          Additionally, the information exposed by this API is volatile, meaning that it will not be present after node restarts.</p>
+
 
         `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/get-repositories-metering-api.html>`_
 
@@ -151,9 +156,12 @@ class NodesClient(NamespacedClient):
         ] = None,
     ) -> TextApiResponse:
         """
-        Get the hot threads for nodes. Get a breakdown of the hot threads on each selected
-        node in the cluster. The output is plain text with a breakdown of the top hot
-        threads for each node.
+        .. raw:: html
+
+          <p>Get the hot threads for nodes.
+          Get a breakdown of the hot threads on each selected node in the cluster.
+          The output is plain text with a breakdown of the top hot threads for each node.</p>
+
 
         `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/cluster-nodes-hot-threads.html>`_
 
@@ -228,8 +236,11 @@ class NodesClient(NamespacedClient):
         timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Get node information. By default, the API returns all attributes and core settings
-        for cluster nodes.
+        .. raw:: html
+
+          <p>Get node information.
+          By default, the API returns all attributes and core settings for cluster nodes.</p>
+
 
         `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/cluster-nodes-info.html>`_
 
@@ -298,18 +309,16 @@ class NodesClient(NamespacedClient):
         body: t.Optional[t.Dict[str, t.Any]] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Reload the keystore on nodes in the cluster. Secure settings are stored in an
-        on-disk keystore. Certain of these settings are reloadable. That is, you can
-        change them on disk and reload them without restarting any nodes in the cluster.
-        When you have updated reloadable secure settings in your keystore, you can use
-        this API to reload those settings on each node. When the Elasticsearch keystore
-        is password protected and not simply obfuscated, you must provide the password
-        for the keystore when you reload the secure settings. Reloading the settings
-        for the whole cluster assumes that the keystores for all nodes are protected
-        with the same password; this method is allowed only when inter-node communications
-        are encrypted. Alternatively, you can reload the secure settings on each node
-        by locally accessing the API and passing the node-specific Elasticsearch keystore
-        password.
+        .. raw:: html
+
+          <p>Reload the keystore on nodes in the cluster.</p>
+          <p>Secure settings are stored in an on-disk keystore. Certain of these settings are reloadable.
+          That is, you can change them on disk and reload them without restarting any nodes in the cluster.
+          When you have updated reloadable secure settings in your keystore, you can use this API to reload those settings on each node.</p>
+          <p>When the Elasticsearch keystore is password protected and not simply obfuscated, you must provide the password for the keystore when you reload the secure settings.
+          Reloading the settings for the whole cluster assumes that the keystores for all nodes are protected with the same password; this method is allowed only when inter-node communications are encrypted.
+          Alternatively, you can reload the secure settings on each node by locally accessing the API and passing the node-specific Elasticsearch keystore password.</p>
+
 
         `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/secure-settings.html#reloadable-secure-settings>`_
 
@@ -380,8 +389,12 @@ class NodesClient(NamespacedClient):
         types: t.Optional[t.Sequence[str]] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Get node statistics. Get statistics for nodes in a cluster. By default, all stats
-        are returned. You can limit the returned information by using metrics.
+        .. raw:: html
+
+          <p>Get node statistics.
+          Get statistics for nodes in a cluster.
+          By default, all stats are returned. You can limit the returned information by using metrics.</p>
+
 
         `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/cluster-nodes-stats.html>`_
 
@@ -498,7 +511,10 @@ class NodesClient(NamespacedClient):
         timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Get feature usage information.
+        .. raw:: html
+
+          <p>Get feature usage information.</p>
+
 
         `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/cluster-nodes-usage.html>`_
 

elasticsearch/_sync/client/query_rules.py

@@ -37,7 +37,12 @@ class QueryRulesClient(NamespacedClient):
         pretty: t.Optional[bool] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Delete a query rule. Delete a query rule within a query ruleset.
+        .. raw:: html
+
+          <p>Delete a query rule.
+          Delete a query rule within a query ruleset.
+          This is a destructive action that is only recoverable by re-adding the same rule with the create or update query rule API.</p>
+
 
         `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/delete-query-rule.html>`_
 
@@ -85,7 +90,12 @@ class QueryRulesClient(NamespacedClient):
         pretty: t.Optional[bool] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Delete a query ruleset.
+        .. raw:: html
+
+          <p>Delete a query ruleset.
+          Remove a query ruleset and its associated data.
+          This is a destructive action that is not recoverable.</p>
+
 
         `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/delete-query-ruleset.html>`_
 
@@ -126,7 +136,11 @@ class QueryRulesClient(NamespacedClient):
         pretty: t.Optional[bool] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Get a query rule. Get details about a query rule within a query ruleset.
+        .. raw:: html
+
+          <p>Get a query rule.
+          Get details about a query rule within a query ruleset.</p>
+
 
         `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/get-query-rule.html>`_
 
@@ -174,7 +188,11 @@ class QueryRulesClient(NamespacedClient):
         pretty: t.Optional[bool] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Get a query ruleset. Get details about a query ruleset.
+        .. raw:: html
+
+          <p>Get a query ruleset.
+          Get details about a query ruleset.</p>
+
 
         `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/get-query-ruleset.html>`_
 
@@ -217,12 +235,16 @@ class QueryRulesClient(NamespacedClient):
         size: t.Optional[int] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Get all query rulesets. Get summarized information about the query rulesets.
+        .. raw:: html
+
+          <p>Get all query rulesets.
+          Get summarized information about the query rulesets.</p>
+
 
         `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/list-query-rulesets.html>`_
 
-        :param from_: Starting offset (default: 0)
-        :param size: specifies a max number of results to get
+        :param from_: The offset from the first result to fetch.
+        :param size: The maximum number of results to retrieve.
         """
         __path_parts: t.Dict[str, str] = {}
         __path = "/_query_rules"
@@ -270,17 +292,28 @@ class QueryRulesClient(NamespacedClient):
         body: t.Optional[t.Dict[str, t.Any]] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Create or update a query rule. Create or update a query rule within a query ruleset.
+        .. raw:: html
+
+          <p>Create or update a query rule.
+          Create or update a query rule within a query ruleset.</p>
+          <p>IMPORTANT: Due to limitations within pinned queries, you can only pin documents using ids or docs, but cannot use both in single rule.
+          It is advised to use one or the other in query rulesets, to avoid errors.
+          Additionally, pinned queries have a maximum limit of 100 pinned hits.
+          If multiple matching rules pin more than 100 documents, only the first 100 documents are pinned in the order they are specified in the ruleset.</p>
+
 
         `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/put-query-rule.html>`_
 
         :param ruleset_id: The unique identifier of the query ruleset containing the
-            rule to be created or updated
+            rule to be created or updated.
         :param rule_id: The unique identifier of the query rule within the specified
-            ruleset to be created or updated
-        :param actions:
-        :param criteria:
-        :param type:
+            ruleset to be created or updated.
+        :param actions: The actions to take when the rule is matched. The format of this
+            action depends on the rule type.
+        :param criteria: The criteria that must be met for the rule to be applied. If
+            multiple criteria are specified for a rule, all criteria must be met for
+            the rule to be applied.
+        :param type: The type of rule.
         :param priority:
         """
         if ruleset_id in SKIP_IN_PATH:
@@ -345,12 +378,21 @@ class QueryRulesClient(NamespacedClient):
         body: t.Optional[t.Dict[str, t.Any]] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Create or update a query ruleset.
+        .. raw:: html
+
+          <p>Create or update a query ruleset.
+          There is a limit of 100 rules per ruleset.
+          This limit can be increased by using the <code>xpack.applications.rules.max_rules_per_ruleset</code> cluster setting.</p>
+          <p>IMPORTANT: Due to limitations within pinned queries, you can only select documents using <code>ids</code> or <code>docs</code>, but cannot use both in single rule.
+          It is advised to use one or the other in query rulesets, to avoid errors.
+          Additionally, pinned queries have a maximum limit of 100 pinned hits.
+          If multiple matching rules pin more than 100 documents, only the first 100 documents are pinned in the order they are specified in the ruleset.</p>
+
 
         `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/put-query-ruleset.html>`_
 
         :param ruleset_id: The unique identifier of the query ruleset to be created or
-            updated
+            updated.
         :param rules:
         """
         if ruleset_id in SKIP_IN_PATH:
@@ -398,14 +440,19 @@ class QueryRulesClient(NamespacedClient):
         body: t.Optional[t.Dict[str, t.Any]] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Test a query ruleset. Evaluate match criteria against a query ruleset to identify
-        the rules that would match that criteria.
+        .. raw:: html
+
+          <p>Test a query ruleset.
+          Evaluate match criteria against a query ruleset to identify the rules that would match that criteria.</p>
+
 
         `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/test-query-ruleset.html>`_
 
         :param ruleset_id: The unique identifier of the query ruleset to be created or
             updated
-        :param match_criteria:
+        :param match_criteria: The match criteria to apply to rules in the given query
+            ruleset. Match criteria should match the keys defined in the `criteria.metadata`
+            field of the rule.
         """
         if ruleset_id in SKIP_IN_PATH:
             raise ValueError("Empty value passed for parameter 'ruleset_id'")

elasticsearch/_sync/client/rollup.py

@@ -43,7 +43,29 @@ class RollupClient(NamespacedClient):
         pretty: t.Optional[bool] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Deletes an existing rollup job.
+        .. raw:: html
+
+          <p>Delete a rollup job.</p>
+          <p>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.</p>
+          <p>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:</p>
+          <pre><code>POST my_rollup_index/_delete_by_query
+          {
+            &quot;query&quot;: {
+              &quot;term&quot;: {
+                &quot;_rollup.id&quot;: &quot;the_rollup_job_id&quot;
+              }
+            }
+          }
+          </code></pre>
+
 
         `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/rollup-delete-job.html>`_
 
@@ -84,7 +106,14 @@ class RollupClient(NamespacedClient):
         pretty: t.Optional[bool] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Retrieves the configuration, stats, and status of rollup jobs.
+        .. raw:: html
+
+          <p>Get rollup job information.
+          Get the configuration, stats, and status of rollup jobs.</p>
+          <p>NOTE: This API returns only active (both <code>STARTED</code> and <code>STOPPED</code>) 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.</p>
+
 
         `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/rollup-get-job.html>`_
 
@@ -129,8 +158,18 @@ 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.
+        .. raw:: html
+
+          <p>Get the rollup job capabilities.
+          Get the capabilities of any rollup jobs that have been configured for a specific index or index pattern.</p>
+          <p>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:</p>
+          <ol>
+          <li>Does this index have associated rollup data somewhere in the cluster?</li>
+          <li>If yes to the first question, what fields were rolled up, what aggregations can be performed, and where does the data live?</li>
+          </ol>
+
 
         `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/rollup-get-rollup-caps.html>`_
 
@@ -175,8 +214,16 @@ 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).
+        .. raw:: html
+
+          <p>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:</p>
+          <ul>
+          <li>What jobs are stored in an index (or indices specified via a pattern)?</li>
+          <li>What target indices were rolled up, what fields were used in those rollups, and what aggregations can be performed on each job?</li>
+          </ul>
+
 
         `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/rollup-get-rollup-index-caps.html>`_
 
@@ -239,7 +286,14 @@ class RollupClient(NamespacedClient):
         body: t.Optional[t.Dict[str, t.Any]] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Creates a rollup job.
+        .. raw:: html
+
+          <p>Create a rollup job.</p>
+          <p>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.</p>
+          <p>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.</p>
+          <p>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.</p>
+          <p>Jobs are created in a <code>STOPPED</code> state. You can start them with the start rollup jobs API.</p>
+
 
         `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/rollup-put-job.html>`_
 
@@ -356,14 +410,54 @@ 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.
+        .. raw:: html
+
+          <p>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.</p>
+          <p>The request body supports a subset of features from the regular search API.
+          The following functionality is not available:</p>
+          <p><code>size</code>: Because rollups work on pre-aggregated data, no search hits can be returned and so size must be set to zero or omitted entirely.
+          <code>highlighter</code>, <code>suggestors</code>, <code>post_filter</code>, <code>profile</code>, <code>explain</code>: These are similarly disallowed.</p>
+          <p><strong>Searching both historical rollup and non-rollup data</strong></p>
+          <p>The rollup search API has the capability to search across both &quot;live&quot; non-rollup data and the aggregated rollup data.
+          This is done by simply adding the live indices to the URI. For example:</p>
+          <pre><code>GET sensor-1,sensor_rollup/_rollup_search
+          {
+            &quot;size&quot;: 0,
+            &quot;aggregations&quot;: {
+               &quot;max_temperature&quot;: {
+                &quot;max&quot;: {
+                  &quot;field&quot;: &quot;temperature&quot;
+                }
+              }
+            }
+          }
+          </code></pre>
+          <p>The rollup search endpoint does two things when the search runs:</p>
+          <ul>
+          <li>The original request is sent to the non-rollup index unaltered.</li>
+          <li>A rewritten version of the original request is sent to the rollup index.</li>
+          </ul>
+          <p>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.</p>
+
 
         `<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 +514,12 @@ class RollupClient(NamespacedClient):
         pretty: t.Optional[bool] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Starts an existing, stopped rollup job.
+        .. raw:: html
+
+          <p>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.</p>
+
 
         `<https://www.elastic.co/guide/en/elasticsearch/reference/8.17/rollup-start-job.html>`_
 
@@ -463,14 +562,28 @@ class RollupClient(NamespacedClient):
         wait_for_completion: t.Optional[bool] = None,
     ) -> ObjectApiResponse[t.Any]:
         """
-        Stops an existing, started rollup job.
+        .. raw:: html
+
+          <p>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.</p>
+          <p>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 <code>wait_for_completion</code> query parameter, and optionally a timeout. For example:</p>
+          <pre><code>POST _rollup/job/sensor/_stop?wait_for_completion=true&amp;timeout=10s
+          </code></pre>
+          <p>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.</p>
+
 
         `<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.