From ca8bcad72223aa0b1acd1e9beff80872ad1c00fc Mon Sep 17 00:00:00 2001 From: Elastic Machine Date: Mon, 3 Mar 2025 06:03:10 +0000 Subject: [PATCH 1/6] Auto-generated API code --- .../_async/client/__init__.py | 2750 ++++++++++++----- .../_async/client/async_search.py | 75 +- elasticsearch_serverless/_async/client/cat.py | 186 +- .../_async/client/cluster.py | 68 +- .../_async/client/connector.py | 238 +- .../_async/client/enrich.py | 32 +- elasticsearch_serverless/_async/client/eql.py | 50 +- .../_async/client/esql.py | 19 +- .../_async/client/graph.py | 19 +- .../_async/client/indices.py | 617 ++-- .../_async/client/inference.py | 83 +- .../_async/client/ingest.py | 50 +- .../_async/client/license.py | 17 +- .../_async/client/logstash.py | 29 +- elasticsearch_serverless/_async/client/ml.py | 703 +++-- .../_async/client/query_rules.py | 92 +- .../_async/client/search_application.py | 68 +- .../_async/client/security.py | 325 +- elasticsearch_serverless/_async/client/sql.py | 65 +- .../_async/client/synonyms.py | 95 +- .../_async/client/tasks.py | 17 +- .../_async/client/transform.py | 181 +- .../_sync/client/__init__.py | 2750 ++++++++++++----- .../_sync/client/async_search.py | 75 +- elasticsearch_serverless/_sync/client/cat.py | 186 +- .../_sync/client/cluster.py | 68 +- .../_sync/client/connector.py | 238 +- .../_sync/client/enrich.py | 32 +- elasticsearch_serverless/_sync/client/eql.py | 50 +- elasticsearch_serverless/_sync/client/esql.py | 19 +- .../_sync/client/graph.py | 19 +- .../_sync/client/indices.py | 617 ++-- .../_sync/client/inference.py | 83 +- .../_sync/client/ingest.py | 50 +- .../_sync/client/license.py | 17 +- .../_sync/client/logstash.py | 29 +- elasticsearch_serverless/_sync/client/ml.py | 703 +++-- .../_sync/client/query_rules.py | 92 +- .../_sync/client/search_application.py | 68 +- .../_sync/client/security.py | 325 +- elasticsearch_serverless/_sync/client/sql.py | 65 +- .../_sync/client/synonyms.py | 95 +- .../_sync/client/tasks.py | 17 +- .../_sync/client/transform.py | 181 +- 44 files changed, 7862 insertions(+), 3696 deletions(-) diff --git a/elasticsearch_serverless/_async/client/__init__.py b/elasticsearch_serverless/_async/client/__init__.py index 3031fef..8f6e472 100644 --- a/elasticsearch_serverless/_async/client/__init__.py +++ b/elasticsearch_serverless/_async/client/__init__.py @@ -456,6 +456,7 @@ async def bulk( error_trace: t.Optional[bool] = None, filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, human: t.Optional[bool] = None, + include_source_on_error: t.Optional[bool] = None, list_executed_pipelines: t.Optional[bool] = None, pipeline: t.Optional[str] = None, pretty: t.Optional[bool] = None, @@ -474,41 +475,133 @@ async def bulk( ] = None, ) -> ObjectApiResponse[t.Any]: """ - Bulk index or delete documents. Performs multiple indexing or delete operations - in a single API call. This reduces overhead and can greatly increase indexing - speed. - - ``_ + .. raw:: html + +

Bulk index or delete documents. + Perform multiple index, create, delete, and update actions in a single request. + This reduces overhead and can greatly increase indexing speed.

+

If the Elasticsearch security features are enabled, you must have the following index privileges for the target data stream, index, or index alias:

+ +

Automatic data stream creation requires a matching index template with data stream enabled.

+

The actions are specified in the request body using a newline delimited JSON (NDJSON) structure:

+ 
action_and_meta_data\\n
+          optional_source\\n
+          action_and_meta_data\\n
+          optional_source\\n
+          ....
+          action_and_meta_data\\n
+          optional_source\\n
+
+

The index and create actions expect a source on the next line and have the same semantics as the op_type parameter in the standard index API. + A create action fails if a document with the same ID already exists in the target + An index action adds or replaces a document as necessary.

+

NOTE: Data streams support only the create action. + To update or delete a document in a data stream, you must target the backing index containing the document.

+

An update action expects that the partial doc, upsert, and script and its options are specified on the next line.

+

A delete action does not expect a source on the next line and has the same semantics as the standard delete API.

+

NOTE: The final line of data must end with a newline character (\\n). + Each newline character may be preceded by a carriage return (\\r). + When sending NDJSON data to the _bulk endpoint, use a Content-Type header of application/json or application/x-ndjson. + Because this format uses literal newline characters (\\n) as delimiters, make sure that the JSON actions and sources are not pretty printed.

+

If you provide a target in the request path, it is used for any actions that don't explicitly specify an _index argument.

+

A note on the format: the idea here is to make processing as fast as possible. + As some of the actions are redirected to other shards on other nodes, only action_meta_data is parsed on the receiving node side.

+

Client libraries using this protocol should try and strive to do something similar on the client side, and reduce buffering as much as possible.

+

There is no "correct" number of actions to perform in a single bulk request. + Experiment with different settings to find the optimal size for your particular workload. + Note that Elasticsearch limits the maximum size of a HTTP request to 100mb by default so clients must ensure that no request exceeds this size. + It is not possible to index a single document that exceeds the size limit, so you must pre-process any such documents into smaller pieces before sending them to Elasticsearch. + For instance, split documents into pages or chapters before indexing them, or store raw binary data in a system outside Elasticsearch and replace the raw data with a link to the external system in the documents that you send to Elasticsearch.

+

Client suppport for bulk requests

+

Some of the officially supported clients provide helpers to assist with bulk requests and reindexing:

+ +

Submitting bulk requests with cURL

+

If you're providing text file input to curl, you must use the --data-binary flag instead of plain -d. + The latter doesn't preserve newlines. For example:

+ 
$ cat requests
+          { "index" : { "_index" : "test", "_id" : "1" } }
+          { "field1" : "value1" }
+          $ curl -s -H "Content-Type: application/x-ndjson" -XPOST localhost:9200/_bulk --data-binary "@requests"; echo
+          {"took":7, "errors": false, "items":[{"index":{"_index":"test","_id":"1","_version":1,"result":"created","forced_refresh":false}}]}
+
+

Optimistic concurrency control

+

Each index and delete action within a bulk API call may include the if_seq_no and if_primary_term parameters in their respective action and meta data lines. + The if_seq_no and if_primary_term parameters control how operations are run, based on the last modification to existing documents. See Optimistic concurrency control for more details.

+

Versioning

+

Each bulk item can include the version value using the version field. + It automatically follows the behavior of the index or delete operation based on the _version mapping. + It also support the version_type.

+

Routing

+

Each bulk item can include the routing value using the routing field. + It automatically follows the behavior of the index or delete operation based on the _routing mapping.

+

NOTE: Data streams do not support custom routing unless they were created with the allow_custom_routing setting enabled in the template.

+

Wait for active shards

+

When making bulk calls, you can set the wait_for_active_shards parameter to require a minimum number of shard copies to be active before starting to process the bulk request.

+

Refresh

+

Control when the changes made by this request are visible to search.

+

NOTE: Only the shards that receive the bulk request will be affected by refresh. + Imagine a _bulk?refresh=wait_for request with three documents in it that happen to be routed to different shards in an index with five shards. + The request will only wait for those three shards to refresh. + The other two shards that make up the index do not participate in the _bulk request at all.

+ + + ``_ :param operations: - :param index: Name of the data stream, index, or index alias to perform bulk + :param index: The name of the data stream, index, or index alias to perform bulk actions on. + :param include_source_on_error: True or false if to include the document source + in the error message in case of parsing errors. :param list_executed_pipelines: If `true`, the response will include the ingest - pipelines that were executed for each index or create. - :param pipeline: ID of the pipeline to use to preprocess incoming documents. - If the index has a default ingest pipeline specified, then setting the value - to `_none` disables the default ingest pipeline for this request. If a final - pipeline is configured it will always run, regardless of the value of this + pipelines that were run for each index or create. + :param pipeline: The pipeline identifier to use to preprocess incoming documents. + If the index has a default ingest pipeline specified, setting the value to + `_none` turns off the default ingest pipeline for this request. If a final + pipeline is configured, it will always run regardless of the value of this parameter. :param refresh: If `true`, Elasticsearch refreshes the affected shards to make - this operation visible to search, if `wait_for` then wait for a refresh to - make this operation visible to search, if `false` do nothing with refreshes. + this operation visible to search. If `wait_for`, wait for a refresh to make + this operation visible to search. If `false`, do nothing with refreshes. Valid values: `true`, `false`, `wait_for`. - :param require_alias: If `true`, the request’s actions must target an index alias. + :param require_alias: If `true`, the request's actions must target an index alias. :param require_data_stream: If `true`, the request's actions must target a data - stream (existing or to-be-created). - :param routing: Custom value used to route operations to a specific shard. - :param source: `true` or `false` to return the `_source` field or not, or a list - of fields to return. + stream (existing or to be created). + :param routing: A custom value that is used to route operations to a specific + shard. + :param source: Indicates whether to return the `_source` field (`true` or `false`) + or contains a list of fields to return. :param source_excludes: A comma-separated list of source fields to exclude from - the response. + the response. You can also use this parameter to exclude fields from the + subset specified in `_source_includes` query parameter. If the `_source` + parameter is `false`, this parameter is ignored. :param source_includes: A comma-separated list of source fields to include in - the response. - :param timeout: Period each action waits for the following operations: automatic - index creation, dynamic mapping updates, waiting for active shards. + the response. If this parameter is specified, only these source fields are + returned. You can exclude fields from this subset using the `_source_excludes` + query parameter. If the `_source` parameter is `false`, this parameter is + ignored. + :param timeout: The period each action waits for the following operations: automatic + index creation, dynamic mapping updates, and waiting for active shards. The + default is `1m` (one minute), which guarantees Elasticsearch waits for at + least the timeout before failing. The actual wait time could be longer, particularly + when multiple waits occur. :param wait_for_active_shards: The number of shard copies that must be active - before proceeding with the operation. Set to all or any positive integer - up to the total number of shards in the index (`number_of_replicas+1`). + before proceeding with the operation. Set to `all` or any positive integer + up to the total number of shards in the index (`number_of_replicas+1`). The + default is `1`, which waits for each primary shard to be active. """ if operations is None and body is None: raise ValueError( @@ -530,6 +623,8 @@ async def bulk( __query["filter_path"] = filter_path if human is not None: __query["human"] = human + if include_source_on_error is not None: + __query["include_source_on_error"] = include_source_on_error if list_executed_pipelines is not None: __query["list_executed_pipelines"] = list_executed_pipelines if pipeline is not None: @@ -583,12 +678,15 @@ async def clear_scroll( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Clear a scrolling search. Clear the search context and results for a scrolling - search. + .. raw:: html - ``_ +

Clear a scrolling search. + Clear the search context and results for a scrolling search.

- :param scroll_id: Scroll IDs to clear. To clear all scroll IDs, use `_all`. + + ``_ + + :param scroll_id: The scroll IDs to clear. To clear all scroll IDs, use `_all`. """ __path_parts: t.Dict[str, str] = {} __path = "/_search/scroll" @@ -634,13 +732,16 @@ async def close_point_in_time( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - 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. + .. raw:: html + +

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.

- ``_ + + ``_ :param id: The ID of the point-in-time. """ @@ -712,46 +813,65 @@ async def count( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Count search results. Get the number of documents matching a query. + .. raw:: html + +

Count search results. + Get the number of documents matching a query.

+

The query can be provided either by using a simple query string as a parameter, or by defining Query DSL within the request body. + The query is optional. When no query is provided, the API uses match_all to count all the documents.

+

The count API supports multi-target syntax. You can run a single count API search across multiple data streams and indices.

+

The operation is broadcast across all shards. + For each shard ID group, a replica is chosen and the search is run against it. + This means that replicas increase the scalability of the count.

- ``_ - :param index: Comma-separated list of data streams, indices, and aliases to search. - Supports wildcards (`*`). To search all data streams and indices, omit this - parameter or use `*` or `_all`. + ``_ + + :param index: A comma-separated list of data streams, indices, and aliases to + search. It supports wildcards (`*`). To search all data streams and indices, + omit this parameter or use `*` or `_all`. :param allow_no_indices: If `false`, the request returns an error if any wildcard expression, index alias, or `_all` value targets only missing or closed indices. - This behavior applies even if the request targets other open indices. + This behavior applies even if the request targets other open indices. For + example, a request targeting `foo*,bar*` returns an error if an index starts + with `foo` but no index starts with `bar`. :param analyze_wildcard: If `true`, wildcard and prefix queries are analyzed. - This parameter can only be used when the `q` query string parameter is specified. - :param analyzer: Analyzer to use for the query string. This parameter can only - be used when the `q` query string parameter is specified. + This parameter can be used only when the `q` query string parameter is specified. + :param analyzer: The analyzer to use for the query string. This parameter can + be used only when the `q` query string parameter is specified. :param default_operator: The default operator for query string query: `AND` or - `OR`. This parameter can only be used when the `q` query string parameter + `OR`. This parameter can be used only when the `q` query string parameter is specified. - :param df: Field to use as default where no field prefix is given in the query - string. This parameter can only be used when the `q` query string parameter + :param df: The field to use as a default when no field prefix is given in the + query string. This parameter can be used only when the `q` query string parameter is specified. - :param expand_wildcards: Type of index that wildcard patterns can match. If the - request can target data streams, this argument determines whether wildcard - expressions match hidden data streams. Supports comma-separated values, such - as `open,hidden`. - :param ignore_throttled: If `true`, concrete, expanded or aliased indices are + :param expand_wildcards: The type of index that wildcard patterns can match. + If the request can target data streams, this argument determines whether + wildcard expressions match hidden data streams. It supports comma-separated + values, such as `open,hidden`. + :param ignore_throttled: If `true`, concrete, expanded, or aliased indices are ignored when frozen. :param ignore_unavailable: If `false`, the request returns an error if it targets a missing or closed index. :param lenient: If `true`, format-based query failures (such as providing text - to a numeric field) in the query string will be ignored. - :param min_score: Sets the minimum `_score` value that documents must have to - be included in the result. - :param preference: Specifies the node or shard the operation should be performed - on. Random by default. - :param q: Query in the Lucene query string syntax. - :param query: Defines the search definition using the Query DSL. - :param routing: Custom value used to route operations to a specific shard. - :param terminate_after: Maximum number of documents to collect for each shard. + to a numeric field) in the query string will be ignored. This parameter can + be used only when the `q` query string parameter is specified. + :param min_score: The minimum `_score` value that documents must have to be included + in the result. + :param preference: The node or shard the operation should be performed on. By + default, it is random. + :param q: The query in Lucene query string syntax. This parameter cannot be used + with a request body. + :param query: Defines the search query using Query DSL. A request body query + cannot be used with the `q` query string parameter. + :param routing: A custom value used to route operations to a specific shard. + :param terminate_after: The maximum number of documents to collect for each shard. If a query reaches this limit, Elasticsearch terminates the query early. - Elasticsearch collects documents before sorting. + Elasticsearch collects documents before sorting. IMPORTANT: Use with caution. + Elasticsearch applies this parameter to each shard handling the request. + When possible, let Elasticsearch perform early termination automatically. + Avoid specifying this parameter for requests that target data streams with + backing indices across multiple data tiers. """ __path_parts: t.Dict[str, str] if index not in SKIP_IN_PATH: @@ -829,6 +949,7 @@ async def create( error_trace: t.Optional[bool] = None, filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, human: t.Optional[bool] = None, + include_source_on_error: t.Optional[bool] = None, pipeline: t.Optional[str] = None, pretty: t.Optional[bool] = None, refresh: t.Optional[ @@ -845,38 +966,102 @@ async def create( ] = None, ) -> ObjectApiResponse[t.Any]: """ - Index a document. Adds a JSON document to the specified data stream or index - and makes it searchable. If the target is an index and the document already exists, - the request updates the document and increments its version. - - ``_ - - :param index: Name of the data stream or index to target. If the target doesn’t + .. raw:: html + +

Create a new document in the index.

+

You can index a new JSON document with the /<target>/_doc/ or /<target>/_create/<_id> APIs + Using _create guarantees that the document is indexed only if it does not already exist. + It returns a 409 response when a document with a same ID already exists in the index. + To update an existing document, you must use the /<target>/_doc/ API.

+

If the Elasticsearch security features are enabled, you must have the following index privileges for the target data stream, index, or index alias:

+
    +
  • To add a document using the PUT /<target>/_create/<_id> or POST /<target>/_create/<_id> request formats, you must have the create_doc, create, index, or write index privilege.
    • +
  • To automatically create a data stream or index with this API request, you must have the auto_configure, create_index, or manage index privilege.
    • +
+

Automatic data stream creation requires a matching index template with data stream enabled.

+

Automatically create data streams and indices

+

If the request's target doesn't exist and matches an index template with a data_stream definition, the index operation automatically creates the data stream.

+

If the target doesn't exist and doesn't match a data stream template, the operation automatically creates the index and applies any matching index templates.

+

NOTE: Elasticsearch includes several built-in index templates. To avoid naming collisions with these templates, refer to index pattern documentation.

+

If no mapping exists, the index operation creates a dynamic mapping. + By default, new fields and objects are automatically added to the mapping if needed.

+

Automatic index creation is controlled by the action.auto_create_index setting. + If it is true, any index can be created automatically. + You can modify this setting to explicitly allow or block automatic creation of indices that match specified patterns or set it to false to turn off automatic index creation entirely. + Specify a comma-separated list of patterns you want to allow or prefix each pattern with + or - to indicate whether it should be allowed or blocked. + When a list is specified, the default behaviour is to disallow.

+

NOTE: The action.auto_create_index setting affects the automatic creation of indices only. + It does not affect the creation of data streams.

+

Routing

+

By default, shard placement — or routing — is controlled by using a hash of the document's ID value. + For more explicit control, the value fed into the hash function used by the router can be directly specified on a per-operation basis using the routing parameter.

+

When setting up explicit mapping, you can also use the _routing field to direct the index operation to extract the routing value from the document itself. + This does come at the (very minimal) cost of an additional document parsing pass. + If the _routing mapping is defined and set to be required, the index operation will fail if no routing value is provided or extracted.

+

NOTE: Data streams do not support custom routing unless they were created with the allow_custom_routing setting enabled in the template.

+

Distributed

+

The index operation is directed to the primary shard based on its route and performed on the actual node containing this shard. + After the primary shard completes the operation, if needed, the update is distributed to applicable replicas.

+

Active shards

+

To improve the resiliency of writes to the system, indexing operations can be configured to wait for a certain number of active shard copies before proceeding with the operation. + If the requisite number of active shard copies are not available, then the write operation must wait and retry, until either the requisite shard copies have started or a timeout occurs. + By default, write operations only wait for the primary shards to be active before proceeding (that is to say wait_for_active_shards is 1). + This default can be overridden in the index settings dynamically by setting index.write.wait_for_active_shards. + To alter this behavior per operation, use the wait_for_active_shards request parameter.

+

Valid values are all or any positive integer up to the total number of configured copies per shard in the index (which is number_of_replicas+1). + Specifying a negative value or a number greater than the number of shard copies will throw an error.

+

For example, suppose you have a cluster of three nodes, A, B, and C and you create an index index with the number of replicas set to 3 (resulting in 4 shard copies, one more copy than there are nodes). + If you attempt an indexing operation, by default the operation will only ensure the primary copy of each shard is available before proceeding. + This means that even if B and C went down and A hosted the primary shard copies, the indexing operation would still proceed with only one copy of the data. + If wait_for_active_shards is set on the request to 3 (and all three nodes are up), the indexing operation will require 3 active shard copies before proceeding. + This requirement should be met because there are 3 active nodes in the cluster, each one holding a copy of the shard. + However, if you set wait_for_active_shards to all (or to 4, which is the same in this situation), the indexing operation will not proceed as you do not have all 4 copies of each shard active in the index. + The operation will timeout unless a new node is brought up in the cluster to host the fourth copy of the shard.

+

It is important to note that this setting greatly reduces the chances of the write operation not writing to the requisite number of shard copies, but it does not completely eliminate the possibility, because this check occurs before the write operation starts. + After the write operation is underway, it is still possible for replication to fail on any number of shard copies but still succeed on the primary. + The _shards section of the API response reveals the number of shard copies on which replication succeeded and failed.

+ + + ``_ + + :param index: The name of the data stream or index to target. If the target doesn't exist and matches the name or wildcard (`*`) pattern of an index template with a `data_stream` definition, this request creates the data stream. If - the target doesn’t exist and doesn’t match a data stream template, this request + the target doesn't exist and doesn’t match a data stream template, this request creates the index. - :param id: Unique identifier for the document. + :param id: A unique identifier for the document. To automatically generate a + document ID, use the `POST //_doc/` request format. :param document: - :param pipeline: ID of the pipeline to use to preprocess incoming documents. - If the index has a default ingest pipeline specified, then setting the value - to `_none` disables the default ingest pipeline for this request. If a final - pipeline is configured it will always run, regardless of the value of this + :param include_source_on_error: True or false if to include the document source + in the error message in case of parsing errors. + :param pipeline: The ID of the pipeline to use to preprocess incoming documents. + If the index has a default ingest pipeline specified, setting the value to + `_none` turns off the default ingest pipeline for this request. If a final + pipeline is configured, it will always run regardless of the value of this parameter. :param refresh: If `true`, Elasticsearch refreshes the affected shards to make - this operation visible to search, if `wait_for` then wait for a refresh to - make this operation visible to search, if `false` do nothing with refreshes. - Valid values: `true`, `false`, `wait_for`. - :param routing: Custom value used to route operations to a specific shard. - :param timeout: Period the request waits for the following operations: automatic - index creation, dynamic mapping updates, waiting for active shards. - :param version: Explicit version number for concurrency control. The specified - version must match the current version of the document for the request to - succeed. - :param version_type: Specific version type: `external`, `external_gte`. + this operation visible to search. If `wait_for`, it waits for a refresh to + make this operation visible to search. If `false`, it does nothing with refreshes. + :param routing: A custom value that is used to route operations to a specific + shard. + :param timeout: The period the request waits for the following operations: automatic + index creation, dynamic mapping updates, waiting for active shards. Elasticsearch + waits for at least the specified timeout period before failing. The actual + wait time could be longer, particularly when multiple waits occur. This parameter + is useful for situations where the primary shard assigned to perform the + operation might not be available when the operation runs. Some reasons for + this might be that the primary shard is currently recovering from a gateway + or undergoing relocation. By default, the operation will wait on the primary + shard to become available for at least 1 minute before failing and responding + with an error. The actual wait time could be longer, particularly when multiple + waits occur. + :param version: The explicit version number for concurrency control. It must + be a non-negative long number. + :param version_type: The version type. :param wait_for_active_shards: The number of shard copies that must be active - before proceeding with the operation. Set to `all` or any positive integer - up to the total number of shards in the index (`number_of_replicas+1`). + before proceeding with the operation. You can set it to `all` or any positive + integer up to the total number of shards in the index (`number_of_replicas+1`). + The default value of `1` means it waits for each primary shard to be active. """ if index in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'index'") @@ -897,6 +1082,8 @@ async def create( __query["filter_path"] = filter_path if human is not None: __query["human"] = human + if include_source_on_error is not None: + __query["include_source_on_error"] = include_source_on_error if pipeline is not None: __query["pipeline"] = pipeline if pretty is not None: @@ -951,29 +1138,60 @@ async def delete( ] = None, ) -> ObjectApiResponse[t.Any]: """ - Delete a document. Removes a JSON document from the specified index. - - ``_ - - :param index: Name of the target index. - :param id: Unique identifier for the document. + .. raw:: html + +

Delete a document.

+

Remove a JSON document from the specified index.

+

NOTE: You cannot send deletion requests directly to a data stream. + To delete a document in a data stream, you must target the backing index containing the document.

+

Optimistic concurrency control

+

Delete operations can be made conditional and only be performed if the last modification to the document was assigned the sequence number and primary term specified by the if_seq_no and if_primary_term parameters. + If a mismatch is detected, the operation will result in a VersionConflictException and a status code of 409.

+

Versioning

+

Each document indexed is versioned. + When deleting a document, the version can be specified to make sure the relevant document you are trying to delete is actually being deleted and it has not changed in the meantime. + Every write operation run on a document, deletes included, causes its version to be incremented. + The version number of a deleted document remains available for a short time after deletion to allow for control of concurrent operations. + The length of time for which a deleted document's version remains available is determined by the index.gc_deletes index setting.

+

Routing

+

If routing is used during indexing, the routing value also needs to be specified to delete a document.

+

If the _routing mapping is set to required and no routing value is specified, the delete API throws a RoutingMissingException and rejects the request.

+

For example:

+ 
DELETE /my-index-000001/_doc/1?routing=shard-1
+
+

This request deletes the document with ID 1, but it is routed based on the user. + The document is not deleted if the correct routing is not specified.

+

Distributed

+

The delete operation gets hashed into a specific shard ID. + It then gets redirected into the primary shard within that ID group and replicated (if needed) to shard replicas within that ID group.

+ + + ``_ + + :param index: The name of the target index. + :param id: A unique identifier for the document. :param if_primary_term: Only perform the operation if the document has this primary term. :param if_seq_no: Only perform the operation if the document has this sequence number. :param refresh: If `true`, Elasticsearch refreshes the affected shards to make - this operation visible to search, if `wait_for` then wait for a refresh to - make this operation visible to search, if `false` do nothing with refreshes. - Valid values: `true`, `false`, `wait_for`. - :param routing: Custom value used to route operations to a specific shard. - :param timeout: Period to wait for active shards. - :param version: Explicit version number for concurrency control. The specified - version must match the current version of the document for the request to - succeed. - :param version_type: Specific version type: `external`, `external_gte`. - :param wait_for_active_shards: The number of shard copies that must be active - before proceeding with the operation. Set to `all` or any positive integer - up to the total number of shards in the index (`number_of_replicas+1`). + this operation visible to search. If `wait_for`, it waits for a refresh to + make this operation visible to search. If `false`, it does nothing with refreshes. + :param routing: A custom value used to route operations to a specific shard. + :param timeout: The period to wait for active shards. This parameter is useful + for situations where the primary shard assigned to perform the delete operation + might not be available when the delete operation runs. Some reasons for this + might be that the primary shard is currently recovering from a store or undergoing + relocation. By default, the delete operation will wait on the primary shard + to become available for up to 1 minute before failing and responding with + an error. + :param version: An explicit version number for concurrency control. It must match + the current version of the document for the request to succeed. + :param version_type: The version type. + :param wait_for_active_shards: The minimum number of shard copies that must be + active before proceeding with the operation. You can set it to `all` or any + positive integer up to the total number of shards in the index (`number_of_replicas+1`). + The default value of `1` means it waits for each primary shard to be active. """ if index in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'index'") @@ -1073,72 +1291,148 @@ async def delete_by_query( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Delete documents. Deletes documents that match the specified query. - - ``_ - - :param index: Comma-separated list of data streams, indices, and aliases to search. - Supports wildcards (`*`). To search all data streams or indices, omit this - parameter or use `*` or `_all`. + .. raw:: html + +

Delete documents.

+

Deletes documents that match the specified query.

+

If the Elasticsearch security features are enabled, you must have the following index privileges for the target data stream, index, or alias:

+
    +
  • read
    • +
  • delete or write
    • +
+

You can specify the query criteria in the request URI or the request body using the same syntax as the search API. + When you submit a delete by query request, Elasticsearch gets a snapshot of the data stream or index when it begins processing the request and deletes matching documents using internal versioning. + If a document changes between the time that the snapshot is taken and the delete operation is processed, it results in a version conflict and the delete operation fails.

+

NOTE: Documents with a version equal to 0 cannot be deleted using delete by query because internal versioning does not support 0 as a valid version number.

+

While processing a delete by query request, Elasticsearch performs multiple search requests sequentially to find all of the matching documents to delete. + A bulk delete request is performed for each batch of matching documents. + If a search or bulk request is rejected, the requests are retried up to 10 times, with exponential back off. + If the maximum retry limit is reached, processing halts and all failed requests are returned in the response. + Any delete requests that completed successfully still stick, they are not rolled back.

+

You can opt to count version conflicts instead of halting and returning by setting conflicts to proceed. + Note that if you opt to count version conflicts the operation could attempt to delete more documents from the source than max_docs until it has successfully deleted max_docs documents, or it has gone through every document in the source query.

+

Throttling delete requests

+

To control the rate at which delete by query issues batches of delete operations, you can set requests_per_second to any positive decimal number. + This pads each batch with a wait time to throttle the rate. + Set requests_per_second to -1 to disable throttling.

+

Throttling uses a wait time between batches so that the internal scroll requests can be given a timeout that takes the request padding into account. + The padding time is the difference between the batch size divided by the requests_per_second and the time spent writing. + By default the batch size is 1000, so if requests_per_second is set to 500:

+ 
target_time = 1000 / 500 per second = 2 seconds
+          wait_time = target_time - write_time = 2 seconds - .5 seconds = 1.5 seconds
+
+

Since the batch is issued as a single _bulk request, large batch sizes cause Elasticsearch to create many requests and wait before starting the next set. + This is "bursty" instead of "smooth".

+

Slicing

+

Delete by query supports sliced scroll to parallelize the delete process. + This can improve efficiency and provide a convenient way to break the request down into smaller parts.

+

Setting slices to auto lets Elasticsearch choose the number of slices to use. + This setting will use one slice per shard, up to a certain limit. + If there are multiple source data streams or indices, it will choose the number of slices based on the index or backing index with the smallest number of shards. + Adding slices to the delete by query operation creates sub-requests which means it has some quirks:

+
    +
  • You can see these requests in the tasks APIs. These sub-requests are "child" tasks of the task for the request with slices.
    • +
  • Fetching the status of the task for the request with slices only contains the status of completed slices.
    • +
  • These sub-requests are individually addressable for things like cancellation and rethrottling.
    • +
  • Rethrottling the request with slices will rethrottle the unfinished sub-request proportionally.
    • +
  • Canceling the request with slices will cancel each sub-request.
    • +
  • Due to the nature of slices each sub-request won't get a perfectly even portion of the documents. All documents will be addressed, but some slices may be larger than others. Expect larger slices to have a more even distribution.
    • +
  • Parameters like requests_per_second and max_docs on a request with slices are distributed proportionally to each sub-request. Combine that with the earlier point about distribution being uneven and you should conclude that using max_docs with slices might not result in exactly max_docs documents being deleted.
    • +
  • Each sub-request gets a slightly different snapshot of the source data stream or index though these are all taken at approximately the same time.
    • +
+

If you're slicing manually or otherwise tuning automatic slicing, keep in mind that:

+
    +
  • Query performance is most efficient when the number of slices is equal to the number of shards in the index or backing index. If that number is large (for example, 500), choose a lower number as too many slices hurts performance. Setting slices higher than the number of shards generally does not improve efficiency and adds overhead.
    • +
  • Delete performance scales linearly across available resources with the number of slices.
    • +
+

Whether query or delete performance dominates the runtime depends on the documents being reindexed and cluster resources.

+

Cancel a delete by query operation

+

Any delete by query can be canceled using the task cancel API. For example:

+ 
POST _tasks/r1A2WoRbTwKZ516z6NEs5A:36619/_cancel
+
+

The task ID can be found by using the get tasks API.

+

Cancellation should happen quickly but might take a few seconds. + The get task status API will continue to list the delete by query task until this task checks that it has been cancelled and terminates itself.

+ + + ``_ + + :param index: A comma-separated list of data streams, indices, and aliases to + search. It supports wildcards (`*`). To search all data streams or indices, + omit this parameter or use `*` or `_all`. :param allow_no_indices: If `false`, the request returns an error if any wildcard expression, index alias, or `_all` value targets only missing or closed indices. This behavior applies even if the request targets other open indices. For example, a request targeting `foo*,bar*` returns an error if an index starts with `foo` but no index starts with `bar`. :param analyze_wildcard: If `true`, wildcard and prefix queries are analyzed. - :param analyzer: Analyzer to use for the query string. + This parameter can be used only when the `q` query string parameter is specified. + :param analyzer: Analyzer to use for the query string. This parameter can be + used only when the `q` query string parameter is specified. :param conflicts: What to do if delete by query hits version conflicts: `abort` or `proceed`. :param default_operator: The default operator for query string query: `AND` or - `OR`. - :param df: Field to use as default where no field prefix is given in the query - string. - :param expand_wildcards: Type of index that wildcard patterns can match. If the - request can target data streams, this argument determines whether wildcard - expressions match hidden data streams. Supports comma-separated values, such - as `open,hidden`. Valid values are: `all`, `open`, `closed`, `hidden`, `none`. + `OR`. This parameter can be used only when the `q` query string parameter + is specified. + :param df: The field to use as default where no field prefix is given in the + query string. This parameter can be used only when the `q` query string parameter + is specified. + :param expand_wildcards: The type of index that wildcard patterns can match. + If the request can target data streams, this argument determines whether + wildcard expressions match hidden data streams. It supports comma-separated + values, such as `open,hidden`. :param from_: Starting offset (default: 0) :param ignore_unavailable: If `false`, the request returns an error if it targets a missing or closed index. :param lenient: If `true`, format-based query failures (such as providing text - to a numeric field) in the query string will be ignored. + to a numeric field) in the query string will be ignored. This parameter can + be used only when the `q` query string parameter is specified. :param max_docs: The maximum number of documents to delete. - :param preference: Specifies the node or shard the operation should be performed - on. Random by default. - :param q: Query in the Lucene query string syntax. - :param query: Specifies the documents to delete using the Query DSL. + :param preference: The node or shard the operation should be performed on. It + is random by default. + :param q: A query in the Lucene query string syntax. + :param query: The documents to delete specified with Query DSL. :param refresh: If `true`, Elasticsearch refreshes all shards involved in the - delete by query after the request completes. + delete by query after the request completes. This is different than the delete + API's `refresh` parameter, which causes just the shard that received the + delete request to be refreshed. Unlike the delete API, it does not support + `wait_for`. :param request_cache: If `true`, the request cache is used for this request. Defaults to the index-level setting. :param requests_per_second: The throttle for this request in sub-requests per second. - :param routing: Custom value used to route operations to a specific shard. - :param scroll: Period to retain the search context for scrolling. - :param scroll_size: Size of the scroll request that powers the operation. - :param search_timeout: Explicit timeout for each search request. Defaults to - no timeout. - :param search_type: The type of the search operation. Available options: `query_then_fetch`, - `dfs_query_then_fetch`. + :param routing: A custom value used to route operations to a specific shard. + :param scroll: The period to retain the search context for scrolling. + :param scroll_size: The size of the scroll request that powers the operation. + :param search_timeout: The explicit timeout for each search request. It defaults + to no timeout. + :param search_type: The type of the search operation. Available options include + `query_then_fetch` and `dfs_query_then_fetch`. :param slice: Slice the request manually using the provided slice ID and total number of slices. :param slices: The number of slices this task should be divided into. - :param sort: A comma-separated list of : pairs. - :param stats: Specific `tag` of the request for logging and statistical purposes. - :param terminate_after: Maximum number of documents to collect for each shard. + :param sort: A comma-separated list of `:` pairs. + :param stats: The specific `tag` of the request for logging and statistical purposes. + :param terminate_after: The maximum number of documents to collect for each shard. If a query reaches this limit, Elasticsearch terminates the query early. Elasticsearch collects documents before sorting. Use with caution. Elasticsearch applies this parameter to each shard handling the request. When possible, let Elasticsearch perform early termination automatically. Avoid specifying this parameter for requests that target data streams with backing indices across multiple data tiers. - :param timeout: Period each deletion request waits for active shards. + :param timeout: The period each deletion request waits for active shards. :param version: If `true`, returns the document version as part of a hit. :param wait_for_active_shards: The number of shard copies that must be active - before proceeding with the operation. Set to all or any positive integer - up to the total number of shards in the index (`number_of_replicas+1`). + before proceeding with the operation. Set to `all` or any positive integer + up to the total number of shards in the index (`number_of_replicas+1`). The + `timeout` value controls how long each write request waits for unavailable + shards to become available. :param wait_for_completion: If `true`, the request blocks until the operation - is complete. + is complete. If `false`, Elasticsearch performs some preflight checks, launches + the request, and returns a task you can use to cancel or get the status of + the task. Elasticsearch creates a record of this task as a document at `.tasks/task/${taskId}`. + When you are done with a task, you should delete the task document so Elasticsearch + can reclaim the space. """ if index in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'index'") @@ -1252,16 +1546,22 @@ async def delete_script( timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, ) -> ObjectApiResponse[t.Any]: """ - Delete a script or search template. Deletes a stored script or search template. + .. raw:: html - ``_ +

Delete a script or search template. + Deletes a stored script or search template.

- :param id: Identifier for the stored script or search template. - :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 timeout: Period to wait for a response. If no response is received before - the timeout expires, the request fails and returns an error. + + ``_ + + :param id: The identifier for the stored script or search template. + :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. It can also be set to `-1` to indicate that the request + should never timeout. + :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. It can + also be set to `-1` to indicate that the request should never timeout. """ if id in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'id'") @@ -1320,32 +1620,60 @@ async def exists( ] = None, ) -> HeadApiResponse: """ - Check a document. Checks if a specified document exists. - - ``_ - - :param index: Comma-separated list of data streams, indices, and aliases. Supports - wildcards (`*`). - :param id: Identifier of the document. - :param preference: Specifies the node or shard the operation should be performed - on. Random by default. + .. raw:: html + +

Check a document.

+

Verify that a document exists. + For example, check to see if a document with the _id 0 exists:

+ 
HEAD my-index-000001/_doc/0
+
+

If the document exists, the API returns a status code of 200 - OK. + If the document doesn’t exist, the API returns 404 - Not Found.

+

Versioning support

+

You can use the version parameter to check the document only if its current version is equal to the specified one.

+

Internally, Elasticsearch has marked the old document as deleted and added an entirely new document. + The old version of the document doesn't disappear immediately, although you won't be able to access it. + Elasticsearch cleans up deleted documents in the background as you continue to index more data.

+ + + ``_ + + :param index: A comma-separated list of data streams, indices, and aliases. It + supports wildcards (`*`). + :param id: A unique document identifier. + :param preference: The node or shard the operation should be performed on. By + default, the operation is randomized between the shard replicas. If it is + set to `_local`, the operation will prefer to be run on a local allocated + shard when possible. If it is set to a custom value, the value is used to + guarantee that the same shards will be used for the same custom value. This + can help with "jumping values" when hitting different shards in different + refresh states. A sample value can be something like the web session ID or + the user name. :param realtime: If `true`, the request is real-time as opposed to near-real-time. - :param refresh: If `true`, Elasticsearch refreshes all shards involved in the - delete by query after the request completes. - :param routing: Target the specified primary shard. - :param source: `true` or `false` to return the `_source` field or not, or a list - of fields to return. - :param source_excludes: A comma-separated list of source fields to exclude in - the response. + :param refresh: If `true`, the request refreshes the relevant shards before retrieving + the document. Setting it to `true` should be done after careful thought and + verification that this does not cause a heavy load on the system (and slow + down indexing). + :param routing: A custom value used to route operations to a specific shard. + :param source: Indicates whether to return the `_source` field (`true` or `false`) + or lists the fields to return. + :param source_excludes: A comma-separated list of source fields to exclude from + the response. You can also use this parameter to exclude fields from the + subset specified in `_source_includes` query parameter. If the `_source` + parameter is `false`, this parameter is ignored. :param source_includes: A comma-separated list of source fields to include in - the response. - :param stored_fields: List of stored fields to return as part of a hit. If no - fields are specified, no stored fields are included in the response. If this - field is specified, the `_source` parameter defaults to false. + the response. If this parameter is specified, only these source fields are + returned. You can exclude fields from this subset using the `_source_excludes` + query parameter. If the `_source` parameter is `false`, this parameter is + ignored. + :param stored_fields: A comma-separated list of stored fields to return as part + of a hit. If no fields are specified, no stored fields are included in the + response. If this field is specified, the `_source` parameter defaults to + `false`. :param version: Explicit version number for concurrency control. The specified version must match the current version of the document for the request to succeed. - :param version_type: Specific version type: `external`, `external_gte`. + :param version_type: The version type. """ if index in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'index'") @@ -1421,29 +1749,38 @@ async def exists_source( ] = None, ) -> HeadApiResponse: """ - Check for a document source. Checks if a document's `_source` is stored. + .. raw:: html - ``_ +

Check for a document source.

+

Check whether a document source exists in an index. + For example:

+ 
HEAD my-index-000001/_source/1
+
+

A document's source is not available if it is disabled in the mapping.

- :param index: Comma-separated list of data streams, indices, and aliases. Supports - wildcards (`*`). - :param id: Identifier of the document. - :param preference: Specifies the node or shard the operation should be performed - on. Random by default. - :param realtime: If true, the request is real-time as opposed to near-real-time. - :param refresh: If `true`, Elasticsearch refreshes all shards involved in the - delete by query after the request completes. - :param routing: Target the specified primary shard. - :param source: `true` or `false` to return the `_source` field or not, or a list - of fields to return. + + ``_ + + :param index: A comma-separated list of data streams, indices, and aliases. It + supports wildcards (`*`). + :param id: A unique identifier for the document. + :param preference: The node or shard the operation should be performed on. By + default, the operation is randomized between the shard replicas. + :param realtime: If `true`, the request is real-time as opposed to near-real-time. + :param refresh: If `true`, the request refreshes the relevant shards before retrieving + the document. Setting it to `true` should be done after careful thought and + verification that this does not cause a heavy load on the system (and slow + down indexing). + :param routing: A custom value used to route operations to a specific shard. + :param source: Indicates whether to return the `_source` field (`true` or `false`) + or lists the fields to return. :param source_excludes: A comma-separated list of source fields to exclude in the response. :param source_includes: A comma-separated list of source fields to include in the response. - :param version: Explicit version number for concurrency control. The specified - version must match the current version of the document for the request to - succeed. - :param version_type: Specific version type: `external`, `external_gte`. + :param version: The version number for concurrency control. It must match the + current version of the document for the request to succeed. + :param version_type: The version type. """ if index in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'index'") @@ -1521,34 +1858,47 @@ async def explain( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Explain a document match result. Returns information about why a specific document - matches, or doesn’t match, a query. + .. raw:: html + +

Explain a document match result. + Get information about why a specific document matches, or doesn't match, a query. + It computes a score explanation for a query and a specific document.

- ``_ - :param index: Index names used to limit the request. Only a single index name - can be provided to this parameter. - :param id: Defines the document ID. + ``_ + + :param index: Index names that are used to limit the request. Only a single index + name can be provided to this parameter. + :param id: The document identifier. :param analyze_wildcard: If `true`, wildcard and prefix queries are analyzed. - :param analyzer: Analyzer to use for the query string. This parameter can only - be used when the `q` query string parameter is specified. + This parameter can be used only when the `q` query string parameter is specified. + :param analyzer: The analyzer to use for the query string. This parameter can + be used only when the `q` query string parameter is specified. :param default_operator: The default operator for query string query: `AND` or - `OR`. - :param df: Field to use as default where no field prefix is given in the query - string. + `OR`. This parameter can be used only when the `q` query string parameter + is specified. + :param df: The field to use as default where no field prefix is given in the + query string. This parameter can be used only when the `q` query string parameter + is specified. :param lenient: If `true`, format-based query failures (such as providing text - to a numeric field) in the query string will be ignored. - :param preference: Specifies the node or shard the operation should be performed - on. Random by default. - :param q: Query in the Lucene query string syntax. + to a numeric field) in the query string will be ignored. This parameter can + be used only when the `q` query string parameter is specified. + :param preference: The node or shard the operation should be performed on. It + is random by default. + :param q: The query in the Lucene query string syntax. :param query: Defines the search definition using the Query DSL. - :param routing: Custom value used to route operations to a specific shard. - :param source: True or false to return the `_source` field or not, or a list + :param routing: A custom value used to route operations to a specific shard. + :param source: `True` or `false` to return the `_source` field or not or a list of fields to return. :param source_excludes: A comma-separated list of source fields to exclude from - the response. + the response. You can also use this parameter to exclude fields from the + subset specified in `_source_includes` query parameter. If the `_source` + parameter is `false`, this parameter is ignored. :param source_includes: A comma-separated list of source fields to include in - the response. + the response. If this parameter is specified, only these source fields are + returned. You can exclude fields from this subset using the `_source_excludes` + query parameter. If the `_source` parameter is `false`, this parameter is + ignored. :param stored_fields: A comma-separated list of stored fields to return in the response. """ @@ -1641,15 +1991,18 @@ async def field_caps( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - 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. + .. raw:: html + +

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.

+ - ``_ + ``_ - :param index: Comma-separated list of data streams, indices, and aliases used + :param index: A comma-separated list of data streams, indices, and aliases used to limit the request. Supports wildcards (*). To target all data streams and indices, omit this parameter or use * or _all. :param allow_no_indices: If false, the request returns an error if any wildcard @@ -1657,25 +2010,32 @@ async def field_caps( This behavior applies even if the request targets other open indices. For example, a request targeting `foo*,bar*` returns an error if an index starts with foo but no index starts with bar. - :param expand_wildcards: Type of index that wildcard patterns can match. If the - request can target data streams, this argument determines whether wildcard - expressions match hidden data streams. Supports comma-separated values, such - as `open,hidden`. - :param fields: List of fields to retrieve capabilities for. Wildcard (`*`) expressions - are supported. - :param filters: An optional set of filters: can include +metadata,-metadata,-nested,-multifield,-parent + :param expand_wildcards: The type of index that wildcard patterns can match. + If the request can target data streams, this argument determines whether + wildcard expressions match hidden data streams. Supports comma-separated + values, such as `open,hidden`. + :param fields: A list of fields to retrieve capabilities for. Wildcard (`*`) + expressions are supported. + :param filters: A comma-separated list of filters to apply to the response. :param ignore_unavailable: If `true`, missing or closed indices are not included in the response. :param include_empty_fields: If false, empty fields are not included in the response. :param include_unmapped: If true, unmapped fields are included in the response. - :param index_filter: Allows to filter indices if the provided query rewrites - to match_none on every shard. - :param runtime_mappings: Defines ad-hoc runtime fields in the request similar + :param index_filter: Filter indices if the provided query rewrites to `match_none` + on every shard. IMPORTANT: The filtering is done on a best-effort basis, + it uses index statistics and mappings to rewrite queries to `match_none` + instead of fully running the request. For instance a range query over a date + field can rewrite to `match_none` if all documents within a shard (including + deleted documents) are outside of the provided range. However, not all queries + can rewrite to `match_none` so this API may return an index even if the provided + filter matches no document. + :param runtime_mappings: Define ad-hoc runtime fields in the request similar to the way it is done in search requests. These fields exist only as part of the query and take precedence over fields defined with the same name in the index mappings. - :param types: Only return results for fields that have one of the types in the - list + :param types: A comma-separated list of field types to include. Any fields that + do not match one of these types will be excluded from the results. It defaults + to empty, meaning that all field types are returned. """ __path_parts: t.Dict[str, str] if index not in SKIP_IN_PATH: @@ -1761,36 +2121,87 @@ async def get( ] = None, ) -> ObjectApiResponse[t.Any]: """ - Get a document by its ID. Retrieves the document with the specified ID from an - index. - - ``_ - - :param index: Name of the index that contains the document. - :param id: Unique identifier of the document. - :param force_synthetic_source: Should this request force synthetic _source? Use - this to test if the mapping supports synthetic _source and to get a sense - of the worst case performance. Fetches with this enabled will be slower the - enabling synthetic source natively in the index. - :param preference: Specifies the node or shard the operation should be performed - on. Random by default. + .. raw:: html + +

Get a document by its ID.

+

Get a document and its source or stored fields from an index.

+

By default, this API is realtime and is not affected by the refresh rate of the index (when data will become visible for search). + In the case where stored fields are requested with the stored_fields parameter and the document has been updated but is not yet refreshed, the API will have to parse and analyze the source to extract the stored fields. + To turn off realtime behavior, set the realtime parameter to false.

+

Source filtering

+

By default, the API returns the contents of the _source field unless you have used the stored_fields parameter or the _source field is turned off. + You can turn off _source retrieval by using the _source parameter:

+ 
GET my-index-000001/_doc/0?_source=false
+
+

If you only need one or two fields from the _source, use the _source_includes or _source_excludes parameters to include or filter out particular fields. + This can be helpful with large documents where partial retrieval can save on network overhead + Both parameters take a comma separated list of fields or wildcard expressions. + For example:

+ 
GET my-index-000001/_doc/0?_source_includes=*.id&_source_excludes=entities
+
+

If you only want to specify includes, you can use a shorter notation:

+ 
GET my-index-000001/_doc/0?_source=*.id
+
+

Routing

+

If routing is used during indexing, the routing value also needs to be specified to retrieve a document. + For example:

+ 
GET my-index-000001/_doc/2?routing=user1
+
+

This request gets the document with ID 2, but it is routed based on the user. + The document is not fetched if the correct routing is not specified.

+

Distributed

+

The GET operation is hashed into a specific shard ID. + It is then redirected to one of the replicas within that shard ID and returns the result. + The replicas are the primary shard and its replicas within that shard ID group. + This means that the more replicas you have, the better your GET scaling will be.

+

Versioning support

+

You can use the version parameter to retrieve the document only if its current version is equal to the specified one.

+

Internally, Elasticsearch has marked the old document as deleted and added an entirely new document. + The old version of the document doesn't disappear immediately, although you won't be able to access it. + Elasticsearch cleans up deleted documents in the background as you continue to index more data.

+ + + ``_ + + :param index: The name of the index that contains the document. + :param id: A unique document identifier. + :param force_synthetic_source: Indicates whether the request forces synthetic + `_source`. Use this paramater to test if the mapping supports synthetic `_source` + and to get a sense of the worst case performance. Fetches with this parameter + enabled will be slower than enabling synthetic source natively in the index. + :param preference: The node or shard the operation should be performed on. By + default, the operation is randomized between the shard replicas. If it is + set to `_local`, the operation will prefer to be run on a local allocated + shard when possible. If it is set to a custom value, the value is used to + guarantee that the same shards will be used for the same custom value. This + can help with "jumping values" when hitting different shards in different + refresh states. A sample value can be something like the web session ID or + the user name. :param realtime: If `true`, the request is real-time as opposed to near-real-time. - :param refresh: If true, Elasticsearch refreshes the affected shards to make - this operation visible to search. If false, do nothing with refreshes. - :param routing: Target the specified primary shard. - :param source: True or false to return the _source field or not, or a list of - fields to return. - :param source_excludes: A comma-separated list of source fields to exclude in - the response. + :param refresh: If `true`, the request refreshes the relevant shards before retrieving + the document. Setting it to `true` should be done after careful thought and + verification that this does not cause a heavy load on the system (and slow + down indexing). + :param routing: A custom value used to route operations to a specific shard. + :param source: Indicates whether to return the `_source` field (`true` or `false`) + or lists the fields to return. + :param source_excludes: A comma-separated list of source fields to exclude from + the response. You can also use this parameter to exclude fields from the + subset specified in `_source_includes` query parameter. If the `_source` + parameter is `false`, this parameter is ignored. :param source_includes: A comma-separated list of source fields to include in - the response. - :param stored_fields: List of stored fields to return as part of a hit. If no - fields are specified, no stored fields are included in the response. If this - field is specified, the `_source` parameter defaults to false. - :param version: Explicit version number for concurrency control. The specified - version must match the current version of the document for the request to - succeed. - :param version_type: Specific version type: internal, external, external_gte. + the response. If this parameter is specified, only these source fields are + returned. You can exclude fields from this subset using the `_source_excludes` + query parameter. If the `_source` parameter is `false`, this parameter is + ignored. + :param stored_fields: A comma-separated list of stored fields to return as part + of a hit. If no fields are specified, no stored fields are included in the + response. If this field is specified, the `_source` parameter defaults to + `false`. Only leaf fields can be retrieved with the `stored_field` option. + Object fields can't be returned;​if specified, the request fails. + :param version: The version number for concurrency control. It must match the + current version of the document for the request to succeed. + :param version_type: The version type. """ if index in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'index'") @@ -1851,12 +2262,19 @@ async def get_script( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Get a script or search template. Retrieves a stored script or search template. + .. raw:: html + +

Get a script or search template. + Retrieves a stored script or search template.

- ``_ - :param id: Identifier for the stored script or search template. - :param master_timeout: Specify timeout for connection to master + ``_ + + :param id: The identifier for the stored script or search template. + :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. It can also be set to `-1` to indicate that the request should + never timeout. """ if id in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'id'") @@ -1913,29 +2331,41 @@ async def get_source( ] = None, ) -> ObjectApiResponse[t.Any]: """ - Get a document's source. Returns the source of a document. + .. raw:: html - ``_ +

Get a document's source.

+

Get the source of a document. + For example:

+ 
GET my-index-000001/_source/1
+
+

You can use the source filtering parameters to control which parts of the _source are returned:

+ 
GET my-index-000001/_source/1/?_source_includes=*.id&_source_excludes=entities
+
- :param index: Name of the index that contains the document. - :param id: Unique identifier of the document. - :param preference: Specifies the node or shard the operation should be performed - on. Random by default. - :param realtime: Boolean) If true, the request is real-time as opposed to near-real-time. - :param refresh: If true, Elasticsearch refreshes the affected shards to make - this operation visible to search. If false, do nothing with refreshes. - :param routing: Target the specified primary shard. - :param source: True or false to return the _source field or not, or a list of - fields to return. + + ``_ + + :param index: The name of the index that contains the document. + :param id: A unique document identifier. + :param preference: The node or shard the operation should be performed on. By + default, the operation is randomized between the shard replicas. + :param realtime: If `true`, the request is real-time as opposed to near-real-time. + :param refresh: If `true`, the request refreshes the relevant shards before retrieving + the document. Setting it to `true` should be done after careful thought and + verification that this does not cause a heavy load on the system (and slow + down indexing). + :param routing: A custom value used to route operations to a specific shard. + :param source: Indicates whether to return the `_source` field (`true` or `false`) + or lists the fields to return. :param source_excludes: A comma-separated list of source fields to exclude in the response. :param source_includes: A comma-separated list of source fields to include in the response. - :param stored_fields: - :param version: Explicit version number for concurrency control. The specified - version must match the current version of the document for the request to - succeed. - :param version_type: Specific version type: internal, external, external_gte. + :param stored_fields: A comma-separated list of stored fields to return as part + of a hit. + :param version: The version number for concurrency control. It must match the + current version of the document for the request to succeed. + :param version_type: The version type. """ if index in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'index'") @@ -1997,6 +2427,7 @@ async def index( human: t.Optional[bool] = None, if_primary_term: t.Optional[int] = None, if_seq_no: t.Optional[int] = None, + include_source_on_error: t.Optional[bool] = None, op_type: t.Optional[t.Union[str, t.Literal["create", "index"]]] = None, pipeline: t.Optional[str] = None, pretty: t.Optional[bool] = None, @@ -2015,44 +2446,148 @@ async def index( ] = None, ) -> ObjectApiResponse[t.Any]: """ - Index a document. Adds a JSON document to the specified data stream or index - and makes it searchable. If the target is an index and the document already exists, - the request updates the document and increments its version. - - ``_ - - :param index: Name of the data stream or index to target. + .. raw:: html + +

Create or update a document in an index.

+

Add a JSON document to the specified data stream or index and make it searchable. + If the target is an index and the document already exists, the request updates the document and increments its version.

+

NOTE: You cannot use this API to send update requests for existing documents in a data stream.

+

If the Elasticsearch security features are enabled, you must have the following index privileges for the target data stream, index, or index alias:

+
    +
  • To add or overwrite a document using the PUT /<target>/_doc/<_id> request format, you must have the create, index, or write index privilege.
    • +
  • To add a document using the POST /<target>/_doc/ request format, you must have the create_doc, create, index, or write index privilege.
    • +
  • To automatically create a data stream or index with this API request, you must have the auto_configure, create_index, or manage index privilege.
    • +
+

Automatic data stream creation requires a matching index template with data stream enabled.

+

NOTE: Replica shards might not all be started when an indexing operation returns successfully. + By default, only the primary is required. Set wait_for_active_shards to change this default behavior.

+

Automatically create data streams and indices

+

If the request's target doesn't exist and matches an index template with a data_stream definition, the index operation automatically creates the data stream.

+

If the target doesn't exist and doesn't match a data stream template, the operation automatically creates the index and applies any matching index templates.

+

NOTE: Elasticsearch includes several built-in index templates. To avoid naming collisions with these templates, refer to index pattern documentation.

+

If no mapping exists, the index operation creates a dynamic mapping. + By default, new fields and objects are automatically added to the mapping if needed.

+

Automatic index creation is controlled by the action.auto_create_index setting. + If it is true, any index can be created automatically. + You can modify this setting to explicitly allow or block automatic creation of indices that match specified patterns or set it to false to turn off automatic index creation entirely. + Specify a comma-separated list of patterns you want to allow or prefix each pattern with + or - to indicate whether it should be allowed or blocked. + When a list is specified, the default behaviour is to disallow.

+

NOTE: The action.auto_create_index setting affects the automatic creation of indices only. + It does not affect the creation of data streams.

+

Optimistic concurrency control

+

Index operations can be made conditional and only be performed if the last modification to the document was assigned the sequence number and primary term specified by the if_seq_no and if_primary_term parameters. + If a mismatch is detected, the operation will result in a VersionConflictException and a status code of 409.

+

Routing

+

By default, shard placement — or routing — is controlled by using a hash of the document's ID value. + For more explicit control, the value fed into the hash function used by the router can be directly specified on a per-operation basis using the routing parameter.

+

When setting up explicit mapping, you can also use the _routing field to direct the index operation to extract the routing value from the document itself. + This does come at the (very minimal) cost of an additional document parsing pass. + If the _routing mapping is defined and set to be required, the index operation will fail if no routing value is provided or extracted.

+

NOTE: Data streams do not support custom routing unless they were created with the allow_custom_routing setting enabled in the template.

+

Distributed

+

The index operation is directed to the primary shard based on its route and performed on the actual node containing this shard. + After the primary shard completes the operation, if needed, the update is distributed to applicable replicas.

+

Active shards

+

To improve the resiliency of writes to the system, indexing operations can be configured to wait for a certain number of active shard copies before proceeding with the operation. + If the requisite number of active shard copies are not available, then the write operation must wait and retry, until either the requisite shard copies have started or a timeout occurs. + By default, write operations only wait for the primary shards to be active before proceeding (that is to say wait_for_active_shards is 1). + This default can be overridden in the index settings dynamically by setting index.write.wait_for_active_shards. + To alter this behavior per operation, use the wait_for_active_shards request parameter.

+

Valid values are all or any positive integer up to the total number of configured copies per shard in the index (which is number_of_replicas+1). + Specifying a negative value or a number greater than the number of shard copies will throw an error.

+

For example, suppose you have a cluster of three nodes, A, B, and C and you create an index index with the number of replicas set to 3 (resulting in 4 shard copies, one more copy than there are nodes). + If you attempt an indexing operation, by default the operation will only ensure the primary copy of each shard is available before proceeding. + This means that even if B and C went down and A hosted the primary shard copies, the indexing operation would still proceed with only one copy of the data. + If wait_for_active_shards is set on the request to 3 (and all three nodes are up), the indexing operation will require 3 active shard copies before proceeding. + This requirement should be met because there are 3 active nodes in the cluster, each one holding a copy of the shard. + However, if you set wait_for_active_shards to all (or to 4, which is the same in this situation), the indexing operation will not proceed as you do not have all 4 copies of each shard active in the index. + The operation will timeout unless a new node is brought up in the cluster to host the fourth copy of the shard.

+

It is important to note that this setting greatly reduces the chances of the write operation not writing to the requisite number of shard copies, but it does not completely eliminate the possibility, because this check occurs before the write operation starts. + After the write operation is underway, it is still possible for replication to fail on any number of shard copies but still succeed on the primary. + The _shards section of the API response reveals the number of shard copies on which replication succeeded and failed.

+

No operation (noop) updates

+

When updating a document by using this API, a new version of the document is always created even if the document hasn't changed. + If this isn't acceptable use the _update API with detect_noop set to true. + The detect_noop option isn't available on this API because it doesn’t fetch the old source and isn't able to compare it against the new source.

+

There isn't a definitive rule for when noop updates aren't acceptable. + It's a combination of lots of factors like how frequently your data source sends updates that are actually noops and how many queries per second Elasticsearch runs on the shard receiving the updates.

+

Versioning

+

Each indexed document is given a version number. + By default, internal versioning is used that starts at 1 and increments with each update, deletes included. + Optionally, the version number can be set to an external value (for example, if maintained in a database). + To enable this functionality, version_type should be set to external. + The value provided must be a numeric, long value greater than or equal to 0, and less than around 9.2e+18.

+

NOTE: Versioning is completely real time, and is not affected by the near real time aspects of search operations. + If no version is provided, the operation runs without any version checks.

+

When using the external version type, the system checks to see if the version number passed to the index request is greater than the version of the currently stored document. + If true, the document will be indexed and the new version number used. + If the value provided is less than or equal to the stored document's version number, a version conflict will occur and the index operation will fail. For example:

+ 
PUT my-index-000001/_doc/1?version=2&version_type=external
+          {
+            "user": {
+              "id": "elkbee"
+            }
+          }
+
+          In this example, the operation will succeed since the supplied version of 2 is higher than the current document version of 1.
+          If the document was already updated and its version was set to 2 or higher, the indexing command will fail and result in a conflict (409 HTTP status code).
+
+          A nice side effect is that there is no need to maintain strict ordering of async indexing operations run as a result of changes to a source database, as long as version numbers from the source database are used.
+          Even the simple case of updating the Elasticsearch index using data from a database is simplified if external versioning is used, as only the latest version will be used if the index operations arrive out of order.
+
+ + + ``_ + + :param index: The name of the data stream or index to target. If the target doesn't + exist and matches the name or wildcard (`*`) pattern of an index template + with a `data_stream` definition, this request creates the data stream. If + the target doesn't exist and doesn't match a data stream template, this request + creates the index. You can check for existing targets with the resolve index + API. :param document: - :param id: Unique identifier for the document. + :param id: A unique identifier for the document. To automatically generate a + document ID, use the `POST //_doc/` request format and omit this + parameter. :param if_primary_term: Only perform the operation if the document has this primary term. :param if_seq_no: Only perform the operation if the document has this sequence number. - :param op_type: Set to create to only index the document if it does not already + :param include_source_on_error: True or false if to include the document source + in the error message in case of parsing errors. + :param op_type: Set to `create` to only index the document if it does not already exist (put if absent). If a document with the specified `_id` already exists, - the indexing operation will fail. Same as using the `/_create` endpoint. - Valid values: `index`, `create`. If document id is specified, it defaults - to `index`. Otherwise, it defaults to `create`. - :param pipeline: ID of the pipeline to use to preprocess incoming documents. + the indexing operation will fail. The behavior is the same as using the `/_create` + endpoint. If a document ID is specified, this paramater defaults to `index`. + Otherwise, it defaults to `create`. If the request targets a data stream, + an `op_type` of `create` is required. + :param pipeline: The ID of the pipeline to use to preprocess incoming documents. If the index has a default ingest pipeline specified, then setting the value to `_none` disables the default ingest pipeline for this request. If a final pipeline is configured it will always run, regardless of the value of this parameter. :param refresh: If `true`, Elasticsearch refreshes the affected shards to make - this operation visible to search, if `wait_for` then wait for a refresh to - make this operation visible to search, if `false` do nothing with refreshes. - Valid values: `true`, `false`, `wait_for`. + this operation visible to search. If `wait_for`, it waits for a refresh to + make this operation visible to search. If `false`, it does nothing with refreshes. :param require_alias: If `true`, the destination must be an index alias. - :param routing: Custom value used to route operations to a specific shard. - :param timeout: Period the request waits for the following operations: automatic - index creation, dynamic mapping updates, waiting for active shards. - :param version: Explicit version number for concurrency control. The specified - version must match the current version of the document for the request to - succeed. - :param version_type: Specific version type: `external`, `external_gte`. + :param routing: A custom value that is used to route operations to a specific + shard. + :param timeout: The period the request waits for the following operations: automatic + index creation, dynamic mapping updates, waiting for active shards. This + parameter is useful for situations where the primary shard assigned to perform + the operation might not be available when the operation runs. Some reasons + for this might be that the primary shard is currently recovering from a gateway + or undergoing relocation. By default, the operation will wait on the primary + shard to become available for at least 1 minute before failing and responding + with an error. The actual wait time could be longer, particularly when multiple + waits occur. + :param version: An explicit version number for concurrency control. It must be + a non-negative long number. + :param version_type: The version type. :param wait_for_active_shards: The number of shard copies that must be active - before proceeding with the operation. Set to all or any positive integer - up to the total number of shards in the index (`number_of_replicas+1`). + before proceeding with the operation. You can set it to `all` or any positive + integer up to the total number of shards in the index (`number_of_replicas+1`). + The default value of `1` means it waits for each primary shard to be active. """ if index in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'index'") @@ -2084,6 +2619,8 @@ async def index( __query["if_primary_term"] = if_primary_term if if_seq_no is not None: __query["if_seq_no"] = if_seq_no + if include_source_on_error is not None: + __query["include_source_on_error"] = include_source_on_error if op_type is not None: __query["op_type"] = op_type if pipeline is not None: @@ -2126,9 +2663,13 @@ async def info( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Get cluster info. Get basic build, version, and cluster information. + .. raw:: html + +

Get cluster info. + Get basic build, version, and cluster information.

- ``_ + + ``_ """ __path_parts: t.Dict[str, str] = {} __path = "/" @@ -2181,12 +2722,23 @@ async def mget( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Get multiple documents. Get multiple JSON documents by ID from one or more indices. - If you specify an index in the request URI, you only need to specify the document - IDs in the request body. To ensure fast responses, this multi get (mget) API - responds with partial results if one or more shards fail. + .. raw:: html + +

Get multiple documents.

+

Get multiple JSON documents by ID from one or more indices. + If you specify an index in the request URI, you only need to specify the document IDs in the request body. + To ensure fast responses, this multi get (mget) API responds with partial results if one or more shards fail.

+

Filter source fields

+

By default, the _source field is returned for every document (if stored). + Use the _source and _source_include or source_exclude attributes to filter what fields are returned for a particular document. + You can include the _source, _source_includes, and _source_excludes query parameters in the request URI to specify the defaults to use when there are no per-document instructions.

+

Get stored fields

+

Use the stored_fields attribute to specify the set of stored fields you want to retrieve. + Any requested fields that are not stored are ignored. + You can include the stored_fields query parameter in the request URI to specify the defaults to use when there are no per-document instructions.

- ``_ + + ``_ :param index: Name of the index to retrieve documents from when `ids` are specified, or when a document in the `docs` array does not specify an index. @@ -2305,15 +2857,23 @@ async def msearch( typed_keys: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Run multiple searches. The format of the request is similar to the bulk API format - and makes use of the newline delimited JSON (NDJSON) format. The structure is - as follows: ``` header\\n body\\n header\\n body\\n ``` This structure is specifically - optimized to reduce parsing if a specific search ends up redirected to another - node. IMPORTANT: The final line of data must end with a newline character `\\n`. - Each newline character may be preceded by a carriage return `\\r`. When sending - requests to this endpoint the `Content-Type` header should be set to `application/x-ndjson`. + .. raw:: html + +

Run multiple searches.

+

The format of the request is similar to the bulk API format and makes use of the newline delimited JSON (NDJSON) format. + The structure is as follows:

+ 
header\\n
+          body\\n
+          header\\n
+          body\\n
+
+

This structure is specifically optimized to reduce parsing if a specific search ends up redirected to another node.

+

IMPORTANT: The final line of data must end with a newline character \\n. + Each newline character may be preceded by a carriage return \\r. + When sending requests to this endpoint the Content-Type header should be set to application/x-ndjson.

- ``_ + + ``_ :param searches: :param index: Comma-separated list of data streams, indices, and index aliases @@ -2443,22 +3003,35 @@ async def msearch_template( typed_keys: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Run multiple templated searches. + .. raw:: html + +

Run multiple templated searches.

+

Run multiple templated searches with a single request. + If you are providing a text file or text input to curl, use the --data-binary flag instead of -d to preserve newlines. + For example:

+ 
$ cat requests
+          { "index": "my-index" }
+          { "id": "my-search-template", "params": { "query_string": "hello world", "from": 0, "size": 10 }}
+          { "index": "my-other-index" }
+          { "id": "my-other-search-template", "params": { "query_type": "match_all" }}
 
-        ``_
+          $ curl -H "Content-Type: application/x-ndjson" -XGET localhost:9200/_msearch/template --data-binary "@requests"; echo
+
+ + + ``_ :param search_templates: - :param index: Comma-separated list of data streams, indices, and aliases to search. - Supports wildcards (`*`). To search all data streams and indices, omit this - parameter or use `*`. + :param index: A comma-separated list of data streams, indices, and aliases to + search. It supports wildcards (`*`). To search all data streams and indices, + omit this parameter or use `*`. :param ccs_minimize_roundtrips: If `true`, network round-trips are minimized for cross-cluster search requests. - :param max_concurrent_searches: Maximum number of concurrent searches the API - can run. + :param max_concurrent_searches: The maximum number of concurrent searches the + API can run. :param rest_total_hits_as_int: If `true`, the response returns `hits.total` as an integer. If `false`, it returns `hits.total` as an object. - :param search_type: The type of the search operation. Available options: `query_then_fetch`, - `dfs_query_then_fetch`. + :param search_type: The type of the search operation. :param typed_keys: If `true`, the response prefixes aggregation and suggester names with their respective types. """ @@ -2538,34 +3111,41 @@ async def mtermvectors( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Get multiple term vectors. You can specify existing documents by index and ID - or provide artificial documents in the body of the request. You can specify the - index in the request body or request URI. The response contains a `docs` array - with all the fetched termvectors. Each element has the structure provided by - the termvectors API. + .. raw:: html + +

Get multiple term vectors.

+

Get multiple term vectors with a single request. + You can specify existing documents by index and ID or provide artificial documents in the body of the request. + You can specify the index in the request body or request URI. + The response contains a docs array with all the fetched termvectors. + Each element has the structure provided by the termvectors API.

+

Artificial documents

+

You can also use mtermvectors to generate term vectors for artificial documents provided in the body of the request. + The mapping used is determined by the specified _index.

- ``_ - :param index: Name of the index that contains the documents. - :param docs: Array of existing or artificial documents. + ``_ + + :param index: The name of the index that contains the documents. + :param docs: An array of existing or artificial documents. :param field_statistics: If `true`, the response includes the document count, sum of document frequencies, and sum of total term frequencies. - :param fields: Comma-separated list or wildcard expressions of fields to include - in the statistics. Used as the default list unless a specific field list - is provided in the `completion_fields` or `fielddata_fields` parameters. - :param ids: Simplified syntax to specify documents by their ID if they're in + :param fields: A comma-separated list or wildcard expressions of fields to include + in the statistics. It is used as the default list unless a specific field + list is provided in the `completion_fields` or `fielddata_fields` parameters. + :param ids: A simplified syntax to specify documents by their ID if they're in the same index. :param offsets: If `true`, the response includes term offsets. :param payloads: If `true`, the response includes term payloads. :param positions: If `true`, the response includes term positions. - :param preference: Specifies the node or shard the operation should be performed - on. Random by default. + :param preference: The node or shard the operation should be performed on. It + is random by default. :param realtime: If true, the request is real-time as opposed to near-real-time. - :param routing: Custom value used to route operations to a specific shard. + :param routing: A custom value used to route operations to a specific shard. :param term_statistics: If true, the response includes term frequency and document frequency. :param version: If `true`, returns the document version as part of a hit. - :param version_type: Specific version type. + :param version_type: The version type. """ __path_parts: t.Dict[str, str] if index not in SKIP_IN_PATH: @@ -2654,36 +3234,59 @@ async def open_point_in_time( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - 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. - - ``_ + .. raw:: html + +

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.

+

A subsequent search request with the pit parameter must not specify index, routing, or preference values as these parameters are copied from the point in time.

+

Just like regular searches, you can use from and size to page through point in time search results, up to the first 10,000 hits. + If you want to retrieve more hits, use PIT with search_after.

+

IMPORTANT: The open point in time request and each subsequent search request can return different identifiers; always use the most recently received ID for the next search request.

+

When a PIT that contains shard failures is used in a search request, the missing are always reported in the search response as a NoShardAvailableActionException exception. + To get rid of these exceptions, a new PIT needs to be created so that shards missing from the previous PIT can be handled, assuming they become available in the meantime.

+

Keeping point in time alive

+

The keep_alive parameter, which is passed to a open point in time request and search request, extends the time to live of the corresponding point in time. + The value does not need to be long enough to process all data — it just needs to be long enough for the next request.

+

Normally, the background merge process optimizes the index by merging together smaller segments to create new, bigger segments. + Once the smaller segments are no longer needed they are deleted. + However, open point-in-times prevent the old segments from being deleted since they are still in use.

+

TIP: Keeping older segments alive means that more disk space and file handles are needed. + Ensure that you have configured your nodes to have ample free file handles.

+

Additionally, if a segment contains deleted or updated documents then the point in time must keep track of whether each document in the segment was live at the time of the initial search request. + Ensure that your nodes have sufficient heap space if you have many open point-in-times on an index that is subject to ongoing deletes or updates. + Note that a point-in-time doesn't prevent its associated indices from being deleted. + You can check how many point-in-times (that is, search contexts) are open with the nodes stats API.

+ + + ``_ :param index: A comma-separated list of index names to open point in time; use `_all` or empty string to perform the operation on all indices - :param keep_alive: Extends the time to live of the corresponding point in time. - :param allow_partial_search_results: If `false`, creating a point in time request - when a shard is missing or unavailable will throw an exception. If `true`, - the point in time will contain all the shards that are available at the time - of the request. - :param expand_wildcards: Type of index that wildcard patterns can match. If the - request can target data streams, this argument determines whether wildcard - expressions match hidden data streams. Supports comma-separated values, such - as `open,hidden`. Valid values are: `all`, `open`, `closed`, `hidden`, `none`. + :param keep_alive: Extend the length of time that the point in time persists. + :param allow_partial_search_results: Indicates whether the point in time tolerates + unavailable shards or shard failures when initially creating the PIT. If + `false`, creating a point in time request when a shard is missing or unavailable + will throw an exception. If `true`, the point in time will contain all the + shards that are available at the time of the request. + :param expand_wildcards: The type of index that wildcard patterns can match. + If the request can target data streams, this argument determines whether + wildcard expressions match hidden data streams. It supports comma-separated + values, such as `open,hidden`. Valid values are: `all`, `open`, `closed`, + `hidden`, `none`. :param ignore_unavailable: If `false`, the request returns an error if it targets a missing or closed index. - :param index_filter: Allows to filter indices if the provided query rewrites - to `match_none` on every shard. - :param preference: Specifies the node or shard the operation should be performed - on. Random by default. - :param routing: Custom value used to route operations to a specific shard. + :param index_filter: Filter indices if the provided query rewrites to `match_none` + on every shard. + :param preference: The node or shard the operation should be performed on. By + default, it is random. + :param routing: A custom value that is used to route operations to a specific + shard. """ if index in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'index'") @@ -2749,23 +3352,27 @@ async def put_script( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Create or update a script or search template. Creates or updates a stored script - or search template. - - ``_ - - :param id: Identifier for the stored script or search template. Must be unique - within the cluster. - :param script: Contains the script or search template, its parameters, and its - language. - :param context: Context in which the script or search template should run. To - prevent errors, the API immediately compiles the script or template in this - context. - :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 timeout: Period to wait for a response. If no response is received before - the timeout expires, the request fails and returns an error. + .. raw:: html + +

Create or update a script or search template. + Creates or updates a stored script or search template.

+ + + ``_ + + :param id: The identifier for the stored script or search template. It must be + unique within the cluster. + :param script: The script or search template, its parameters, and its language. + :param context: The context in which the script or search template should run. + To prevent errors, the API immediately compiles the script or template in + this context. + :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. It can also be set to `-1` to indicate that the request + should never timeout. + :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. It can + also be set to `-1` to indicate that the request should never timeout. """ if id in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'id'") @@ -2835,14 +3442,17 @@ async def rank_eval( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Evaluate ranked search results. Evaluate the quality of ranked search results - over a set of typical search queries. + .. raw:: html - ``_ +

Evaluate ranked search results.

+

Evaluate the quality of ranked search results over a set of typical search queries.

+ + + ``_ :param requests: A set of typical search requests, together with their provided ratings. - :param index: Comma-separated list of data streams, indices, and index aliases + :param index: A comma-separated list of data streams, indices, and index aliases used to limit the request. Wildcard (`*`) expressions are supported. To target all data streams and indices in a cluster, omit this parameter or use `_all` or `*`. @@ -2930,33 +3540,187 @@ async def reindex( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Reindex documents. Copies documents from a source to a destination. The source - can be any existing index, alias, or data stream. The destination must differ - from the source. For example, you cannot reindex a data stream into itself. - - ``_ + .. raw:: html + +

Reindex documents.

+

Copy documents from a source to a destination. + You can copy all documents to the destination index or reindex a subset of the documents. + The source can be any existing index, alias, or data stream. + The destination must differ from the source. + For example, you cannot reindex a data stream into itself.

+

IMPORTANT: Reindex requires _source to be enabled for all documents in the source. + The destination should be configured as wanted before calling the reindex API. + Reindex does not copy the settings from the source or its associated template. + Mappings, shard counts, and replicas, for example, must be configured ahead of time.

+

If the Elasticsearch security features are enabled, you must have the following security privileges:

+
    +
  • The read index privilege for the source data stream, index, or alias.
    • +
  • The write index privilege for the destination data stream, index, or index alias.
    • +
  • To automatically create a data stream or index with a reindex API request, you must have the auto_configure, create_index, or manage index privilege for the destination data stream, index, or alias.
    • +
  • If reindexing from a remote cluster, the source.remote.user must have the monitor cluster privilege and the read index privilege for the source data stream, index, or alias.
    • +
+

If reindexing from a remote cluster, you must explicitly allow the remote host in the reindex.remote.whitelist setting. + Automatic data stream creation requires a matching index template with data stream enabled.

+

The dest element can be configured like the index API to control optimistic concurrency control. + Omitting version_type or setting it to internal causes Elasticsearch to blindly dump documents into the destination, overwriting any that happen to have the same ID.

+

Setting version_type to external causes Elasticsearch to preserve the version from the source, create any documents that are missing, and update any documents that have an older version in the destination than they do in the source.

+

Setting op_type to create causes the reindex API to create only missing documents in the destination. + All existing documents will cause a version conflict.

+

IMPORTANT: Because data streams are append-only, any reindex request to a destination data stream must have an op_type of create. + A reindex can only add new documents to a destination data stream. + It cannot update existing documents in a destination data stream.

+

By default, version conflicts abort the reindex process. + To continue reindexing if there are conflicts, set the conflicts request body property to proceed. + In this case, the response includes a count of the version conflicts that were encountered. + Note that the handling of other error types is unaffected by the conflicts property. + Additionally, if you opt to count version conflicts, the operation could attempt to reindex more documents from the source than max_docs until it has successfully indexed max_docs documents into the target or it has gone through every document in the source query.

+

NOTE: The reindex API makes no effort to handle ID collisions. + The last document written will "win" but the order isn't usually predictable so it is not a good idea to rely on this behavior. + Instead, make sure that IDs are unique by using a script.

+

Running reindex asynchronously

+

If the request contains wait_for_completion=false, Elasticsearch performs some preflight checks, launches the request, and returns a task you can use to cancel or get the status of the task. + Elasticsearch creates a record of this task as a document at _tasks/<task_id>.

+

Reindex from multiple sources

+

If you have many sources to reindex it is generally better to reindex them one at a time rather than using a glob pattern to pick up multiple sources. + That way you can resume the process if there are any errors by removing the partially completed source and starting over. + It also makes parallelizing the process fairly simple: split the list of sources to reindex and run each list in parallel.

+

For example, you can use a bash script like this:

+ 
for index in i1 i2 i3 i4 i5; do
+            curl -HContent-Type:application/json -XPOST localhost:9200/_reindex?pretty -d'{
+              "source": {
+                "index": "'$index'"
+              },
+              "dest": {
+                "index": "'$index'-reindexed"
+              }
+            }'
+          done
+
+

Throttling

+

Set requests_per_second to any positive decimal number (1.4, 6, 1000, for example) to throttle the rate at which reindex issues batches of index operations. + Requests are throttled by padding each batch with a wait time. + To turn off throttling, set requests_per_second to -1.

+

The throttling is done by waiting between batches so that the scroll that reindex uses internally can be given a timeout that takes into account the padding. + The padding time is the difference between the batch size divided by the requests_per_second and the time spent writing. + By default the batch size is 1000, so if requests_per_second is set to 500:

+ 
target_time = 1000 / 500 per second = 2 seconds
+          wait_time = target_time - write_time = 2 seconds - .5 seconds = 1.5 seconds
+
+

Since the batch is issued as a single bulk request, large batch sizes cause Elasticsearch to create many requests and then wait for a while before starting the next set. + This is "bursty" instead of "smooth".

+

Slicing

+

Reindex supports sliced scroll to parallelize the reindexing process. + This parallelization can improve efficiency and provide a convenient way to break the request down into smaller parts.

+

NOTE: Reindexing from remote clusters does not support manual or automatic slicing.

+

You can slice a reindex request manually by providing a slice ID and total number of slices to each request. + You can also let reindex automatically parallelize by using sliced scroll to slice on _id. + The slices parameter specifies the number of slices to use.

+

Adding slices to the reindex request just automates the manual process, creating sub-requests which means it has some quirks:

+
    +
  • You can see these requests in the tasks API. These sub-requests are "child" tasks of the task for the request with slices.
    • +
  • Fetching the status of the task for the request with slices only contains the status of completed slices.
    • +
  • These sub-requests are individually addressable for things like cancellation and rethrottling.
    • +
  • Rethrottling the request with slices will rethrottle the unfinished sub-request proportionally.
    • +
  • Canceling the request with slices will cancel each sub-request.
    • +
  • Due to the nature of slices, each sub-request won't get a perfectly even portion of the documents. All documents will be addressed, but some slices may be larger than others. Expect larger slices to have a more even distribution.
    • +
  • Parameters like requests_per_second and max_docs on a request with slices are distributed proportionally to each sub-request. Combine that with the previous point about distribution being uneven and you should conclude that using max_docs with slices might not result in exactly max_docs documents being reindexed.
    • +
  • Each sub-request gets a slightly different snapshot of the source, though these are all taken at approximately the same time.
    • +
+

If slicing automatically, setting slices to auto will choose a reasonable number for most indices. + If slicing manually or otherwise tuning automatic slicing, use the following guidelines.

+

Query performance is most efficient when the number of slices is equal to the number of shards in the index. + If that number is large (for example, 500), choose a lower number as too many slices will hurt performance. + Setting slices higher than the number of shards generally does not improve efficiency and adds overhead.

+

Indexing performance scales linearly across available resources with the number of slices.

+

Whether query or indexing performance dominates the runtime depends on the documents being reindexed and cluster resources.

+

Modify documents during reindexing

+

Like _update_by_query, reindex operations support a script that modifies the document. + Unlike _update_by_query, the script is allowed to modify the document's metadata.

+

Just as in _update_by_query, you can set ctx.op to change the operation that is run on the destination. + For example, set ctx.op to noop if your script decides that the document doesn’t have to be indexed in the destination. This "no operation" will be reported in the noop counter in the response body. + Set ctx.op to delete if your script decides that the document must be deleted from the destination. + The deletion will be reported in the deleted counter in the response body. + Setting ctx.op to anything else will return an error, as will setting any other field in ctx.

+

Think of the possibilities! Just be careful; you are able to change:

+
    +
  • _id
    • +
  • _index
    • +
  • _version
    • +
  • _routing
    • +
+

Setting _version to null or clearing it from the ctx map is just like not sending the version in an indexing request. + It will cause the document to be overwritten in the destination regardless of the version on the target or the version type you use in the reindex API.

+

Reindex from remote

+

Reindex supports reindexing from a remote Elasticsearch cluster. + The host parameter must contain a scheme, host, port, and optional path. + The username and password parameters are optional and when they are present the reindex operation will connect to the remote Elasticsearch node using basic authentication. + Be sure to use HTTPS when using basic authentication or the password will be sent in plain text. + There are a range of settings available to configure the behavior of the HTTPS connection.

+

When using Elastic Cloud, it is also possible to authenticate against the remote cluster through the use of a valid API key. + Remote hosts must be explicitly allowed with the reindex.remote.whitelist setting. + It can be set to a comma delimited list of allowed remote host and port combinations. + Scheme is ignored; only the host and port are used. + For example:

+ 
reindex.remote.whitelist: [otherhost:9200, another:9200, 127.0.10.*:9200, localhost:*"]
+
+

The list of allowed hosts must be configured on any nodes that will coordinate the reindex. + This feature should work with remote clusters of any version of Elasticsearch. + This should enable you to upgrade from any version of Elasticsearch to the current version by reindexing from a cluster of the old version.

+

WARNING: Elasticsearch does not support forward compatibility across major versions. + For example, you cannot reindex from a 7.x cluster into a 6.x cluster.

+

To enable queries sent to older versions of Elasticsearch, the query parameter is sent directly to the remote host without validation or modification.

+

NOTE: Reindexing from remote clusters does not support manual or automatic slicing.

+

Reindexing from a remote server uses an on-heap buffer that defaults to a maximum size of 100mb. + If the remote index includes very large documents you'll need to use a smaller batch size. + It is also possible to set the socket read timeout on the remote connection with the socket_timeout field and the connection timeout with the connect_timeout field. + Both default to 30 seconds.

+

Configuring SSL parameters

+

Reindex from remote supports configurable SSL settings. + These must be specified in the elasticsearch.yml file, with the exception of the secure settings, which you add in the Elasticsearch keystore. + It is not possible to configure SSL in the body of the reindex request.

+ + + ``_ :param dest: The destination you are copying to. :param source: The source you are copying from. - :param conflicts: Set to proceed to continue reindexing even if there are conflicts. - :param max_docs: The maximum number of documents to reindex. + :param conflicts: Indicates whether to continue reindexing even when there are + conflicts. + :param max_docs: The maximum number of documents to reindex. By default, all + documents are reindexed. If it is a value less then or equal to `scroll_size`, + a scroll will not be used to retrieve the results for the operation. If `conflicts` + is set to `proceed`, the reindex operation could attempt to reindex more + documents from the source than `max_docs` until it has successfully indexed + `max_docs` documents into the target or it has gone through every document + in the source query. :param refresh: If `true`, the request refreshes affected shards to make this operation visible to search. :param requests_per_second: The throttle for this request in sub-requests per - second. Defaults to no throttle. + second. By default, there is no throttle. :param require_alias: If `true`, the destination must be an index alias. :param script: The script to run to update the document source or metadata when reindexing. - :param scroll: Specifies how long a consistent view of the index should be maintained - for scrolled search. + :param scroll: The period of time that a consistent view of the index should + be maintained for scrolled search. :param size: - :param slices: The number of slices this task should be divided into. Defaults - to 1 slice, meaning the task isn’t sliced into subtasks. - :param timeout: Period each indexing waits for automatic index creation, dynamic - mapping updates, and waiting for active shards. + :param slices: The number of slices this task should be divided into. It defaults + to one slice, which means the task isn't sliced into subtasks. Reindex supports + sliced scroll to parallelize the reindexing process. This parallelization + can improve efficiency and provide a convenient way to break the request + down into smaller parts. NOTE: Reindexing from remote clusters does not support + manual or automatic slicing. If set to `auto`, Elasticsearch chooses the + number of slices to use. This setting will use one slice per shard, up to + a certain limit. If there are multiple sources, it will choose the number + of slices based on the index or backing index with the smallest number of + shards. + :param timeout: The period each indexing waits for automatic index creation, + dynamic mapping updates, and waiting for active shards. By default, Elasticsearch + waits for at least one minute before failing. The actual wait time could + be longer, particularly when multiple waits occur. :param wait_for_active_shards: The number of shard copies that must be active - before proceeding with the operation. Set to `all` or any positive integer - up to the total number of shards in the index (`number_of_replicas+1`). + before proceeding with the operation. Set it to `all` or any positive integer + up to the total number of shards in the index (`number_of_replicas+1`). The + default value is one, which means it waits for each primary shard to be active. :param wait_for_completion: If `true`, the request blocks until the operation is complete. """ @@ -3034,17 +3798,21 @@ async def render_search_template( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Render a search template. Render a search template as a search request body. + .. raw:: html + +

Render a search template.

+

Render a search template as a search request body.

- ``_ - :param id: ID of the search template to render. If no `source` is specified, + ``_ + + :param id: The ID of the search template to render. If no `source` is specified, this or the `id` request body parameter is required. :param file: :param params: Key-value pairs used to replace Mustache variables in the template. The key is the variable name. The value is the variable value. - :param source: An inline search template. Supports the same parameters as the - search API's request body. These parameters also support Mustache variables. + :param source: An inline search template. It supports the same parameters as + the search API's request body. These parameters also support Mustache variables. If no `id` or `` is specified, this parameter is required. """ __path_parts: t.Dict[str, str] @@ -3093,7 +3861,24 @@ async def render_search_template( async def scripts_painless_execute( self, *, - context: t.Optional[str] = None, + context: t.Optional[ + t.Union[ + str, + t.Literal[ + "boolean_field", + "composite_field", + "date_field", + "double_field", + "filter", + "geo_point_field", + "ip_field", + "keyword_field", + "long_field", + "painless_test", + "score", + ], + ] + ] = None, context_setup: t.Optional[t.Mapping[str, t.Any]] = None, error_trace: t.Optional[bool] = None, filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, @@ -3103,13 +3888,24 @@ async def scripts_painless_execute( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Run a script. Runs a script and returns a result. + .. raw:: html + +

Run a script.

+

Runs a script and returns a result. + Use this API to build and test scripts, such as when defining a script for a runtime field. + This API requires very few dependencies and is especially useful if you don't have permissions to write documents on a cluster.

+

The API uses several contexts, which control how scripts are run, what variables are available at runtime, and what the return type is.

+

Each context requires a script, but additional parameters depend on the context you're using for that script.

+ ``_ - :param context: The context that the script should run in. - :param context_setup: Additional parameters for the `context`. - :param script: The Painless script to execute. + :param context: The context that the script should run in. NOTE: Result ordering + in the field contexts is not guaranteed. + :param context_setup: Additional parameters for the `context`. NOTE: This parameter + is required for all contexts except `painless_test`, which is the default + if no value is provided for `context`. + :param script: The Painless script to run. """ __path_parts: t.Dict[str, str] = {} __path = "/_scripts/painless/_execute" @@ -3161,30 +3957,27 @@ async def scroll( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Run a scrolling search. IMPORTANT: The scroll API is no longer recommend for - deep pagination. If you need to preserve the index state while paging through - more than 10,000 hits, use the `search_after` parameter with a point in time - (PIT). The scroll API gets large sets of results from a single scrolling search - request. To get the necessary scroll ID, submit a search API request that includes - an argument for the `scroll` query parameter. The `scroll` parameter indicates - how long Elasticsearch should retain the search context for the request. The - search response returns a scroll ID in the `_scroll_id` response body parameter. - You can then use the scroll ID with the scroll API to retrieve the next batch - of results for the request. If the Elasticsearch security features are enabled, - the access to the results of a specific scroll ID is restricted to the user or - API key that submitted the search. You can also use the scroll API to specify - a new scroll parameter that extends or shortens the retention period for the - search context. IMPORTANT: Results from a scrolling search reflect the state - of the index at the time of the initial search request. Subsequent indexing or - document changes only affect later search and scroll requests. - - ``_ - - :param scroll_id: Scroll ID of the search. + .. raw:: html + +

Run a scrolling search.

+

IMPORTANT: The scroll API is no longer recommend for deep pagination. If you need to preserve the index state while paging through more than 10,000 hits, use the search_after parameter with a point in time (PIT).

+

The scroll API gets large sets of results from a single scrolling search request. + To get the necessary scroll ID, submit a search API request that includes an argument for the scroll query parameter. + The scroll parameter indicates how long Elasticsearch should retain the search context for the request. + The search response returns a scroll ID in the _scroll_id response body parameter. + You can then use the scroll ID with the scroll API to retrieve the next batch of results for the request. + If the Elasticsearch security features are enabled, the access to the results of a specific scroll ID is restricted to the user or API key that submitted the search.

+

You can also use the scroll API to specify a new scroll parameter that extends or shortens the retention period for the search context.

+

IMPORTANT: Results from a scrolling search reflect the state of the index at the time of the initial search request. Subsequent indexing or document changes only affect later search and scroll requests.

+ + + ``_ + + :param scroll_id: The scroll ID of the search. :param rest_total_hits_as_int: If true, the API response’s hit.total property is returned as an integer. If false, the API response’s hit.total property is returned as an object. - :param scroll: Period to retain the search context for scrolling. + :param scroll: The period to retain the search context for scrolling. """ if scroll_id is None and body is None: raise ValueError("Empty value passed for parameter 'scroll_id'") @@ -3330,7 +4123,7 @@ async def search( script_fields: t.Optional[t.Mapping[str, t.Mapping[str, t.Any]]] = None, scroll: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, search_after: t.Optional[ - t.Sequence[t.Union[None, bool, float, int, str, t.Any]] + t.Sequence[t.Union[None, bool, float, int, str]] ] = None, search_type: t.Optional[ t.Union[str, t.Literal["dfs_query_then_fetch", "query_then_fetch"]] @@ -3365,15 +4158,29 @@ async def search( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - 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. - - ``_ - - :param index: Comma-separated list of data streams, indices, and aliases to search. - Supports wildcards (`*`). To search all data streams and indices, omit this - parameter or use `*` or `_all`. + .. raw:: html + +

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.

+

If the Elasticsearch security features are enabled, you must have the read index privilege for the target data stream, index, or alias. For cross-cluster search, refer to the documentation about configuring CCS privileges. + To search a point in time (PIT) for an alias, you must have the read index privilege for the alias's data streams or indices.

+

Search slicing

+

When paging through a large number of documents, it can be helpful to split the search into multiple slices to consume them independently with the slice and pit properties. + By default the splitting is done first on the shards, then locally on each shard. + The local splitting partitions the shard into contiguous ranges based on Lucene document IDs.

+

For instance if the number of shards is equal to 2 and you request 4 slices, the slices 0 and 2 are assigned to the first shard and the slices 1 and 3 are assigned to the second shard.

+

IMPORTANT: The same point-in-time ID should be used for all slices. + If different PIT IDs are used, slices can overlap and miss documents. + This situation can occur because the splitting criterion is based on Lucene document IDs, which are not stable across changes to the index.

+ + + ``_ + + :param index: A comma-separated list of data streams, indices, and aliases to + search. It supports wildcards (`*`). To search all data streams and indices, + omit this parameter or use `*` or `_all`. :param aggregations: Defines the aggregations that are run as part of the search request. :param aggs: Defines the aggregations that are run as part of the search request. @@ -3382,45 +4189,46 @@ async def search( This behavior applies even if the request targets other open indices. For example, a request targeting `foo*,bar*` returns an error if an index starts with `foo` but no index starts with `bar`. - :param allow_partial_search_results: If true, returns partial results if there - are shard request timeouts or shard failures. If false, returns an error - with no partial results. - :param analyze_wildcard: If true, wildcard and prefix queries are analyzed. This - parameter can only be used when the q query string parameter is specified. - :param analyzer: Analyzer to use for the query string. This parameter can only - be used when the q query string parameter is specified. + :param allow_partial_search_results: If `true` and there are shard request timeouts + or shard failures, the request returns partial results. If `false`, it returns + an error with no partial results. To override the default behavior, you can + set the `search.default_allow_partial_results` cluster setting to `false`. + :param analyze_wildcard: If `true`, wildcard and prefix queries are analyzed. + This parameter can be used only when the `q` query string parameter is specified. + :param analyzer: The analyzer to use for the query string. This parameter can + be used only when the `q` query string parameter is specified. :param batched_reduce_size: The number of shard results that should be reduced - at once on the coordinating node. This value should be used as a protection - mechanism to reduce the memory overhead per search request if the potential - number of shards in the request can be large. - :param ccs_minimize_roundtrips: If true, network round-trips between the coordinating - node and the remote clusters are minimized when executing cross-cluster search + at once on the coordinating node. If the potential number of shards in the + request can be large, this value should be used as a protection mechanism + to reduce the memory overhead per search request. + :param ccs_minimize_roundtrips: If `true`, network round-trips between the coordinating + node and the remote clusters are minimized when running cross-cluster search (CCS) requests. :param collapse: Collapses search results the values of the specified field. - :param default_operator: The default operator for query string query: AND or - OR. This parameter can only be used when the `q` query string parameter is - specified. - :param df: Field to use as default where no field prefix is given in the query - string. This parameter can only be used when the q query string parameter + :param default_operator: The default operator for the query string query: `AND` + or `OR`. This parameter can be used only when the `q` query string parameter is specified. - :param docvalue_fields: Array of wildcard (`*`) patterns. The request returns - doc values for field names matching these patterns in the `hits.fields` property - of the response. - :param expand_wildcards: Type of index that wildcard patterns can match. If the - request can target data streams, this argument determines whether wildcard - expressions match hidden data streams. Supports comma-separated values, such - as `open,hidden`. - :param explain: If true, returns detailed information about score computation - as part of a hit. + :param df: The field to use as a default when no field prefix is given in the + query string. This parameter can be used only when the `q` query string parameter + is specified. + :param docvalue_fields: An array of wildcard (`*`) field patterns. The request + returns doc values for field names matching these patterns in the `hits.fields` + property of the response. + :param expand_wildcards: The type of index that wildcard patterns can match. + If the request can target data streams, this argument determines whether + wildcard expressions match hidden data streams. It supports comma-separated + values such as `open,hidden`. + :param explain: If `true`, the request returns detailed information about score + computation as part of a hit. :param ext: Configuration of search extensions defined by Elasticsearch plugins. - :param fields: Array of wildcard (`*`) patterns. The request returns values for - field names matching these patterns in the `hits.fields` property of the - response. + :param fields: An array of wildcard (`*`) field patterns. The request returns + values for field names matching these patterns in the `hits.fields` property + of the response. :param force_synthetic_source: Should this request force synthetic _source? Use this to test if the mapping supports synthetic _source and to get a sense of the worst case performance. Fetches with this enabled will be slower the enabling synthetic source natively in the index. - :param from_: Starting document offset. Needs to be non-negative. By default, + :param from_: The starting document offset, which must be non-negative. By default, you cannot page through more than 10,000 hits using the `from` and `size` parameters. To page through more hits, use the `search_after` parameter. :param highlight: Specifies the highlighter to use for retrieving highlighted @@ -3429,93 +4237,100 @@ async def search( be ignored when frozen. :param ignore_unavailable: If `false`, the request returns an error if it targets a missing or closed index. - :param include_named_queries_score: Indicates whether hit.matched_queries should - be rendered as a map that includes the name of the matched query associated - with its score (true) or as an array containing the name of the matched queries - (false) This functionality reruns each named query on every hit in a search - response. Typically, this adds a small overhead to a request. However, using - computationally expensive named queries on a large number of hits may add - significant overhead. - :param indices_boost: Boosts the _score of documents from specified indices. - :param knn: Defines the approximate kNN search to run. + :param include_named_queries_score: If `true`, the response includes the score + contribution from any named queries. This functionality reruns each named + query on every hit in a search response. Typically, this adds a small overhead + to a request. However, using computationally expensive named queries on a + large number of hits may add significant overhead. + :param indices_boost: Boost the `_score` of documents from specified indices. + The boost value is the factor by which scores are multiplied. A boost value + greater than `1.0` increases the score. A boost value between `0` and `1.0` + decreases the score. + :param knn: The approximate kNN search to run. :param lenient: If `true`, format-based query failures (such as providing text to a numeric field) in the query string will be ignored. This parameter can - only be used when the `q` query string parameter is specified. - :param max_concurrent_shard_requests: Defines the number of concurrent shard - requests per node this search executes concurrently. This value should be - used to limit the impact of the search on the cluster in order to limit the - number of concurrent shard requests. - :param min_score: Minimum `_score` for matching documents. Documents with a lower - `_score` are not included in the search results. - :param pit: Limits the search to a point in time (PIT). If you provide a PIT, + be used only when the `q` query string parameter is specified. + :param max_concurrent_shard_requests: The number of concurrent shard requests + per node that the search runs concurrently. This value should be used to + limit the impact of the search on the cluster in order to limit the number + of concurrent shard requests. + :param min_score: The minimum `_score` for matching documents. Documents with + a lower `_score` are not included in the search results. + :param pit: Limit the search to a point in time (PIT). If you provide a PIT, you cannot specify an `` in the request path. :param post_filter: Use the `post_filter` parameter to filter search results. The search hits are filtered after the aggregations are calculated. A post filter has no impact on the aggregation results. - :param pre_filter_shard_size: Defines a threshold that enforces a pre-filter - roundtrip to prefilter search shards based on query rewriting if the number - of shards the search request expands to exceeds the threshold. This filter - roundtrip can limit the number of shards significantly if for instance a - shard can not match any documents based on its rewrite method (if date filters - are mandatory to match but the shard bounds and the query are disjoint). - When unspecified, the pre-filter phase is executed if any of these conditions - is met: the request targets more than 128 shards; the request targets one - or more read-only index; the primary sort of the query targets an indexed + :param pre_filter_shard_size: A threshold that enforces a pre-filter roundtrip + to prefilter search shards based on query rewriting if the number of shards + the search request expands to exceeds the threshold. This filter roundtrip + can limit the number of shards significantly if for instance a shard can + not match any documents based on its rewrite method (if date filters are + mandatory to match but the shard bounds and the query are disjoint). When + unspecified, the pre-filter phase is executed if any of these conditions + is met: * The request targets more than 128 shards. * The request targets + one or more read-only index. * The primary sort of the query targets an indexed field. - :param preference: Nodes and shards used for the search. By default, Elasticsearch + :param preference: The nodes and shards used for the search. By default, Elasticsearch selects from eligible nodes and shards using adaptive replica selection, - accounting for allocation awareness. Valid values are: `_only_local` to run - the search only on shards on the local node; `_local` to, if possible, run - the search on shards on the local node, or if not, select shards using the - default method; `_only_nodes:,` to run the search on only - the specified nodes IDs, where, if suitable shards exist on more than one - selected node, use shards on those nodes using the default method, or if - none of the specified nodes are available, select shards from any available - node using the default method; `_prefer_nodes:,` to if - possible, run the search on the specified nodes IDs, or if not, select shards - using the default method; `_shards:,` to run the search only - on the specified shards; `` (any string that does not start - with `_`) to route searches with the same `` to the same shards - in the same order. + accounting for allocation awareness. Valid values are: * `_only_local` to + run the search only on shards on the local node. * `_local` to, if possible, + run the search on shards on the local node, or if not, select shards using + the default method. * `_only_nodes:,` to run the search + on only the specified nodes IDs. If suitable shards exist on more than one + selected node, use shards on those nodes using the default method. If none + of the specified nodes are available, select shards from any available node + using the default method. * `_prefer_nodes:,` to if possible, + run the search on the specified nodes IDs. If not, select shards using the + default method. `_shards:,` to run the search only on the specified + shards. You can combine this value with other `preference` values. However, + the `_shards` value must come first. For example: `_shards:2,3|_local`. `` + (any string that does not start with `_`) to route searches with the same + `` to the same shards in the same order. :param profile: Set to `true` to return detailed timing information about the execution of individual components in a search request. NOTE: This is a debugging tool and adds significant overhead to search execution. - :param q: Query in the Lucene query string syntax using query parameter search. - Query parameter searches do not support the full Elasticsearch Query DSL - but are handy for testing. - :param query: Defines the search definition using the Query DSL. - :param rank: Defines the Reciprocal Rank Fusion (RRF) to use. + :param q: A query in the Lucene query string syntax. Query parameter searches + do not support the full Elasticsearch Query DSL but are handy for testing. + IMPORTANT: This parameter overrides the query parameter in the request body. + If both parameters are specified, documents matching the query request body + parameter are not returned. + :param query: The search definition using the Query DSL. + :param rank: The Reciprocal Rank Fusion (RRF) to use. :param request_cache: If `true`, the caching of search results is enabled for - requests where `size` is `0`. Defaults to index level settings. + requests where `size` is `0`. It defaults to index level settings. :param rescore: Can be used to improve precision by reordering just the top (for example 100 - 500) documents returned by the `query` and `post_filter` phases. :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 retriever: A retriever is a specification to describe top documents returned from a search. A retriever replaces other elements of the search API that - also return top documents such as query and knn. - :param routing: Custom value used to route operations to a specific shard. - :param runtime_mappings: Defines one or more runtime fields in the search request. - These fields take precedence over mapped fields with the same name. + also return top documents such as `query` and `knn`. + :param routing: A custom value that is used to route operations to a specific + shard. + :param runtime_mappings: One or more runtime fields in the search request. These + fields take precedence over mapped fields with the same name. :param script_fields: Retrieve a script evaluation (based on different fields) for each hit. - :param scroll: Period to retain the search context for scrolling. See Scroll - search results. By default, this value cannot exceed `1d` (24 hours). You - can change this limit using the `search.max_keep_alive` cluster-level setting. + :param scroll: The period to retain the search context for scrolling. By default, + this value cannot exceed `1d` (24 hours). You can change this limit by using + the `search.max_keep_alive` cluster-level setting. :param search_after: Used to retrieve the next page of hits using a set of sort values from the previous page. - :param search_type: How distributed term frequencies are calculated for relevance - scoring. - :param seq_no_primary_term: If `true`, returns sequence number and primary term - of the last modification of each hit. - :param size: The number of hits to return. By default, you cannot page through - more than 10,000 hits using the `from` and `size` parameters. To page through - more hits, use the `search_after` parameter. - :param slice: Can be used to split a scrolled search into multiple slices that - can be consumed independently. + :param search_type: Indicates how distributed term frequencies are calculated + for relevance scoring. + :param seq_no_primary_term: If `true`, the request returns sequence number and + primary term of the last modification of each hit. + :param size: The number of hits to return, which must not be negative. By default, + you cannot page through more than 10,000 hits using the `from` and `size` + parameters. To page through more hits, use the `search_after` property. + :param slice: Split a scrolled search into multiple slices that can be consumed + independently. :param sort: A comma-separated list of : pairs. - :param source: Indicates which source fields are returned for matching documents. - These fields are returned in the hits._source property of the search response. + :param source: The source fields that are returned for matching documents. These + fields are returned in the `hits._source` property of the search response. + If the `stored_fields` property is specified, the `_source` property defaults + to `false`. Otherwise, it defaults to `true`. :param source_excludes: A comma-separated list of source fields to exclude from the response. You can also use this parameter to exclude fields from the subset specified in `_source_includes` query parameter. If the `_source` @@ -3525,45 +4340,46 @@ async def search( returned. You can exclude fields from this subset using the `_source_excludes` query parameter. If the `_source` parameter is `false`, this parameter is ignored. - :param stats: Stats groups to associate with the search. Each group maintains + :param stats: The stats groups to associate with the search. Each group maintains a statistics aggregation for its associated searches. You can retrieve these stats using the indices stats API. - :param stored_fields: List of stored fields to return as part of a hit. If no - fields are specified, no stored fields are included in the response. If this - field is specified, the `_source` parameter defaults to `false`. You can - pass `_source: true` to return both source fields and stored fields in the - search response. + :param stored_fields: A comma-separated list of stored fields to return as part + of a hit. If no fields are specified, no stored fields are included in the + response. If this field is specified, the `_source` property defaults to + `false`. You can pass `_source: true` to return both source fields and stored + fields in the search response. :param suggest: Defines a suggester that provides similar looking terms based on a provided text. - :param suggest_field: Specifies which field to use for suggestions. - :param suggest_mode: Specifies the suggest mode. This parameter can only be used - when the `suggest_field` and `suggest_text` query string parameters are specified. - :param suggest_size: Number of suggestions to return. This parameter can only - be used when the `suggest_field` and `suggest_text` query string parameters + :param suggest_field: The field to use for suggestions. + :param suggest_mode: The suggest mode. This parameter can be used only when the + `suggest_field` and `suggest_text` query string parameters are specified. + :param suggest_size: The number of suggestions to return. This parameter can + be used only when the `suggest_field` and `suggest_text` query string parameters are specified. :param suggest_text: The source text for which the suggestions should be returned. - This parameter can only be used when the `suggest_field` and `suggest_text` + This parameter can be used only when the `suggest_field` and `suggest_text` query string parameters are specified. - :param terminate_after: Maximum number of documents to collect for each shard. + :param terminate_after: The maximum number of documents to collect for each shard. If a query reaches this limit, Elasticsearch terminates the query early. - Elasticsearch collects documents before sorting. Use with caution. Elasticsearch - applies this parameter to each shard handling the request. When possible, - let Elasticsearch perform early termination automatically. Avoid specifying - this parameter for requests that target data streams with backing indices - across multiple data tiers. If set to `0` (default), the query does not terminate - early. - :param timeout: Specifies the period of time to wait for a response from each - shard. If no response is received before the timeout expires, the request - fails and returns an error. Defaults to no timeout. - :param track_scores: If true, calculate and return document scores, even if the - scores are not used for sorting. + Elasticsearch collects documents before sorting. IMPORTANT: Use with caution. + Elasticsearch applies this property to each shard handling the request. When + possible, let Elasticsearch perform early termination automatically. Avoid + specifying this property for requests that target data streams with backing + indices across multiple data tiers. If set to `0` (default), the query does + not terminate early. + :param timeout: The period of time to wait for a response from each shard. If + no response is received before the timeout expires, the request fails and + returns an error. Defaults to no timeout. + :param track_scores: If `true`, calculate and return document scores, even if + the scores are not used for sorting. :param track_total_hits: Number of hits matching the query to count accurately. If `true`, the exact number of hits is returned at the cost of some performance. If `false`, the response does not include the total number of hits matching the query. :param typed_keys: If `true`, aggregation and suggester names are be prefixed by their respective types in the response. - :param version: If true, returns document version as part of a hit. + :param version: If `true`, the request returns the document version as part of + a hit. """ __path_parts: t.Dict[str, str] if index not in SKIP_IN_PATH: @@ -3793,52 +4609,376 @@ async def search_mvt( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> BinaryApiResponse: """ - Search a vector tile. Search a vector tile for geospatial values. - - ``_ + .. raw:: html + +

Search a vector tile.

+

Search a vector tile for geospatial values. + Before using this API, you should be familiar with the Mapbox vector tile specification. + The API returns results as a binary mapbox vector tile.

+

Internally, Elasticsearch translates a vector tile search API request into a search containing:

+
    +
  • A geo_bounding_box query on the <field>. The query uses the <zoom>/<x>/<y> tile as a bounding box.
    • +
  • A geotile_grid or geohex_grid aggregation on the <field>. The grid_agg parameter determines the aggregation type. The aggregation uses the <zoom>/<x>/<y> tile as a bounding box.
    • +
  • Optionally, a geo_bounds aggregation on the <field>. The search only includes this aggregation if the exact_bounds parameter is true.
    • +
  • If the optional parameter with_labels is true, the internal search will include a dynamic runtime field that calls the getLabelPosition function of the geometry doc value. This enables the generation of new point features containing suggested geometry labels, so that, for example, multi-polygons will have only one label.
    • +
+

For example, Elasticsearch may translate a vector tile search API request with a grid_agg argument of geotile and an exact_bounds argument of true into the following search

+ 
GET my-index/_search
+          {
+            "size": 10000,
+            "query": {
+              "geo_bounding_box": {
+                "my-geo-field": {
+                  "top_left": {
+                    "lat": -40.979898069620134,
+                    "lon": -45
+                  },
+                  "bottom_right": {
+                    "lat": -66.51326044311186,
+                    "lon": 0
+                  }
+                }
+              }
+            },
+            "aggregations": {
+              "grid": {
+                "geotile_grid": {
+                  "field": "my-geo-field",
+                  "precision": 11,
+                  "size": 65536,
+                  "bounds": {
+                    "top_left": {
+                      "lat": -40.979898069620134,
+                      "lon": -45
+                    },
+                    "bottom_right": {
+                      "lat": -66.51326044311186,
+                      "lon": 0
+                    }
+                  }
+                }
+              },
+              "bounds": {
+                "geo_bounds": {
+                  "field": "my-geo-field",
+                  "wrap_longitude": false
+                }
+              }
+            }
+          }
+
+

The API returns results as a binary Mapbox vector tile. + Mapbox vector tiles are encoded as Google Protobufs (PBF). By default, the tile contains three layers:

+
    +
  • A hits layer containing a feature for each <field> value matching the geo_bounding_box query.
    • +
  • An aggs layer containing a feature for each cell of the geotile_grid or geohex_grid. The layer only contains features for cells with matching data.
    • +
  • A meta layer containing: +
      +
    • A feature containing a bounding box. By default, this is the bounding box of the tile.
      • +
    • Value ranges for any sub-aggregations on the geotile_grid or geohex_grid.
      • +
    • Metadata for the search.
      • +
    +
    • +
+

The API only returns features that can display at its zoom level. + For example, if a polygon feature has no area at its zoom level, the API omits it. + The API returns errors as UTF-8 encoded JSON.

+

IMPORTANT: You can specify several options for this API as either a query parameter or request body parameter. + If you specify both parameters, the query parameter takes precedence.

+

Grid precision for geotile

+

For a grid_agg of geotile, you can use cells in the aggs layer as tiles for lower zoom levels. + grid_precision represents the additional zoom levels available through these cells. The final precision is computed by as follows: <zoom> + grid_precision. + For example, if <zoom> is 7 and grid_precision is 8, then the geotile_grid aggregation will use a precision of 15. + The maximum final precision is 29. + The grid_precision also determines the number of cells for the grid as follows: (2^grid_precision) x (2^grid_precision). + For example, a value of 8 divides the tile into a grid of 256 x 256 cells. + The aggs layer only contains features for cells with matching data.

+

Grid precision for geohex

+

For a grid_agg of geohex, Elasticsearch uses <zoom> and grid_precision to calculate a final precision as follows: <zoom> + grid_precision.

+

This precision determines the H3 resolution of the hexagonal cells produced by the geohex aggregation. + The following table maps the H3 resolution for each precision. + For example, if <zoom> is 3 and grid_precision is 3, the precision is 6. + At a precision of 6, hexagonal cells have an H3 resolution of 2. + If <zoom> is 3 and grid_precision is 4, the precision is 7. + At a precision of 7, hexagonal cells have an H3 resolution of 3.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PrecisionUnique tile binsH3 resolutionUnique hex binsRatio
14012230.5
21601227.625
364184213.15625
425618423.2890625
51024258825.744140625
64096258821.436035156
7163843411622.512329102
8655363411620.6280822754
926214442881221.099098206
10104857642881220.2747745514
114194304520168420.4808526039
12167772166141178820.8414913416
13671088646141178820.2103728354
142684354567988251620.3681524172
15107374182486917761220.644266719
16429496729686917761220.1610666797
1717179869184948424328420.2818666889
186871947673610338970298820.4932667053
19274877906944112372792091620.8632167343
201099511627776112372792091620.2158041836
2143980465111041216609544641220.3776573213
221759218604441613116266812488420.6609003122
237036874417766413116266812488420.165225078
2428147497671065614813867687418820.2891438866
251125899906842620155697073811931620.5060018015
264503599627370500155697073811931620.1265004504
2718014398509482000155697073811931620.03162511259
2872057594037927900155697073811931620.007906278149
29288230376151712000155697073811931620.001976569537
+

Hexagonal cells don't align perfectly on a vector tile. + Some cells may intersect more than one vector tile. + To compute the H3 resolution for each precision, Elasticsearch compares the average density of hexagonal bins at each resolution with the average density of tile bins at each zoom level. + Elasticsearch uses the H3 resolution that is closest to the corresponding geotile density.

+ + + ``_ :param index: Comma-separated list of data streams, indices, or aliases to search :param field: Field containing geospatial data to return :param zoom: Zoom level for the vector tile to search :param x: X coordinate for the vector tile to search :param y: Y coordinate for the vector tile to search - :param aggs: Sub-aggregations for the geotile_grid. Supports the following aggregation - types: - avg - cardinality - max - min - sum - :param buffer: Size, in pixels, of a clipping buffer outside the tile. This allows - renderers to avoid outline artifacts from geometries that extend past the - extent of the tile. - :param exact_bounds: If false, the meta layer’s feature is the bounding box of - the tile. If true, the meta layer’s feature is a bounding box resulting from - a geo_bounds aggregation. The aggregation runs on values that intersect - the // tile with wrap_longitude set to false. The resulting bounding - box may be larger than the vector tile. - :param extent: Size, in pixels, of a side of the tile. Vector tiles are square + :param aggs: Sub-aggregations for the geotile_grid. It supports the following + aggregation types: - `avg` - `boxplot` - `cardinality` - `extended stats` + - `max` - `median absolute deviation` - `min` - `percentile` - `percentile-rank` + - `stats` - `sum` - `value count` The aggregation names can't start with + `_mvt_`. The `_mvt_` prefix is reserved for internal aggregations. + :param buffer: The size, in pixels, of a clipping buffer outside the tile. This + allows renderers to avoid outline artifacts from geometries that extend past + the extent of the tile. + :param exact_bounds: If `false`, the meta layer's feature is the bounding box + of the tile. If `true`, the meta layer's feature is a bounding box resulting + from a `geo_bounds` aggregation. The aggregation runs on values that + intersect the `//` tile with `wrap_longitude` set to `false`. + The resulting bounding box may be larger than the vector tile. + :param extent: The size, in pixels, of a side of the tile. Vector tiles are square with equal sides. - :param fields: Fields to return in the `hits` layer. Supports wildcards (`*`). - This parameter does not support fields with array values. Fields with array - values may return inconsistent results. - :param grid_agg: Aggregation used to create a grid for the `field`. + :param fields: The fields to return in the `hits` layer. It supports wildcards + (`*`). This parameter does not support fields with array values. Fields with + array values may return inconsistent results. + :param grid_agg: The aggregation used to create a grid for the `field`. :param grid_precision: Additional zoom levels available through the aggs layer. - For example, if is 7 and grid_precision is 8, you can zoom in up to - level 15. Accepts 0-8. If 0, results don’t include the aggs layer. + For example, if `` is `7` and `grid_precision` is `8`, you can zoom + in up to level 15. Accepts 0-8. If 0, results don't include the aggs layer. :param grid_type: Determines the geometry type for features in the aggs layer. - In the aggs layer, each feature represents a geotile_grid cell. If 'grid' - each feature is a Polygon of the cells bounding box. If 'point' each feature + In the aggs layer, each feature represents a `geotile_grid` cell. If `grid, + each feature is a polygon of the cells bounding box. If `point`, each feature is a Point that is the centroid of the cell. - :param query: Query DSL used to filter documents for the search. + :param query: The query DSL used to filter documents for the search. :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 size: Maximum number of features to return in the hits layer. Accepts - 0-10000. If 0, results don’t include the hits layer. - :param sort: Sorts features in the hits layer. By default, the API calculates - a bounding box for each feature. It sorts features based on this box’s diagonal + :param size: The maximum number of features to return in the hits layer. Accepts + 0-10000. If 0, results don't include the hits layer. + :param sort: Sort the features in the hits layer. By default, the API calculates + a bounding box for each feature. It sorts features based on this box's diagonal length, from longest to shortest. - :param track_total_hits: Number of hits matching the query to count accurately. + :param track_total_hits: The number of hits matching the query to count accurately. If `true`, the exact number of hits is returned at the cost of some performance. If `false`, the response does not include the total number of hits matching the query. :param with_labels: If `true`, the hits and aggs layers will contain additional point features representing suggested label positions for the original features. + * `Point` and `MultiPoint` features will have one of the points selected. + * `Polygon` and `MultiPolygon` features will have a single point generated, + either the centroid, if it is within the polygon, or another point within + the polygon selected from the sorted triangle-tree. * `LineString` features + will likewise provide a roughly central point selected from the triangle-tree. + * The aggregation results will provide one central point for each aggregation + bucket. All attributes from the original features will also be copied to + the new label features. In addition, the new features will be distinguishable + using the tag `_mvt_label_position`. """ if index in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'index'") @@ -3963,12 +5103,15 @@ async def search_template( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Run a search with a search template. + .. raw:: html + +

Run a search with a search template.

- ``_ - :param index: Comma-separated list of data streams, indices, and aliases to search. - Supports wildcards (*). + ``_ + + :param index: A comma-separated list of data streams, indices, and aliases to + search. It supports wildcards (`*`). :param allow_no_indices: If `false`, the request returns an error if any wildcard expression, index alias, or `_all` value targets only missing or closed indices. This behavior applies even if the request targets other open indices. For @@ -3976,32 +5119,34 @@ async def search_template( with `foo` but no index starts with `bar`. :param ccs_minimize_roundtrips: If `true`, network round-trips are minimized for cross-cluster search requests. - :param expand_wildcards: Type of index that wildcard patterns can match. If the - request can target data streams, this argument determines whether wildcard - expressions match hidden data streams. Supports comma-separated values, such - as `open,hidden`. Valid values are: `all`, `open`, `closed`, `hidden`, `none`. + :param expand_wildcards: The type of index that wildcard patterns can match. + If the request can target data streams, this argument determines whether + wildcard expressions match hidden data streams. Supports comma-separated + values, such as `open,hidden`. Valid values are: `all`, `open`, `closed`, + `hidden`, `none`. :param explain: If `true`, returns detailed information about score calculation - as part of each hit. - :param id: ID of the search template to use. If no source is specified, this - parameter is required. + as part of each hit. If you specify both this and the `explain` query parameter, + the API uses only the query parameter. + :param id: The ID of the search template to use. If no `source` is specified, + this parameter is required. :param ignore_throttled: If `true`, specified concrete, expanded, or aliased indices are not included in the response when throttled. :param ignore_unavailable: If `false`, the request returns an error if it targets a missing or closed index. :param params: Key-value pairs used to replace Mustache variables in the template. The key is the variable name. The value is the variable value. - :param preference: Specifies the node or shard the operation should be performed - on. Random by default. + :param preference: The node or shard the operation should be performed on. It + is random by default. :param profile: If `true`, the query execution is profiled. - :param rest_total_hits_as_int: If true, hits.total are rendered as an integer - in the response. - :param routing: Custom value used to route operations to a specific shard. + :param rest_total_hits_as_int: If `true`, `hits.total` is rendered as an integer + in the response. If `false`, it is rendered as an object. + :param routing: A custom value used to route operations to a specific shard. :param scroll: Specifies how long a consistent view of the index should be maintained for scrolled search. :param search_type: The type of the search operation. :param source: An inline search template. Supports the same parameters as the - search API's request body. Also supports Mustache variables. If no id is - specified, this parameter is required. + search API's request body. It also supports Mustache variables. If no `id` + is specified, this parameter is required. :param typed_keys: If `true`, the response prefixes aggregation and suggester names with their respective types. """ @@ -4095,34 +5240,39 @@ async def terms_enum( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Get terms in an index. Discover terms that match a partial string in an index. - This "terms enum" API is designed for low-latency look-ups used in auto-complete - scenarios. If the `complete` property in the response is false, the returned - terms set may be incomplete and should be treated as approximate. This can occur - due to a few reasons, such as a request timeout or a node error. NOTE: The terms - enum API may return terms from deleted documents. Deleted documents are initially - only marked as deleted. It is not until their segments are merged that documents - are actually deleted. Until that happens, the terms enum API will return terms - from these documents. - - ``_ + .. raw:: html - :param index: Comma-separated list of data streams, indices, and index aliases - to search. Wildcard (*) expressions are supported. +

Get terms in an index.

+

Discover terms that match a partial string in an index. + This API is designed for low-latency look-ups used in auto-complete scenarios.

+
+

info + The terms enum API may return terms from deleted documents. Deleted documents are initially only marked as deleted. It is not until their segments are merged that documents are actually deleted. Until that happens, the terms enum API will return terms from these documents.

+
+ + + ``_ + + :param index: A comma-separated list of data streams, indices, and index aliases + to search. Wildcard (`*`) expressions are supported. To search all data streams + or indices, omit this parameter or use `*` or `_all`. :param field: The string to match at the start of indexed terms. If not provided, all terms in the field are considered. - :param case_insensitive: When true the provided search string is matched against + :param case_insensitive: When `true`, the provided search string is matched against index terms without case sensitivity. - :param index_filter: Allows to filter an index shard if the provided query rewrites - to match_none. - :param search_after: - :param size: How many matching terms to return. - :param string: The string after which terms in the index should be returned. - Allows for a form of pagination if the last result from one request is passed - as the search_after parameter for a subsequent request. - :param timeout: The maximum length of time to spend collecting results. Defaults - to "1s" (one second). If the timeout is exceeded the complete flag set to - false in the response and the results may be partial or empty. + :param index_filter: Filter an index shard if the provided query rewrites to + `match_none`. + :param search_after: The string after which terms in the index should be returned. + It allows for a form of pagination if the last result from one request is + passed as the `search_after` parameter for a subsequent request. + :param size: The number of matching terms to return. + :param string: The string to match at the start of indexed terms. If it is not + provided, all terms in the field are considered. > info > The prefix string + cannot be larger than the largest possible keyword value, which is Lucene's + term byte-length limit of 32766. + :param timeout: The maximum length of time to spend collecting results. If the + timeout is exceeded the `complete` flag set to `false` in the response and + the results may be partial or empty. """ if index in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'index'") @@ -4201,33 +5351,77 @@ async def termvectors( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Get term vector information. Get information and statistics about terms in the - fields of a particular document. - - ``_ - - :param index: Name of the index that contains the document. - :param id: Unique identifier of the document. + .. raw:: html + +

Get term vector information.

+

Get information and statistics about terms in the fields of a particular document.

+

You can retrieve term vectors for documents stored in the index or for artificial documents passed in the body of the request. + You can specify the fields you are interested in through the fields parameter or by adding the fields to the request body. + For example:

+ 
GET /my-index-000001/_termvectors/1?fields=message
+
+

Fields can be specified using wildcards, similar to the multi match query.

+

Term vectors are real-time by default, not near real-time. + This can be changed by setting realtime parameter to false.

+

You can request three types of values: term information, term statistics, and field statistics. + By default, all term information and field statistics are returned for all fields but term statistics are excluded.

+

Term information

+
    +
  • term frequency in the field (always returned)
    • +
  • term positions (positions: true)
    • +
  • start and end offsets (offsets: true)
    • +
  • term payloads (payloads: true), as base64 encoded bytes
    • +
+

If the requested information wasn't stored in the index, it will be computed on the fly if possible. + Additionally, term vectors could be computed for documents not even existing in the index, but instead provided by the user.

+
+

warn + Start and end offsets assume UTF-16 encoding is being used. If you want to use these offsets in order to get the original text that produced this token, you should make sure that the string you are taking a sub-string of is also encoded using UTF-16.

+
+

Behaviour

+

The term and field statistics are not accurate. + Deleted documents are not taken into account. + The information is only retrieved for the shard the requested document resides in. + The term and field statistics are therefore only useful as relative measures whereas the absolute numbers have no meaning in this context. + By default, when requesting term vectors of artificial documents, a shard to get the statistics from is randomly selected. + Use routing only to hit a particular shard.

+ + + ``_ + + :param index: The name of the index that contains the document. + :param id: A unique identifier for the document. :param doc: An artificial document (a document not present in the index) for which you want to retrieve term vectors. - :param field_statistics: If `true`, the response includes the document count, - sum of document frequencies, and sum of total term frequencies. - :param fields: Comma-separated list or wildcard expressions of fields to include - in the statistics. Used as the default list unless a specific field list - is provided in the `completion_fields` or `fielddata_fields` parameters. - :param filter: Filter terms based on their tf-idf scores. + :param field_statistics: If `true`, the response includes: * The document count + (how many documents contain this field). * The sum of document frequencies + (the sum of document frequencies for all terms in this field). * The sum + of total term frequencies (the sum of total term frequencies of each term + in this field). + :param fields: A comma-separated list or wildcard expressions of fields to include + in the statistics. It is used as the default list unless a specific field + list is provided in the `completion_fields` or `fielddata_fields` parameters. + :param filter: Filter terms based on their tf-idf scores. This could be useful + in order find out a good characteristic vector of a document. This feature + works in a similar manner to the second phase of the More Like This Query. :param offsets: If `true`, the response includes term offsets. :param payloads: If `true`, the response includes term payloads. - :param per_field_analyzer: Overrides the default per-field analyzer. + :param per_field_analyzer: Override the default per-field analyzer. This is useful + in order to generate term vectors in any fashion, especially when using artificial + documents. When providing an analyzer for a field that already stores term + vectors, the term vectors will be regenerated. :param positions: If `true`, the response includes term positions. - :param preference: Specifies the node or shard the operation should be performed - on. Random by default. + :param preference: The node or shard the operation should be performed on. It + is random by default. :param realtime: If true, the request is real-time as opposed to near-real-time. - :param routing: Custom value used to route operations to a specific shard. - :param term_statistics: If `true`, the response includes term frequency and document - frequency. + :param routing: A custom value that is used to route operations to a specific + shard. + :param term_statistics: If `true`, the response includes: * The total term frequency + (how often a term occurs in all documents). * The document frequency (the + number of documents containing the current term). By default these values + are not returned since term statistics can have a serious performance impact. :param version: If `true`, returns the document version as part of a hit. - :param version_type: Specific version type. + :param version_type: The version type. """ if index in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'index'") @@ -4323,6 +5517,7 @@ async def update( human: t.Optional[bool] = None, if_primary_term: t.Optional[int] = None, if_seq_no: t.Optional[int] = None, + include_source_on_error: t.Optional[bool] = None, lang: t.Optional[str] = None, pretty: t.Optional[bool] = None, refresh: t.Optional[ @@ -4344,46 +5539,67 @@ async def update( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Update a document. Updates a document by running a script or passing a partial - document. - - ``_ - - :param index: The name of the index - :param id: Document ID - :param detect_noop: Set to false to disable setting 'result' in the response - to 'noop' if no change to the document occurred. - :param doc: A partial update to an existing document. - :param doc_as_upsert: Set to true to use the contents of 'doc' as the value of - 'upsert' + .. raw:: html + +

Update a document.

+

Update a document by running a script or passing a partial document.

+

If the Elasticsearch security features are enabled, you must have the index or write index privilege for the target index or index alias.

+

The script can update, delete, or skip modifying the document. + The API also supports passing a partial document, which is merged into the existing document. + To fully replace an existing document, use the index API. + This operation:

+
    +
  • Gets the document (collocated with the shard) from the index.
    • +
  • Runs the specified script.
    • +
  • Indexes the result.
    • +
+

The document must still be reindexed, but using this API removes some network roundtrips and reduces chances of version conflicts between the GET and the index operation.

+

The _source field must be enabled to use this API. + In addition to _source, you can access the following variables through the ctx map: _index, _type, _id, _version, _routing, and _now (the current timestamp).

+ + + ``_ + + :param index: The name of the target index. By default, the index is created + automatically if it doesn't exist. + :param id: A unique identifier for the document to be updated. + :param detect_noop: If `true`, the `result` in the response is set to `noop` + (no operation) when there are no changes to the document. + :param doc: A partial update to an existing document. If both `doc` and `script` + are specified, `doc` is ignored. + :param doc_as_upsert: If `true`, use the contents of 'doc' as the value of 'upsert'. + NOTE: Using ingest pipelines with `doc_as_upsert` is not supported. :param if_primary_term: Only perform the operation if the document has this primary term. :param if_seq_no: Only perform the operation if the document has this sequence number. + :param include_source_on_error: True or false if to include the document source + in the error message in case of parsing errors. :param lang: The script language. :param refresh: If 'true', Elasticsearch refreshes the affected shards to make - this operation visible to search, if 'wait_for' then wait for a refresh to - make this operation visible to search, if 'false' do nothing with refreshes. - :param require_alias: If true, the destination must be an index alias. - :param retry_on_conflict: Specify how many times should the operation be retried + this operation visible to search. If 'wait_for', it waits for a refresh to + make this operation visible to search. If 'false', it does nothing with refreshes. + :param require_alias: If `true`, the destination must be an index alias. + :param retry_on_conflict: The number of times the operation should be retried when a conflict occurs. - :param routing: Custom value used to route operations to a specific shard. - :param script: Script to execute to update the document. - :param scripted_upsert: Set to true to execute the script whether or not the - document exists. - :param source: Set to false to disable source retrieval. You can also specify - a comma-separated list of the fields you want to retrieve. - :param source_excludes: Specify the source fields you want to exclude. - :param source_includes: Specify the source fields you want to retrieve. - :param timeout: Period to wait for dynamic mapping updates and active shards. - This guarantees Elasticsearch waits for at least the timeout before failing. - The actual wait time could be longer, particularly when multiple waits occur. + :param routing: A custom value used to route operations to a specific shard. + :param script: The script to run to update the document. + :param scripted_upsert: If `true`, run the script whether or not the document + exists. + :param source: If `false`, turn off source retrieval. You can also specify a + comma-separated list of the fields you want to retrieve. + :param source_excludes: The source fields you want to exclude. + :param source_includes: The source fields you want to retrieve. + :param timeout: The period to wait for the following operations: dynamic mapping + updates and waiting for active shards. Elasticsearch waits for at least the + timeout period before failing. The actual wait time could be longer, particularly + when multiple waits occur. :param upsert: If the document does not already exist, the contents of 'upsert' - are inserted as a new document. If the document exists, the 'script' is executed. - :param wait_for_active_shards: The number of shard copies that must be active - before proceeding with the operations. Set to 'all' or any positive integer - up to the total number of shards in the index (number_of_replicas+1). Defaults - to 1 meaning the primary shard. + are inserted as a new document. If the document exists, the 'script' is run. + :param wait_for_active_shards: The number of copies of each shard that must be + active before proceeding with the operation. Set to 'all' or any positive + integer up to the total number of shards in the index (`number_of_replicas`+1). + The default value of `1` means it waits for each primary shard to be active. """ if index in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'index'") @@ -4403,6 +5619,8 @@ async def update( __query["if_primary_term"] = if_primary_term if if_seq_no is not None: __query["if_seq_no"] = if_seq_no + if include_source_on_error is not None: + __query["include_source_on_error"] = include_source_on_error if lang is not None: __query["lang"] = lang if pretty is not None: @@ -4509,82 +5727,166 @@ async def update_by_query( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Update documents. Updates documents that match the specified query. If no query - is specified, performs an update on every document in the data stream or index - without modifying the source, which is useful for picking up mapping changes. - - ``_ - - :param index: Comma-separated list of data streams, indices, and aliases to search. - Supports wildcards (`*`). To search all data streams or indices, omit this - parameter or use `*` or `_all`. + .. raw:: html + +

Update documents. + Updates documents that match the specified query. + If no query is specified, performs an update on every document in the data stream or index without modifying the source, which is useful for picking up mapping changes.

+

If the Elasticsearch security features are enabled, you must have the following index privileges for the target data stream, index, or alias:

+
    +
  • read
    • +
  • index or write
    • +
+

You can specify the query criteria in the request URI or the request body using the same syntax as the search API.

+

When you submit an update by query request, Elasticsearch gets a snapshot of the data stream or index when it begins processing the request and updates matching documents using internal versioning. + When the versions match, the document is updated and the version number is incremented. + If a document changes between the time that the snapshot is taken and the update operation is processed, it results in a version conflict and the operation fails. + You can opt to count version conflicts instead of halting and returning by setting conflicts to proceed. + Note that if you opt to count version conflicts, the operation could attempt to update more documents from the source than max_docs until it has successfully updated max_docs documents or it has gone through every document in the source query.

+

NOTE: Documents with a version equal to 0 cannot be updated using update by query because internal versioning does not support 0 as a valid version number.

+

While processing an update by query request, Elasticsearch performs multiple search requests sequentially to find all of the matching documents. + A bulk update request is performed for each batch of matching documents. + Any query or update failures cause the update by query request to fail and the failures are shown in the response. + Any update requests that completed successfully still stick, they are not rolled back.

+

Throttling update requests

+

To control the rate at which update by query issues batches of update operations, you can set requests_per_second to any positive decimal number. + This pads each batch with a wait time to throttle the rate. + Set requests_per_second to -1 to turn off throttling.

+

Throttling uses a wait time between batches so that the internal scroll requests can be given a timeout that takes the request padding into account. + The padding time is the difference between the batch size divided by the requests_per_second and the time spent writing. + By default the batch size is 1000, so if requests_per_second is set to 500:

+ 
target_time = 1000 / 500 per second = 2 seconds
+          wait_time = target_time - write_time = 2 seconds - .5 seconds = 1.5 seconds
+
+

Since the batch is issued as a single _bulk request, large batch sizes cause Elasticsearch to create many requests and wait before starting the next set. + This is "bursty" instead of "smooth".

+

Slicing

+

Update by query supports sliced scroll to parallelize the update process. + This can improve efficiency and provide a convenient way to break the request down into smaller parts.

+

Setting slices to auto chooses a reasonable number for most data streams and indices. + This setting will use one slice per shard, up to a certain limit. + If there are multiple source data streams or indices, it will choose the number of slices based on the index or backing index with the smallest number of shards.

+

Adding slices to _update_by_query just automates the manual process of creating sub-requests, which means it has some quirks:

+
    +
  • You can see these requests in the tasks APIs. These sub-requests are "child" tasks of the task for the request with slices.
    • +
  • Fetching the status of the task for the request with slices only contains the status of completed slices.
    • +
  • These sub-requests are individually addressable for things like cancellation and rethrottling.
    • +
  • Rethrottling the request with slices will rethrottle the unfinished sub-request proportionally.
    • +
  • Canceling the request with slices will cancel each sub-request.
    • +
  • Due to the nature of slices each sub-request won't get a perfectly even portion of the documents. All documents will be addressed, but some slices may be larger than others. Expect larger slices to have a more even distribution.
    • +
  • Parameters like requests_per_second and max_docs on a request with slices are distributed proportionally to each sub-request. Combine that with the point above about distribution being uneven and you should conclude that using max_docs with slices might not result in exactly max_docs documents being updated.
    • +
  • Each sub-request gets a slightly different snapshot of the source data stream or index though these are all taken at approximately the same time.
    • +
+

If you're slicing manually or otherwise tuning automatic slicing, keep in mind that:

+
    +
  • Query performance is most efficient when the number of slices is equal to the number of shards in the index or backing index. If that number is large (for example, 500), choose a lower number as too many slices hurts performance. Setting slices higher than the number of shards generally does not improve efficiency and adds overhead.
    • +
  • Update performance scales linearly across available resources with the number of slices.
    • +
+

Whether query or update performance dominates the runtime depends on the documents being reindexed and cluster resources.

+

Update the document source

+

Update by query supports scripts to update the document source. + As with the update API, you can set ctx.op to change the operation that is performed.

+

Set ctx.op = "noop" if your script decides that it doesn't have to make any changes. + The update by query operation skips updating the document and increments the noop counter.

+

Set ctx.op = "delete" if your script decides that the document should be deleted. + The update by query operation deletes the document and increments the deleted counter.

+

Update by query supports only index, noop, and delete. + Setting ctx.op to anything else is an error. + Setting any other field in ctx is an error. + This API enables you to only modify the source of matching documents; you cannot move them.

+ + + ``_ + + :param index: A comma-separated list of data streams, indices, and aliases to + search. It supports wildcards (`*`). To search all data streams or indices, + omit this parameter or use `*` or `_all`. :param allow_no_indices: If `false`, the request returns an error if any wildcard expression, index alias, or `_all` value targets only missing or closed indices. This behavior applies even if the request targets other open indices. For example, a request targeting `foo*,bar*` returns an error if an index starts with `foo` but no index starts with `bar`. :param analyze_wildcard: If `true`, wildcard and prefix queries are analyzed. - :param analyzer: Analyzer to use for the query string. - :param conflicts: What to do if update by query hits version conflicts: `abort` - or `proceed`. + This parameter can be used only when the `q` query string parameter is specified. + :param analyzer: The analyzer to use for the query string. This parameter can + be used only when the `q` query string parameter is specified. + :param conflicts: The preferred behavior when update by query hits version conflicts: + `abort` or `proceed`. :param default_operator: The default operator for query string query: `AND` or - `OR`. - :param df: Field to use as default where no field prefix is given in the query - string. - :param expand_wildcards: Type of index that wildcard patterns can match. If the - request can target data streams, this argument determines whether wildcard - expressions match hidden data streams. Supports comma-separated values, such - as `open,hidden`. Valid values are: `all`, `open`, `closed`, `hidden`, `none`. + `OR`. This parameter can be used only when the `q` query string parameter + is specified. + :param df: The field to use as default where no field prefix is given in the + query string. This parameter can be used only when the `q` query string parameter + is specified. + :param expand_wildcards: The type of index that wildcard patterns can match. + If the request can target data streams, this argument determines whether + wildcard expressions match hidden data streams. It supports comma-separated + values, such as `open,hidden`. Valid values are: `all`, `open`, `closed`, + `hidden`, `none`. :param from_: Starting offset (default: 0) :param ignore_unavailable: If `false`, the request returns an error if it targets a missing or closed index. :param lenient: If `true`, format-based query failures (such as providing text - to a numeric field) in the query string will be ignored. + to a numeric field) in the query string will be ignored. This parameter can + be used only when the `q` query string parameter is specified. :param max_docs: The maximum number of documents to update. - :param pipeline: ID of the pipeline to use to preprocess incoming documents. + :param pipeline: The ID of the pipeline to use to preprocess incoming documents. If the index has a default ingest pipeline specified, then setting the value to `_none` disables the default ingest pipeline for this request. If a final pipeline is configured it will always run, regardless of the value of this parameter. - :param preference: Specifies the node or shard the operation should be performed - on. Random by default. - :param q: Query in the Lucene query string syntax. - :param query: Specifies the documents to update using the Query DSL. + :param preference: The node or shard the operation should be performed on. It + is random by default. + :param q: A query in the Lucene query string syntax. + :param query: The documents to update using the Query DSL. :param refresh: If `true`, Elasticsearch refreshes affected shards to make the - operation visible to search. + operation visible to search after the request completes. This is different + than the update API's `refresh` parameter, which causes just the shard that + received the request to be refreshed. :param request_cache: If `true`, the request cache is used for this request. + It defaults to the index-level setting. :param requests_per_second: The throttle for this request in sub-requests per second. - :param routing: Custom value used to route operations to a specific shard. + :param routing: A custom value used to route operations to a specific shard. :param script: The script to run to update the document source or metadata when updating. - :param scroll: Period to retain the search context for scrolling. - :param scroll_size: Size of the scroll request that powers the operation. - :param search_timeout: Explicit timeout for each search request. - :param search_type: The type of the search operation. Available options: `query_then_fetch`, - `dfs_query_then_fetch`. + :param scroll: The period to retain the search context for scrolling. + :param scroll_size: The size of the scroll request that powers the operation. + :param search_timeout: An explicit timeout for each search request. By default, + there is no timeout. + :param search_type: The type of the search operation. Available options include + `query_then_fetch` and `dfs_query_then_fetch`. :param slice: Slice the request manually using the provided slice ID and total number of slices. :param slices: The number of slices this task should be divided into. :param sort: A comma-separated list of : pairs. - :param stats: Specific `tag` of the request for logging and statistical purposes. - :param terminate_after: Maximum number of documents to collect for each shard. + :param stats: The specific `tag` of the request for logging and statistical purposes. + :param terminate_after: The maximum number of documents to collect for each shard. If a query reaches this limit, Elasticsearch terminates the query early. - Elasticsearch collects documents before sorting. Use with caution. Elasticsearch - applies this parameter to each shard handling the request. When possible, - let Elasticsearch perform early termination automatically. Avoid specifying - this parameter for requests that target data streams with backing indices - across multiple data tiers. - :param timeout: Period each update request waits for the following operations: - dynamic mapping updates, waiting for active shards. + Elasticsearch collects documents before sorting. IMPORTANT: Use with caution. + Elasticsearch applies this parameter to each shard handling the request. + When possible, let Elasticsearch perform early termination automatically. + Avoid specifying this parameter for requests that target data streams with + backing indices across multiple data tiers. + :param timeout: The period each update request waits for the following operations: + dynamic mapping updates, waiting for active shards. By default, it is one + minute. This guarantees Elasticsearch waits for at least the timeout before + failing. The actual wait time could be longer, particularly when multiple + waits occur. :param version: If `true`, returns the document version as part of a hit. :param version_type: Should the document increment the version number (internal) on hit or not (reindex) :param wait_for_active_shards: The number of shard copies that must be active before proceeding with the operation. Set to `all` or any positive integer - up to the total number of shards in the index (`number_of_replicas+1`). + up to the total number of shards in the index (`number_of_replicas+1`). The + `timeout` parameter controls how long each write request waits for unavailable + shards to become available. Both work exactly the way they work in the bulk + API. :param wait_for_completion: If `true`, the request blocks until the operation - is complete. + is complete. If `false`, Elasticsearch performs some preflight checks, launches + the request, and returns a task ID that you can use to cancel or get the + status of the task. Elasticsearch creates a record of this task as a document + at `.tasks/task/${taskId}`. """ if index in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'index'") diff --git a/elasticsearch_serverless/_async/client/async_search.py b/elasticsearch_serverless/_async/client/async_search.py index 2379b50..b667d94 100644 --- a/elasticsearch_serverless/_async/client/async_search.py +++ b/elasticsearch_serverless/_async/client/async_search.py @@ -36,13 +36,15 @@ async def delete( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Delete an async search. If the asynchronous search is still running, it is cancelled. - Otherwise, the saved search results are deleted. If the Elasticsearch security - features are enabled, the deletion of a specific async search is restricted to: - the authenticated user that submitted the original search request; users that - have the `cancel_task` cluster privilege. + .. raw:: html - ``_ +

Delete an async search.

+

If the asynchronous search is still running, it is cancelled. + Otherwise, the saved search results are deleted. + If the Elasticsearch security features are enabled, the deletion of a specific async search is restricted to: the authenticated user that submitted the original search request; users that have the cancel_task cluster privilege.

+ + + ``_ :param id: A unique identifier for the async search. """ @@ -85,16 +87,18 @@ async def get( ] = None, ) -> ObjectApiResponse[t.Any]: """ - Get async search results. Retrieve the results of a previously submitted asynchronous - search request. If the Elasticsearch security features are enabled, access to - the results of a specific async search is restricted to the user or API key that - submitted it. + .. raw:: html + +

Get async search results.

+

Retrieve the results of a previously submitted asynchronous search request. + If the Elasticsearch security features are enabled, access to the results of a specific async search is restricted to the user or API key that submitted it.

+ - ``_ + ``_ :param id: A unique identifier for the async search. - :param keep_alive: Specifies how long the async search should be available in - the cluster. When not specified, the `keep_alive` set with the corresponding + :param keep_alive: The length of time that the async search should be available + in the cluster. When not specified, the `keep_alive` set with the corresponding submit async request will be used. Otherwise, it is possible to override the value and extend the validity of the request. When this period expires, the search, if still running, is cancelled. If the search is completed, its @@ -149,15 +153,21 @@ async def status( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - 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. + .. raw:: html - ``_ +

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, the access to the status of a specific async search is restricted to:

+
    +
  • The user or API key that submitted the original async search request.
    • +
  • Users that have the monitor cluster privilege or greater privileges.
    • +
+ + + ``_ :param id: A unique identifier for the async search. - :param keep_alive: Specifies how long the async search needs to be available. + :param keep_alive: The length of time that the async search needs to be available. Ongoing async searches and any saved search results are deleted after this period. """ @@ -264,6 +274,7 @@ async def submit( ignore_throttled: t.Optional[bool] = None, ignore_unavailable: t.Optional[bool] = None, indices_boost: t.Optional[t.Sequence[t.Mapping[str, float]]] = None, + keep_alive: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, keep_on_completion: t.Optional[bool] = None, knn: t.Optional[ t.Union[t.Mapping[str, t.Any], t.Sequence[t.Mapping[str, t.Any]]] @@ -287,7 +298,7 @@ async def submit( runtime_mappings: t.Optional[t.Mapping[str, t.Mapping[str, t.Any]]] = None, script_fields: t.Optional[t.Mapping[str, t.Mapping[str, t.Any]]] = None, search_after: t.Optional[ - t.Sequence[t.Union[None, bool, float, int, str, t.Any]] + t.Sequence[t.Union[None, bool, float, int, str]] ] = None, search_type: t.Optional[ t.Union[str, t.Literal["dfs_query_then_fetch", "query_then_fetch"]] @@ -325,17 +336,16 @@ async def submit( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Run an async search. When the primary sort of the results is an indexed field, - shards get sorted based on minimum and maximum value that they hold for that - field. Partial results become available following the sort criteria that was - requested. Warning: Asynchronous search does not support scroll or search requests - that include only the suggest section. By default, Elasticsearch does not allow - you to store an async search response larger than 10Mb and an attempt to do this - results in an error. The maximum allowed size for a stored async search response - can be set by changing the `search.max_async_search_response_size` cluster level - setting. + .. raw:: html - ``_ +

Run an async search.

+

When the primary sort of the results is an indexed field, shards get sorted based on minimum and maximum value that they hold for that field. Partial results become available following the sort criteria that was requested.

+

Warning: Asynchronous search does not support scroll or search requests that include only the suggest section.

+

By default, Elasticsearch does not allow you to store an async search response larger than 10Mb and an attempt to do this results in an error. + The maximum allowed size for a stored async search response can be set by changing the search.max_async_search_response_size cluster level setting.

+ + + ``_ :param index: A comma-separated list of index names to search; use `_all` or empty string to perform the operation on all indices @@ -378,6 +388,9 @@ async def submit( :param ignore_unavailable: Whether specified concrete indices should be ignored when unavailable (missing or closed) :param indices_boost: Boosts the _score of documents from specified indices. + :param keep_alive: Specifies how long the async search needs to be available. + Ongoing async searches and any saved search results are deleted after this + period. :param keep_on_completion: If `true`, results are stored for later retrieval when the search completes within the `wait_for_completion_timeout`. :param knn: Defines the approximate kNN search to run. @@ -503,6 +516,8 @@ async def submit( __query["ignore_throttled"] = ignore_throttled if ignore_unavailable is not None: __query["ignore_unavailable"] = ignore_unavailable + if keep_alive is not None: + __query["keep_alive"] = keep_alive if keep_on_completion is not None: __query["keep_on_completion"] = keep_on_completion if lenient is not None: diff --git a/elasticsearch_serverless/_async/client/cat.py b/elasticsearch_serverless/_async/client/cat.py index 688fe7b..52aa54a 100644 --- a/elasticsearch_serverless/_async/client/cat.py +++ b/elasticsearch_serverless/_async/client/cat.py @@ -50,24 +50,31 @@ async def aliases( v: t.Optional[bool] = None, ) -> t.Union[ObjectApiResponse[t.Any], TextApiResponse]: """ - Get aliases. Retrieves the cluster’s index aliases, including filter and routing - information. The API does not return data stream aliases. CAT APIs are only intended - for human consumption using the command line or the Kibana console. They are - not intended for use by applications. For application consumption, use the aliases - API. + .. raw:: html - ``_ +

Get aliases.

+

Get the cluster's index aliases, including filter and routing information. + This API does not return data stream aliases.

+

IMPORTANT: CAT APIs are only intended for human consumption using the command line or the Kibana console. They are not intended for use by applications. For application consumption, use the aliases API.

+ + + ``_ :param name: A comma-separated list of aliases to retrieve. Supports wildcards (`*`). To retrieve all aliases, omit this parameter or use `*` or `_all`. - :param expand_wildcards: Whether to expand wildcard expression to concrete indices - that are open, closed or both. + :param expand_wildcards: The type of index that wildcard patterns can match. + If the request can target data streams, this argument determines whether + wildcard expressions match hidden data streams. It supports comma-separated + values, such as `open,hidden`. :param format: Specifies the format to return the columnar data in, can be set to `text`, `json`, `cbor`, `yaml`, or `smile`. :param h: List of columns to appear in the response. Supports simple wildcards. :param help: When set to `true` will output available columns. This option can't be combined with any other query string option. - :param master_timeout: Period to wait for a connection to the master node. + :param master_timeout: The period to wait for a connection to the master node. + If the master node is not available before the timeout expires, the request + fails and returns an error. To indicated that the request should never timeout, + you can set it to `-1`. :param s: List of columns that determine how the table should be sorted. Sorting defaults to ascending and can be changed by setting `:asc` or `:desc` as a suffix to the column name. @@ -131,17 +138,19 @@ async def component_templates( v: t.Optional[bool] = None, ) -> t.Union[ObjectApiResponse[t.Any], TextApiResponse]: """ - Get component templates. Returns information about component templates in a cluster. - Component templates are building blocks for constructing index templates that - specify index mappings, settings, and aliases. CAT APIs are only intended for - human consumption using the command line or Kibana console. They are not intended - for use by applications. For application consumption, use the get component template - API. + .. raw:: html - ``_ +

Get component templates.

+

Get information about component templates in a cluster. + Component templates are building blocks for constructing index templates that specify index mappings, settings, and aliases.

+

IMPORTANT: CAT APIs are only intended for human consumption using the command line or Kibana console. + They are not intended for use by applications. For application consumption, use the get component template API.

- :param name: The name of the component template. Accepts wildcard expressions. - If omitted, all component templates are returned. + + ``_ + + :param name: The name of the component template. It accepts wildcard expressions. + If it is omitted, all component templates are returned. :param format: Specifies the format to return the columnar data in, can be set to `text`, `json`, `cbor`, `yaml`, or `smile`. :param h: List of columns to appear in the response. Supports simple wildcards. @@ -151,7 +160,7 @@ async def component_templates( the local cluster state. If `false` the list of selected nodes are computed from the cluster state of the master node. In both cases the coordinating node will send requests for further information to each selected node. - :param master_timeout: Period to wait for a connection to the master node. + :param master_timeout: The period to wait for a connection to the master node. :param s: List of columns that determine how the table should be sorted. Sorting defaults to ascending and can be changed by setting `:asc` or `:desc` as a suffix to the column name. @@ -213,17 +222,19 @@ async def count( v: t.Optional[bool] = None, ) -> t.Union[ObjectApiResponse[t.Any], TextApiResponse]: """ - Get a document count. Provides quick access to a document count for a data stream, - an index, or an entire cluster. The document count only includes live documents, - not deleted documents which have not yet been removed by the merge process. CAT - APIs are only intended for human consumption using the command line or Kibana - console. They are not intended for use by applications. For application consumption, - use the count API. + .. raw:: html - ``_ +

Get a document count.

+

Get quick access to a document count for a data stream, an index, or an entire cluster. + The document count only includes live documents, not deleted documents which have not yet been removed by the merge process.

+

IMPORTANT: CAT APIs are only intended for human consumption using the command line or Kibana console. + They are not intended for use by applications. For application consumption, use the count API.

- :param index: Comma-separated list of data streams, indices, and aliases used - to limit the request. Supports wildcards (`*`). To target all data streams + + ``_ + + :param index: A comma-separated list of data streams, indices, and aliases used + to limit the request. It supports wildcards (`*`). To target all data streams and indices, omit this parameter or use `*` or `_all`. :param format: Specifies the format to return the columnar data in, can be set to `text`, `json`, `cbor`, `yaml`, or `smile`. @@ -274,9 +285,13 @@ async def count( @_rewrite_parameters() async def help(self) -> TextApiResponse: """ - Get CAT help. Returns help for the CAT APIs. + .. raw:: html + +

Get CAT help.

+

Get help for the CAT APIs.

+ - ``_ + ``_ """ __path_parts: t.Dict[str, str] = {} __path = "/_cat" @@ -325,18 +340,25 @@ async def indices( v: t.Optional[bool] = None, ) -> t.Union[ObjectApiResponse[t.Any], TextApiResponse]: """ - Get index information. Returns high-level information about indices in a cluster, - including backing indices for data streams. Use this request to get the following - information for each index in a cluster: - shard count - document count - deleted - document count - primary store size - total store size of all shards, including - shard replicas These metrics are retrieved directly from Lucene, which Elasticsearch - uses internally to power indexing and search. As a result, all document counts - include hidden nested documents. To get an accurate count of Elasticsearch documents, - use the cat count or count APIs. CAT APIs are only intended for human consumption - using the command line or Kibana console. They are not intended for use by applications. - For application consumption, use an index endpoint. + .. raw:: html - ``_ +

Get index information.

+

Get high-level information about indices in a cluster, including backing indices for data streams.

+

Use this request to get the following information for each index in a cluster:

+
    +
  • shard count
    • +
  • document count
    • +
  • deleted document count
    • +
  • primary store size
    • +
  • total store size of all shards, including shard replicas
    • +
+

These metrics are retrieved directly from Lucene, which Elasticsearch uses internally to power indexing and search. As a result, all document counts include hidden nested documents. + To get an accurate count of Elasticsearch documents, use the cat count or count APIs.

+

CAT APIs are only intended for human consumption using the command line or Kibana console. + They are not intended for use by applications. For application consumption, use an index endpoint.

+ + + ``_ :param index: Comma-separated list of data streams, indices, and aliases used to limit the request. Supports wildcards (`*`). To target all data streams @@ -527,13 +549,16 @@ async def ml_data_frame_analytics( v: t.Optional[bool] = None, ) -> t.Union[ObjectApiResponse[t.Any], TextApiResponse]: """ - Get data frame analytics jobs. Returns configuration and usage information about - data frame analytics jobs. CAT APIs are only intended for human consumption using - the Kibana console or command line. They are not intended for use by applications. - For application consumption, use the get data frame analytics jobs statistics - API. + .. raw:: html + +

Get data frame analytics jobs.

+

Get configuration and usage information about data frame analytics jobs.

+

IMPORTANT: CAT APIs are only intended for human consumption using the Kibana + console or command line. They are not intended for use by applications. For + application consumption, use the get data frame analytics jobs statistics API.

- ``_ + + ``_ :param id: The ID of the data frame analytics to fetch :param allow_no_match: Whether to ignore if a wildcard expression matches no @@ -689,14 +714,19 @@ async def ml_datafeeds( v: t.Optional[bool] = None, ) -> t.Union[ObjectApiResponse[t.Any], TextApiResponse]: """ - Get datafeeds. Returns configuration and usage information about datafeeds. This - API returns a maximum of 10,000 datafeeds. If the Elasticsearch security features - are enabled, you must have `monitor_ml`, `monitor`, `manage_ml`, or `manage` - cluster privileges to use this API. CAT APIs are only intended for human consumption - using the Kibana console or command line. They are not intended for use by applications. - For application consumption, use the get datafeed statistics API. + .. raw:: html + +

Get datafeeds.

+

Get configuration and usage information about datafeeds. + This API returns a maximum of 10,000 datafeeds. + If the Elasticsearch security features are enabled, you must have monitor_ml, monitor, manage_ml, or manage + cluster privileges to use this API.

+

IMPORTANT: CAT APIs are only intended for human consumption using the Kibana + console or command line. They are not intended for use by applications. For + application consumption, use the get datafeed statistics API.

+ - ``_ + ``_ :param datafeed_id: A numerical character string that uniquely identifies the datafeed. @@ -1050,15 +1080,19 @@ async def ml_jobs( v: t.Optional[bool] = None, ) -> t.Union[ObjectApiResponse[t.Any], TextApiResponse]: """ - Get anomaly detection jobs. Returns configuration and usage information for anomaly - detection jobs. This API returns a maximum of 10,000 jobs. If the Elasticsearch - security features are enabled, you must have `monitor_ml`, `monitor`, `manage_ml`, - or `manage` cluster privileges to use this API. CAT APIs are only intended for - human consumption using the Kibana console or command line. They are not intended - for use by applications. For application consumption, use the get anomaly detection - job statistics API. + .. raw:: html - ``_ +

Get anomaly detection jobs.

+

Get configuration and usage information for anomaly detection jobs. + This API returns a maximum of 10,000 jobs. + If the Elasticsearch security features are enabled, you must have monitor_ml, + monitor, manage_ml, or manage cluster privileges to use this API.

+

IMPORTANT: CAT APIs are only intended for human consumption using the Kibana + console or command line. They are not intended for use by applications. For + application consumption, use the get anomaly detection job statistics API.

+ + + ``_ :param job_id: Identifier for the anomaly detection job. :param allow_no_match: Specifies what to do when the request: * Contains wildcard @@ -1234,12 +1268,16 @@ async def ml_trained_models( v: t.Optional[bool] = None, ) -> t.Union[ObjectApiResponse[t.Any], TextApiResponse]: """ - Get trained models. Returns configuration and usage information about inference - trained models. CAT APIs are only intended for human consumption using the Kibana - console or command line. They are not intended for use by applications. For application - consumption, use the get trained models statistics API. + .. raw:: html + +

Get trained models.

+

Get configuration and usage information about inference trained models.

+

IMPORTANT: CAT APIs are only intended for human consumption using the Kibana + console or command line. They are not intended for use by applications. For + application consumption, use the get trained models statistics API.

- ``_ + + ``_ :param model_id: A unique identifier for the trained model. :param allow_no_match: Specifies what to do when the request: contains wildcard @@ -1494,12 +1532,16 @@ async def transforms( v: t.Optional[bool] = None, ) -> t.Union[ObjectApiResponse[t.Any], TextApiResponse]: """ - Get transform information. Get configuration and usage information about transforms. - CAT APIs are only intended for human consumption using the Kibana console or - command line. They are not intended for use by applications. For application - consumption, use the get transform statistics API. + .. raw:: html + +

Get transform information.

+

Get configuration and usage information about transforms.

+

CAT APIs are only intended for human consumption using the Kibana + console or command line. They are not intended for use by applications. For + application consumption, use the get transform statistics API.

+ - ``_ + ``_ :param transform_id: A transform identifier or a wildcard expression. If you do not specify one of these options, the API returns information for all diff --git a/elasticsearch_serverless/_async/client/cluster.py b/elasticsearch_serverless/_async/client/cluster.py index 1b7a004..e65a726 100644 --- a/elasticsearch_serverless/_async/client/cluster.py +++ b/elasticsearch_serverless/_async/client/cluster.py @@ -38,10 +38,13 @@ async def delete_component_template( timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, ) -> ObjectApiResponse[t.Any]: """ - Delete component templates. Component templates are building blocks for constructing - index templates that specify index mappings, settings, and aliases. + .. raw:: html - ``_ +

Delete component templates. + Component templates are building blocks for constructing index templates that specify index mappings, settings, and aliases.

+ + + ``_ :param name: Comma-separated list or wildcard expression of component template names used to limit the request. @@ -91,10 +94,13 @@ async def exists_component_template( pretty: t.Optional[bool] = None, ) -> HeadApiResponse: """ - Check component templates. Returns information about whether a particular component - template exists. + .. raw:: html + +

Check component templates. + Returns information about whether a particular component template exists.

- ``_ + + ``_ :param name: Comma-separated list of component template names used to limit the request. Wildcard (*) expressions are supported. @@ -147,9 +153,13 @@ async def get_component_template( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Get component templates. Get information about component templates. + .. raw:: html + +

Get component templates. + Get information about component templates.

- ``_ + + ``_ :param name: Comma-separated list of component template names used to limit the request. Wildcard (`*`) expressions are supported. @@ -214,9 +224,13 @@ async def info( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Get cluster info. Returns basic information about the cluster. + .. raw:: html + +

Get cluster info. + Returns basic information about the cluster.

+ - ``_ + ``_ :param target: Limits the information returned to the specific target. Supports a comma-separated list, such as http,ingest. @@ -265,23 +279,25 @@ async def put_component_template( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Create or update a component template. Component templates are building blocks - for constructing index templates that specify index mappings, settings, and aliases. - An index template can be composed of multiple component templates. To use a component - template, specify it in an index template’s `composed_of` list. Component templates - are only applied to new data streams and indices as part of a matching index - template. Settings and mappings specified directly in the index template or the - create index request override any settings or mappings specified in a component - template. Component templates are only used during index creation. For data streams, - this includes data stream creation and the creation of a stream’s backing indices. - Changes to component templates do not affect existing indices, including a stream’s - backing indices. You can use C-style `/* *\\/` block comments in component templates. - You can include comments anywhere in the request body except before the opening - curly bracket. **Applying component templates** You cannot directly apply a component - template to a data stream or index. To be applied, a component template must - be included in an index template's `composed_of` list. + .. raw:: html + +

Create or update a component template. + Component templates are building blocks for constructing index templates that specify index mappings, settings, and aliases.

+

An index template can be composed of multiple component templates. + To use a component template, specify it in an index template’s composed_of list. + Component templates are only applied to new data streams and indices as part of a matching index template.

+

Settings and mappings specified directly in the index template or the create index request override any settings or mappings specified in a component template.

+

Component templates are only used during index creation. + For data streams, this includes data stream creation and the creation of a stream’s backing indices. + Changes to component templates do not affect existing indices, including a stream’s backing indices.

+

You can use C-style /* *\\/ block comments in component templates. + You can include comments anywhere in the request body except before the opening curly bracket.

+

Applying component templates

+

You cannot directly apply a component template to a data stream or index. + To be applied, a component template must be included in an index template's composed_of list.

+ - ``_ + ``_ :param name: Name of the component template to create. Elasticsearch includes the following built-in component templates: `logs-mappings`; `logs-settings`; diff --git a/elasticsearch_serverless/_async/client/connector.py b/elasticsearch_serverless/_async/client/connector.py index 79ffd7d..e76a1cc 100644 --- a/elasticsearch_serverless/_async/client/connector.py +++ b/elasticsearch_serverless/_async/client/connector.py @@ -43,10 +43,13 @@ async def check_in( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Check in a connector. Update the `last_seen` field in the connector and set it - to the current timestamp. + .. raw:: html - ``_ +

Check in a connector.

+

Update the last_seen field in the connector and set it to the current timestamp.

+ + + ``_ :param connector_id: The unique identifier of the connector to be checked in """ @@ -82,20 +85,26 @@ async def delete( delete_sync_jobs: t.Optional[bool] = None, error_trace: t.Optional[bool] = None, filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, + hard: t.Optional[bool] = None, human: t.Optional[bool] = None, pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Delete a connector. Removes a connector and associated sync jobs. This is a destructive - action that is not recoverable. NOTE: This action doesn’t delete any API keys, - ingest pipelines, or data indices associated with the connector. These need to - be removed manually. + .. raw:: html + +

Delete a connector.

+

Removes a connector and associated sync jobs. + This is a destructive action that is not recoverable. + NOTE: This action doesn’t delete any API keys, ingest pipelines, or data indices associated with the connector. + These need to be removed manually.

- ``_ + + ``_ :param connector_id: The unique identifier of the connector to be deleted :param delete_sync_jobs: A flag indicating if associated sync jobs should be also removed. Defaults to false. + :param hard: A flag indicating if the connector should be hard deleted. """ if connector_id in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'connector_id'") @@ -108,6 +117,8 @@ async def delete( __query["error_trace"] = error_trace if filter_path is not None: __query["filter_path"] = filter_path + if hard is not None: + __query["hard"] = hard if human is not None: __query["human"] = human if pretty is not None: @@ -131,14 +142,21 @@ async def get( error_trace: t.Optional[bool] = None, filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, human: t.Optional[bool] = None, + include_deleted: t.Optional[bool] = None, pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Get a connector. Get the details about a connector. + .. raw:: html + +

Get a connector.

+

Get the details about a connector.

+ - ``_ + ``_ :param connector_id: The unique identifier of the connector + :param include_deleted: A flag to indicate if the desired connector should be + fetched, even if it was soft-deleted. """ if connector_id in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'connector_id'") @@ -151,6 +169,8 @@ async def get( __query["filter_path"] = filter_path if human is not None: __query["human"] = human + if include_deleted is not None: + __query["include_deleted"] = include_deleted if pretty is not None: __query["pretty"] = pretty __headers = {"accept": "application/json"} @@ -175,6 +195,7 @@ async def list( filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, from_: t.Optional[int] = None, human: t.Optional[bool] = None, + include_deleted: t.Optional[bool] = None, index_name: t.Optional[t.Union[str, t.Sequence[str]]] = None, pretty: t.Optional[bool] = None, query: t.Optional[str] = None, @@ -182,13 +203,19 @@ async def list( size: t.Optional[int] = None, ) -> ObjectApiResponse[t.Any]: """ - Get all connectors. Get information about all connectors. + .. raw:: html - ``_ +

Get all connectors.

+

Get information about all connectors.

+ + + ``_ :param connector_name: A comma-separated list of connector names to fetch connector documents for :param from_: Starting offset (default: 0) + :param include_deleted: A flag to indicate if the desired connector should be + fetched, even if it was soft-deleted. :param index_name: A comma-separated list of connector index names to fetch connector documents for :param query: A wildcard query string that filters connectors with matching name, @@ -210,6 +237,8 @@ async def list( __query["from"] = from_ if human is not None: __query["human"] = human + if include_deleted is not None: + __query["include_deleted"] = include_deleted if index_name is not None: __query["index_name"] = index_name if pretty is not None: @@ -257,13 +286,15 @@ async def post( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Create a connector. Connectors are Elasticsearch integrations that bring content - from third-party data sources, which can be deployed on Elastic Cloud or hosted - on your own infrastructure. Elastic managed connectors (Native connectors) are - a managed service on Elastic Cloud. Self-managed connectors (Connector clients) - are self-managed on your infrastructure. + .. raw:: html + +

Create a connector.

+

Connectors are Elasticsearch integrations that bring content from third-party data sources, which can be deployed on Elastic Cloud or hosted on your own infrastructure. + Elastic managed connectors (Native connectors) are a managed service on Elastic Cloud. + Self-managed connectors (Connector clients) are self-managed on your infrastructure.

- ``_ + + ``_ :param description: :param index_name: @@ -340,9 +371,12 @@ async def put( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Create or update a connector. + .. raw:: html + +

Create or update a connector.

+ - ``_ + ``_ :param connector_id: The unique identifier of the connector to be created or updated. ID is auto-generated if not provided. @@ -410,12 +444,14 @@ async def sync_job_cancel( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Cancel a connector sync job. Cancel a connector sync job, which sets the status - to cancelling and updates `cancellation_requested_at` to the current time. The - connector service is then responsible for setting the status of connector sync - jobs to cancelled. + .. raw:: html - ``_ +

Cancel a connector sync job.

+

Cancel a connector sync job, which sets the status to cancelling and updates cancellation_requested_at to the current time. + The connector service is then responsible for setting the status of connector sync jobs to cancelled.

+ + + ``_ :param connector_sync_job_id: The unique identifier of the connector sync job """ @@ -458,10 +494,14 @@ async def sync_job_delete( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Delete a connector sync job. Remove a connector sync job and its associated data. - This is a destructive action that is not recoverable. + .. raw:: html + +

Delete a connector sync job.

+

Remove a connector sync job and its associated data. + This is a destructive action that is not recoverable.

- ``_ + + ``_ :param connector_sync_job_id: The unique identifier of the connector sync job to be deleted @@ -503,9 +543,12 @@ async def sync_job_get( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Get a connector sync job. + .. raw:: html + +

Get a connector sync job.

+ - ``_ + ``_ :param connector_sync_job_id: The unique identifier of the connector sync job """ @@ -572,10 +615,13 @@ async def sync_job_list( ] = None, ) -> ObjectApiResponse[t.Any]: """ - Get all connector sync jobs. Get information about all stored connector sync - jobs listed by their creation date in ascending order. + .. raw:: html - ``_ +

Get all connector sync jobs.

+

Get information about all stored connector sync jobs listed by their creation date in ascending order.

+ + + ``_ :param connector_id: A connector id to fetch connector sync jobs for :param from_: Starting offset (default: 0) @@ -635,10 +681,13 @@ async def sync_job_post( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Create a connector sync job. Create a connector sync job document in the internal - index and initialize its counters and timestamps with default values. + .. raw:: html + +

Create a connector sync job.

+

Create a connector sync job document in the internal index and initialize its counters and timestamps with default values.

- ``_ + + ``_ :param id: The id of the associated connector :param job_type: @@ -688,10 +737,13 @@ async def update_active_filtering( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Activate the connector draft filter. Activates the valid draft filtering for - a connector. + .. raw:: html + +

Activate the connector draft filter.

+

Activates the valid draft filtering for a connector.

+ - ``_ + ``_ :param connector_id: The unique identifier of the connector to be updated """ @@ -735,13 +787,16 @@ async def update_api_key_id( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Update the connector API key ID. Update the `api_key_id` and `api_key_secret_id` - fields of a connector. You can specify the ID of the API key used for authorization - and the ID of the connector secret where the API key is stored. The connector - secret ID is required only for Elastic managed (native) connectors. Self-managed - connectors (connector clients) do not use this field. + .. raw:: html - ``_ +

Update the connector API key ID.

+

Update the api_key_id and api_key_secret_id fields of a connector. + You can specify the ID of the API key used for authorization and the ID of the connector secret where the API key is stored. + The connector secret ID is required only for Elastic managed (native) connectors. + Self-managed connectors (connector clients) do not use this field.

+ + + ``_ :param connector_id: The unique identifier of the connector to be updated :param api_key_id: @@ -794,10 +849,13 @@ async def update_configuration( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Update the connector configuration. Update the configuration field in the connector - document. + .. raw:: html + +

Update the connector configuration.

+

Update the configuration field in the connector document.

- ``_ + + ``_ :param connector_id: The unique identifier of the connector to be updated :param configuration: @@ -849,12 +907,15 @@ async def update_error( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Update the connector error field. Set the error field for the connector. If the - error provided in the request body is non-null, the connector’s status is updated - to error. Otherwise, if the error is reset to null, the connector status is updated - to connected. + .. raw:: html + +

Update the connector error field.

+

Set the error field for the connector. + If the error provided in the request body is non-null, the connector’s status is updated to error. + Otherwise, if the error is reset to null, the connector status is updated to connected.

+ - ``_ + ``_ :param connector_id: The unique identifier of the connector to be updated :param error: @@ -907,12 +968,15 @@ async def update_filtering( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Update the connector filtering. Update the draft filtering configuration of a - connector and marks the draft validation state as edited. The filtering draft - is activated once validated by the running Elastic connector service. The filtering - property is used to configure sync rules (both basic and advanced) for a connector. + .. raw:: html - ``_ +

Update the connector filtering.

+

Update the draft filtering configuration of a connector and marks the draft validation state as edited. + The filtering draft is activated once validated by the running Elastic connector service. + The filtering property is used to configure sync rules (both basic and advanced) for a connector.

+ + + ``_ :param connector_id: The unique identifier of the connector to be updated :param advanced_snippet: @@ -967,8 +1031,11 @@ async def update_filtering_validation( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Update the connector draft filtering validation. Update the draft filtering validation - info for a connector. + .. raw:: html + +

Update the connector draft filtering validation.

+

Update the draft filtering validation info for a connector.

+ ``_ @@ -1021,10 +1088,13 @@ async def update_index_name( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Update the connector index name. Update the `index_name` field of a connector, - specifying the index where the data ingested by the connector is stored. + .. raw:: html + +

Update the connector index name.

+

Update the index_name field of a connector, specifying the index where the data ingested by the connector is stored.

+ - ``_ + ``_ :param connector_id: The unique identifier of the connector to be updated :param index_name: @@ -1076,9 +1146,12 @@ async def update_name( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Update the connector name and description. + .. raw:: html - ``_ +

Update the connector name and description.

+ + + ``_ :param connector_id: The unique identifier of the connector to be updated :param description: @@ -1130,7 +1203,10 @@ async def update_native( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Update the connector is_native flag. + .. raw:: html + +

Update the connector is_native flag.

+ ``_ @@ -1183,10 +1259,13 @@ async def update_pipeline( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Update the connector pipeline. When you create a new connector, the configuration - of an ingest pipeline is populated with default settings. + .. raw:: html + +

Update the connector pipeline.

+

When you create a new connector, the configuration of an ingest pipeline is populated with default settings.

+ - ``_ + ``_ :param connector_id: The unique identifier of the connector to be updated :param pipeline: @@ -1237,9 +1316,12 @@ async def update_scheduling( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Update the connector scheduling. + .. raw:: html - ``_ +

Update the connector scheduling.

+ + + ``_ :param connector_id: The unique identifier of the connector to be updated :param scheduling: @@ -1290,9 +1372,12 @@ async def update_service_type( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Update the connector service type. + .. raw:: html + +

Update the connector service type.

- ``_ + + ``_ :param connector_id: The unique identifier of the connector to be updated :param service_type: @@ -1350,9 +1435,12 @@ async def update_status( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Update the connector status. + .. raw:: html + +

Update the connector status.

+ - ``_ + ``_ :param connector_id: The unique identifier of the connector to be updated :param status: diff --git a/elasticsearch_serverless/_async/client/enrich.py b/elasticsearch_serverless/_async/client/enrich.py index b544bf0..541adea 100644 --- a/elasticsearch_serverless/_async/client/enrich.py +++ b/elasticsearch_serverless/_async/client/enrich.py @@ -37,9 +37,13 @@ async def delete_policy( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Delete an enrich policy. Deletes an existing enrich policy and its enrich index. + .. raw:: html - ``_ +

Delete an enrich policy. + Deletes an existing enrich policy and its enrich index.

+ + + ``_ :param name: Enrich policy to delete. :param master_timeout: Period to wait for a connection to the master node. @@ -82,9 +86,13 @@ async def execute_policy( wait_for_completion: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Run an enrich policy. Create the enrich index for an existing enrich policy. + .. raw:: html + +

Run an enrich policy. + Create the enrich index for an existing enrich policy.

+ - ``_ + ``_ :param name: Enrich policy to execute. :param master_timeout: Period to wait for a connection to the master node. @@ -130,9 +138,13 @@ async def get_policy( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Get an enrich policy. Returns information about an enrich policy. + .. raw:: html - ``_ +

Get an enrich policy. + Returns information about an enrich policy.

+ + + ``_ :param name: Comma-separated list of enrich policy names used to limit the request. To return information for all enrich policies, omit this parameter. @@ -184,9 +196,13 @@ async def put_policy( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Create an enrich policy. Creates an enrich policy. + .. raw:: html + +

Create an enrich policy. + Creates an enrich policy.

+ - ``_ + ``_ :param name: Name of the enrich policy to create or update. :param geo_match: Matches enrich data to incoming documents based on a `geo_shape` diff --git a/elasticsearch_serverless/_async/client/eql.py b/elasticsearch_serverless/_async/client/eql.py index f0395ef..524604f 100644 --- a/elasticsearch_serverless/_async/client/eql.py +++ b/elasticsearch_serverless/_async/client/eql.py @@ -36,10 +36,14 @@ async def delete( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Delete an async EQL search. Delete an async EQL search or a stored synchronous - EQL search. The API also deletes results for the search. + .. raw:: html - ``_ +

Delete an async EQL search. + Delete an async EQL search or a stored synchronous EQL search. + The API also deletes results for the search.

+ + + ``_ :param id: Identifier for the search to delete. A search ID is provided in the EQL search API's response for an async search. A search ID is also provided @@ -83,10 +87,13 @@ async def get( ] = None, ) -> ObjectApiResponse[t.Any]: """ - Get async EQL search results. Get the current status and available results for - an async EQL search or a stored synchronous EQL search. + .. raw:: html + +

Get async EQL search results. + Get the current status and available results for an async EQL search or a stored synchronous EQL search.

+ - ``_ + ``_ :param id: Identifier for the search. :param keep_alive: Period for which the search and its results are stored on @@ -134,10 +141,13 @@ async def get_status( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Get the async EQL status. Get the current status for an async EQL search or a - stored synchronous EQL search without returning results. + .. raw:: html - ``_ +

Get the async EQL status. + Get the current status for an async EQL search or a stored synchronous EQL search without returning results.

+ + + ``_ :param id: Identifier for the search. """ @@ -229,17 +239,27 @@ async def search( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Get EQL search results. Returns search results for an Event Query Language (EQL) - query. EQL assumes each document in a data stream or index corresponds to an - event. + .. raw:: html + +

Get EQL search results. + Returns search results for an Event Query Language (EQL) query. + EQL assumes each document in a data stream or index corresponds to an event.

+ - ``_ + ``_ :param index: The name of the index to scope the operation :param query: EQL query you wish to run. :param allow_no_indices: - :param allow_partial_search_results: - :param allow_partial_sequence_results: + :param allow_partial_search_results: Allow query execution also in case of shard + failures. If true, the query will keep running and will return results based + on the available shards. For sequences, the behavior can be further refined + using allow_partial_sequence_results + :param allow_partial_sequence_results: This flag applies only to sequences and + has effect only if allow_partial_search_results=true. If true, the sequence + query will return results based on the available shards, ignoring the others. + If false, the sequence query will return successfully, but will always have + empty results. :param case_sensitive: :param event_category_field: Field containing the event classification, such as process, file, or network. diff --git a/elasticsearch_serverless/_async/client/esql.py b/elasticsearch_serverless/_async/client/esql.py index 43b14a9..0093694 100644 --- a/elasticsearch_serverless/_async/client/esql.py +++ b/elasticsearch_serverless/_async/client/esql.py @@ -30,6 +30,7 @@ class EsqlClient(NamespacedClient): "query", "columnar", "filter", + "include_ccs_metadata", "locale", "params", "profile", @@ -56,10 +57,9 @@ async def query( ] ] = None, human: t.Optional[bool] = None, + include_ccs_metadata: t.Optional[bool] = None, locale: t.Optional[str] = None, - params: t.Optional[ - t.Sequence[t.Union[None, bool, float, int, str, t.Any]] - ] = None, + params: t.Optional[t.Sequence[t.Union[None, bool, float, int, str]]] = None, pretty: t.Optional[bool] = None, profile: t.Optional[bool] = None, tables: t.Optional[ @@ -68,8 +68,11 @@ async def query( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Run an ES|QL query. Get search results for an ES|QL (Elasticsearch query language) - query. + .. raw:: html + +

Run an ES|QL query. + Get search results for an ES|QL (Elasticsearch query language) query.

+ ``_ @@ -88,6 +91,10 @@ async def query( :param filter: Specify a Query DSL query in the filter parameter to filter the set of documents that an ES|QL query runs on. :param format: A short version of the Accept header, e.g. json, yaml. + :param include_ccs_metadata: When set to `true` and performing a cross-cluster + query, the response will include an extra `_clusters` object with information + about the clusters that participated in the search along with info such as + shards count. :param locale: :param params: To avoid any attempts of hacking or code injection, extract the values in a separate list of parameters. Use question mark placeholders (?) @@ -126,6 +133,8 @@ async def query( __body["columnar"] = columnar if filter is not None: __body["filter"] = filter + if include_ccs_metadata is not None: + __body["include_ccs_metadata"] = include_ccs_metadata if locale is not None: __body["locale"] = locale if params is not None: diff --git a/elasticsearch_serverless/_async/client/graph.py b/elasticsearch_serverless/_async/client/graph.py index 1cda9f1..a8c35db 100644 --- a/elasticsearch_serverless/_async/client/graph.py +++ b/elasticsearch_serverless/_async/client/graph.py @@ -45,16 +45,17 @@ async def explore( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Explore graph analytics. Extract and summarize information about the documents - and terms in an Elasticsearch data stream or index. The easiest way to understand - the behavior of this API is to use the Graph UI to explore connections. An initial - request to the `_explore` API contains a seed query that identifies the documents - of interest and specifies the fields that define the vertices and connections - you want to include in the graph. Subsequent requests enable you to spider out - from one more vertices of interest. You can exclude vertices that have already - been returned. + .. raw:: html - ``_ +

Explore graph analytics. + Extract and summarize information about the documents and terms in an Elasticsearch data stream or index. + The easiest way to understand the behavior of this API is to use the Graph UI to explore connections. + An initial request to the _explore API contains a seed query that identifies the documents of interest and specifies the fields that define the vertices and connections you want to include in the graph. + Subsequent requests enable you to spider out from one more vertices of interest. + You can exclude vertices that have already been returned.

+ + + ``_ :param index: Name of the index. :param connections: Specifies or more fields from which you want to extract terms diff --git a/elasticsearch_serverless/_async/client/indices.py b/elasticsearch_serverless/_async/client/indices.py index 7cc94d4..13c38d7 100644 --- a/elasticsearch_serverless/_async/client/indices.py +++ b/elasticsearch_serverless/_async/client/indices.py @@ -49,22 +49,42 @@ async def add_block( timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, ) -> ObjectApiResponse[t.Any]: """ - Add an index block. Limits the operations allowed on an index by blocking specific - operation types. - - ``_ - - :param index: A comma separated list of indices to add a block to - :param block: The block to add (one of read, write, read_only or metadata) - :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) - :param expand_wildcards: Whether to expand wildcard expression to concrete indices - that are open, closed or both. - :param ignore_unavailable: Whether specified concrete indices should be ignored - when unavailable (missing or closed) - :param master_timeout: Specify timeout for connection to master - :param timeout: Explicit operation timeout + .. raw:: html + +

Add an index block.

+

Add an index block to an index. + Index blocks limit the operations allowed on an index by blocking specific operation types.

+ + + ``_ + + :param index: A comma-separated list or wildcard expression of index names used + to limit the request. By default, you must explicitly name the indices you + are adding blocks to. To allow the adding of blocks to indices with `_all`, + `*`, or other wildcard expressions, change the `action.destructive_requires_name` + setting to `false`. You can update this setting in the `elasticsearch.yml` + file or by using the cluster update settings API. + :param block: The block type to add to the index. + :param allow_no_indices: If `false`, the request returns an error if any wildcard + expression, index alias, or `_all` value targets only missing or closed indices. + This behavior applies even if the request targets other open indices. For + example, a request targeting `foo*,bar*` returns an error if an index starts + with `foo` but no index starts with `bar`. + :param expand_wildcards: The type of index that wildcard patterns can match. + If the request can target data streams, this argument determines whether + wildcard expressions match hidden data streams. It supports comma-separated + values, such as `open,hidden`. + :param ignore_unavailable: If `false`, the request returns an error if it targets + a missing or closed index. + :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. It can also be set to `-1` to indicate that the request should + never timeout. + :param timeout: The period to wait for a response from all relevant nodes in + the cluster after updating the cluster metadata. If no response is received + before the timeout expires, the cluster metadata update still applies but + the response will indicate that it was not completely acknowledged. It can + also be set to `-1` to indicate that the request should never timeout. """ if index in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'index'") @@ -137,14 +157,17 @@ async def analyze( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Get tokens from text analysis. The analyze API performs analysis on a text string - and returns the resulting tokens. Generating excessive amount of tokens may cause - a node to run out of memory. The `index.analyze.max_token_count` setting enables - you to limit the number of tokens that can be produced. If more than this limit - of tokens gets generated, an error occurs. The `_analyze` endpoint without a - specified index will always use `10000` as its limit. + .. raw:: html - ``_ +

Get tokens from text analysis. + The analyze API performs analysis on a text string and returns the resulting tokens.

+

Generating excessive amount of tokens may cause a node to run out of memory. + The index.analyze.max_token_count setting enables you to limit the number of tokens that can be produced. + If more than this limit of tokens gets generated, an error occurs. + The _analyze endpoint without a specified index will always use 10000 as its limit.

+ + + ``_ :param index: Index used to derive the analyzer. If specified, the `analyzer` or field parameter overrides this value. If no index is specified or the @@ -240,28 +263,29 @@ async def create( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Create an index. You can use the create index API to add a new index to an Elasticsearch - cluster. When creating an index, you can specify the following: * Settings for - the index. * Mappings for fields in the index. * Index aliases **Wait for active - shards** By default, index creation will only return a response to the client - when the primary copies of each shard have been started, or the request times - out. The index creation response will indicate what happened. For example, `acknowledged` - indicates whether the index was successfully created in the cluster, `while shards_acknowledged` - indicates whether the requisite number of shard copies were started for each - shard in the index before timing out. Note that it is still possible for either - `acknowledged` or `shards_acknowledged` to be `false`, but for the index creation - to be successful. These values simply indicate whether the operation completed - before the timeout. If `acknowledged` is false, the request timed out before - the cluster state was updated with the newly created index, but it probably will - be created sometime soon. If `shards_acknowledged` is false, then the request - timed out before the requisite number of shards were started (by default just - the primaries), even if the cluster state was successfully updated to reflect - the newly created index (that is to say, `acknowledged` is `true`). You can change - the default of only waiting for the primary shards to start through the index - setting `index.write.wait_for_active_shards`. Note that changing this setting - will also affect the `wait_for_active_shards` value on all subsequent write operations. - - ``_ + .. raw:: html + +

Create an index. + You can use the create index API to add a new index to an Elasticsearch cluster. + When creating an index, you can specify the following:

+
    +
  • Settings for the index.
    • +
  • Mappings for fields in the index.
    • +
  • Index aliases
    • +
+

Wait for active shards

+

By default, index creation will only return a response to the client when the primary copies of each shard have been started, or the request times out. + The index creation response will indicate what happened. + For example, acknowledged indicates whether the index was successfully created in the cluster, while shards_acknowledged indicates whether the requisite number of shard copies were started for each shard in the index before timing out. + Note that it is still possible for either acknowledged or shards_acknowledged to be false, but for the index creation to be successful. + These values simply indicate whether the operation completed before the timeout. + If acknowledged is false, the request timed out before the cluster state was updated with the newly created index, but it probably will be created sometime soon. + If shards_acknowledged is false, then the request timed out before the requisite number of shards were started (by default just the primaries), even if the cluster state was successfully updated to reflect the newly created index (that is to say, acknowledged is true).

+

You can change the default of only waiting for the primary shards to start through the index setting index.write.wait_for_active_shards. + Note that changing this setting will also affect the wait_for_active_shards value on all subsequent write operations.

+ + + ``_ :param index: Name of the index you wish to create. :param aliases: Aliases for the index. @@ -332,10 +356,13 @@ async def create_data_stream( timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, ) -> ObjectApiResponse[t.Any]: """ - Create a data stream. Creates a data stream. You must have a matching index template - with data stream enabled. + .. raw:: html - ``_ +

Create a data stream.

+

You must have a matching index template with data stream enabled.

+ + + ``_ :param name: Name of the data stream, which must meet the following criteria: Lowercase only; Cannot include `\\`, `/`, `*`, `?`, `"`, `<`, `>`, `|`, `,`, @@ -398,13 +425,17 @@ async def delete( timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, ) -> ObjectApiResponse[t.Any]: """ - Delete indices. Deleting an index deletes its documents, shards, and metadata. - It does not delete related Kibana components, such as data views, visualizations, - or dashboards. You cannot delete the current write index of a data stream. To - delete the index, you must roll over the data stream so a new write index is - created. You can then use the delete index API to delete the previous write index. + .. raw:: html + +

Delete indices. + Deleting an index deletes its documents, shards, and metadata. + It does not delete related Kibana components, such as data views, visualizations, or dashboards.

+

You cannot delete the current write index of a data stream. + To delete the index, you must roll over the data stream so a new write index is created. + You can then use the delete index API to delete the previous write index.

- ``_ + + ``_ :param index: Comma-separated list of indices to delete. You cannot specify index aliases. By default, this parameter does not support wildcards (`*`) or `_all`. @@ -472,9 +503,13 @@ async def delete_alias( timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, ) -> ObjectApiResponse[t.Any]: """ - Delete an alias. Removes a data stream or index from an alias. + .. raw:: html + +

Delete an alias. + Removes a data stream or index from an alias.

+ - ``_ + ``_ :param index: Comma-separated list of data streams or indices used to limit the request. Supports wildcards (`*`). @@ -535,9 +570,13 @@ async def delete_data_stream( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Delete data streams. Deletes one or more data streams and their backing indices. + .. raw:: html + +

Delete data streams. + Deletes one or more data streams and their backing indices.

- ``_ + + ``_ :param name: Comma-separated list of data streams to delete. Wildcard (`*`) expressions are supported. @@ -587,12 +626,15 @@ async def delete_index_template( timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, ) -> ObjectApiResponse[t.Any]: """ - Delete an index template. The provided may contain multiple - template names separated by a comma. If multiple template names are specified - then there is no wildcard support and the provided names should match completely - with existing templates. + .. raw:: html + +

Delete an index template. + The provided may contain multiple template names separated by a comma. If multiple template + names are specified then there is no wildcard support and the provided names should match completely with + existing templates.

+ - ``_ + ``_ :param name: Comma-separated list of index template names used to limit the request. Wildcard (*) expressions are supported. @@ -653,9 +695,13 @@ async def exists( pretty: t.Optional[bool] = None, ) -> HeadApiResponse: """ - Check indices. Check if one or more indices, index aliases, or data streams exist. + .. raw:: html - ``_ +

Check indices. + Check if one or more indices, index aliases, or data streams exist.

+ + + ``_ :param index: Comma-separated list of data streams, indices, and aliases. Supports wildcards (`*`). @@ -731,9 +777,13 @@ async def exists_alias( pretty: t.Optional[bool] = None, ) -> HeadApiResponse: """ - Check aliases. Checks if one or more data stream or index aliases exist. + .. raw:: html - ``_ +

Check aliases.

+

Check if one or more data stream or index aliases exist.

+ + + ``_ :param name: Comma-separated list of aliases to check. Supports wildcards (`*`). :param index: Comma-separated list of data streams or indices used to limit the @@ -802,9 +852,13 @@ async def exists_index_template( pretty: t.Optional[bool] = None, ) -> HeadApiResponse: """ - Check index templates. Check whether index templates exist. + .. raw:: html + +

Check index templates.

+

Check whether index templates exist.

- ``_ + + ``_ :param name: Comma-separated list of index template names used to limit the request. Wildcard (*) expressions are supported. @@ -850,12 +904,13 @@ async def explain_data_lifecycle( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Get the status for a data stream lifecycle. Get information about an index or - data stream's current data stream lifecycle status, such as time since index - creation, time since rollover, the lifecycle configuration managing the index, - or any errors encountered during lifecycle execution. + .. raw:: html + +

Get the status for a data stream lifecycle. + Get information about an index or data stream's current data stream lifecycle status, such as time since index creation, time since rollover, the lifecycle configuration managing the index, or any errors encountered during lifecycle execution.

- ``_ + + ``_ :param index: The name of the index to explain :param include_defaults: indicates if the API should return the default values @@ -920,10 +975,14 @@ async def get( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Get index information. Get information about one or more indices. For data streams, - the API returns information about the stream’s backing indices. + .. raw:: html + +

Get index information. + Get information about one or more indices. For data streams, the API returns information about the + stream’s backing indices.

+ - ``_ + ``_ :param index: Comma-separated list of data streams, indices, and index aliases used to limit the request. Wildcard expressions (*) are supported. @@ -1010,7 +1069,13 @@ async def get_alias( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Get aliases. Retrieves information for one or more data stream or index aliases. + .. raw:: html + +

Get aliases. + Retrieves information for one or more data stream or index aliases.

+ + + ``_ :param index: Comma-separated list of data streams or indices used to limit the request. Supports wildcards (`*`). To target all data streams and indices, @@ -1091,10 +1156,13 @@ async def get_data_lifecycle( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Get data stream lifecycles. Retrieves the data stream lifecycle configuration - of one or more data streams. + .. raw:: html - ``_ +

Get data stream lifecycles.

+

Get the data stream lifecycle configuration of one or more data streams.

+ + + ``_ :param name: Comma-separated list of data streams to limit the request. Supports wildcards (`*`). To target all data streams, omit this parameter or use `*` @@ -1158,9 +1226,13 @@ async def get_data_stream( verbose: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Get data streams. Retrieves information about one or more data streams. + .. raw:: html - ``_ +

Get data streams.

+

Get information about one or more data streams.

+ + + ``_ :param name: Comma-separated list of data stream names used to limit the request. Wildcard (`*`) expressions are supported. If omitted, all data streams are @@ -1224,9 +1296,13 @@ async def get_index_template( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Get index templates. Get information about one or more index templates. + .. raw:: html - ``_ +

Get index templates. + Get information about one or more index templates.

+ + + ``_ :param name: Comma-separated list of index template names used to limit the request. Wildcard (*) expressions are supported. @@ -1297,10 +1373,13 @@ async def get_mapping( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Get mapping definitions. For data streams, the API retrieves mappings for the - stream’s backing indices. + .. raw:: html + +

Get mapping definitions. + For data streams, the API retrieves mappings for the stream’s backing indices.

- ``_ + + ``_ :param index: Comma-separated list of data streams, indices, and aliases used to limit the request. Supports wildcards (`*`). To target all data streams @@ -1382,10 +1461,14 @@ async def get_settings( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Get index settings. Get setting information for one or more indices. For data - streams, it returns setting information for the stream's backing indices. + .. raw:: html + +

Get index settings. + Get setting information for one or more indices. + For data streams, it returns setting information for the stream's backing indices.

+ - ``_ + ``_ :param index: Comma-separated list of data streams, indices, and aliases used to limit the request. Supports wildcards (`*`). To target all data streams @@ -1469,14 +1552,20 @@ async def migrate_to_data_stream( timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, ) -> ObjectApiResponse[t.Any]: """ - Convert an index alias to a data stream. Converts an index alias to a data stream. - You must have a matching index template that is data stream enabled. The alias - must meet the following criteria: The alias must have a write index; All indices - for the alias must have a `@timestamp` field mapping of a `date` or `date_nanos` - field type; The alias must not have any filters; The alias must not use custom - routing. If successful, the request removes the alias and creates a data stream - with the same name. The indices for the alias become hidden backing indices for - the stream. The write index for the alias becomes the write index for the stream. + .. raw:: html + +

Convert an index alias to a data stream. + Converts an index alias to a data stream. + You must have a matching index template that is data stream enabled. + The alias must meet the following criteria: + The alias must have a write index; + All indices for the alias must have a @timestamp field mapping of a date or date_nanos field type; + The alias must not have any filters; + The alias must not use custom routing. + If successful, the request removes the alias and creates a data stream with the same name. + The indices for the alias become hidden backing indices for the stream. + The write index for the alias becomes the write index for the stream.

+ ``_ @@ -1528,8 +1617,11 @@ async def modify_data_stream( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Update data streams. Performs one or more data stream modification actions in - a single atomic operation. + .. raw:: html + +

Update data streams. + Performs one or more data stream modification actions in a single atomic operation.

+ ``_ @@ -1591,7 +1683,11 @@ async def put_alias( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Create or update an alias. Adds a data stream or index to an alias. + .. raw:: html + +

Create or update an alias. + Adds a data stream or index to an alias.

+ ``_ @@ -1668,14 +1764,15 @@ async def put_alias( ) @_rewrite_parameters( - body_name="lifecycle", + body_fields=("data_retention", "downsampling", "enabled"), ) async def put_data_lifecycle( self, *, name: t.Union[str, t.Sequence[str]], - lifecycle: t.Optional[t.Mapping[str, t.Any]] = None, - body: t.Optional[t.Mapping[str, t.Any]] = None, + data_retention: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, + downsampling: t.Optional[t.Mapping[str, t.Any]] = None, + enabled: t.Optional[bool] = None, error_trace: t.Optional[bool] = None, expand_wildcards: t.Optional[ t.Union[ @@ -1690,16 +1787,28 @@ async def put_data_lifecycle( master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, pretty: t.Optional[bool] = None, timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, + body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Update data stream lifecycles. Update the data stream lifecycle of the specified - data streams. + .. raw:: html + +

Update data stream lifecycles. + Update the data stream lifecycle of the specified data streams.

+ ``_ :param name: Comma-separated list of data streams used to limit the request. Supports wildcards (`*`). To target all data streams use `*` or `_all`. - :param lifecycle: + :param data_retention: If defined, every document added to this data stream will + be stored at least for this time frame. Any time after this duration the + document could be deleted. When empty, every document in this data stream + will be stored indefinitely. + :param downsampling: The downsampling configuration to execute for the managed + backing index after rollover. + :param enabled: If defined, it turns data stream lifecycle on/off (`true`/`false`) + for this data stream. A data stream lifecycle that's disabled (enabled: `false`) + will have no effect on the data stream. :param expand_wildcards: Type of data stream that wildcard patterns can match. Supports comma-separated values, such as `open,hidden`. Valid values are: `all`, `hidden`, `open`, `closed`, `none`. @@ -1711,15 +1820,10 @@ async def put_data_lifecycle( """ if name in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'name'") - if lifecycle is None and body is None: - raise ValueError( - "Empty value passed for parameters 'lifecycle' and 'body', one of them should be set." - ) - elif lifecycle is not None and body is not None: - raise ValueError("Cannot set both 'lifecycle' and 'body'") __path_parts: t.Dict[str, str] = {"name": _quote(name)} __path = f'/_data_stream/{__path_parts["name"]}/_lifecycle' __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 expand_wildcards is not None: @@ -1734,8 +1838,18 @@ async def put_data_lifecycle( __query["pretty"] = pretty if timeout is not None: __query["timeout"] = timeout - __body = lifecycle if lifecycle is not None else body - __headers = {"accept": "application/json", "content-type": "application/json"} + if not __body: + if data_retention is not None: + __body["data_retention"] = data_retention + if downsampling is not None: + __body["downsampling"] = downsampling + if enabled is not None: + __body["enabled"] = enabled + 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] "PUT", __path, @@ -1785,34 +1899,30 @@ async def put_index_template( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Create or update an index template. Index templates define settings, mappings, - and aliases that can be applied automatically to new indices. Elasticsearch applies - templates to new indices based on an wildcard pattern that matches the index - name. Index templates are applied during data stream or index creation. For data - streams, these settings and mappings are applied when the stream's backing indices - are created. Settings and mappings specified in a create index API request override - any settings or mappings specified in an index template. Changes to index templates - do not affect existing indices, including the existing backing indices of a data - stream. You can use C-style `/* *\\/` block comments in index templates. You - can include comments anywhere in the request body, except before the opening - curly bracket. **Multiple matching templates** If multiple index templates match - the name of a new index or data stream, the template with the highest priority - is used. Multiple templates with overlapping index patterns at the same priority - are not allowed and an error will be thrown when attempting to create a template - matching an existing index template at identical priorities. **Composing aliases, - mappings, and settings** When multiple component templates are specified in the - `composed_of` field for an index template, they are merged in the order specified, - meaning that later component templates override earlier component templates. - Any mappings, settings, or aliases from the parent index template are merged - in next. Finally, any configuration on the index request itself is merged. Mapping - definitions are merged recursively, which means that later mapping components - can introduce new field mappings and update the mapping configuration. If a field - mapping is already contained in an earlier component, its definition will be - completely overwritten by the later one. This recursive merging strategy applies - not only to field mappings, but also root options like `dynamic_templates` and - `meta`. If an earlier component contains a `dynamic_templates` block, then by - default new `dynamic_templates` entries are appended onto the end. If an entry - already exists with the same key, then it is overwritten by the new definition. + .. raw:: html + +

Create or update an index template. + Index templates define settings, mappings, and aliases that can be applied automatically to new indices.

+

Elasticsearch applies templates to new indices based on an wildcard pattern that matches the index name. + Index templates are applied during data stream or index creation. + For data streams, these settings and mappings are applied when the stream's backing indices are created. + Settings and mappings specified in a create index API request override any settings or mappings specified in an index template. + Changes to index templates do not affect existing indices, including the existing backing indices of a data stream.

+

You can use C-style /* *\\/ block comments in index templates. + You can include comments anywhere in the request body, except before the opening curly bracket.

+

Multiple matching templates

+

If multiple index templates match the name of a new index or data stream, the template with the highest priority is used.

+

Multiple templates with overlapping index patterns at the same priority are not allowed and an error will be thrown when attempting to create a template matching an existing index template at identical priorities.

+

Composing aliases, mappings, and settings

+

When multiple component templates are specified in the composed_of field for an index template, they are merged in the order specified, meaning that later component templates override earlier component templates. + Any mappings, settings, or aliases from the parent index template are merged in next. + Finally, any configuration on the index request itself is merged. + Mapping definitions are merged recursively, which means that later mapping components can introduce new field mappings and update the mapping configuration. + If a field mapping is already contained in an earlier component, its definition will be completely overwritten by the later one. + This recursive merging strategy applies not only to field mappings, but also root options like dynamic_templates and meta. + If an earlier component contains a dynamic_templates block, then by default new dynamic_templates entries are appended onto the end. + If an entry already exists with the same key, then it is overwritten by the new definition.

+ ``_ @@ -1945,10 +2055,7 @@ async def put_mapping( ] = None, dynamic_date_formats: t.Optional[t.Sequence[str]] = None, dynamic_templates: t.Optional[ - t.Union[ - t.Mapping[str, t.Mapping[str, t.Any]], - t.Sequence[t.Mapping[str, t.Mapping[str, t.Any]]], - ] + t.Sequence[t.Mapping[str, t.Mapping[str, t.Any]]] ] = None, error_trace: t.Optional[bool] = None, expand_wildcards: t.Optional[ @@ -1976,29 +2083,31 @@ async def put_mapping( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Update field mappings. Add new fields to an existing data stream or index. You - can also use this API to change the search settings of existing fields and add - new properties to existing object fields. For data streams, these changes are - applied to all backing indices by default. **Add multi-fields to an existing - field** Multi-fields let you index the same field in different ways. You can - use this API to update the fields mapping parameter and enable multi-fields for - an existing field. WARNING: If an index (or data stream) contains documents when - you add a multi-field, those documents will not have values for the new multi-field. - You can populate the new multi-field with the update by query API. **Change supported - mapping parameters for an existing field** The documentation for each mapping - parameter indicates whether you can update it for an existing field using this - API. For example, you can use the update mapping API to update the `ignore_above` - parameter. **Change the mapping of an existing field** Except for supported mapping - parameters, you can't change the mapping or field type of an existing field. - Changing an existing field could invalidate data that's already indexed. If you - need to change the mapping of a field in a data stream's backing indices, refer - to documentation about modifying data streams. If you need to change the mapping - of a field in other indices, create a new index with the correct mapping and - reindex your data into that index. **Rename a field** Renaming a field would - invalidate data already indexed under the old field name. Instead, add an alias - field to create an alternate field name. - - ``_ + .. raw:: html + +

Update field mappings. + Add new fields to an existing data stream or index. + You can also use this API to change the search settings of existing fields and add new properties to existing object fields. + For data streams, these changes are applied to all backing indices by default.

+

Add multi-fields to an existing field

+

Multi-fields let you index the same field in different ways. + You can use this API to update the fields mapping parameter and enable multi-fields for an existing field. + WARNING: If an index (or data stream) contains documents when you add a multi-field, those documents will not have values for the new multi-field. + You can populate the new multi-field with the update by query API.

+

Change supported mapping parameters for an existing field

+

The documentation for each mapping parameter indicates whether you can update it for an existing field using this API. + For example, you can use the update mapping API to update the ignore_above parameter.

+

Change the mapping of an existing field

+

Except for supported mapping parameters, you can't change the mapping or field type of an existing field. + Changing an existing field could invalidate data that's already indexed.

+

If you need to change the mapping of a field in a data stream's backing indices, refer to documentation about modifying data streams. + If you need to change the mapping of a field in other indices, create a new index with the correct mapping and reindex your data into that index.

+

Rename a field

+

Renaming a field would invalidate data already indexed under the old field name. + Instead, add an alias field to create an alternate field name.

+ + + ``_ :param index: A comma-separated list of index names the mapping should be added to (supports wildcards); use `_all` or omit to add the mapping on all indices. @@ -2125,23 +2234,25 @@ async def put_settings( timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, ) -> ObjectApiResponse[t.Any]: """ - Update index settings. Changes dynamic index settings in real time. For data - streams, index setting changes are applied to all backing indices by default. - To revert a setting to the default value, use a null value. The list of per-index - settings that can be updated dynamically on live indices can be found in index - module documentation. To preserve existing settings from being updated, set the - `preserve_existing` parameter to `true`. NOTE: You can only define new analyzers - on closed indices. To add an analyzer, you must close the index, define the analyzer, - and reopen the index. You cannot close the write index of a data stream. To update - the analyzer for a data stream's write index and future backing indices, update - the analyzer in the index template used by the stream. Then roll over the data - stream to apply the new analyzer to the stream's write index and future backing - indices. This affects searches and any new data added to the stream after the - rollover. However, it does not affect the data stream's backing indices or their - existing data. To change the analyzer for existing backing indices, you must - create a new data stream and reindex your data into it. - - ``_ + .. raw:: html + +

Update index settings. + Changes dynamic index settings in real time. + For data streams, index setting changes are applied to all backing indices by default.

+

To revert a setting to the default value, use a null value. + The list of per-index settings that can be updated dynamically on live indices can be found in index module documentation. + To preserve existing settings from being updated, set the preserve_existing parameter to true.

+

NOTE: You can only define new analyzers on closed indices. + To add an analyzer, you must close the index, define the analyzer, and reopen the index. + You cannot close the write index of a data stream. + To update the analyzer for a data stream's write index and future backing indices, update the analyzer in the index template used by the stream. + Then roll over the data stream to apply the new analyzer to the stream's write index and future backing indices. + This affects searches and any new data added to the stream after the rollover. + However, it does not affect the data stream's backing indices or their existing data. + To change the analyzer for existing backing indices, you must create a new data stream and reindex your data into it.

+ + + ``_ :param settings: :param index: Comma-separated list of data streams, indices, and aliases used @@ -2234,21 +2345,21 @@ async def refresh( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Refresh an index. A refresh makes recent operations performed on one or more - indices available for search. For data streams, the API runs the refresh operation - on the stream’s backing indices. By default, Elasticsearch periodically refreshes - indices every second, but only on indices that have received one search request - or more in the last 30 seconds. You can change this default interval with the - `index.refresh_interval` setting. Refresh requests are synchronous and do not - return a response until the refresh operation completes. Refreshes are resource-intensive. - To ensure good cluster performance, it's recommended to wait for Elasticsearch's - periodic refresh rather than performing an explicit refresh when possible. If - your application workflow indexes documents and then runs a search to retrieve - the indexed document, it's recommended to use the index API's `refresh=wait_for` - query parameter option. This option ensures the indexing operation waits for - a periodic refresh before running the search. - - ``_ + .. raw:: html + +

Refresh an index. + A refresh makes recent operations performed on one or more indices available for search. + For data streams, the API runs the refresh operation on the stream’s backing indices.

+

By default, Elasticsearch periodically refreshes indices every second, but only on indices that have received one search request or more in the last 30 seconds. + You can change this default interval with the index.refresh_interval setting.

+

Refresh requests are synchronous and do not return a response until the refresh operation completes.

+

Refreshes are resource-intensive. + To ensure good cluster performance, it's recommended to wait for Elasticsearch's periodic refresh rather than performing an explicit refresh when possible.

+

If your application workflow indexes documents and then runs a search to retrieve the indexed document, it's recommended to use the index API's refresh=wait_for query parameter option. + This option ensures the indexing operation waits for a periodic refresh before running the search.

+ + + ``_ :param index: Comma-separated list of data streams, indices, and aliases used to limit the request. Supports wildcards (`*`). To target all data streams @@ -2316,10 +2427,14 @@ async def resolve_index( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Resolve indices. Resolve the names and/or index patterns for indices, aliases, - and data streams. Multiple patterns and remote clusters are supported. + .. raw:: html + +

Resolve indices. + Resolve the names and/or index patterns for indices, aliases, and data streams. + Multiple patterns and remote clusters are supported.

+ - ``_ + ``_ :param name: Comma-separated name(s) or index pattern(s) of the indices, aliases, and data streams to resolve. Resources on remote clusters can be specified @@ -2390,35 +2505,37 @@ async def rollover( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Roll over to a new index. TIP: It is recommended to use the index lifecycle rollover - action to automate rollovers. The rollover API creates a new index for a data - stream or index alias. The API behavior depends on the rollover target. **Roll - over a data stream** If you roll over a data stream, the API creates a new write - index for the stream. The stream's previous write index becomes a regular backing - index. A rollover also increments the data stream's generation. **Roll over an - index alias with a write index** TIP: Prior to Elasticsearch 7.9, you'd typically - use an index alias with a write index to manage time series data. Data streams - replace this functionality, require less maintenance, and automatically integrate - with data tiers. If an index alias points to multiple indices, one of the indices - must be a write index. The rollover API creates a new write index for the alias - with `is_write_index` set to `true`. The API also `sets is_write_index` to `false` - for the previous write index. **Roll over an index alias with one index** If - you roll over an index alias that points to only one index, the API creates a - new index for the alias and removes the original index from the alias. NOTE: - A rollover creates a new index and is subject to the `wait_for_active_shards` - setting. **Increment index names for an alias** When you roll over an index alias, - you can specify a name for the new index. If you don't specify a name and the - current index ends with `-` and a number, such as `my-index-000001` or `my-index-3`, - the new index name increments that number. For example, if you roll over an alias - with a current index of `my-index-000001`, the rollover creates a new index named - `my-index-000002`. This number is always six characters and zero-padded, regardless - of the previous index's name. If you use an index alias for time series data, - you can use date math in the index name to track the rollover date. For example, - you can create an alias that points to an index named ``. - If you create the index on May 6, 2099, the index's name is `my-index-2099.05.06-000001`. - If you roll over the alias on May 7, 2099, the new index's name is `my-index-2099.05.07-000002`. - - ``_ + .. raw:: html + +

Roll over to a new index. + TIP: It is recommended to use the index lifecycle rollover action to automate rollovers.

+

The rollover API creates a new index for a data stream or index alias. + The API behavior depends on the rollover target.

+

Roll over a data stream

+

If you roll over a data stream, the API creates a new write index for the stream. + The stream's previous write index becomes a regular backing index. + A rollover also increments the data stream's generation.

+

Roll over an index alias with a write index

+

TIP: Prior to Elasticsearch 7.9, you'd typically use an index alias with a write index to manage time series data. + Data streams replace this functionality, require less maintenance, and automatically integrate with data tiers.

+

If an index alias points to multiple indices, one of the indices must be a write index. + The rollover API creates a new write index for the alias with is_write_index set to true. + The API also sets is_write_index to false for the previous write index.

+

Roll over an index alias with one index

+

If you roll over an index alias that points to only one index, the API creates a new index for the alias and removes the original index from the alias.

+

NOTE: A rollover creates a new index and is subject to the wait_for_active_shards setting.

+

Increment index names for an alias

+

When you roll over an index alias, you can specify a name for the new index. + If you don't specify a name and the current index ends with - and a number, such as my-index-000001 or my-index-3, the new index name increments that number. + For example, if you roll over an alias with a current index of my-index-000001, the rollover creates a new index named my-index-000002. + This number is always six characters and zero-padded, regardless of the previous index's name.

+

If you use an index alias for time series data, you can use date math in the index name to track the rollover date. + For example, you can create an alias that points to an index named <my-index-{now/d}-000001>. + If you create the index on May 6, 2099, the index's name is my-index-2099.05.06-000001. + If you roll over the alias on May 7, 2099, the new index's name is my-index-2099.05.07-000002.

+ + + ``_ :param alias: Name of the data stream or index alias to roll over. :param new_index: Name of the index to create. Supports date math. Data streams @@ -2512,10 +2629,13 @@ async def simulate_index_template( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Simulate an index. Get the index configuration that would be applied to the specified - index from an existing index template. + .. raw:: html - ``_ +

Simulate an index. + Get the index configuration that would be applied to the specified index from an existing index template.

+ + + ``_ :param name: Name of the index to simulate :param include_defaults: If true, returns all relevant default configurations @@ -2590,10 +2710,13 @@ async def simulate_template( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Simulate an index template. Get the index configuration that would be applied - by a particular index template. + .. raw:: html + +

Simulate an index template. + Get the index configuration that would be applied by a particular index template.

- ``_ + + ``_ :param name: Name of the index template to simulate. To test a template configuration before you add it to the cluster, omit this parameter and specify the template @@ -2716,7 +2839,11 @@ async def update_aliases( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Create or update an alias. Adds a data stream or index to an alias. + .. raw:: html + +

Create or update an alias. + Adds a data stream or index to an alias.

+ ``_ @@ -2791,7 +2918,11 @@ async def validate_query( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Validate a query. Validates a query without running it. + .. raw:: html + +

Validate a query. + Validates a query without running it.

+ ``_ diff --git a/elasticsearch_serverless/_async/client/inference.py b/elasticsearch_serverless/_async/client/inference.py index 1e248fc..3fc933b 100644 --- a/elasticsearch_serverless/_async/client/inference.py +++ b/elasticsearch_serverless/_async/client/inference.py @@ -44,16 +44,19 @@ async def delete( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Delete an inference endpoint + .. raw:: html - ``_ +

Delete an inference endpoint

- :param inference_id: The inference Id + + ``_ + + :param inference_id: The inference identifier. :param task_type: The task type - :param dry_run: When true, the endpoint is not deleted, and a list of ingest - processors which reference this endpoint is returned + :param dry_run: When true, the endpoint is not deleted and a list of ingest processors + which reference this endpoint is returned. :param force: When true, the inference endpoint is forcefully deleted even if - it is still being used by ingest processors or semantic text fields + it is still being used by ingest processors or semantic text fields. """ if inference_id in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'inference_id'") @@ -109,9 +112,12 @@ async def get( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Get an inference endpoint + .. raw:: html - ``_ +

Get an inference endpoint

+ + + ``_ :param task_type: The task type :param inference_id: The inference Id @@ -172,17 +178,31 @@ async def inference( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Perform inference on the service + .. raw:: html - ``_ +

Perform inference on the service.

+

This API enables you to use machine learning models to perform specific tasks on data that you provide as an input. + It returns a response with the results of the tasks. + The inference endpoint you use can perform one specific task that has been defined when the endpoint was created with the create inference API.

+
+

info + The inference APIs enable you to use certain services, such as built-in machine learning models (ELSER, E5), models uploaded through Eland, Cohere, OpenAI, Azure, Google AI Studio, Google Vertex AI, Anthropic, Watsonx.ai, or Hugging Face. For built-in models and models uploaded through Eland, the inference APIs offer an alternative way to use and manage trained models. However, if you do not plan to use the inference APIs to use these models or if you want to use non-NLP models, use the machine learning trained model APIs.

+
- :param inference_id: The inference Id - :param input: Inference input. Either a string or an array of strings. - :param task_type: The task type - :param query: Query input, required for rerank task. Not required for other tasks. - :param task_settings: Optional task settings - :param timeout: Specifies the amount of time to wait for the inference request - to complete. + + ``_ + + :param inference_id: The unique identifier for the inference endpoint. + :param input: The text on which you want to perform the inference task. It can + be a single string or an array. > info > Inference endpoints for the `completion` + task type currently only support a single string as input. + :param task_type: The type of inference task that the model performs. + :param query: The query input, which is required only for the `rerank` task. + It is not required for other tasks. + :param task_settings: Task settings for the individual inference request. These + settings are specific to the task type you specified and override the task + settings specified when initializing the service. + :param timeout: The amount of time to wait for the inference request to complete. """ if inference_id in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'inference_id'") @@ -255,23 +275,20 @@ async def put( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Create an inference endpoint. When you create an inference endpoint, the associated - machine learning model is automatically deployed if it is not already running. - After creating the endpoint, wait for the model deployment to complete before - using it. To verify the deployment status, use the get trained model statistics - API. Look for `"state": "fully_allocated"` in the response and ensure that the - `"allocation_count"` matches the `"target_allocation_count"`. Avoid creating - multiple endpoints for the same model unless required, as each endpoint consumes - significant resources. IMPORTANT: The inference APIs enable you to use certain - services, such as built-in machine learning models (ELSER, E5), models uploaded - through Eland, Cohere, OpenAI, Mistral, Azure OpenAI, Google AI Studio, Google - Vertex AI, Anthropic, Watsonx.ai, or Hugging Face. For built-in models and models - uploaded through Eland, the inference APIs offer an alternative way to use and - manage trained models. However, if you do not plan to use the inference APIs - to use these models or if you want to use non-NLP models, use the machine learning - trained model APIs. + .. raw:: html + +

Create an inference endpoint. + When you create an inference endpoint, the associated machine learning model is automatically deployed if it is not already running. + After creating the endpoint, wait for the model deployment to complete before using it. + To verify the deployment status, use the get trained model statistics API. + Look for "state": "fully_allocated" in the response and ensure that the "allocation_count" matches the "target_allocation_count". + Avoid creating multiple endpoints for the same model unless required, as each endpoint consumes significant resources.

+

IMPORTANT: The inference APIs enable you to use certain services, such as built-in machine learning models (ELSER, E5), models uploaded through Eland, Cohere, OpenAI, Mistral, Azure OpenAI, Google AI Studio, Google Vertex AI, Anthropic, Watsonx.ai, or Hugging Face. + For built-in models and models uploaded through Eland, the inference APIs offer an alternative way to use and manage trained models. + However, if you do not plan to use the inference APIs to use these models or if you want to use non-NLP models, use the machine learning trained model APIs.

+ - ``_ + ``_ :param inference_id: The inference Id :param inference_config: diff --git a/elasticsearch_serverless/_async/client/ingest.py b/elasticsearch_serverless/_async/client/ingest.py index 9434d76..8b27ab9 100644 --- a/elasticsearch_serverless/_async/client/ingest.py +++ b/elasticsearch_serverless/_async/client/ingest.py @@ -38,9 +38,13 @@ async def delete_pipeline( timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, ) -> ObjectApiResponse[t.Any]: """ - Delete pipelines. Delete one or more ingest pipelines. + .. raw:: html - ``_ +

Delete pipelines. + Delete one or more ingest pipelines.

+ + + ``_ :param id: Pipeline ID or wildcard expression of pipeline IDs used to limit the request. To delete all ingest pipelines in a cluster, use a value of `*`. @@ -90,10 +94,14 @@ async def get_pipeline( summary: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Get pipelines. Get information about one or more ingest pipelines. This API returns - a local reference of the pipeline. + .. raw:: html + +

Get pipelines.

+

Get information about one or more ingest pipelines. + This API returns a local reference of the pipeline.

- ``_ + + ``_ :param id: Comma-separated list of pipeline IDs to retrieve. Wildcard (`*`) expressions are supported. To get all ingest pipelines, omit this parameter or use `*`. @@ -142,10 +150,13 @@ async def processor_grok( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Run a grok processor. Extract structured fields out of a single text field within - a document. You must choose which field to extract matched fields from, as well - as the grok pattern you expect will match. A grok pattern is like a regular expression - that supports aliased expressions that can be reused. + .. raw:: html + +

Run a grok processor. + Extract structured fields out of a single text field within a document. + You must choose which field to extract matched fields from, as well as the grok pattern you expect will match. + A grok pattern is like a regular expression that supports aliased expressions that can be reused.

+ ``_ """ @@ -201,7 +212,11 @@ async def put_pipeline( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Create or update a pipeline. Changes made using this API take effect immediately. + .. raw:: html + +

Create or update a pipeline. + Changes made using this API take effect immediately.

+ ``_ @@ -293,16 +308,19 @@ async def simulate( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Simulate a pipeline. Run an ingest pipeline against a set of provided documents. - You can either specify an existing pipeline to use with the provided documents - or supply a pipeline definition in the body of the request. + .. raw:: html + +

Simulate a pipeline.

+

Run an ingest pipeline against a set of provided documents. + You can either specify an existing pipeline to use with the provided documents or supply a pipeline definition in the body of the request.

+ - ``_ + ``_ :param docs: Sample documents to test in the pipeline. - :param id: Pipeline to test. If you don’t specify a `pipeline` in the request + :param id: The pipeline to test. If you don't specify a `pipeline` in the request body, this parameter is required. - :param pipeline: Pipeline to test. If you don’t specify the `pipeline` request + :param pipeline: The pipeline to test. If you don't specify the `pipeline` request path parameter, this parameter is required. If you specify both this and the request path parameter, the API only uses the request path parameter. :param verbose: If `true`, the response includes output data for each processor diff --git a/elasticsearch_serverless/_async/client/license.py b/elasticsearch_serverless/_async/client/license.py index 41f7bc8..95b9122 100644 --- a/elasticsearch_serverless/_async/client/license.py +++ b/elasticsearch_serverless/_async/client/license.py @@ -37,13 +37,18 @@ async def get( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Get license information. Get information about your Elastic license including - its type, its status, when it was issued, and when it expires. NOTE: If the master - node is generating a new cluster state, the get license API may return a `404 - Not Found` response. If you receive an unexpected 404 response after cluster - startup, wait a short period and retry the request. + .. raw:: html - ``_ +

Get license information.

+

Get information about your Elastic license including its type, its status, when it was issued, and when it expires.

+
+

info + If the master node is generating a new cluster state, the get license API may return a 404 Not Found response. + If you receive an unexpected 404 response after cluster startup, wait a short period and retry the request.

+
+ + + ``_ :param accept_enterprise: If `true`, this parameter returns enterprise for Enterprise license types. If `false`, this parameter returns platinum for both platinum diff --git a/elasticsearch_serverless/_async/client/logstash.py b/elasticsearch_serverless/_async/client/logstash.py index 406aea3..c639837 100644 --- a/elasticsearch_serverless/_async/client/logstash.py +++ b/elasticsearch_serverless/_async/client/logstash.py @@ -36,11 +36,14 @@ async def delete_pipeline( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Delete a Logstash pipeline. Delete a pipeline that is used for Logstash Central - Management. If the request succeeds, you receive an empty response with an appropriate - status code. + .. raw:: html - ``_ +

Delete a Logstash pipeline. + Delete a pipeline that is used for Logstash Central Management. + If the request succeeds, you receive an empty response with an appropriate status code.

+ + + ``_ :param id: An identifier for the pipeline. """ @@ -78,9 +81,13 @@ async def get_pipeline( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Get Logstash pipelines. Get pipelines that are used for Logstash Central Management. + .. raw:: html + +

Get Logstash pipelines. + Get pipelines that are used for Logstash Central Management.

- ``_ + + ``_ :param id: A comma-separated list of pipeline identifiers. """ @@ -125,10 +132,14 @@ async def put_pipeline( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Create or update a Logstash pipeline. Create a pipeline that is used for Logstash - Central Management. If the specified pipeline exists, it is replaced. + .. raw:: html + +

Create or update a Logstash pipeline.

+

Create a pipeline that is used for Logstash Central Management. + If the specified pipeline exists, it is replaced.

+ - ``_ + ``_ :param id: An identifier for the pipeline. :param pipeline: diff --git a/elasticsearch_serverless/_async/client/ml.py b/elasticsearch_serverless/_async/client/ml.py index f2846f4..d83994d 100644 --- a/elasticsearch_serverless/_async/client/ml.py +++ b/elasticsearch_serverless/_async/client/ml.py @@ -48,21 +48,16 @@ async def close_job( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Close anomaly detection jobs. A job can be opened and closed multiple times throughout - its lifecycle. A closed job cannot receive data or perform analysis operations, - but you can still explore and navigate results. When you close a job, it runs - housekeeping tasks such as pruning the model history, flushing buffers, calculating - final results and persisting the model snapshots. Depending upon the size of - the job, it could take several minutes to close and the equivalent time to re-open. - After it is closed, the job has a minimal overhead on the cluster except for - maintaining its meta data. Therefore it is a best practice to close jobs that - are no longer required to process data. If you close an anomaly detection job - whose datafeed is running, the request first tries to stop the datafeed. This - behavior is equivalent to calling stop datafeed API with the same timeout and - force parameters as the close job request. When a datafeed that has a specified - end date stops, it automatically closes its associated job. - - ``_ + .. raw:: html + +

Close anomaly detection jobs.

+

A job can be opened and closed multiple times throughout its lifecycle. A closed job cannot receive data or perform analysis operations, but you can still explore and navigate results. + When you close a job, it runs housekeeping tasks such as pruning the model history, flushing buffers, calculating final results and persisting the model snapshots. Depending upon the size of the job, it could take several minutes to close and the equivalent time to re-open. After it is closed, the job has a minimal overhead on the cluster except for maintaining its meta data. Therefore it is a best practice to close jobs that are no longer required to process data. + If you close an anomaly detection job whose datafeed is running, the request first tries to stop the datafeed. This behavior is equivalent to calling stop datafeed API with the same timeout and force parameters as the close job request. + When a datafeed that has a specified end date stops, it automatically closes its associated job.

+ + + ``_ :param job_id: Identifier for the anomaly detection job. It can be a job identifier, a group name, or a wildcard expression. You can close multiple anomaly detection @@ -121,10 +116,13 @@ async def delete_calendar( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Delete a calendar. Removes all scheduled events from a calendar, then deletes - it. + .. raw:: html + +

Delete a calendar.

+

Remove all scheduled events from a calendar, then delete it.

- ``_ + + ``_ :param calendar_id: A string that uniquely identifies a calendar. """ @@ -163,9 +161,12 @@ async def delete_calendar_event( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Delete events from a calendar. + .. raw:: html + +

Delete events from a calendar.

- ``_ + + ``_ :param calendar_id: A string that uniquely identifies a calendar. :param event_id: Identifier for the scheduled event. You can obtain this identifier @@ -211,9 +212,12 @@ async def delete_calendar_job( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Delete anomaly jobs from a calendar. + .. raw:: html + +

Delete anomaly jobs from a calendar.

- ``_ + + ``_ :param calendar_id: A string that uniquely identifies a calendar. :param job_id: An identifier for the anomaly detection jobs. It can be a job @@ -260,9 +264,12 @@ async def delete_data_frame_analytics( timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, ) -> ObjectApiResponse[t.Any]: """ - Delete a data frame analytics job. + .. raw:: html + +

Delete a data frame analytics job.

- ``_ + + ``_ :param id: Identifier for the data frame analytics job. :param force: If `true`, it deletes a job that is not stopped; this method is @@ -308,9 +315,12 @@ async def delete_datafeed( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Delete a datafeed. + .. raw:: html + +

Delete a datafeed.

- ``_ + + ``_ :param datafeed_id: A numerical character string that uniquely identifies the datafeed. This identifier can contain lowercase alphanumeric characters (a-z @@ -355,11 +365,14 @@ async def delete_filter( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Delete a filter. If an anomaly detection job references the filter, you cannot - delete the filter. You must update or delete the job before you can delete the - filter. + .. raw:: html + +

Delete a filter.

+

If an anomaly detection job references the filter, you cannot delete the + filter. You must update or delete the job before you can delete the filter.

+ - ``_ + ``_ :param filter_id: A string that uniquely identifies a filter. """ @@ -400,14 +413,18 @@ async def delete_job( wait_for_completion: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Delete an anomaly detection job. All job configuration, model state and results - are deleted. It is not currently possible to delete multiple jobs using wildcards - or a comma separated list. If you delete a job that has a datafeed, the request - first tries to delete the datafeed. This behavior is equivalent to calling the - delete datafeed API with the same timeout and force parameters as the delete - job request. + .. raw:: html - ``_ +

Delete an anomaly detection job.

+

All job configuration, model state and results are deleted. + It is not currently possible to delete multiple jobs using wildcards or a + comma separated list. If you delete a job that has a datafeed, the request + first tries to delete the datafeed. This behavior is equivalent to calling + the delete datafeed API with the same timeout and force parameters as the + delete job request.

+ + + ``_ :param job_id: Identifier for the anomaly detection job. :param delete_user_annotations: Specifies whether annotations that have been @@ -460,10 +477,13 @@ async def delete_trained_model( timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, ) -> ObjectApiResponse[t.Any]: """ - Delete an unreferenced trained model. The request deletes a trained inference - model that is not referenced by an ingest pipeline. + .. raw:: html + +

Delete an unreferenced trained model.

+

The request deletes a trained inference model that is not referenced by an ingest pipeline.

+ - ``_ + ``_ :param model_id: The unique identifier of the trained model. :param force: Forcefully deletes a trained model that is referenced by ingest @@ -510,11 +530,15 @@ async def delete_trained_model_alias( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Delete a trained model alias. This API deletes an existing model alias that refers - to a trained model. If the model alias is missing or refers to a model other - than the one identified by the `model_id`, this API returns an error. + .. raw:: html - ``_ +

Delete a trained model alias.

+

This API deletes an existing model alias that refers to a trained model. If + the model alias is missing or refers to a model other than the one identified + by the model_id, this API returns an error.

+ + + ``_ :param model_id: The trained model ID to which the model alias refers. :param model_alias: The model alias to delete. @@ -567,11 +591,15 @@ async def estimate_model_memory( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Estimate job model memory usage. Makes an estimation of the memory usage for - an anomaly detection job model. It is based on analysis configuration details - for the job and cardinality estimates for the fields it references. + .. raw:: html + +

Estimate job model memory usage.

+

Make an estimation of the memory usage for an anomaly detection job model. + The estimate is based on analysis configuration details for the job and cardinality + estimates for the fields it references.

- ``_ + + ``_ :param analysis_config: For a list of the properties that you can specify in the `analysis_config` component of the body of this API. @@ -634,12 +662,16 @@ async def evaluate_data_frame( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Evaluate data frame analytics. The API packages together commonly used evaluation - metrics for various types of machine learning features. This has been designed - for use on indexes created by data frame analytics. Evaluation requires both - a ground truth field and an analytics result field to be present. + .. raw:: html + +

Evaluate data frame analytics.

+

The API packages together commonly used evaluation metrics for various types + of machine learning features. This has been designed for use on indexes + created by data frame analytics. Evaluation requires both a ground truth + field and an analytics result field to be present.

- ``_ + + ``_ :param evaluation: Defines the type of evaluation you want to perform. :param index: Defines the `index` in which the evaluation will be performed. @@ -699,16 +731,20 @@ async def flush_job( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Force buffered data to be processed. The flush jobs API is only applicable when - sending data for analysis using the post data API. Depending on the content of - the buffer, then it might additionally calculate new results. Both flush and - close operations are similar, however the flush is more efficient if you are - expecting to send more data for analysis. When flushing, the job remains open - and is available to continue analyzing data. A close operation additionally prunes - and persists the model state to disk and the job must be opened again before - analyzing further data. + .. raw:: html + +

Force buffered data to be processed. + The flush jobs API is only applicable when sending data for analysis using + the post data API. Depending on the content of the buffer, then it might + additionally calculate new results. Both flush and close operations are + similar, however the flush is more efficient if you are expecting to send + more data for analysis. When flushing, the job remains open and is available + to continue analyzing data. A close operation additionally prunes and + persists the model state to disk and the job must be opened again before + analyzing further data.

- ``_ + + ``_ :param job_id: Identifier for the anomaly detection job. :param advance_time: Refer to the description for the `advance_time` query parameter. @@ -775,9 +811,12 @@ async def get_calendar_events( start: t.Optional[t.Union[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Get info about events in calendars. + .. raw:: html + +

Get info about events in calendars.

+ - ``_ + ``_ :param calendar_id: A string that uniquely identifies a calendar. You can get information for multiple calendars by using a comma-separated list of ids @@ -841,9 +880,12 @@ async def get_calendars( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Get calendar configuration info. + .. raw:: html - ``_ +

Get calendar configuration info.

+ + + ``_ :param calendar_id: A string that uniquely identifies a calendar. You can get information for multiple calendars by using a comma-separated list of ids @@ -911,11 +953,15 @@ async def get_data_frame_analytics( size: t.Optional[int] = None, ) -> ObjectApiResponse[t.Any]: """ - Get data frame analytics job configuration info. You can get information for - multiple data frame analytics jobs in a single API request by using a comma-separated - list of data frame analytics jobs or a wildcard expression. + .. raw:: html + +

Get data frame analytics job configuration info. + You can get information for multiple data frame analytics jobs in a single + API request by using a comma-separated list of data frame analytics jobs or a + wildcard expression.

+ - ``_ + ``_ :param id: Identifier for the data frame analytics job. If you do not specify this option, the API returns information for the first hundred data frame @@ -985,9 +1031,12 @@ async def get_data_frame_analytics_stats( verbose: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Get data frame analytics jobs usage info. + .. raw:: html - ``_ +

Get data frame analytics jobs usage info.

+ + + ``_ :param id: Identifier for the data frame analytics job. If you do not specify this option, the API returns information for the first hundred data frame @@ -1050,14 +1099,18 @@ async def get_datafeed_stats( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Get datafeeds usage info. You can get statistics for multiple datafeeds in a - single API request by using a comma-separated list of datafeeds or a wildcard - expression. You can get statistics for all datafeeds by using `_all`, by specifying - `*` as the ``, or by omitting the ``. If the datafeed is stopped, - the only information you receive is the `datafeed_id` and the `state`. This API - returns a maximum of 10,000 datafeeds. + .. raw:: html + +

Get datafeeds usage info. + You can get statistics for multiple datafeeds in a single API request by + using a comma-separated list of datafeeds or a wildcard expression. You can + get statistics for all datafeeds by using _all, by specifying * as the + <feed_id>, or by omitting the <feed_id>. If the datafeed is stopped, the + only information you receive is the datafeed_id and the state. + This API returns a maximum of 10,000 datafeeds.

- ``_ + + ``_ :param datafeed_id: Identifier for the datafeed. It can be a datafeed identifier or a wildcard expression. If you do not specify one of these options, the @@ -1111,13 +1164,17 @@ async def get_datafeeds( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Get datafeeds configuration info. You can get information for multiple datafeeds - in a single API request by using a comma-separated list of datafeeds or a wildcard - expression. You can get information for all datafeeds by using `_all`, by specifying - `*` as the ``, or by omitting the ``. This API returns a maximum - of 10,000 datafeeds. + .. raw:: html + +

Get datafeeds configuration info. + You can get information for multiple datafeeds in a single API request by + using a comma-separated list of datafeeds or a wildcard expression. You can + get information for all datafeeds by using _all, by specifying * as the + <feed_id>, or by omitting the <feed_id>. + This API returns a maximum of 10,000 datafeeds.

- ``_ + + ``_ :param datafeed_id: Identifier for the datafeed. It can be a datafeed identifier or a wildcard expression. If you do not specify one of these options, the @@ -1178,9 +1235,13 @@ async def get_filters( size: t.Optional[int] = None, ) -> ObjectApiResponse[t.Any]: """ - Get filters. You can get a single filter or all filters. + .. raw:: html + +

Get filters. + You can get a single filter or all filters.

- ``_ + + ``_ :param filter_id: A string that uniquely identifies a filter. :param from_: Skips the specified number of filters. @@ -1228,9 +1289,12 @@ async def get_job_stats( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Get anomaly detection jobs usage info. + .. raw:: html + +

Get anomaly detection jobs usage info.

+ - ``_ + ``_ :param job_id: Identifier for the anomaly detection job. It can be a job identifier, a group name, a comma-separated list of jobs, or a wildcard expression. If @@ -1285,13 +1349,16 @@ async def get_jobs( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Get anomaly detection jobs configuration info. You can get information for multiple - anomaly detection jobs in a single API request by using a group name, a comma-separated - list of jobs, or a wildcard expression. You can get information for all anomaly - detection jobs by using `_all`, by specifying `*` as the ``, or by omitting - the ``. + .. raw:: html - ``_ +

Get anomaly detection jobs configuration info. + You can get information for multiple anomaly detection jobs in a single API + request by using a group name, a comma-separated list of jobs, or a wildcard + expression. You can get information for all anomaly detection jobs by using + _all, by specifying * as the <job_id>, or by omitting the <job_id>.

+ + + ``_ :param job_id: Identifier for the anomaly detection job. It can be a job identifier, a group name, or a wildcard expression. If you do not specify one of these @@ -1366,21 +1433,28 @@ async def get_overall_buckets( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Get overall bucket results. Retrievs overall bucket results that summarize the - bucket results of multiple anomaly detection jobs. The `overall_score` is calculated - by combining the scores of all the buckets within the overall bucket span. First, - the maximum `anomaly_score` per anomaly detection job in the overall bucket is - calculated. Then the `top_n` of those scores are averaged to result in the `overall_score`. - This means that you can fine-tune the `overall_score` so that it is more or less - sensitive to the number of jobs that detect an anomaly at the same time. For - example, if you set `top_n` to `1`, the `overall_score` is the maximum bucket - score in the overall bucket. Alternatively, if you set `top_n` to the number - of jobs, the `overall_score` is high only when all jobs detect anomalies in that - overall bucket. If you set the `bucket_span` parameter (to a value greater than - its default), the `overall_score` is the maximum `overall_score` of the overall - buckets that have a span equal to the jobs' largest bucket span. - - ``_ + .. raw:: html + +

Get overall bucket results.

+

Retrievs overall bucket results that summarize the bucket results of + multiple anomaly detection jobs.

+

The overall_score is calculated by combining the scores of all the + buckets within the overall bucket span. First, the maximum + anomaly_score per anomaly detection job in the overall bucket is + calculated. Then the top_n of those scores are averaged to result in + the overall_score. This means that you can fine-tune the + overall_score so that it is more or less sensitive to the number of + jobs that detect an anomaly at the same time. For example, if you set + top_n to 1, the overall_score is the maximum bucket score in the + overall bucket. Alternatively, if you set top_n to the number of jobs, + the overall_score is high only when all jobs detect anomalies in that + overall bucket. If you set the bucket_span parameter (to a value + greater than its default), the overall_score is the maximum + overall_score of the overall buckets that have a span equal to the + jobs' largest bucket span.

+ + + ``_ :param job_id: Identifier for the anomaly detection job. It can be a job identifier, a group name, a comma-separated list of jobs or groups, or a wildcard expression. @@ -1475,9 +1549,12 @@ async def get_trained_models( tags: t.Optional[t.Union[str, t.Sequence[str]]] = None, ) -> ObjectApiResponse[t.Any]: """ - Get trained model configuration info. + .. raw:: html + +

Get trained model configuration info.

+ - ``_ + ``_ :param model_id: The unique identifier of the trained model or a model alias. You can get information for multiple trained models in a single API request @@ -1561,11 +1638,14 @@ async def get_trained_models_stats( size: t.Optional[int] = None, ) -> ObjectApiResponse[t.Any]: """ - Get trained models usage info. You can get usage information for multiple trained - models in a single API request by using a comma-separated list of model IDs or - a wildcard expression. + .. raw:: html - ``_ +

Get trained models usage info. + You can get usage information for multiple trained + models in a single API request by using a comma-separated list of model IDs or a wildcard expression.

+ + + ``_ :param model_id: The unique identifier of the trained model or a model alias. It can be a comma-separated list or a wildcard expression. @@ -1626,9 +1706,12 @@ async def infer_trained_model( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Evaluate a trained model. + .. raw:: html + +

Evaluate a trained model.

- ``_ + + ``_ :param model_id: The unique identifier of the trained model. :param docs: An array of objects to pass to the model for inference. The objects @@ -1688,14 +1771,18 @@ async def open_job( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Open anomaly detection jobs. An anomaly detection job must be opened to be ready - to receive and analyze data. It can be opened and closed multiple times throughout - its lifecycle. When you open a new job, it starts with an empty model. When you - open an existing job, the most recent model state is automatically loaded. The - job is ready to resume its analysis from where it left off, once new data is - received. + .. raw:: html + +

Open anomaly detection jobs.

+

An anomaly detection job must be opened to be ready to receive and analyze + data. It can be opened and closed multiple times throughout its lifecycle. + When you open a new job, it starts with an empty model. + When you open an existing job, the most recent model state is automatically + loaded. The job is ready to resume its analysis from where it left off, once + new data is received.

- ``_ + + ``_ :param job_id: Identifier for the anomaly detection job. :param timeout: Refer to the description for the `timeout` query parameter. @@ -1747,9 +1834,12 @@ async def post_calendar_events( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Add scheduled events to the calendar. + .. raw:: html + +

Add scheduled events to the calendar.

- ``_ + + ``_ :param calendar_id: A string that uniquely identifies a calendar. :param events: A list of one of more scheduled events. The event’s start and @@ -1801,10 +1891,13 @@ async def preview_data_frame_analytics( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Preview features used by data frame analytics. Previews the extracted features - used by a data frame analytics config. + .. raw:: html + +

Preview features used by data frame analytics. + Preview the extracted features used by a data frame analytics config.

+ - ``_ + ``_ :param id: Identifier for the data frame analytics job. :param config: A data frame analytics config as described in create data frame @@ -1864,17 +1957,20 @@ async def preview_datafeed( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Preview a datafeed. This API returns the first "page" of search results from - a datafeed. You can preview an existing datafeed or provide configuration details - for a datafeed and anomaly detection job in the API. The preview shows the structure - of the data that will be passed to the anomaly detection engine. IMPORTANT: When - Elasticsearch security features are enabled, the preview uses the credentials - of the user that called the API. However, when the datafeed starts it uses the - roles of the last user that created or updated the datafeed. To get a preview - that accurately reflects the behavior of the datafeed, use the appropriate credentials. - You can also use secondary authorization headers to supply the credentials. + .. raw:: html - ``_ +

Preview a datafeed. + This API returns the first "page" of search results from a datafeed. + You can preview an existing datafeed or provide configuration details for a datafeed + and anomaly detection job in the API. The preview shows the structure of the data + that will be passed to the anomaly detection engine. + IMPORTANT: When Elasticsearch security features are enabled, the preview uses the credentials of the user that + called the API. However, when the datafeed starts it uses the roles of the last user that created or updated the + datafeed. To get a preview that accurately reflects the behavior of the datafeed, use the appropriate credentials. + You can also use secondary authorization headers to supply the credentials.

+ + + ``_ :param datafeed_id: A numerical character string that uniquely identifies the datafeed. This identifier can contain lowercase alphanumeric characters (a-z @@ -1948,9 +2044,12 @@ async def put_calendar( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Create a calendar. + .. raw:: html + +

Create a calendar.

+ - ``_ + ``_ :param calendar_id: A string that uniquely identifies a calendar. :param description: A description of the calendar. @@ -2002,9 +2101,12 @@ async def put_calendar_job( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Add anomaly detection job to calendar. + .. raw:: html - ``_ +

Add anomaly detection job to calendar.

+ + + ``_ :param calendar_id: A string that uniquely identifies a calendar. :param job_id: An identifier for the anomaly detection jobs. It can be a job @@ -2077,15 +2179,17 @@ async def put_data_frame_analytics( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Create a data frame analytics job. This API creates a data frame analytics job - that performs an analysis on the source indices and stores the outcome in a destination - index. By default, the query used in the source configuration is `{"match_all": - {}}`. If the destination index does not exist, it is created automatically when - you start the job. If you supply only a subset of the regression or classification - parameters, hyperparameter optimization occurs. It determines a value for each - of the undefined parameters. + .. raw:: html + +

Create a data frame analytics job. + This API creates a data frame analytics job that performs an analysis on the + source indices and stores the outcome in a destination index. + By default, the query used in the source configuration is {"match_all": {}}.

+

If the destination index does not exist, it is created automatically when you start the job.

+

If you supply only a subset of the regression or classification parameters, hyperparameter optimization occurs. It determines a value for each of the undefined parameters.

- ``_ + + ``_ :param id: Identifier for the data frame analytics job. This identifier can contain lowercase alphanumeric characters (a-z and 0-9), hyphens, and underscores. @@ -2256,20 +2360,21 @@ async def put_datafeed( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Create a datafeed. Datafeeds retrieve data from Elasticsearch for analysis by - an anomaly detection job. You can associate only one datafeed with each anomaly - detection job. The datafeed contains a query that runs at a defined interval - (`frequency`). If you are concerned about delayed data, you can add a delay (`query_delay') - at each interval. By default, the datafeed uses the following query: `{"match_all": - {"boost": 1}}`. When Elasticsearch security features are enabled, your datafeed - remembers which roles the user who created it had at the time of creation and - runs the query using those same roles. If you provide secondary authorization - headers, those credentials are used instead. You must use Kibana, this API, or - the create anomaly detection jobs API to create a datafeed. Do not add a datafeed - directly to the `.ml-config` index. Do not give users `write` privileges on the - `.ml-config` index. - - ``_ + .. raw:: html + +

Create a datafeed. + Datafeeds retrieve data from Elasticsearch for analysis by an anomaly detection job. + You can associate only one datafeed with each anomaly detection job. + The datafeed contains a query that runs at a defined interval (frequency). + If you are concerned about delayed data, you can add a delay (query_delay') at each interval. By default, the datafeed uses the following query: {"match_all": {"boost": 1}}`.

+

When Elasticsearch security features are enabled, your datafeed remembers which roles the user who created it had + at the time of creation and runs the query using those same roles. If you provide secondary authorization headers, + those credentials are used instead. + You must use Kibana, this API, or the create anomaly detection jobs API to create a datafeed. Do not add a datafeed + directly to the .ml-config index. Do not give users write privileges on the .ml-config index.

+ + + ``_ :param datafeed_id: A numerical character string that uniquely identifies the datafeed. This identifier can contain lowercase alphanumeric characters (a-z @@ -2424,11 +2529,14 @@ async def put_filter( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Create a filter. A filter contains a list of strings. It can be used by one or - more anomaly detection jobs. Specifically, filters are referenced in the `custom_rules` - property of detector configuration objects. + .. raw:: html - ``_ +

Create a filter. + A filter contains a list of strings. It can be used by one or more anomaly detection jobs. + Specifically, filters are referenced in the custom_rules property of detector configuration objects.

+ + + ``_ :param filter_id: A string that uniquely identifies a filter. :param description: A description of the filter. @@ -2523,11 +2631,14 @@ async def put_job( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Create an anomaly detection job. If you include a `datafeed_config`, you must - have read index privileges on the source index. If you include a `datafeed_config` - but do not provide a query, the datafeed uses `{"match_all": {"boost": 1}}`. + .. raw:: html + +

Create an anomaly detection job.

+

If you include a datafeed_config, you must have read index privileges on the source index. + If you include a datafeed_config but do not provide a query, the datafeed uses {"match_all": {"boost": 1}}.

- ``_ + + ``_ :param job_id: The identifier for the anomaly detection job. This identifier can contain lowercase alphanumeric characters (a-z and 0-9), hyphens, and @@ -2729,10 +2840,13 @@ async def put_trained_model( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Create a trained model. Enable you to supply a trained model that is not created - by data frame analytics. + .. raw:: html + +

Create a trained model. + Enable you to supply a trained model that is not created by data frame analytics.

- ``_ + + ``_ :param model_id: The unique identifier of the trained model. :param compressed_definition: The compressed (GZipped and Base64 encoded) inference @@ -2832,21 +2946,28 @@ async def put_trained_model_alias( reassign: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Create or update a trained model alias. A trained model alias is a logical name - used to reference a single trained model. You can use aliases instead of trained - model identifiers to make it easier to reference your models. For example, you - can use aliases in inference aggregations and processors. An alias must be unique - and refer to only a single trained model. However, you can have multiple aliases - for each trained model. If you use this API to update an alias such that it references - a different trained model ID and the model uses a different type of data frame - analytics, an error occurs. For example, this situation occurs if you have a - trained model for regression analysis and a trained model for classification - analysis; you cannot reassign an alias from one type of trained model to another. - If you use this API to update an alias and there are very few input fields in - common between the old and new trained models for the model alias, the API returns - a warning. - - ``_ + .. raw:: html + +

Create or update a trained model alias. + A trained model alias is a logical name used to reference a single trained + model. + You can use aliases instead of trained model identifiers to make it easier to + reference your models. For example, you can use aliases in inference + aggregations and processors. + An alias must be unique and refer to only a single trained model. However, + you can have multiple aliases for each trained model. + If you use this API to update an alias such that it references a different + trained model ID and the model uses a different type of data frame analytics, + an error occurs. For example, this situation occurs if you have a trained + model for regression analysis and a trained model for classification + analysis; you cannot reassign an alias from one type of trained model to + another. + If you use this API to update an alias and there are very few input fields in + common between the old and new trained models for the model alias, the API + returns a warning.

+ + + ``_ :param model_id: The identifier for the trained model that the alias refers to. :param model_alias: The alias to create or update. This value cannot end in numbers. @@ -2902,9 +3023,12 @@ async def put_trained_model_definition_part( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Create part of a trained model definition. + .. raw:: html + +

Create part of a trained model definition.

- ``_ + + ``_ :param model_id: The unique identifier of the trained model. :param part: The definition part number. When the definition is loaded for inference @@ -2979,11 +3103,14 @@ async def put_trained_model_vocabulary( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Create a trained model vocabulary. This API is supported only for natural language - processing (NLP) models. The vocabulary is stored in the index as described in - `inference_config.*.vocabulary` of the trained model definition. + .. raw:: html + +

Create a trained model vocabulary. + This API is supported only for natural language processing (NLP) models. + The vocabulary is stored in the index as described in inference_config.*.vocabulary of the trained model definition.

+ - ``_ + ``_ :param model_id: The unique identifier of the trained model. :param vocabulary: The model vocabulary, which must not be empty. @@ -3037,11 +3164,16 @@ async def reset_job( wait_for_completion: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Reset an anomaly detection job. All model state and results are deleted. The - job is ready to start over as if it had just been created. It is not currently - possible to reset multiple jobs using wildcards or a comma separated list. + .. raw:: html - ``_ +

Reset an anomaly detection job. + All model state and results are deleted. The job is ready to start over as if + it had just been created. + It is not currently possible to reset multiple jobs using wildcards or a + comma separated list.

+ + + ``_ :param job_id: The ID of the job to reset. :param delete_user_annotations: Specifies whether annotations that have been @@ -3089,18 +3221,23 @@ async def start_data_frame_analytics( timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, ) -> ObjectApiResponse[t.Any]: """ - Start a data frame analytics job. A data frame analytics job can be started and - stopped multiple times throughout its lifecycle. If the destination index does - not exist, it is created automatically the first time you start the data frame - analytics job. The `index.number_of_shards` and `index.number_of_replicas` settings - for the destination index are copied from the source index. If there are multiple - source indices, the destination index copies the highest setting values. The - mappings for the destination index are also copied from the source indices. If - there are any mapping conflicts, the job fails to start. If the destination index - exists, it is used as is. You can therefore set up the destination index in advance - with custom settings and mappings. + .. raw:: html + +

Start a data frame analytics job. + A data frame analytics job can be started and stopped multiple times + throughout its lifecycle. + If the destination index does not exist, it is created automatically the + first time you start the data frame analytics job. The + index.number_of_shards and index.number_of_replicas settings for the + destination index are copied from the source index. If there are multiple + source indices, the destination index copies the highest setting values. The + mappings for the destination index are also copied from the source indices. + If there are any mapping conflicts, the job fails to start. + If the destination index exists, it is used as is. You can therefore set up + the destination index in advance with custom settings and mappings.

+ - ``_ + ``_ :param id: Identifier for the data frame analytics job. This identifier can contain lowercase alphanumeric characters (a-z and 0-9), hyphens, and underscores. @@ -3150,19 +3287,20 @@ async def start_datafeed( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Start datafeeds. A datafeed must be started in order to retrieve data from Elasticsearch. - A datafeed can be started and stopped multiple times throughout its lifecycle. - Before you can start a datafeed, the anomaly detection job must be open. Otherwise, - an error occurs. If you restart a stopped datafeed, it continues processing input - data from the next millisecond after it was stopped. If new data was indexed - for that exact millisecond between stopping and starting, it will be ignored. - When Elasticsearch security features are enabled, your datafeed remembers which - roles the last user to create or update it had at the time of creation or update - and runs the query using those same roles. If you provided secondary authorization - headers when you created or updated the datafeed, those credentials are used - instead. + .. raw:: html - ``_ +

Start datafeeds.

+

A datafeed must be started in order to retrieve data from Elasticsearch. A datafeed can be started and stopped + multiple times throughout its lifecycle.

+

Before you can start a datafeed, the anomaly detection job must be open. Otherwise, an error occurs.

+

If you restart a stopped datafeed, it continues processing input data from the next millisecond after it was stopped. + If new data was indexed for that exact millisecond between stopping and starting, it will be ignored.

+

When Elasticsearch security features are enabled, your datafeed remembers which roles the last user to create or + update it had at the time of creation or update and runs the query using those same roles. If you provided secondary + authorization headers when you created or updated the datafeed, those credentials are used instead.

+ + + ``_ :param datafeed_id: A numerical character string that uniquely identifies the datafeed. This identifier can contain lowercase alphanumeric characters (a-z @@ -3208,11 +3346,14 @@ async def start_datafeed( path_parts=__path_parts, ) - @_rewrite_parameters() + @_rewrite_parameters( + body_fields=("adaptive_allocations",), + ) async def start_trained_model_deployment( self, *, model_id: str, + adaptive_allocations: t.Optional[t.Mapping[str, t.Any]] = None, cache_size: t.Optional[t.Union[int, str]] = None, deployment_id: t.Optional[str] = None, error_trace: t.Optional[bool] = None, @@ -3227,15 +3368,22 @@ async def start_trained_model_deployment( wait_for: t.Optional[ t.Union[str, t.Literal["fully_allocated", "started", "starting"]] ] = None, + body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Start a trained model deployment. It allocates the model to every machine learning - node. + .. raw:: html + +

Start a trained model deployment. + It allocates the model to every machine learning node.

- ``_ + + ``_ :param model_id: The unique identifier of the trained model. Currently, only PyTorch models are supported. + :param adaptive_allocations: Adaptive allocations configuration. When enabled, + the number of allocations is set based on the current load. If adaptive_allocations + is enabled, do not set the number of allocations manually. :param cache_size: The inference cache size (in memory outside the JVM heap) per node for the model. The default value is the same size as the `model_size_bytes`. To disable the cache, `0b` can be provided. @@ -3245,7 +3393,8 @@ async def start_trained_model_deployment( model in memory but use a separate set of threads to evaluate the model. Increasing this value generally increases the throughput. If this setting is greater than the number of hardware threads it will automatically be changed - to a value less than the number of hardware threads. + to a value less than the number of hardware threads. If adaptive_allocations + is enabled, do not set this value, because it’s automatically set. :param priority: The deployment priority. :param queue_capacity: Specifies the number of inference requests that are allowed in the queue. After the number of requests exceeds this value, new requests @@ -3265,6 +3414,7 @@ async def start_trained_model_deployment( __path_parts: t.Dict[str, str] = {"model_id": _quote(model_id)} __path = f'/_ml/trained_models/{__path_parts["model_id"]}/deployment/_start' __query: t.Dict[str, t.Any] = {} + __body: t.Dict[str, t.Any] = body if body is not None else {} if cache_size is not None: __query["cache_size"] = cache_size if deployment_id is not None: @@ -3289,12 +3439,20 @@ async def start_trained_model_deployment( __query["timeout"] = timeout if wait_for is not None: __query["wait_for"] = wait_for + if not __body: + if adaptive_allocations is not None: + __body["adaptive_allocations"] = adaptive_allocations + 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="ml.start_trained_model_deployment", path_parts=__path_parts, ) @@ -3313,10 +3471,14 @@ async def stop_data_frame_analytics( timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, ) -> ObjectApiResponse[t.Any]: """ - Stop data frame analytics jobs. A data frame analytics job can be started and - stopped multiple times throughout its lifecycle. + .. raw:: html + +

Stop data frame analytics jobs. + A data frame analytics job can be started and stopped multiple times + throughout its lifecycle.

+ - ``_ + ``_ :param id: Identifier for the data frame analytics job. This identifier can contain lowercase alphanumeric characters (a-z and 0-9), hyphens, and underscores. @@ -3379,10 +3541,14 @@ async def stop_datafeed( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Stop datafeeds. A datafeed that is stopped ceases to retrieve data from Elasticsearch. - A datafeed can be started and stopped multiple times throughout its lifecycle. + .. raw:: html - ``_ +

Stop datafeeds. + A datafeed that is stopped ceases to retrieve data from Elasticsearch. A datafeed can be started and stopped + multiple times throughout its lifecycle.

+ + + ``_ :param datafeed_id: Identifier for the datafeed. You can stop multiple datafeeds in a single API request by using a comma-separated list of datafeeds or a @@ -3442,9 +3608,12 @@ async def stop_trained_model_deployment( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Stop a trained model deployment. + .. raw:: html + +

Stop a trained model deployment.

+ - ``_ + ``_ :param model_id: The unique identifier of the trained model. :param allow_no_match: Specifies what to do when the request: contains wildcard @@ -3507,9 +3676,12 @@ async def update_data_frame_analytics( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Update a data frame analytics job. + .. raw:: html - ``_ +

Update a data frame analytics job.

+ + + ``_ :param id: Identifier for the data frame analytics job. This identifier can contain lowercase alphanumeric characters (a-z and 0-9), hyphens, and underscores. @@ -3615,13 +3787,16 @@ async def update_datafeed( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Update a datafeed. You must stop and start the datafeed for the changes to be - applied. When Elasticsearch security features are enabled, your datafeed remembers - which roles the user who updated it had at the time of the update and runs the - query using those same roles. If you provide secondary authorization headers, - those credentials are used instead. + .. raw:: html + +

Update a datafeed. + You must stop and start the datafeed for the changes to be applied. + When Elasticsearch security features are enabled, your datafeed remembers which roles the user who updated it had at + the time of the update and runs the query using those same roles. If you provide secondary authorization headers, + those credentials are used instead.

- ``_ + + ``_ :param datafeed_id: A numerical character string that uniquely identifies the datafeed. This identifier can contain lowercase alphanumeric characters (a-z @@ -3782,10 +3957,13 @@ async def update_filter( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Update a filter. Updates the description of a filter, adds items, or removes - items from the list. + .. raw:: html + +

Update a filter. + Updates the description of a filter, adds items, or removes items from the list.

- ``_ + + ``_ :param filter_id: A string that uniquely identifies a filter. :param add_items: The items to add to the filter. @@ -3873,10 +4051,13 @@ async def update_job( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Update an anomaly detection job. Updates certain properties of an anomaly detection - job. + .. raw:: html + +

Update an anomaly detection job. + Updates certain properties of an anomaly detection job.

- ``_ + + ``_ :param job_id: Identifier for the job. :param allow_lazy_open: Advanced configuration option. Specifies whether this @@ -3986,13 +4167,14 @@ async def update_job( ) @_rewrite_parameters( - body_fields=("number_of_allocations",), + body_fields=("adaptive_allocations", "number_of_allocations"), ) @_stability_warning(Stability.BETA) async def update_trained_model_deployment( self, *, model_id: str, + adaptive_allocations: t.Optional[t.Mapping[str, t.Any]] = None, error_trace: t.Optional[bool] = None, filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, human: t.Optional[bool] = None, @@ -4001,18 +4183,25 @@ async def update_trained_model_deployment( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Update a trained model deployment. + .. raw:: html + +

Update a trained model deployment.

+ - ``_ + ``_ :param model_id: The unique identifier of the trained model. Currently, only PyTorch models are supported. + :param adaptive_allocations: Adaptive allocations configuration. When enabled, + the number of allocations is set based on the current load. If adaptive_allocations + is enabled, do not set the number of allocations manually. :param number_of_allocations: The number of model allocations on each node where the model is deployed. All allocations on a node share the same copy of the model in memory but use a separate set of threads to evaluate the model. Increasing this value generally increases the throughput. If this setting is greater than the number of hardware threads it will automatically be changed - to a value less than the number of hardware threads. + to a value less than the number of hardware threads. If adaptive_allocations + is enabled, do not set this value, because it’s automatically set. """ if model_id in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'model_id'") @@ -4029,6 +4218,8 @@ async def update_trained_model_deployment( if pretty is not None: __query["pretty"] = pretty if not __body: + if adaptive_allocations is not None: + __body["adaptive_allocations"] = adaptive_allocations if number_of_allocations is not None: __body["number_of_allocations"] = number_of_allocations if not __body: diff --git a/elasticsearch_serverless/_async/client/query_rules.py b/elasticsearch_serverless/_async/client/query_rules.py index 4218557..c898544 100644 --- a/elasticsearch_serverless/_async/client/query_rules.py +++ b/elasticsearch_serverless/_async/client/query_rules.py @@ -38,11 +38,14 @@ async def delete_rule( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - 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. + .. raw:: html - ``_ +

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.

+ + + ``_ :param ruleset_id: The unique identifier of the query ruleset containing the rule to delete @@ -88,10 +91,14 @@ async def delete_ruleset( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Delete a query ruleset. Remove a query ruleset and its associated data. This - is a destructive action that is not recoverable. + .. raw:: html + +

Delete a query ruleset. + Remove a query ruleset and its associated data. + This is a destructive action that is not recoverable.

+ - ``_ + ``_ :param ruleset_id: The unique identifier of the query ruleset to delete """ @@ -130,9 +137,13 @@ async def get_rule( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Get a query rule. Get details about a query rule within a query ruleset. + .. raw:: html - ``_ +

Get a query rule. + Get details about a query rule within a query ruleset.

+ + + ``_ :param ruleset_id: The unique identifier of the query ruleset containing the rule to retrieve @@ -178,9 +189,13 @@ async def get_ruleset( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Get a query ruleset. Get details about a query ruleset. + .. raw:: html + +

Get a query ruleset. + Get details about a query ruleset.

+ - ``_ + ``_ :param ruleset_id: The unique identifier of the query ruleset """ @@ -221,9 +236,13 @@ async def list_rulesets( size: t.Optional[int] = None, ) -> ObjectApiResponse[t.Any]: """ - Get all query rulesets. Get summarized information about the query rulesets. + .. raw:: html - ``_ +

Get all query rulesets. + Get summarized information about the query rulesets.

+ + + ``_ :param from_: The offset from the first result to fetch. :param size: The maximum number of results to retrieve. @@ -274,15 +293,17 @@ async def put_rule( 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. - 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. + .. raw:: html + +

Create or update a query rule. + Create or update a query rule within a query ruleset.

+

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.

+ - ``_ + ``_ :param ruleset_id: The unique identifier of the query ruleset containing the rule to be created or updated. @@ -358,16 +379,18 @@ async def put_ruleset( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Create or update a query ruleset. There is a limit of 100 rules per ruleset. - This limit can be increased by using the `xpack.applications.rules.max_rules_per_ruleset` - cluster setting. IMPORTANT: Due to limitations within pinned queries, you can - only select 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. + .. raw:: html - ``_ +

Create or update a query ruleset. + There is a limit of 100 rules per ruleset. + This limit can be increased by using the xpack.applications.rules.max_rules_per_ruleset cluster setting.

+

IMPORTANT: Due to limitations within pinned queries, you can only select 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.

+ + + ``_ :param ruleset_id: The unique identifier of the query ruleset to be created or updated. @@ -418,10 +441,13 @@ async def test( 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 + +

Test a query ruleset. + Evaluate match criteria against a query ruleset to identify the rules that would match that criteria.

+ - ``_ + ``_ :param ruleset_id: The unique identifier of the query ruleset to be created or updated diff --git a/elasticsearch_serverless/_async/client/search_application.py b/elasticsearch_serverless/_async/client/search_application.py index df4131f..66605cc 100644 --- a/elasticsearch_serverless/_async/client/search_application.py +++ b/elasticsearch_serverless/_async/client/search_application.py @@ -43,12 +43,15 @@ async def delete( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Delete a search application. Remove a search application and its associated alias. - Indices attached to the search application are not removed. + .. raw:: html - ``_ +

Delete a search application.

+

Remove a search application and its associated alias. Indices attached to the search application are not removed.

- :param name: The name of the search application to delete + + ``_ + + :param name: The name of the search application to delete. """ if name in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'name'") @@ -85,10 +88,13 @@ async def delete_behavioral_analytics( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Delete a behavioral analytics collection. The associated data stream is also - deleted. + .. raw:: html + +

Delete a behavioral analytics collection. + The associated data stream is also deleted.

+ - ``_ + ``_ :param name: The name of the analytics collection to be deleted """ @@ -127,9 +133,12 @@ async def get( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Get search application details. + .. raw:: html - ``_ +

Get search application details.

+ + + ``_ :param name: The name of the search application """ @@ -168,9 +177,12 @@ async def get_behavioral_analytics( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Get behavioral analytics collections. + .. raw:: html + +

Get behavioral analytics collections.

+ - ``_ + ``_ :param name: A list of analytics collections to limit the returned information """ @@ -216,9 +228,13 @@ async def list( size: t.Optional[int] = None, ) -> ObjectApiResponse[t.Any]: """ - Get search applications. Get information about search applications. + .. raw:: html - ``_ +

Get search applications. + Get information about search applications.

+ + + ``_ :param from_: Starting offset. :param q: Query in the Lucene query string syntax. @@ -268,9 +284,12 @@ async def put( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Create or update a search application. + .. raw:: html + +

Create or update a search application.

+ - ``_ + ``_ :param name: The name of the search application to be created or updated. :param search_application: @@ -322,9 +341,12 @@ async def put_behavioral_analytics( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Create a behavioral analytics collection. + .. raw:: html - ``_ +

Create a behavioral analytics collection.

+ + + ``_ :param name: The name of the analytics collection to be created or updated. """ @@ -369,12 +391,14 @@ async def search( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Run a search application search. Generate and run an Elasticsearch query that - uses the specified query parameteter and the search template associated with - the search application or default template. Unspecified template parameters are - assigned their default values if applicable. + .. raw:: html + +

Run a search application search. + Generate and run an Elasticsearch query that uses the specified query parameteter and the search template associated with the search application or default template. + Unspecified template parameters are assigned their default values if applicable.

+ - ``_ + ``_ :param name: The name of the search application to be searched. :param params: Query parameters specific to this request, which will override diff --git a/elasticsearch_serverless/_async/client/security.py b/elasticsearch_serverless/_async/client/security.py index fa9bcf4..eeb26ec 100644 --- a/elasticsearch_serverless/_async/client/security.py +++ b/elasticsearch_serverless/_async/client/security.py @@ -35,14 +35,16 @@ async def authenticate( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Authenticate a user. Authenticates a user and returns information about the authenticated - user. Include the user information in a [basic auth header](https://en.wikipedia.org/wiki/Basic_access_authentication). - A successful call returns a JSON structure that shows user information such as - their username, the roles that are assigned to the user, any assigned metadata, - and information about the realms that authenticated and authorized the user. - If the user cannot be authenticated, this API returns a 401 status code. + .. raw:: html - ``_ +

Authenticate a user.

+

Authenticates a user and returns information about the authenticated user. + Include the user information in a basic auth header. + A successful call returns a JSON structure that shows user information such as their username, the roles that are assigned to the user, any assigned metadata, and information about the realms that authenticated and authorized the user. + If the user cannot be authenticated, this API returns a 401 status code.

+ + + ``_ """ __path_parts: t.Dict[str, str] = {} __path = "/_security/_authenticate" @@ -85,31 +87,43 @@ async def create_api_key( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Create an API key. Create an API key for access without requiring basic authentication. - A successful request returns a JSON structure that contains the API key, its - unique id, and its name. If applicable, it also returns expiration information - for the API key in milliseconds. NOTE: By default, API keys never expire. You - can specify expiration information when you create the API keys. + .. raw:: html + +

Create an API key.

+

Create an API key for access without requiring basic authentication.

+

IMPORTANT: If the credential that is used to authenticate this request is an API key, the derived API key cannot have any privileges. + If you specify privileges, the API returns an error.

+

A successful request returns a JSON structure that contains the API key, its unique id, and its name. + If applicable, it also returns expiration information for the API key in milliseconds.

+

NOTE: By default, API keys never expire. You can specify expiration information when you create the API keys.

+

The API keys are created by the Elasticsearch API key service, which is automatically enabled. + To configure or turn off the API key service, refer to API key service setting documentation.

+ - ``_ + ``_ - :param expiration: Expiration time for the API key. By default, API keys never - expire. + :param expiration: The expiration time for the API key. By default, API keys + never expire. :param metadata: Arbitrary metadata that you want to associate with the API key. It supports nested data structure. Within the metadata object, keys beginning with `_` are reserved for system usage. - :param name: Specifies the name for this API key. + :param name: A name for the API key. :param refresh: If `true` (the default) then refresh the affected shards to make this operation visible to search, if `wait_for` then wait for a refresh to make this operation visible to search, if `false` then do nothing with refreshes. - :param role_descriptors: An array of role descriptors for this API key. This - parameter is optional. When it is not specified or is an empty array, then - the API key will have a point in time snapshot of permissions of the authenticated - user. If you supply role descriptors then the resultant permissions would - be an intersection of API keys permissions and authenticated user’s permissions - thereby limiting the access scope for API keys. The structure of role descriptor - is the same as the request for create role API. For more details, see create - or update roles API. + :param role_descriptors: An array of role descriptors for this API key. When + it is not specified or it is an empty array, the API key will have a point + in time snapshot of permissions of the authenticated user. If you supply + role descriptors, the resultant permissions are an intersection of API keys + permissions and the authenticated user's permissions thereby limiting the + access scope for API keys. The structure of role descriptor is the same as + the request for the create role API. For more details, refer to the create + or update roles API. NOTE: Due to the way in which this permission intersection + is calculated, it is not possible to create an API key that is a child of + another API key, unless the derived key is created without any privileges. + In this case, you must explicitly specify a role descriptor with no privileges. + The derived API key can be used for authentication; it will not have authority + to call Elasticsearch APIs. """ __path_parts: t.Dict[str, str] = {} __path = "/_security/api_key" @@ -159,11 +173,17 @@ async def delete_role( ] = None, ) -> ObjectApiResponse[t.Any]: """ - Delete roles. Delete roles in the native realm. + .. raw:: html - ``_ +

Delete roles.

+

Delete roles in the native realm. + The role management APIs are generally the preferred way to manage roles, rather than using file-based role management. + The delete roles API cannot remove roles that are defined in roles files.

- :param name: Role name + + ``_ + + :param name: The name of the role. :param refresh: If `true` (the default) then refresh the affected shards to make this operation visible to search, if `wait_for` then wait for a refresh to make this operation visible to search, if `false` then do nothing with refreshes. @@ -211,13 +231,15 @@ async def get_api_key( with_profile_uid: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Get API key information. Retrieves information for one or more API keys. NOTE: - If you have only the `manage_own_api_key` privilege, this API returns only the - API keys that you own. If you have `read_security`, `manage_api_key` or greater - privileges (including `manage_security`), this API returns all API keys regardless - of ownership. + .. raw:: html + +

Get API key information.

+

Retrieves information for one or more API keys. + NOTE: If you have only the manage_own_api_key privilege, this API returns only the API keys that you own. + If you have read_security, manage_api_key or greater privileges (including manage_security), this API returns all API keys regardless of ownership.

+ - ``_ + ``_ :param active_only: A boolean flag that can be used to query API keys that are currently active. An API key is considered active if it is neither invalidated, @@ -289,10 +311,13 @@ async def get_builtin_privileges( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Get builtin privileges. Get the list of cluster privileges and index privileges - that are available in this version of Elasticsearch. + .. raw:: html - ``_ +

Get builtin privileges.

+

Get the list of cluster privileges and index privileges that are available in this version of Elasticsearch.

+ + + ``_ """ __path_parts: t.Dict[str, str] = {} __path = "/_security/privilege/_builtin" @@ -326,9 +351,15 @@ async def get_role( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Get roles. Get roles in the native realm. + .. raw:: html + +

Get roles.

+

Get roles in the native realm. + The role management APIs are generally the preferred way to manage roles, rather than using file-based role management. + The get roles API cannot retrieve roles that are defined in roles files.

+ - ``_ + ``_ :param name: The name of the role. You can specify multiple roles as a comma-separated list. If you do not specify this parameter, the API returns information about @@ -444,10 +475,15 @@ async def has_privileges( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Check user privileges. Determine whether the specified user has a specified list - of privileges. + .. raw:: html - ``_ +

Check user privileges.

+

Determine whether the specified user has a specified list of privileges. + All users can use this API, but only to determine their own privileges. + To check the privileges of other users, you must use the run as feature.

+ + + ``_ :param user: Username :param application: @@ -508,33 +544,39 @@ async def invalidate_api_key( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Invalidate API keys. This API invalidates API keys created by the create API - key or grant API key APIs. Invalidated API keys fail authentication, but they - can still be viewed using the get API key information and query API key information - APIs, for at least the configured retention period, until they are automatically - deleted. The `manage_api_key` privilege allows deleting any API keys. The `manage_own_api_key` - only allows deleting API keys that are owned by the user. In addition, with the - `manage_own_api_key` privilege, an invalidation request must be issued in one - of the three formats: - Set the parameter `owner=true`. - Or, set both `username` - and `realm_name` to match the user’s identity. - Or, if the request is issued - by an API key, that is to say an API key invalidates itself, specify its ID in - the `ids` field. + .. raw:: html + +

Invalidate API keys.

+

This API invalidates API keys created by the create API key or grant API key APIs. + Invalidated API keys fail authentication, but they can still be viewed using the get API key information and query API key information APIs, for at least the configured retention period, until they are automatically deleted.

+

To use this API, you must have at least the manage_security, manage_api_key, or manage_own_api_key cluster privileges. + The manage_security privilege allows deleting any API key, including both REST and cross cluster API keys. + The manage_api_key privilege allows deleting any REST API key, but not cross cluster API keys. + The manage_own_api_key only allows deleting REST API keys that are owned by the user. + In addition, with the manage_own_api_key privilege, an invalidation request must be issued in one of the three formats:

+
    +
  • Set the parameter owner=true.
    • +
  • Or, set both username and realm_name to match the user's identity.
    • +
  • Or, if the request is issued by an API key, that is to say an API key invalidates itself, specify its ID in the ids field.
    • +
+ - ``_ + ``_ :param id: :param ids: A list of API key ids. This parameter cannot be used with any of `name`, `realm_name`, or `username`. :param name: An API key name. This parameter cannot be used with any of `ids`, `realm_name` or `username`. - :param owner: Can be used to query API keys owned by the currently authenticated - user. The `realm_name` or `username` parameters cannot be specified when - this parameter is set to `true` as they are assumed to be the currently authenticated - ones. + :param owner: Query API keys owned by the currently authenticated user. The `realm_name` + or `username` parameters cannot be specified when this parameter is set to + `true` as they are assumed to be the currently authenticated ones. NOTE: + At least one of `ids`, `name`, `username`, and `realm_name` must be specified + if `owner` is `false`. :param realm_name: The name of an authentication realm. This parameter cannot be used with either `ids` or `name`, or when `owner` flag is set to `true`. :param username: The username of a user. This parameter cannot be used with either - `ids` or `name`, or when `owner` flag is set to `true`. + `ids` or `name` or when `owner` flag is set to `true`. """ __path_parts: t.Dict[str, str] = {} __path = "/_security/api_key" @@ -678,12 +720,15 @@ async def put_role( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Create or update roles. The role management APIs are generally the preferred - way to manage roles in the native realm, rather than using file-based role management. - The create or update roles API cannot update roles that are defined in roles - files. File-based role management is not available in Elastic Serverless. + .. raw:: html - ``_ +

Create or update roles.

+

The role management APIs are generally the preferred way to manage roles in the native realm, rather than using file-based role management. + The create or update roles API cannot update roles that are defined in roles files. + File-based role management is not available in Elastic Serverless.

+ + + ``_ :param name: The name of the role that is being created or updated. On Elasticsearch Serverless, the role name must begin with a letter or digit and can only @@ -703,7 +748,10 @@ async def put_role( this operation visible to search, if `wait_for` then wait for a refresh to make this operation visible to search, if `false` then do nothing with refreshes. :param remote_cluster: A list of remote cluster permissions entries. - :param remote_indices: A list of remote indices permissions entries. + :param remote_indices: A list of remote indices permissions entries. NOTE: Remote + indices are effective for remote clusters configured with the API key based + model. They have no effect for remote clusters configured with the certificate + based model. :param run_as: A list of users that the owners of this role can impersonate. *Note*: in Serverless, the run-as feature is disabled. For API compatibility, you can still specify an empty `run_as` field, but a non-empty list will @@ -787,7 +835,7 @@ async def query_api_keys( pretty: t.Optional[bool] = None, query: t.Optional[t.Mapping[str, t.Any]] = None, search_after: t.Optional[ - t.Sequence[t.Union[None, bool, float, int, str, t.Any]] + t.Sequence[t.Union[None, bool, float, int, str]] ] = None, size: t.Optional[int] = None, sort: t.Optional[ @@ -802,10 +850,17 @@ async def query_api_keys( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Find API keys with a query. Get a paginated list of API keys and their information. - You can optionally filter the results with a query. + .. raw:: html + +

Find API keys with a query.

+

Get a paginated list of API keys and their information. + You can optionally filter the results with a query.

+

To use this API, you must have at least the manage_own_api_key or the read_security cluster privileges. + If you have only the manage_own_api_key privilege, this API returns only the API keys that you own. + If you have the read_security, manage_api_key, or greater privileges (including manage_security), this API returns all API keys regardless of ownership.

+ - ``_ + ``_ :param aggregations: Any aggregations to run over the corpus of returned API keys. Aggregations and queries work together. Aggregations are computed only @@ -819,30 +874,39 @@ async def query_api_keys( `terms`, `range`, `date_range`, `missing`, `cardinality`, `value_count`, `composite`, `filter`, and `filters`. Additionally, aggregations only run over the same subset of fields that query works with. - :param from_: Starting document offset. By default, you cannot page through more - than 10,000 hits using the from and size parameters. To page through more - hits, use the `search_after` parameter. + :param from_: The starting document offset. It must not be negative. By default, + you cannot page through more than 10,000 hits using the `from` and `size` + parameters. To page through more hits, use the `search_after` parameter. :param query: A query to filter which API keys to return. If the query parameter is missing, it is equivalent to a `match_all` query. The query supports a subset of query types, including `match_all`, `bool`, `term`, `terms`, `match`, `ids`, `prefix`, `wildcard`, `exists`, `range`, and `simple_query_string`. You can query the following public information associated with an API key: `id`, `type`, `name`, `creation`, `expiration`, `invalidated`, `invalidation`, - `username`, `realm`, and `metadata`. - :param search_after: Search after definition - :param size: The number of hits to return. By default, you cannot page through - more than 10,000 hits using the `from` and `size` parameters. To page through - more hits, use the `search_after` parameter. - :param sort: Other than `id`, all public fields of an API key are eligible for - sorting. In addition, sort can also be applied to the `_doc` field to sort - by index order. + `username`, `realm`, and `metadata`. NOTE: The queryable string values associated + with API keys are internally mapped as keywords. Consequently, if no `analyzer` + parameter is specified for a `match` query, then the provided match query + string is interpreted as a single keyword value. Such a match query is hence + equivalent to a `term` query. + :param search_after: The search after definition. + :param size: The number of hits to return. It must not be negative. The `size` + parameter can be set to `0`, in which case no API key matches are returned, + only the aggregation results. By default, you cannot page through more than + 10,000 hits using the `from` and `size` parameters. To page through more + hits, use the `search_after` parameter. + :param sort: The sort definition. Other than `id`, all public fields of an API + key are eligible for sorting. In addition, sort can also be applied to the + `_doc` field to sort by index order. :param typed_keys: Determines whether aggregation names are prefixed by their respective types in the response. :param with_limited_by: Return the snapshot of the owner user's role descriptors associated with the API key. An API key's actual permission is the intersection - of its assigned role descriptors and the owner user's role descriptors. - :param with_profile_uid: Determines whether to also retrieve the profile uid, - for the API key owner principal, if it exists. + of its assigned role descriptors and the owner user's role descriptors (effectively + limited by it). An API key cannot retrieve any API key’s limited-by role + descriptors (including itself) unless it has `manage_api_key` or higher privileges. + :param with_profile_uid: Determines whether to also retrieve the profile UID + for the API key owner principal. If it exists, the profile UID is returned + under the `profile_uid` response field for each API key. """ __path_parts: t.Dict[str, str] = {} __path = "/_security/_query/api_key" @@ -917,7 +981,7 @@ async def query_role( pretty: t.Optional[bool] = None, query: t.Optional[t.Mapping[str, t.Any]] = None, search_after: t.Optional[ - t.Sequence[t.Union[None, bool, float, int, str, t.Any]] + t.Sequence[t.Union[None, bool, float, int, str]] ] = None, size: t.Optional[int] = None, sort: t.Optional[ @@ -929,26 +993,34 @@ async def query_role( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Find roles with a query. Get roles in a paginated manner. You can optionally - filter the results with a query. + .. raw:: html - ``_ +

Find roles with a query.

+

Get roles in a paginated manner. + The role management APIs are generally the preferred way to manage roles, rather than using file-based role management. + The query roles API does not retrieve roles that are defined in roles files, nor built-in ones. + You can optionally filter the results with a query. + Also, the results can be paginated and sorted.

- :param from_: Starting document offset. By default, you cannot page through more - than 10,000 hits using the from and size parameters. To page through more - hits, use the `search_after` parameter. + + ``_ + + :param from_: The starting document offset. It must not be negative. By default, + you cannot page through more than 10,000 hits using the `from` and `size` + parameters. To page through more hits, use the `search_after` parameter. :param query: A query to filter which roles to return. If the query parameter is missing, it is equivalent to a `match_all` query. The query supports a subset of query types, including `match_all`, `bool`, `term`, `terms`, `match`, `ids`, `prefix`, `wildcard`, `exists`, `range`, and `simple_query_string`. You can query the following information associated with roles: `name`, `description`, - `metadata`, `applications.application`, `applications.privileges`, `applications.resources`. - :param search_after: Search after definition - :param size: The number of hits to return. By default, you cannot page through - more than 10,000 hits using the `from` and `size` parameters. To page through - more hits, use the `search_after` parameter. - :param sort: All public fields of a role are eligible for sorting. In addition, - sort can also be applied to the `_doc` field to sort by index order. + `metadata`, `applications.application`, `applications.privileges`, and `applications.resources`. + :param search_after: The search after definition. + :param size: The number of hits to return. It must not be negative. By default, + you cannot page through more than 10,000 hits using the `from` and `size` + parameters. To page through more hits, use the `search_after` parameter. + :param sort: The sort definition. You can sort on `username`, `roles`, or `enabled`. + In addition, sort can also be applied to the `_doc` field to sort by index + order. """ __path_parts: t.Dict[str, str] = {} __path = "/_security/_query/role" @@ -1005,38 +1077,43 @@ async def update_api_key( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Update an API key. Updates attributes of an existing API key. Users can only - update API keys that they created or that were granted to them. Use this API - to update API keys created by the create API Key or grant API Key APIs. If you - need to apply the same update to many API keys, you can use bulk update API Keys - to reduce overhead. It’s not possible to update expired API keys, or API keys - that have been invalidated by invalidate API Key. This API supports updates to - an API key’s access scope and metadata. The access scope of an API key is derived - from the `role_descriptors` you specify in the request, and a snapshot of the - owner user’s permissions at the time of the request. The snapshot of the owner’s - permissions is updated automatically on every call. If you don’t specify `role_descriptors` - in the request, a call to this API might still change the API key’s access scope. - This change can occur if the owner user’s permissions have changed since the - API key was created or last modified. To update another user’s API key, use the - `run_as` feature to submit a request on behalf of another user. IMPORTANT: It’s - not possible to use an API key as the authentication credential for this API. - To update an API key, the owner user’s credentials are required. + .. raw:: html - ``_ +

Update an API key.

+

Update attributes of an existing API key. + This API supports updates to an API key's access scope, expiration, and metadata.

+

To use this API, you must have at least the manage_own_api_key cluster privilege. + Users can only update API keys that they created or that were granted to them. + To update another user’s API key, use the run_as feature to submit a request on behalf of another user.

+

IMPORTANT: It's not possible to use an API key as the authentication credential for this API. The owner user’s credentials are required.

+

Use this API to update API keys created by the create API key or grant API Key APIs. + If you need to apply the same update to many API keys, you can use the bulk update API keys API to reduce overhead. + It's not possible to update expired API keys or API keys that have been invalidated by the invalidate API key API.

+

The access scope of an API key is derived from the role_descriptors you specify in the request and a snapshot of the owner user's permissions at the time of the request. + The snapshot of the owner's permissions is updated automatically on every call.

+

IMPORTANT: If you don't specify role_descriptors in the request, a call to this API might still change the API key's access scope. + This change can occur if the owner user's permissions have changed since the API key was created or last modified.

+ + + ``_ :param id: The ID of the API key to update. - :param expiration: Expiration time for the API key. + :param expiration: The expiration time for the API key. By default, API keys + never expire. This property can be omitted to leave the expiration unchanged. :param metadata: Arbitrary metadata that you want to associate with the API key. - It supports nested data structure. Within the metadata object, keys beginning - with _ are reserved for system usage. - :param role_descriptors: An array of role descriptors for this API key. This - parameter is optional. When it is not specified or is an empty array, then - the API key will have a point in time snapshot of permissions of the authenticated - user. If you supply role descriptors then the resultant permissions would - be an intersection of API keys permissions and authenticated user’s permissions - thereby limiting the access scope for API keys. The structure of role descriptor - is the same as the request for create role API. For more details, see create - or update roles API. + It supports a nested data structure. Within the metadata object, keys beginning + with `_` are reserved for system usage. When specified, this value fully + replaces the metadata previously associated with the API key. + :param role_descriptors: The role descriptors to assign to this API key. The + API key's effective permissions are an intersection of its assigned privileges + and the point in time snapshot of permissions of the owner user. You can + assign new privileges by specifying them in this parameter. To remove assigned + privileges, you can supply an empty `role_descriptors` parameter, that is + to say, an empty object `{}`. If an API key has no assigned privileges, it + inherits the owner user's full permissions. The snapshot of the owner's permissions + is always updated, whether you supply the `role_descriptors` parameter or + not. The structure of a role descriptor is the same as the request for the + create API keys API. """ if id in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'id'") diff --git a/elasticsearch_serverless/_async/client/sql.py b/elasticsearch_serverless/_async/client/sql.py index 239df90..3eb37a6 100644 --- a/elasticsearch_serverless/_async/client/sql.py +++ b/elasticsearch_serverless/_async/client/sql.py @@ -39,9 +39,12 @@ async def clear_cursor( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Clear an SQL search cursor. + .. raw:: html - ``_ +

Clear an SQL search cursor.

+ + + ``_ :param cursor: Cursor to clear. """ @@ -84,13 +87,19 @@ async def delete_async( 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. If the Elasticsearch - security features are enabled, only the following users can use this API to delete - a search: * Users with the `cancel_task` cluster privilege. * The user who first - submitted the search. + .. raw:: html + +

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.

+

If the Elasticsearch security features are enabled, only the following users can use this API to delete a search:

+
    +
  • Users with the cancel_task cluster privilege.
    • +
  • The user who first submitted the search.
    • +
- ``_ + + ``_ :param id: The identifier for the search. """ @@ -134,12 +143,14 @@ async def get_async( ] = 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. If the Elasticsearch security - features are enabled, only the user who first submitted the SQL search can retrieve - the search using this API. + .. raw:: html + +

Get async SQL search results. + Get the current status and available results for an async SQL search or stored synchronous SQL search.

+

If the Elasticsearch security features are enabled, only the user who first submitted the SQL search can retrieve the search using this API.

+ - ``_ + ``_ :param id: The identifier for the search. :param delimiter: The separator for CSV results. The API supports this parameter @@ -195,10 +206,13 @@ async def get_async_status( 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 - ``_ +

Get the async SQL search status. + Get the current status of an async SQL search or a stored synchronous SQL search.

+ + + ``_ :param id: The identifier for the search. """ @@ -281,9 +295,13 @@ async def query( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Get SQL search results. Run an SQL request. + .. raw:: html + +

Get SQL search results. + Run an SQL request.

- ``_ + + ``_ :param allow_partial_search_results: If `true`, the response has partial results when there are shard request timeouts or shard failures. If `false`, the @@ -402,11 +420,14 @@ async def translate( 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. It accepts the same request body parameters - as the SQL search API, excluding `cursor`. + .. raw:: html + +

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 cursor.

+ - ``_ + ``_ :param query: The SQL query to run. :param fetch_size: The maximum number of rows (or entries) to return in one response. diff --git a/elasticsearch_serverless/_async/client/synonyms.py b/elasticsearch_serverless/_async/client/synonyms.py index 9cb6d9a..26b248a 100644 --- a/elasticsearch_serverless/_async/client/synonyms.py +++ b/elasticsearch_serverless/_async/client/synonyms.py @@ -36,23 +36,24 @@ async def delete_synonym( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - 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. - - ``_ + .. raw:: html + +

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.

+ + + ``_ :param id: The synonyms set identifier to delete. """ @@ -91,9 +92,13 @@ async def delete_synonym_rule( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Delete a synonym rule. Delete a synonym rule from a synonym set. + .. raw:: html + +

Delete a synonym rule. + Delete a synonym rule from a synonym set.

- ``_ + + ``_ :param set_id: The ID of the synonym set to update. :param rule_id: The ID of the synonym rule to delete. @@ -141,9 +146,12 @@ async def get_synonym( size: t.Optional[int] = None, ) -> ObjectApiResponse[t.Any]: """ - Get a synonym set. + .. raw:: html + +

Get a synonym set.

- ``_ + + ``_ :param id: The synonyms set identifier to retrieve. :param from_: The starting offset for query rules to retrieve. @@ -188,9 +196,13 @@ async def get_synonym_rule( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Get a synonym rule. Get a synonym rule from a synonym set. + .. raw:: html + +

Get a synonym rule. + Get a synonym rule from a synonym set.

- ``_ + + ``_ :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. @@ -237,9 +249,13 @@ async def get_synonyms_sets( size: t.Optional[int] = None, ) -> ObjectApiResponse[t.Any]: """ - Get all synonym sets. Get a summary of all defined synonym sets. + .. raw:: html + +

Get all synonym sets. + Get a summary of all defined synonym sets.

- ``_ + + ``_ :param from_: The starting offset for synonyms sets to retrieve. :param size: The maximum number of synonyms sets to retrieve. @@ -286,14 +302,16 @@ async def put_synonym( 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. 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. + .. raw:: html + +

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.

+

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.

- ``_ + + ``_ :param id: The ID of the synonyms set to be created or updated. :param synonyms_set: The synonym rules definitions for the synonyms set. @@ -344,12 +362,15 @@ async def put_synonym_rule( 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. 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. + .. raw:: html + +

Create or update a synonym rule. + Create or update a synonym rule in a synonym 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.

+ - ``_ + ``_ :param set_id: The ID of the synonym set. :param rule_id: The ID of the synonym rule to be updated or created. diff --git a/elasticsearch_serverless/_async/client/tasks.py b/elasticsearch_serverless/_async/client/tasks.py index 720dcb6..ab50c6c 100644 --- a/elasticsearch_serverless/_async/client/tasks.py +++ b/elasticsearch_serverless/_async/client/tasks.py @@ -45,13 +45,20 @@ async def get( wait_for_completion: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Get task information. Get information about a task currently running in the cluster. + .. raw:: html - ``_ +

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.

- :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. """ diff --git a/elasticsearch_serverless/_async/client/transform.py b/elasticsearch_serverless/_async/client/transform.py index 9e52df1..877119d 100644 --- a/elasticsearch_serverless/_async/client/transform.py +++ b/elasticsearch_serverless/_async/client/transform.py @@ -39,9 +39,12 @@ async def delete_transform( timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, ) -> ObjectApiResponse[t.Any]: """ - Delete a transform. Deletes a transform. + .. raw:: html - ``_ +

Delete a transform.

+ + + ``_ :param transform_id: Identifier for the transform. :param delete_dest_index: If this value is true, the destination index is deleted @@ -99,9 +102,13 @@ async def get_transform( size: t.Optional[int] = None, ) -> ObjectApiResponse[t.Any]: """ - Get transforms. Retrieves configuration information for transforms. + .. raw:: html + +

Get transforms. + Get configuration information for transforms.

- ``_ + + ``_ :param transform_id: Identifier for the transform. It can be a transform identifier or a wildcard expression. You can get information for all transforms by using @@ -168,9 +175,13 @@ async def get_transform_stats( timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, ) -> ObjectApiResponse[t.Any]: """ - Get transform stats. Retrieves usage information for transforms. + .. raw:: html + +

Get transform stats.

+

Get usage information for transforms.

- ``_ + + ``_ :param transform_id: Identifier for the transform. It can be a transform identifier or a wildcard expression. You can get information for all transforms by using @@ -249,14 +260,16 @@ async def preview_transform( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Preview a transform. Generates a preview of the results that you will get when - you create a transform with the same configuration. It returns a maximum of 100 - results. The calculations are based on all the current data in the source index. - It also generates a list of mappings and settings for the destination index. - These values are determined based on the field types of the source index and - the transform aggregations. + .. raw:: html + +

Preview a transform. + Generates a preview of the results that you will get when you create a transform with the same configuration.

+

It returns a maximum of 100 results. The calculations are based on all the current data in the source index. It also + generates a list of mappings and settings for the destination index. These values are determined based on the field + types of the source index and the transform aggregations.

- ``_ + + ``_ :param transform_id: Identifier for the transform to preview. If you specify this path parameter, you cannot provide transform configuration details in @@ -371,29 +384,29 @@ async def put_transform( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Create a transform. Creates a transform. A transform copies data from source - indices, transforms it, and persists it into an entity-centric destination index. - You can also think of the destination index as a two-dimensional tabular data - structure (known as a data frame). The ID for each document in the data frame - is generated from a hash of the entity, so there is a unique row per entity. - You must choose either the latest or pivot method for your transform; you cannot - use both in a single transform. If you choose to use the pivot method for your - transform, the entities are defined by the set of `group_by` fields in the pivot - object. If you choose to use the latest method, the entities are defined by the - `unique_key` field values in the latest object. You must have `create_index`, - `index`, and `read` privileges on the destination index and `read` and `view_index_metadata` - privileges on the source indices. When Elasticsearch security features are enabled, - the transform remembers which roles the user that created it had at the time - of creation and uses those same roles. If those roles do not have the required - privileges on the source and destination indices, the transform fails when it - attempts unauthorized operations. NOTE: You must use Kibana or this API to create - a transform. Do not add a transform directly into any `.transform-internal*` - indices using the Elasticsearch index API. If Elasticsearch security features - are enabled, do not give users any privileges on `.transform-internal*` indices. - If you used transforms prior to 7.5, also do not give users any privileges on - `.data-frame-internal*` indices. - - ``_ + .. raw:: html + +

Create a transform. + Creates a transform.

+

A transform copies data from source indices, transforms it, and persists it into an entity-centric destination index. You can also think of the destination index as a two-dimensional tabular data structure (known as + a data frame). The ID for each document in the data frame is generated from a hash of the entity, so there is a + unique row per entity.

+

You must choose either the latest or pivot method for your transform; you cannot use both in a single transform. If + you choose to use the pivot method for your transform, the entities are defined by the set of group_by fields in + the pivot object. If you choose to use the latest method, the entities are defined by the unique_key field values + in the latest object.

+

You must have create_index, index, and read privileges on the destination index and read and + view_index_metadata privileges on the source indices. When Elasticsearch security features are enabled, the + transform remembers which roles the user that created it had at the time of creation and uses those same roles. If + those roles do not have the required privileges on the source and destination indices, the transform fails when it + attempts unauthorized operations.

+

NOTE: You must use Kibana or this API to create a transform. Do not add a transform directly into any + .transform-internal* indices using the Elasticsearch index API. If Elasticsearch security features are enabled, do + not give users any privileges on .transform-internal* indices. If you used transforms prior to 7.5, also do not + give users any privileges on .data-frame-internal* indices.

+ + + ``_ :param transform_id: Identifier for the transform. This identifier can contain lowercase alphanumeric characters (a-z and 0-9), hyphens, and underscores. @@ -492,11 +505,14 @@ async def reset_transform( timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, ) -> ObjectApiResponse[t.Any]: """ - Reset a transform. Resets a transform. Before you can reset it, you must stop - it; alternatively, use the `force` query parameter. If the destination index - was created by the transform, it is deleted. + .. raw:: html + +

Reset a transform.

+

Before you can reset it, you must stop it; alternatively, use the force query parameter. + If the destination index was created by the transform, it is deleted.

- ``_ + + ``_ :param transform_id: Identifier for the transform. This identifier can contain lowercase alphanumeric characters (a-z and 0-9), hyphens, and underscores. @@ -546,13 +562,17 @@ async def schedule_now_transform( timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, ) -> ObjectApiResponse[t.Any]: """ - Schedule a transform to start now. Instantly runs a transform to process data. - If you _schedule_now a transform, it will process the new data instantly, without - waiting for the configured frequency interval. After _schedule_now API is called, - the transform will be processed again at now + frequency unless _schedule_now - API is called again in the meantime. + .. raw:: html + +

Schedule a transform to start now.

+

Instantly run a transform to process data. + If you run this API, the transform will process the new data instantly, + without waiting for the configured frequency interval. After the API is called, + the transform will be processed again at now + frequency unless the API + is called again in the meantime.

- ``_ + + ``_ :param transform_id: Identifier for the transform. :param timeout: Controls the time to wait for the scheduling to take place @@ -597,26 +617,25 @@ async def start_transform( timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, ) -> ObjectApiResponse[t.Any]: """ - Start a transform. Starts a transform. When you start a transform, it creates - the destination index if it does not already exist. The `number_of_shards` is - set to `1` and the `auto_expand_replicas` is set to `0-1`. If it is a pivot transform, - it deduces the mapping definitions for the destination index from the source - indices and the transform aggregations. If fields in the destination index are - derived from scripts (as in the case of `scripted_metric` or `bucket_script` - aggregations), the transform uses dynamic mappings unless an index template exists. - If it is a latest transform, it does not deduce mapping definitions; it uses - dynamic mappings. To use explicit mappings, create the destination index before - you start the transform. Alternatively, you can create an index template, though - it does not affect the deduced mappings in a pivot transform. When the transform - starts, a series of validations occur to ensure its success. If you deferred - validation when you created the transform, they occur when you start the transform—​with - the exception of privilege checks. When Elasticsearch security features are enabled, - the transform remembers which roles the user that created it had at the time - of creation and uses those same roles. If those roles do not have the required - privileges on the source and destination indices, the transform fails when it - attempts unauthorized operations. - - ``_ + .. raw:: html + +

Start a transform.

+

When you start a transform, it creates the destination index if it does not already exist. The number_of_shards is + set to 1 and the auto_expand_replicas is set to 0-1. If it is a pivot transform, it deduces the mapping + definitions for the destination index from the source indices and the transform aggregations. If fields in the + destination index are derived from scripts (as in the case of scripted_metric or bucket_script aggregations), + the transform uses dynamic mappings unless an index template exists. If it is a latest transform, it does not deduce + mapping definitions; it uses dynamic mappings. To use explicit mappings, create the destination index before you + start the transform. Alternatively, you can create an index template, though it does not affect the deduced mappings + in a pivot transform.

+

When the transform starts, a series of validations occur to ensure its success. If you deferred validation when you + created the transform, they occur when you start the transform—​with the exception of privilege checks. When + Elasticsearch security features are enabled, the transform remembers which roles the user that created it had at the + time of creation and uses those same roles. If those roles do not have the required privileges on the source and + destination indices, the transform fails when it attempts unauthorized operations.

+ + + ``_ :param transform_id: Identifier for the transform. :param from_: Restricts the set of transformed entities to those changed after @@ -668,9 +687,13 @@ async def stop_transform( wait_for_completion: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Stop transforms. Stops one or more transforms. + .. raw:: html + +

Stop transforms. + Stops one or more transforms.

- ``_ + + ``_ :param transform_id: Identifier for the transform. To stop multiple transforms, use a comma-separated list or a wildcard expression. To stop all transforms, @@ -761,16 +784,18 @@ async def update_transform( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Update a transform. Updates certain properties of a transform. All updated properties - except `description` do not take effect until after the transform starts the - next checkpoint, thus there is data consistency in each checkpoint. To use this - API, you must have `read` and `view_index_metadata` privileges for the source - indices. You must also have `index` and `read` privileges for the destination - index. When Elasticsearch security features are enabled, the transform remembers - which roles the user who updated it had at the time of update and runs with those - privileges. - - ``_ + .. raw:: html + +

Update a transform. + Updates certain properties of a transform.

+

All updated properties except description do not take effect until after the transform starts the next checkpoint, + thus there is data consistency in each checkpoint. To use this API, you must have read and view_index_metadata + privileges for the source indices. You must also have index and read privileges for the destination index. When + Elasticsearch security features are enabled, the transform remembers which roles the user who updated it had at the + time of update and runs with those privileges.

+ + + ``_ :param transform_id: Identifier for the transform. :param defer_validation: When true, deferrable validations are not run. This diff --git a/elasticsearch_serverless/_sync/client/__init__.py b/elasticsearch_serverless/_sync/client/__init__.py index 74bca5e..73f8492 100644 --- a/elasticsearch_serverless/_sync/client/__init__.py +++ b/elasticsearch_serverless/_sync/client/__init__.py @@ -454,6 +454,7 @@ def bulk( error_trace: t.Optional[bool] = None, filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, human: t.Optional[bool] = None, + include_source_on_error: t.Optional[bool] = None, list_executed_pipelines: t.Optional[bool] = None, pipeline: t.Optional[str] = None, pretty: t.Optional[bool] = None, @@ -472,41 +473,133 @@ def bulk( ] = None, ) -> ObjectApiResponse[t.Any]: """ - Bulk index or delete documents. Performs multiple indexing or delete operations - in a single API call. This reduces overhead and can greatly increase indexing - speed. - - ``_ + .. raw:: html + +

Bulk index or delete documents. + Perform multiple index, create, delete, and update actions in a single request. + This reduces overhead and can greatly increase indexing speed.

+

If the Elasticsearch security features are enabled, you must have the following index privileges for the target data stream, index, or index alias:

+
    +
  • To use the create action, you must have the create_doc, create, index, or write index privilege. Data streams support only the create action.
    • +
  • To use the index action, you must have the create, index, or write index privilege.
    • +
  • To use the delete action, you must have the delete or write index privilege.
    • +
  • To use the update action, you must have the index or write index privilege.
    • +
  • To automatically create a data stream or index with a bulk API request, you must have the auto_configure, create_index, or manage index privilege.
    • +
  • To make the result of a bulk operation visible to search using the refresh parameter, you must have the maintenance or manage index privilege.
    • +
+

Automatic data stream creation requires a matching index template with data stream enabled.

+

The actions are specified in the request body using a newline delimited JSON (NDJSON) structure:

+ 
action_and_meta_data\\n
+          optional_source\\n
+          action_and_meta_data\\n
+          optional_source\\n
+          ....
+          action_and_meta_data\\n
+          optional_source\\n
+
+

The index and create actions expect a source on the next line and have the same semantics as the op_type parameter in the standard index API. + A create action fails if a document with the same ID already exists in the target + An index action adds or replaces a document as necessary.

+

NOTE: Data streams support only the create action. + To update or delete a document in a data stream, you must target the backing index containing the document.

+

An update action expects that the partial doc, upsert, and script and its options are specified on the next line.

+

A delete action does not expect a source on the next line and has the same semantics as the standard delete API.

+

NOTE: The final line of data must end with a newline character (\\n). + Each newline character may be preceded by a carriage return (\\r). + When sending NDJSON data to the _bulk endpoint, use a Content-Type header of application/json or application/x-ndjson. + Because this format uses literal newline characters (\\n) as delimiters, make sure that the JSON actions and sources are not pretty printed.

+

If you provide a target in the request path, it is used for any actions that don't explicitly specify an _index argument.

+

A note on the format: the idea here is to make processing as fast as possible. + As some of the actions are redirected to other shards on other nodes, only action_meta_data is parsed on the receiving node side.

+

Client libraries using this protocol should try and strive to do something similar on the client side, and reduce buffering as much as possible.

+

There is no "correct" number of actions to perform in a single bulk request. + Experiment with different settings to find the optimal size for your particular workload. + Note that Elasticsearch limits the maximum size of a HTTP request to 100mb by default so clients must ensure that no request exceeds this size. + It is not possible to index a single document that exceeds the size limit, so you must pre-process any such documents into smaller pieces before sending them to Elasticsearch. + For instance, split documents into pages or chapters before indexing them, or store raw binary data in a system outside Elasticsearch and replace the raw data with a link to the external system in the documents that you send to Elasticsearch.

+

Client suppport for bulk requests

+

Some of the officially supported clients provide helpers to assist with bulk requests and reindexing:

+
    +
  • Go: Check out esutil.BulkIndexer
    • +
  • Perl: Check out Search::Elasticsearch::Client::5_0::Bulk and Search::Elasticsearch::Client::5_0::Scroll
    • +
  • Python: Check out elasticsearch.helpers.*
    • +
  • JavaScript: Check out client.helpers.*
    • +
  • .NET: Check out BulkAllObservable
    • +
  • PHP: Check out bulk indexing.
    • +
+

Submitting bulk requests with cURL

+

If you're providing text file input to curl, you must use the --data-binary flag instead of plain -d. + The latter doesn't preserve newlines. For example:

+ 
$ cat requests
+          { "index" : { "_index" : "test", "_id" : "1" } }
+          { "field1" : "value1" }
+          $ curl -s -H "Content-Type: application/x-ndjson" -XPOST localhost:9200/_bulk --data-binary "@requests"; echo
+          {"took":7, "errors": false, "items":[{"index":{"_index":"test","_id":"1","_version":1,"result":"created","forced_refresh":false}}]}
+
+

Optimistic concurrency control

+

Each index and delete action within a bulk API call may include the if_seq_no and if_primary_term parameters in their respective action and meta data lines. + The if_seq_no and if_primary_term parameters control how operations are run, based on the last modification to existing documents. See Optimistic concurrency control for more details.

+

Versioning

+

Each bulk item can include the version value using the version field. + It automatically follows the behavior of the index or delete operation based on the _version mapping. + It also support the version_type.

+

Routing

+

Each bulk item can include the routing value using the routing field. + It automatically follows the behavior of the index or delete operation based on the _routing mapping.

+

NOTE: Data streams do not support custom routing unless they were created with the allow_custom_routing setting enabled in the template.

+

Wait for active shards

+

When making bulk calls, you can set the wait_for_active_shards parameter to require a minimum number of shard copies to be active before starting to process the bulk request.

+

Refresh

+

Control when the changes made by this request are visible to search.

+

NOTE: Only the shards that receive the bulk request will be affected by refresh. + Imagine a _bulk?refresh=wait_for request with three documents in it that happen to be routed to different shards in an index with five shards. + The request will only wait for those three shards to refresh. + The other two shards that make up the index do not participate in the _bulk request at all.

+ + + ``_ :param operations: - :param index: Name of the data stream, index, or index alias to perform bulk + :param index: The name of the data stream, index, or index alias to perform bulk actions on. + :param include_source_on_error: True or false if to include the document source + in the error message in case of parsing errors. :param list_executed_pipelines: If `true`, the response will include the ingest - pipelines that were executed for each index or create. - :param pipeline: ID of the pipeline to use to preprocess incoming documents. - If the index has a default ingest pipeline specified, then setting the value - to `_none` disables the default ingest pipeline for this request. If a final - pipeline is configured it will always run, regardless of the value of this + pipelines that were run for each index or create. + :param pipeline: The pipeline identifier to use to preprocess incoming documents. + If the index has a default ingest pipeline specified, setting the value to + `_none` turns off the default ingest pipeline for this request. If a final + pipeline is configured, it will always run regardless of the value of this parameter. :param refresh: If `true`, Elasticsearch refreshes the affected shards to make - this operation visible to search, if `wait_for` then wait for a refresh to - make this operation visible to search, if `false` do nothing with refreshes. + this operation visible to search. If `wait_for`, wait for a refresh to make + this operation visible to search. If `false`, do nothing with refreshes. Valid values: `true`, `false`, `wait_for`. - :param require_alias: If `true`, the request’s actions must target an index alias. + :param require_alias: If `true`, the request's actions must target an index alias. :param require_data_stream: If `true`, the request's actions must target a data - stream (existing or to-be-created). - :param routing: Custom value used to route operations to a specific shard. - :param source: `true` or `false` to return the `_source` field or not, or a list - of fields to return. + stream (existing or to be created). + :param routing: A custom value that is used to route operations to a specific + shard. + :param source: Indicates whether to return the `_source` field (`true` or `false`) + or contains a list of fields to return. :param source_excludes: A comma-separated list of source fields to exclude from - the response. + the response. You can also use this parameter to exclude fields from the + subset specified in `_source_includes` query parameter. If the `_source` + parameter is `false`, this parameter is ignored. :param source_includes: A comma-separated list of source fields to include in - the response. - :param timeout: Period each action waits for the following operations: automatic - index creation, dynamic mapping updates, waiting for active shards. + the response. If this parameter is specified, only these source fields are + returned. You can exclude fields from this subset using the `_source_excludes` + query parameter. If the `_source` parameter is `false`, this parameter is + ignored. + :param timeout: The period each action waits for the following operations: automatic + index creation, dynamic mapping updates, and waiting for active shards. The + default is `1m` (one minute), which guarantees Elasticsearch waits for at + least the timeout before failing. The actual wait time could be longer, particularly + when multiple waits occur. :param wait_for_active_shards: The number of shard copies that must be active - before proceeding with the operation. Set to all or any positive integer - up to the total number of shards in the index (`number_of_replicas+1`). + before proceeding with the operation. Set to `all` or any positive integer + up to the total number of shards in the index (`number_of_replicas+1`). The + default is `1`, which waits for each primary shard to be active. """ if operations is None and body is None: raise ValueError( @@ -528,6 +621,8 @@ def bulk( __query["filter_path"] = filter_path if human is not None: __query["human"] = human + if include_source_on_error is not None: + __query["include_source_on_error"] = include_source_on_error if list_executed_pipelines is not None: __query["list_executed_pipelines"] = list_executed_pipelines if pipeline is not None: @@ -581,12 +676,15 @@ def clear_scroll( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Clear a scrolling search. Clear the search context and results for a scrolling - search. + .. raw:: html - ``_ +

Clear a scrolling search. + Clear the search context and results for a scrolling search.

- :param scroll_id: Scroll IDs to clear. To clear all scroll IDs, use `_all`. + + ``_ + + :param scroll_id: The scroll IDs to clear. To clear all scroll IDs, use `_all`. """ __path_parts: t.Dict[str, str] = {} __path = "/_search/scroll" @@ -632,13 +730,16 @@ def close_point_in_time( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - 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. + .. raw:: html + +

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.

- ``_ + + ``_ :param id: The ID of the point-in-time. """ @@ -710,46 +811,65 @@ def count( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Count search results. Get the number of documents matching a query. + .. raw:: html + +

Count search results. + Get the number of documents matching a query.

+

The query can be provided either by using a simple query string as a parameter, or by defining Query DSL within the request body. + The query is optional. When no query is provided, the API uses match_all to count all the documents.

+

The count API supports multi-target syntax. You can run a single count API search across multiple data streams and indices.

+

The operation is broadcast across all shards. + For each shard ID group, a replica is chosen and the search is run against it. + This means that replicas increase the scalability of the count.

- ``_ - :param index: Comma-separated list of data streams, indices, and aliases to search. - Supports wildcards (`*`). To search all data streams and indices, omit this - parameter or use `*` or `_all`. + ``_ + + :param index: A comma-separated list of data streams, indices, and aliases to + search. It supports wildcards (`*`). To search all data streams and indices, + omit this parameter or use `*` or `_all`. :param allow_no_indices: If `false`, the request returns an error if any wildcard expression, index alias, or `_all` value targets only missing or closed indices. - This behavior applies even if the request targets other open indices. + This behavior applies even if the request targets other open indices. For + example, a request targeting `foo*,bar*` returns an error if an index starts + with `foo` but no index starts with `bar`. :param analyze_wildcard: If `true`, wildcard and prefix queries are analyzed. - This parameter can only be used when the `q` query string parameter is specified. - :param analyzer: Analyzer to use for the query string. This parameter can only - be used when the `q` query string parameter is specified. + This parameter can be used only when the `q` query string parameter is specified. + :param analyzer: The analyzer to use for the query string. This parameter can + be used only when the `q` query string parameter is specified. :param default_operator: The default operator for query string query: `AND` or - `OR`. This parameter can only be used when the `q` query string parameter + `OR`. This parameter can be used only when the `q` query string parameter is specified. - :param df: Field to use as default where no field prefix is given in the query - string. This parameter can only be used when the `q` query string parameter + :param df: The field to use as a default when no field prefix is given in the + query string. This parameter can be used only when the `q` query string parameter is specified. - :param expand_wildcards: Type of index that wildcard patterns can match. If the - request can target data streams, this argument determines whether wildcard - expressions match hidden data streams. Supports comma-separated values, such - as `open,hidden`. - :param ignore_throttled: If `true`, concrete, expanded or aliased indices are + :param expand_wildcards: The type of index that wildcard patterns can match. + If the request can target data streams, this argument determines whether + wildcard expressions match hidden data streams. It supports comma-separated + values, such as `open,hidden`. + :param ignore_throttled: If `true`, concrete, expanded, or aliased indices are ignored when frozen. :param ignore_unavailable: If `false`, the request returns an error if it targets a missing or closed index. :param lenient: If `true`, format-based query failures (such as providing text - to a numeric field) in the query string will be ignored. - :param min_score: Sets the minimum `_score` value that documents must have to - be included in the result. - :param preference: Specifies the node or shard the operation should be performed - on. Random by default. - :param q: Query in the Lucene query string syntax. - :param query: Defines the search definition using the Query DSL. - :param routing: Custom value used to route operations to a specific shard. - :param terminate_after: Maximum number of documents to collect for each shard. + to a numeric field) in the query string will be ignored. This parameter can + be used only when the `q` query string parameter is specified. + :param min_score: The minimum `_score` value that documents must have to be included + in the result. + :param preference: The node or shard the operation should be performed on. By + default, it is random. + :param q: The query in Lucene query string syntax. This parameter cannot be used + with a request body. + :param query: Defines the search query using Query DSL. A request body query + cannot be used with the `q` query string parameter. + :param routing: A custom value used to route operations to a specific shard. + :param terminate_after: The maximum number of documents to collect for each shard. If a query reaches this limit, Elasticsearch terminates the query early. - Elasticsearch collects documents before sorting. + Elasticsearch collects documents before sorting. IMPORTANT: Use with caution. + Elasticsearch applies this parameter to each shard handling the request. + When possible, let Elasticsearch perform early termination automatically. + Avoid specifying this parameter for requests that target data streams with + backing indices across multiple data tiers. """ __path_parts: t.Dict[str, str] if index not in SKIP_IN_PATH: @@ -827,6 +947,7 @@ def create( error_trace: t.Optional[bool] = None, filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, human: t.Optional[bool] = None, + include_source_on_error: t.Optional[bool] = None, pipeline: t.Optional[str] = None, pretty: t.Optional[bool] = None, refresh: t.Optional[ @@ -843,38 +964,102 @@ def create( ] = None, ) -> ObjectApiResponse[t.Any]: """ - Index a document. Adds a JSON document to the specified data stream or index - and makes it searchable. If the target is an index and the document already exists, - the request updates the document and increments its version. - - ``_ - - :param index: Name of the data stream or index to target. If the target doesn’t + .. raw:: html + +

Create a new document in the index.

+

You can index a new JSON document with the /<target>/_doc/ or /<target>/_create/<_id> APIs + Using _create guarantees that the document is indexed only if it does not already exist. + It returns a 409 response when a document with a same ID already exists in the index. + To update an existing document, you must use the /<target>/_doc/ API.

+

If the Elasticsearch security features are enabled, you must have the following index privileges for the target data stream, index, or index alias:

+
    +
  • To add a document using the PUT /<target>/_create/<_id> or POST /<target>/_create/<_id> request formats, you must have the create_doc, create, index, or write index privilege.
    • +
  • To automatically create a data stream or index with this API request, you must have the auto_configure, create_index, or manage index privilege.
    • +
+

Automatic data stream creation requires a matching index template with data stream enabled.

+

Automatically create data streams and indices

+

If the request's target doesn't exist and matches an index template with a data_stream definition, the index operation automatically creates the data stream.

+

If the target doesn't exist and doesn't match a data stream template, the operation automatically creates the index and applies any matching index templates.

+

NOTE: Elasticsearch includes several built-in index templates. To avoid naming collisions with these templates, refer to index pattern documentation.

+

If no mapping exists, the index operation creates a dynamic mapping. + By default, new fields and objects are automatically added to the mapping if needed.

+

Automatic index creation is controlled by the action.auto_create_index setting. + If it is true, any index can be created automatically. + You can modify this setting to explicitly allow or block automatic creation of indices that match specified patterns or set it to false to turn off automatic index creation entirely. + Specify a comma-separated list of patterns you want to allow or prefix each pattern with + or - to indicate whether it should be allowed or blocked. + When a list is specified, the default behaviour is to disallow.

+

NOTE: The action.auto_create_index setting affects the automatic creation of indices only. + It does not affect the creation of data streams.

+

Routing

+

By default, shard placement — or routing — is controlled by using a hash of the document's ID value. + For more explicit control, the value fed into the hash function used by the router can be directly specified on a per-operation basis using the routing parameter.

+

When setting up explicit mapping, you can also use the _routing field to direct the index operation to extract the routing value from the document itself. + This does come at the (very minimal) cost of an additional document parsing pass. + If the _routing mapping is defined and set to be required, the index operation will fail if no routing value is provided or extracted.

+

NOTE: Data streams do not support custom routing unless they were created with the allow_custom_routing setting enabled in the template.

+

Distributed

+

The index operation is directed to the primary shard based on its route and performed on the actual node containing this shard. + After the primary shard completes the operation, if needed, the update is distributed to applicable replicas.

+

Active shards

+

To improve the resiliency of writes to the system, indexing operations can be configured to wait for a certain number of active shard copies before proceeding with the operation. + If the requisite number of active shard copies are not available, then the write operation must wait and retry, until either the requisite shard copies have started or a timeout occurs. + By default, write operations only wait for the primary shards to be active before proceeding (that is to say wait_for_active_shards is 1). + This default can be overridden in the index settings dynamically by setting index.write.wait_for_active_shards. + To alter this behavior per operation, use the wait_for_active_shards request parameter.

+

Valid values are all or any positive integer up to the total number of configured copies per shard in the index (which is number_of_replicas+1). + Specifying a negative value or a number greater than the number of shard copies will throw an error.

+

For example, suppose you have a cluster of three nodes, A, B, and C and you create an index index with the number of replicas set to 3 (resulting in 4 shard copies, one more copy than there are nodes). + If you attempt an indexing operation, by default the operation will only ensure the primary copy of each shard is available before proceeding. + This means that even if B and C went down and A hosted the primary shard copies, the indexing operation would still proceed with only one copy of the data. + If wait_for_active_shards is set on the request to 3 (and all three nodes are up), the indexing operation will require 3 active shard copies before proceeding. + This requirement should be met because there are 3 active nodes in the cluster, each one holding a copy of the shard. + However, if you set wait_for_active_shards to all (or to 4, which is the same in this situation), the indexing operation will not proceed as you do not have all 4 copies of each shard active in the index. + The operation will timeout unless a new node is brought up in the cluster to host the fourth copy of the shard.

+

It is important to note that this setting greatly reduces the chances of the write operation not writing to the requisite number of shard copies, but it does not completely eliminate the possibility, because this check occurs before the write operation starts. + After the write operation is underway, it is still possible for replication to fail on any number of shard copies but still succeed on the primary. + The _shards section of the API response reveals the number of shard copies on which replication succeeded and failed.

+ + + ``_ + + :param index: The name of the data stream or index to target. If the target doesn't exist and matches the name or wildcard (`*`) pattern of an index template with a `data_stream` definition, this request creates the data stream. If - the target doesn’t exist and doesn’t match a data stream template, this request + the target doesn't exist and doesn’t match a data stream template, this request creates the index. - :param id: Unique identifier for the document. + :param id: A unique identifier for the document. To automatically generate a + document ID, use the `POST //_doc/` request format. :param document: - :param pipeline: ID of the pipeline to use to preprocess incoming documents. - If the index has a default ingest pipeline specified, then setting the value - to `_none` disables the default ingest pipeline for this request. If a final - pipeline is configured it will always run, regardless of the value of this + :param include_source_on_error: True or false if to include the document source + in the error message in case of parsing errors. + :param pipeline: The ID of the pipeline to use to preprocess incoming documents. + If the index has a default ingest pipeline specified, setting the value to + `_none` turns off the default ingest pipeline for this request. If a final + pipeline is configured, it will always run regardless of the value of this parameter. :param refresh: If `true`, Elasticsearch refreshes the affected shards to make - this operation visible to search, if `wait_for` then wait for a refresh to - make this operation visible to search, if `false` do nothing with refreshes. - Valid values: `true`, `false`, `wait_for`. - :param routing: Custom value used to route operations to a specific shard. - :param timeout: Period the request waits for the following operations: automatic - index creation, dynamic mapping updates, waiting for active shards. - :param version: Explicit version number for concurrency control. The specified - version must match the current version of the document for the request to - succeed. - :param version_type: Specific version type: `external`, `external_gte`. + this operation visible to search. If `wait_for`, it waits for a refresh to + make this operation visible to search. If `false`, it does nothing with refreshes. + :param routing: A custom value that is used to route operations to a specific + shard. + :param timeout: The period the request waits for the following operations: automatic + index creation, dynamic mapping updates, waiting for active shards. Elasticsearch + waits for at least the specified timeout period before failing. The actual + wait time could be longer, particularly when multiple waits occur. This parameter + is useful for situations where the primary shard assigned to perform the + operation might not be available when the operation runs. Some reasons for + this might be that the primary shard is currently recovering from a gateway + or undergoing relocation. By default, the operation will wait on the primary + shard to become available for at least 1 minute before failing and responding + with an error. The actual wait time could be longer, particularly when multiple + waits occur. + :param version: The explicit version number for concurrency control. It must + be a non-negative long number. + :param version_type: The version type. :param wait_for_active_shards: The number of shard copies that must be active - before proceeding with the operation. Set to `all` or any positive integer - up to the total number of shards in the index (`number_of_replicas+1`). + before proceeding with the operation. You can set it to `all` or any positive + integer up to the total number of shards in the index (`number_of_replicas+1`). + The default value of `1` means it waits for each primary shard to be active. """ if index in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'index'") @@ -895,6 +1080,8 @@ def create( __query["filter_path"] = filter_path if human is not None: __query["human"] = human + if include_source_on_error is not None: + __query["include_source_on_error"] = include_source_on_error if pipeline is not None: __query["pipeline"] = pipeline if pretty is not None: @@ -949,29 +1136,60 @@ def delete( ] = None, ) -> ObjectApiResponse[t.Any]: """ - Delete a document. Removes a JSON document from the specified index. - - ``_ - - :param index: Name of the target index. - :param id: Unique identifier for the document. + .. raw:: html + +

Delete a document.

+

Remove a JSON document from the specified index.

+

NOTE: You cannot send deletion requests directly to a data stream. + To delete a document in a data stream, you must target the backing index containing the document.

+

Optimistic concurrency control

+

Delete operations can be made conditional and only be performed if the last modification to the document was assigned the sequence number and primary term specified by the if_seq_no and if_primary_term parameters. + If a mismatch is detected, the operation will result in a VersionConflictException and a status code of 409.

+

Versioning

+

Each document indexed is versioned. + When deleting a document, the version can be specified to make sure the relevant document you are trying to delete is actually being deleted and it has not changed in the meantime. + Every write operation run on a document, deletes included, causes its version to be incremented. + The version number of a deleted document remains available for a short time after deletion to allow for control of concurrent operations. + The length of time for which a deleted document's version remains available is determined by the index.gc_deletes index setting.

+

Routing

+

If routing is used during indexing, the routing value also needs to be specified to delete a document.

+

If the _routing mapping is set to required and no routing value is specified, the delete API throws a RoutingMissingException and rejects the request.

+

For example:

+ 
DELETE /my-index-000001/_doc/1?routing=shard-1
+
+

This request deletes the document with ID 1, but it is routed based on the user. + The document is not deleted if the correct routing is not specified.

+

Distributed

+

The delete operation gets hashed into a specific shard ID. + It then gets redirected into the primary shard within that ID group and replicated (if needed) to shard replicas within that ID group.

+ + + ``_ + + :param index: The name of the target index. + :param id: A unique identifier for the document. :param if_primary_term: Only perform the operation if the document has this primary term. :param if_seq_no: Only perform the operation if the document has this sequence number. :param refresh: If `true`, Elasticsearch refreshes the affected shards to make - this operation visible to search, if `wait_for` then wait for a refresh to - make this operation visible to search, if `false` do nothing with refreshes. - Valid values: `true`, `false`, `wait_for`. - :param routing: Custom value used to route operations to a specific shard. - :param timeout: Period to wait for active shards. - :param version: Explicit version number for concurrency control. The specified - version must match the current version of the document for the request to - succeed. - :param version_type: Specific version type: `external`, `external_gte`. - :param wait_for_active_shards: The number of shard copies that must be active - before proceeding with the operation. Set to `all` or any positive integer - up to the total number of shards in the index (`number_of_replicas+1`). + this operation visible to search. If `wait_for`, it waits for a refresh to + make this operation visible to search. If `false`, it does nothing with refreshes. + :param routing: A custom value used to route operations to a specific shard. + :param timeout: The period to wait for active shards. This parameter is useful + for situations where the primary shard assigned to perform the delete operation + might not be available when the delete operation runs. Some reasons for this + might be that the primary shard is currently recovering from a store or undergoing + relocation. By default, the delete operation will wait on the primary shard + to become available for up to 1 minute before failing and responding with + an error. + :param version: An explicit version number for concurrency control. It must match + the current version of the document for the request to succeed. + :param version_type: The version type. + :param wait_for_active_shards: The minimum number of shard copies that must be + active before proceeding with the operation. You can set it to `all` or any + positive integer up to the total number of shards in the index (`number_of_replicas+1`). + The default value of `1` means it waits for each primary shard to be active. """ if index in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'index'") @@ -1071,72 +1289,148 @@ def delete_by_query( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Delete documents. Deletes documents that match the specified query. - - ``_ - - :param index: Comma-separated list of data streams, indices, and aliases to search. - Supports wildcards (`*`). To search all data streams or indices, omit this - parameter or use `*` or `_all`. + .. raw:: html + +

Delete documents.

+

Deletes documents that match the specified query.

+

If the Elasticsearch security features are enabled, you must have the following index privileges for the target data stream, index, or alias:

+
    +
  • read
    • +
  • delete or write
    • +
+

You can specify the query criteria in the request URI or the request body using the same syntax as the search API. + When you submit a delete by query request, Elasticsearch gets a snapshot of the data stream or index when it begins processing the request and deletes matching documents using internal versioning. + If a document changes between the time that the snapshot is taken and the delete operation is processed, it results in a version conflict and the delete operation fails.

+

NOTE: Documents with a version equal to 0 cannot be deleted using delete by query because internal versioning does not support 0 as a valid version number.

+

While processing a delete by query request, Elasticsearch performs multiple search requests sequentially to find all of the matching documents to delete. + A bulk delete request is performed for each batch of matching documents. + If a search or bulk request is rejected, the requests are retried up to 10 times, with exponential back off. + If the maximum retry limit is reached, processing halts and all failed requests are returned in the response. + Any delete requests that completed successfully still stick, they are not rolled back.

+

You can opt to count version conflicts instead of halting and returning by setting conflicts to proceed. + Note that if you opt to count version conflicts the operation could attempt to delete more documents from the source than max_docs until it has successfully deleted max_docs documents, or it has gone through every document in the source query.

+

Throttling delete requests

+

To control the rate at which delete by query issues batches of delete operations, you can set requests_per_second to any positive decimal number. + This pads each batch with a wait time to throttle the rate. + Set requests_per_second to -1 to disable throttling.

+

Throttling uses a wait time between batches so that the internal scroll requests can be given a timeout that takes the request padding into account. + The padding time is the difference between the batch size divided by the requests_per_second and the time spent writing. + By default the batch size is 1000, so if requests_per_second is set to 500:

+ 
target_time = 1000 / 500 per second = 2 seconds
+          wait_time = target_time - write_time = 2 seconds - .5 seconds = 1.5 seconds
+
+

Since the batch is issued as a single _bulk request, large batch sizes cause Elasticsearch to create many requests and wait before starting the next set. + This is "bursty" instead of "smooth".

+

Slicing

+

Delete by query supports sliced scroll to parallelize the delete process. + This can improve efficiency and provide a convenient way to break the request down into smaller parts.

+

Setting slices to auto lets Elasticsearch choose the number of slices to use. + This setting will use one slice per shard, up to a certain limit. + If there are multiple source data streams or indices, it will choose the number of slices based on the index or backing index with the smallest number of shards. + Adding slices to the delete by query operation creates sub-requests which means it has some quirks:

+
    +
  • You can see these requests in the tasks APIs. These sub-requests are "child" tasks of the task for the request with slices.
    • +
  • Fetching the status of the task for the request with slices only contains the status of completed slices.
    • +
  • These sub-requests are individually addressable for things like cancellation and rethrottling.
    • +
  • Rethrottling the request with slices will rethrottle the unfinished sub-request proportionally.
    • +
  • Canceling the request with slices will cancel each sub-request.
    • +
  • Due to the nature of slices each sub-request won't get a perfectly even portion of the documents. All documents will be addressed, but some slices may be larger than others. Expect larger slices to have a more even distribution.
    • +
  • Parameters like requests_per_second and max_docs on a request with slices are distributed proportionally to each sub-request. Combine that with the earlier point about distribution being uneven and you should conclude that using max_docs with slices might not result in exactly max_docs documents being deleted.
    • +
  • Each sub-request gets a slightly different snapshot of the source data stream or index though these are all taken at approximately the same time.
    • +
+

If you're slicing manually or otherwise tuning automatic slicing, keep in mind that:

+
    +
  • Query performance is most efficient when the number of slices is equal to the number of shards in the index or backing index. If that number is large (for example, 500), choose a lower number as too many slices hurts performance. Setting slices higher than the number of shards generally does not improve efficiency and adds overhead.
    • +
  • Delete performance scales linearly across available resources with the number of slices.
    • +
+

Whether query or delete performance dominates the runtime depends on the documents being reindexed and cluster resources.

+

Cancel a delete by query operation

+

Any delete by query can be canceled using the task cancel API. For example:

+ 
POST _tasks/r1A2WoRbTwKZ516z6NEs5A:36619/_cancel
+
+

The task ID can be found by using the get tasks API.

+

Cancellation should happen quickly but might take a few seconds. + The get task status API will continue to list the delete by query task until this task checks that it has been cancelled and terminates itself.

+ + + ``_ + + :param index: A comma-separated list of data streams, indices, and aliases to + search. It supports wildcards (`*`). To search all data streams or indices, + omit this parameter or use `*` or `_all`. :param allow_no_indices: If `false`, the request returns an error if any wildcard expression, index alias, or `_all` value targets only missing or closed indices. This behavior applies even if the request targets other open indices. For example, a request targeting `foo*,bar*` returns an error if an index starts with `foo` but no index starts with `bar`. :param analyze_wildcard: If `true`, wildcard and prefix queries are analyzed. - :param analyzer: Analyzer to use for the query string. + This parameter can be used only when the `q` query string parameter is specified. + :param analyzer: Analyzer to use for the query string. This parameter can be + used only when the `q` query string parameter is specified. :param conflicts: What to do if delete by query hits version conflicts: `abort` or `proceed`. :param default_operator: The default operator for query string query: `AND` or - `OR`. - :param df: Field to use as default where no field prefix is given in the query - string. - :param expand_wildcards: Type of index that wildcard patterns can match. If the - request can target data streams, this argument determines whether wildcard - expressions match hidden data streams. Supports comma-separated values, such - as `open,hidden`. Valid values are: `all`, `open`, `closed`, `hidden`, `none`. + `OR`. This parameter can be used only when the `q` query string parameter + is specified. + :param df: The field to use as default where no field prefix is given in the + query string. This parameter can be used only when the `q` query string parameter + is specified. + :param expand_wildcards: The type of index that wildcard patterns can match. + If the request can target data streams, this argument determines whether + wildcard expressions match hidden data streams. It supports comma-separated + values, such as `open,hidden`. :param from_: Starting offset (default: 0) :param ignore_unavailable: If `false`, the request returns an error if it targets a missing or closed index. :param lenient: If `true`, format-based query failures (such as providing text - to a numeric field) in the query string will be ignored. + to a numeric field) in the query string will be ignored. This parameter can + be used only when the `q` query string parameter is specified. :param max_docs: The maximum number of documents to delete. - :param preference: Specifies the node or shard the operation should be performed - on. Random by default. - :param q: Query in the Lucene query string syntax. - :param query: Specifies the documents to delete using the Query DSL. + :param preference: The node or shard the operation should be performed on. It + is random by default. + :param q: A query in the Lucene query string syntax. + :param query: The documents to delete specified with Query DSL. :param refresh: If `true`, Elasticsearch refreshes all shards involved in the - delete by query after the request completes. + delete by query after the request completes. This is different than the delete + API's `refresh` parameter, which causes just the shard that received the + delete request to be refreshed. Unlike the delete API, it does not support + `wait_for`. :param request_cache: If `true`, the request cache is used for this request. Defaults to the index-level setting. :param requests_per_second: The throttle for this request in sub-requests per second. - :param routing: Custom value used to route operations to a specific shard. - :param scroll: Period to retain the search context for scrolling. - :param scroll_size: Size of the scroll request that powers the operation. - :param search_timeout: Explicit timeout for each search request. Defaults to - no timeout. - :param search_type: The type of the search operation. Available options: `query_then_fetch`, - `dfs_query_then_fetch`. + :param routing: A custom value used to route operations to a specific shard. + :param scroll: The period to retain the search context for scrolling. + :param scroll_size: The size of the scroll request that powers the operation. + :param search_timeout: The explicit timeout for each search request. It defaults + to no timeout. + :param search_type: The type of the search operation. Available options include + `query_then_fetch` and `dfs_query_then_fetch`. :param slice: Slice the request manually using the provided slice ID and total number of slices. :param slices: The number of slices this task should be divided into. - :param sort: A comma-separated list of : pairs. - :param stats: Specific `tag` of the request for logging and statistical purposes. - :param terminate_after: Maximum number of documents to collect for each shard. + :param sort: A comma-separated list of `:` pairs. + :param stats: The specific `tag` of the request for logging and statistical purposes. + :param terminate_after: The maximum number of documents to collect for each shard. If a query reaches this limit, Elasticsearch terminates the query early. Elasticsearch collects documents before sorting. Use with caution. Elasticsearch applies this parameter to each shard handling the request. When possible, let Elasticsearch perform early termination automatically. Avoid specifying this parameter for requests that target data streams with backing indices across multiple data tiers. - :param timeout: Period each deletion request waits for active shards. + :param timeout: The period each deletion request waits for active shards. :param version: If `true`, returns the document version as part of a hit. :param wait_for_active_shards: The number of shard copies that must be active - before proceeding with the operation. Set to all or any positive integer - up to the total number of shards in the index (`number_of_replicas+1`). + before proceeding with the operation. Set to `all` or any positive integer + up to the total number of shards in the index (`number_of_replicas+1`). The + `timeout` value controls how long each write request waits for unavailable + shards to become available. :param wait_for_completion: If `true`, the request blocks until the operation - is complete. + is complete. If `false`, Elasticsearch performs some preflight checks, launches + the request, and returns a task you can use to cancel or get the status of + the task. Elasticsearch creates a record of this task as a document at `.tasks/task/${taskId}`. + When you are done with a task, you should delete the task document so Elasticsearch + can reclaim the space. """ if index in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'index'") @@ -1250,16 +1544,22 @@ def delete_script( timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, ) -> ObjectApiResponse[t.Any]: """ - Delete a script or search template. Deletes a stored script or search template. + .. raw:: html - ``_ +

Delete a script or search template. + Deletes a stored script or search template.

- :param id: Identifier for the stored script or search template. - :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 timeout: Period to wait for a response. If no response is received before - the timeout expires, the request fails and returns an error. + + ``_ + + :param id: The identifier for the stored script or search template. + :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. It can also be set to `-1` to indicate that the request + should never timeout. + :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. It can + also be set to `-1` to indicate that the request should never timeout. """ if id in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'id'") @@ -1318,32 +1618,60 @@ def exists( ] = None, ) -> HeadApiResponse: """ - Check a document. Checks if a specified document exists. - - ``_ - - :param index: Comma-separated list of data streams, indices, and aliases. Supports - wildcards (`*`). - :param id: Identifier of the document. - :param preference: Specifies the node or shard the operation should be performed - on. Random by default. + .. raw:: html + +

Check a document.

+

Verify that a document exists. + For example, check to see if a document with the _id 0 exists:

+ 
HEAD my-index-000001/_doc/0
+
+

If the document exists, the API returns a status code of 200 - OK. + If the document doesn’t exist, the API returns 404 - Not Found.

+

Versioning support

+

You can use the version parameter to check the document only if its current version is equal to the specified one.

+

Internally, Elasticsearch has marked the old document as deleted and added an entirely new document. + The old version of the document doesn't disappear immediately, although you won't be able to access it. + Elasticsearch cleans up deleted documents in the background as you continue to index more data.

+ + + ``_ + + :param index: A comma-separated list of data streams, indices, and aliases. It + supports wildcards (`*`). + :param id: A unique document identifier. + :param preference: The node or shard the operation should be performed on. By + default, the operation is randomized between the shard replicas. If it is + set to `_local`, the operation will prefer to be run on a local allocated + shard when possible. If it is set to a custom value, the value is used to + guarantee that the same shards will be used for the same custom value. This + can help with "jumping values" when hitting different shards in different + refresh states. A sample value can be something like the web session ID or + the user name. :param realtime: If `true`, the request is real-time as opposed to near-real-time. - :param refresh: If `true`, Elasticsearch refreshes all shards involved in the - delete by query after the request completes. - :param routing: Target the specified primary shard. - :param source: `true` or `false` to return the `_source` field or not, or a list - of fields to return. - :param source_excludes: A comma-separated list of source fields to exclude in - the response. + :param refresh: If `true`, the request refreshes the relevant shards before retrieving + the document. Setting it to `true` should be done after careful thought and + verification that this does not cause a heavy load on the system (and slow + down indexing). + :param routing: A custom value used to route operations to a specific shard. + :param source: Indicates whether to return the `_source` field (`true` or `false`) + or lists the fields to return. + :param source_excludes: A comma-separated list of source fields to exclude from + the response. You can also use this parameter to exclude fields from the + subset specified in `_source_includes` query parameter. If the `_source` + parameter is `false`, this parameter is ignored. :param source_includes: A comma-separated list of source fields to include in - the response. - :param stored_fields: List of stored fields to return as part of a hit. If no - fields are specified, no stored fields are included in the response. If this - field is specified, the `_source` parameter defaults to false. + the response. If this parameter is specified, only these source fields are + returned. You can exclude fields from this subset using the `_source_excludes` + query parameter. If the `_source` parameter is `false`, this parameter is + ignored. + :param stored_fields: A comma-separated list of stored fields to return as part + of a hit. If no fields are specified, no stored fields are included in the + response. If this field is specified, the `_source` parameter defaults to + `false`. :param version: Explicit version number for concurrency control. The specified version must match the current version of the document for the request to succeed. - :param version_type: Specific version type: `external`, `external_gte`. + :param version_type: The version type. """ if index in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'index'") @@ -1419,29 +1747,38 @@ def exists_source( ] = None, ) -> HeadApiResponse: """ - Check for a document source. Checks if a document's `_source` is stored. + .. raw:: html - ``_ +

Check for a document source.

+

Check whether a document source exists in an index. + For example:

+ 
HEAD my-index-000001/_source/1
+
+

A document's source is not available if it is disabled in the mapping.

- :param index: Comma-separated list of data streams, indices, and aliases. Supports - wildcards (`*`). - :param id: Identifier of the document. - :param preference: Specifies the node or shard the operation should be performed - on. Random by default. - :param realtime: If true, the request is real-time as opposed to near-real-time. - :param refresh: If `true`, Elasticsearch refreshes all shards involved in the - delete by query after the request completes. - :param routing: Target the specified primary shard. - :param source: `true` or `false` to return the `_source` field or not, or a list - of fields to return. + + ``_ + + :param index: A comma-separated list of data streams, indices, and aliases. It + supports wildcards (`*`). + :param id: A unique identifier for the document. + :param preference: The node or shard the operation should be performed on. By + default, the operation is randomized between the shard replicas. + :param realtime: If `true`, the request is real-time as opposed to near-real-time. + :param refresh: If `true`, the request refreshes the relevant shards before retrieving + the document. Setting it to `true` should be done after careful thought and + verification that this does not cause a heavy load on the system (and slow + down indexing). + :param routing: A custom value used to route operations to a specific shard. + :param source: Indicates whether to return the `_source` field (`true` or `false`) + or lists the fields to return. :param source_excludes: A comma-separated list of source fields to exclude in the response. :param source_includes: A comma-separated list of source fields to include in the response. - :param version: Explicit version number for concurrency control. The specified - version must match the current version of the document for the request to - succeed. - :param version_type: Specific version type: `external`, `external_gte`. + :param version: The version number for concurrency control. It must match the + current version of the document for the request to succeed. + :param version_type: The version type. """ if index in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'index'") @@ -1519,34 +1856,47 @@ def explain( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Explain a document match result. Returns information about why a specific document - matches, or doesn’t match, a query. + .. raw:: html + +

Explain a document match result. + Get information about why a specific document matches, or doesn't match, a query. + It computes a score explanation for a query and a specific document.

- ``_ - :param index: Index names used to limit the request. Only a single index name - can be provided to this parameter. - :param id: Defines the document ID. + ``_ + + :param index: Index names that are used to limit the request. Only a single index + name can be provided to this parameter. + :param id: The document identifier. :param analyze_wildcard: If `true`, wildcard and prefix queries are analyzed. - :param analyzer: Analyzer to use for the query string. This parameter can only - be used when the `q` query string parameter is specified. + This parameter can be used only when the `q` query string parameter is specified. + :param analyzer: The analyzer to use for the query string. This parameter can + be used only when the `q` query string parameter is specified. :param default_operator: The default operator for query string query: `AND` or - `OR`. - :param df: Field to use as default where no field prefix is given in the query - string. + `OR`. This parameter can be used only when the `q` query string parameter + is specified. + :param df: The field to use as default where no field prefix is given in the + query string. This parameter can be used only when the `q` query string parameter + is specified. :param lenient: If `true`, format-based query failures (such as providing text - to a numeric field) in the query string will be ignored. - :param preference: Specifies the node or shard the operation should be performed - on. Random by default. - :param q: Query in the Lucene query string syntax. + to a numeric field) in the query string will be ignored. This parameter can + be used only when the `q` query string parameter is specified. + :param preference: The node or shard the operation should be performed on. It + is random by default. + :param q: The query in the Lucene query string syntax. :param query: Defines the search definition using the Query DSL. - :param routing: Custom value used to route operations to a specific shard. - :param source: True or false to return the `_source` field or not, or a list + :param routing: A custom value used to route operations to a specific shard. + :param source: `True` or `false` to return the `_source` field or not or a list of fields to return. :param source_excludes: A comma-separated list of source fields to exclude from - the response. + the response. You can also use this parameter to exclude fields from the + subset specified in `_source_includes` query parameter. If the `_source` + parameter is `false`, this parameter is ignored. :param source_includes: A comma-separated list of source fields to include in - the response. + the response. If this parameter is specified, only these source fields are + returned. You can exclude fields from this subset using the `_source_excludes` + query parameter. If the `_source` parameter is `false`, this parameter is + ignored. :param stored_fields: A comma-separated list of stored fields to return in the response. """ @@ -1639,15 +1989,18 @@ def field_caps( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - 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. + .. raw:: html + +

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.

+ - ``_ + ``_ - :param index: Comma-separated list of data streams, indices, and aliases used + :param index: A comma-separated list of data streams, indices, and aliases used to limit the request. Supports wildcards (*). To target all data streams and indices, omit this parameter or use * or _all. :param allow_no_indices: If false, the request returns an error if any wildcard @@ -1655,25 +2008,32 @@ def field_caps( This behavior applies even if the request targets other open indices. For example, a request targeting `foo*,bar*` returns an error if an index starts with foo but no index starts with bar. - :param expand_wildcards: Type of index that wildcard patterns can match. If the - request can target data streams, this argument determines whether wildcard - expressions match hidden data streams. Supports comma-separated values, such - as `open,hidden`. - :param fields: List of fields to retrieve capabilities for. Wildcard (`*`) expressions - are supported. - :param filters: An optional set of filters: can include +metadata,-metadata,-nested,-multifield,-parent + :param expand_wildcards: The type of index that wildcard patterns can match. + If the request can target data streams, this argument determines whether + wildcard expressions match hidden data streams. Supports comma-separated + values, such as `open,hidden`. + :param fields: A list of fields to retrieve capabilities for. Wildcard (`*`) + expressions are supported. + :param filters: A comma-separated list of filters to apply to the response. :param ignore_unavailable: If `true`, missing or closed indices are not included in the response. :param include_empty_fields: If false, empty fields are not included in the response. :param include_unmapped: If true, unmapped fields are included in the response. - :param index_filter: Allows to filter indices if the provided query rewrites - to match_none on every shard. - :param runtime_mappings: Defines ad-hoc runtime fields in the request similar + :param index_filter: Filter indices if the provided query rewrites to `match_none` + on every shard. IMPORTANT: The filtering is done on a best-effort basis, + it uses index statistics and mappings to rewrite queries to `match_none` + instead of fully running the request. For instance a range query over a date + field can rewrite to `match_none` if all documents within a shard (including + deleted documents) are outside of the provided range. However, not all queries + can rewrite to `match_none` so this API may return an index even if the provided + filter matches no document. + :param runtime_mappings: Define ad-hoc runtime fields in the request similar to the way it is done in search requests. These fields exist only as part of the query and take precedence over fields defined with the same name in the index mappings. - :param types: Only return results for fields that have one of the types in the - list + :param types: A comma-separated list of field types to include. Any fields that + do not match one of these types will be excluded from the results. It defaults + to empty, meaning that all field types are returned. """ __path_parts: t.Dict[str, str] if index not in SKIP_IN_PATH: @@ -1759,36 +2119,87 @@ def get( ] = None, ) -> ObjectApiResponse[t.Any]: """ - Get a document by its ID. Retrieves the document with the specified ID from an - index. - - ``_ - - :param index: Name of the index that contains the document. - :param id: Unique identifier of the document. - :param force_synthetic_source: Should this request force synthetic _source? Use - this to test if the mapping supports synthetic _source and to get a sense - of the worst case performance. Fetches with this enabled will be slower the - enabling synthetic source natively in the index. - :param preference: Specifies the node or shard the operation should be performed - on. Random by default. + .. raw:: html + +

Get a document by its ID.

+

Get a document and its source or stored fields from an index.

+

By default, this API is realtime and is not affected by the refresh rate of the index (when data will become visible for search). + In the case where stored fields are requested with the stored_fields parameter and the document has been updated but is not yet refreshed, the API will have to parse and analyze the source to extract the stored fields. + To turn off realtime behavior, set the realtime parameter to false.

+

Source filtering

+

By default, the API returns the contents of the _source field unless you have used the stored_fields parameter or the _source field is turned off. + You can turn off _source retrieval by using the _source parameter:

+ 
GET my-index-000001/_doc/0?_source=false
+
+

If you only need one or two fields from the _source, use the _source_includes or _source_excludes parameters to include or filter out particular fields. + This can be helpful with large documents where partial retrieval can save on network overhead + Both parameters take a comma separated list of fields or wildcard expressions. + For example:

+ 
GET my-index-000001/_doc/0?_source_includes=*.id&_source_excludes=entities
+
+

If you only want to specify includes, you can use a shorter notation:

+ 
GET my-index-000001/_doc/0?_source=*.id
+
+

Routing

+

If routing is used during indexing, the routing value also needs to be specified to retrieve a document. + For example:

+ 
GET my-index-000001/_doc/2?routing=user1
+
+

This request gets the document with ID 2, but it is routed based on the user. + The document is not fetched if the correct routing is not specified.

+

Distributed

+

The GET operation is hashed into a specific shard ID. + It is then redirected to one of the replicas within that shard ID and returns the result. + The replicas are the primary shard and its replicas within that shard ID group. + This means that the more replicas you have, the better your GET scaling will be.

+

Versioning support

+

You can use the version parameter to retrieve the document only if its current version is equal to the specified one.

+

Internally, Elasticsearch has marked the old document as deleted and added an entirely new document. + The old version of the document doesn't disappear immediately, although you won't be able to access it. + Elasticsearch cleans up deleted documents in the background as you continue to index more data.

+ + + ``_ + + :param index: The name of the index that contains the document. + :param id: A unique document identifier. + :param force_synthetic_source: Indicates whether the request forces synthetic + `_source`. Use this paramater to test if the mapping supports synthetic `_source` + and to get a sense of the worst case performance. Fetches with this parameter + enabled will be slower than enabling synthetic source natively in the index. + :param preference: The node or shard the operation should be performed on. By + default, the operation is randomized between the shard replicas. If it is + set to `_local`, the operation will prefer to be run on a local allocated + shard when possible. If it is set to a custom value, the value is used to + guarantee that the same shards will be used for the same custom value. This + can help with "jumping values" when hitting different shards in different + refresh states. A sample value can be something like the web session ID or + the user name. :param realtime: If `true`, the request is real-time as opposed to near-real-time. - :param refresh: If true, Elasticsearch refreshes the affected shards to make - this operation visible to search. If false, do nothing with refreshes. - :param routing: Target the specified primary shard. - :param source: True or false to return the _source field or not, or a list of - fields to return. - :param source_excludes: A comma-separated list of source fields to exclude in - the response. + :param refresh: If `true`, the request refreshes the relevant shards before retrieving + the document. Setting it to `true` should be done after careful thought and + verification that this does not cause a heavy load on the system (and slow + down indexing). + :param routing: A custom value used to route operations to a specific shard. + :param source: Indicates whether to return the `_source` field (`true` or `false`) + or lists the fields to return. + :param source_excludes: A comma-separated list of source fields to exclude from + the response. You can also use this parameter to exclude fields from the + subset specified in `_source_includes` query parameter. If the `_source` + parameter is `false`, this parameter is ignored. :param source_includes: A comma-separated list of source fields to include in - the response. - :param stored_fields: List of stored fields to return as part of a hit. If no - fields are specified, no stored fields are included in the response. If this - field is specified, the `_source` parameter defaults to false. - :param version: Explicit version number for concurrency control. The specified - version must match the current version of the document for the request to - succeed. - :param version_type: Specific version type: internal, external, external_gte. + the response. If this parameter is specified, only these source fields are + returned. You can exclude fields from this subset using the `_source_excludes` + query parameter. If the `_source` parameter is `false`, this parameter is + ignored. + :param stored_fields: A comma-separated list of stored fields to return as part + of a hit. If no fields are specified, no stored fields are included in the + response. If this field is specified, the `_source` parameter defaults to + `false`. Only leaf fields can be retrieved with the `stored_field` option. + Object fields can't be returned;​if specified, the request fails. + :param version: The version number for concurrency control. It must match the + current version of the document for the request to succeed. + :param version_type: The version type. """ if index in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'index'") @@ -1849,12 +2260,19 @@ def get_script( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Get a script or search template. Retrieves a stored script or search template. + .. raw:: html + +

Get a script or search template. + Retrieves a stored script or search template.

- ``_ - :param id: Identifier for the stored script or search template. - :param master_timeout: Specify timeout for connection to master + ``_ + + :param id: The identifier for the stored script or search template. + :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. It can also be set to `-1` to indicate that the request should + never timeout. """ if id in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'id'") @@ -1911,29 +2329,41 @@ def get_source( ] = None, ) -> ObjectApiResponse[t.Any]: """ - Get a document's source. Returns the source of a document. + .. raw:: html - ``_ +

Get a document's source.

+

Get the source of a document. + For example:

+ 
GET my-index-000001/_source/1
+
+

You can use the source filtering parameters to control which parts of the _source are returned:

+ 
GET my-index-000001/_source/1/?_source_includes=*.id&_source_excludes=entities
+
- :param index: Name of the index that contains the document. - :param id: Unique identifier of the document. - :param preference: Specifies the node or shard the operation should be performed - on. Random by default. - :param realtime: Boolean) If true, the request is real-time as opposed to near-real-time. - :param refresh: If true, Elasticsearch refreshes the affected shards to make - this operation visible to search. If false, do nothing with refreshes. - :param routing: Target the specified primary shard. - :param source: True or false to return the _source field or not, or a list of - fields to return. + + ``_ + + :param index: The name of the index that contains the document. + :param id: A unique document identifier. + :param preference: The node or shard the operation should be performed on. By + default, the operation is randomized between the shard replicas. + :param realtime: If `true`, the request is real-time as opposed to near-real-time. + :param refresh: If `true`, the request refreshes the relevant shards before retrieving + the document. Setting it to `true` should be done after careful thought and + verification that this does not cause a heavy load on the system (and slow + down indexing). + :param routing: A custom value used to route operations to a specific shard. + :param source: Indicates whether to return the `_source` field (`true` or `false`) + or lists the fields to return. :param source_excludes: A comma-separated list of source fields to exclude in the response. :param source_includes: A comma-separated list of source fields to include in the response. - :param stored_fields: - :param version: Explicit version number for concurrency control. The specified - version must match the current version of the document for the request to - succeed. - :param version_type: Specific version type: internal, external, external_gte. + :param stored_fields: A comma-separated list of stored fields to return as part + of a hit. + :param version: The version number for concurrency control. It must match the + current version of the document for the request to succeed. + :param version_type: The version type. """ if index in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'index'") @@ -1995,6 +2425,7 @@ def index( human: t.Optional[bool] = None, if_primary_term: t.Optional[int] = None, if_seq_no: t.Optional[int] = None, + include_source_on_error: t.Optional[bool] = None, op_type: t.Optional[t.Union[str, t.Literal["create", "index"]]] = None, pipeline: t.Optional[str] = None, pretty: t.Optional[bool] = None, @@ -2013,44 +2444,148 @@ def index( ] = None, ) -> ObjectApiResponse[t.Any]: """ - Index a document. Adds a JSON document to the specified data stream or index - and makes it searchable. If the target is an index and the document already exists, - the request updates the document and increments its version. - - ``_ - - :param index: Name of the data stream or index to target. + .. raw:: html + +

Create or update a document in an index.

+

Add a JSON document to the specified data stream or index and make it searchable. + If the target is an index and the document already exists, the request updates the document and increments its version.

+

NOTE: You cannot use this API to send update requests for existing documents in a data stream.

+

If the Elasticsearch security features are enabled, you must have the following index privileges for the target data stream, index, or index alias:

+
    +
  • To add or overwrite a document using the PUT /<target>/_doc/<_id> request format, you must have the create, index, or write index privilege.
    • +
  • To add a document using the POST /<target>/_doc/ request format, you must have the create_doc, create, index, or write index privilege.
    • +
  • To automatically create a data stream or index with this API request, you must have the auto_configure, create_index, or manage index privilege.
    • +
+

Automatic data stream creation requires a matching index template with data stream enabled.

+

NOTE: Replica shards might not all be started when an indexing operation returns successfully. + By default, only the primary is required. Set wait_for_active_shards to change this default behavior.

+

Automatically create data streams and indices

+

If the request's target doesn't exist and matches an index template with a data_stream definition, the index operation automatically creates the data stream.

+

If the target doesn't exist and doesn't match a data stream template, the operation automatically creates the index and applies any matching index templates.

+

NOTE: Elasticsearch includes several built-in index templates. To avoid naming collisions with these templates, refer to index pattern documentation.

+

If no mapping exists, the index operation creates a dynamic mapping. + By default, new fields and objects are automatically added to the mapping if needed.

+

Automatic index creation is controlled by the action.auto_create_index setting. + If it is true, any index can be created automatically. + You can modify this setting to explicitly allow or block automatic creation of indices that match specified patterns or set it to false to turn off automatic index creation entirely. + Specify a comma-separated list of patterns you want to allow or prefix each pattern with + or - to indicate whether it should be allowed or blocked. + When a list is specified, the default behaviour is to disallow.

+

NOTE: The action.auto_create_index setting affects the automatic creation of indices only. + It does not affect the creation of data streams.

+

Optimistic concurrency control

+

Index operations can be made conditional and only be performed if the last modification to the document was assigned the sequence number and primary term specified by the if_seq_no and if_primary_term parameters. + If a mismatch is detected, the operation will result in a VersionConflictException and a status code of 409.

+

Routing

+

By default, shard placement — or routing — is controlled by using a hash of the document's ID value. + For more explicit control, the value fed into the hash function used by the router can be directly specified on a per-operation basis using the routing parameter.

+

When setting up explicit mapping, you can also use the _routing field to direct the index operation to extract the routing value from the document itself. + This does come at the (very minimal) cost of an additional document parsing pass. + If the _routing mapping is defined and set to be required, the index operation will fail if no routing value is provided or extracted.

+

NOTE: Data streams do not support custom routing unless they were created with the allow_custom_routing setting enabled in the template.

+

Distributed

+

The index operation is directed to the primary shard based on its route and performed on the actual node containing this shard. + After the primary shard completes the operation, if needed, the update is distributed to applicable replicas.

+

Active shards

+

To improve the resiliency of writes to the system, indexing operations can be configured to wait for a certain number of active shard copies before proceeding with the operation. + If the requisite number of active shard copies are not available, then the write operation must wait and retry, until either the requisite shard copies have started or a timeout occurs. + By default, write operations only wait for the primary shards to be active before proceeding (that is to say wait_for_active_shards is 1). + This default can be overridden in the index settings dynamically by setting index.write.wait_for_active_shards. + To alter this behavior per operation, use the wait_for_active_shards request parameter.

+

Valid values are all or any positive integer up to the total number of configured copies per shard in the index (which is number_of_replicas+1). + Specifying a negative value or a number greater than the number of shard copies will throw an error.

+

For example, suppose you have a cluster of three nodes, A, B, and C and you create an index index with the number of replicas set to 3 (resulting in 4 shard copies, one more copy than there are nodes). + If you attempt an indexing operation, by default the operation will only ensure the primary copy of each shard is available before proceeding. + This means that even if B and C went down and A hosted the primary shard copies, the indexing operation would still proceed with only one copy of the data. + If wait_for_active_shards is set on the request to 3 (and all three nodes are up), the indexing operation will require 3 active shard copies before proceeding. + This requirement should be met because there are 3 active nodes in the cluster, each one holding a copy of the shard. + However, if you set wait_for_active_shards to all (or to 4, which is the same in this situation), the indexing operation will not proceed as you do not have all 4 copies of each shard active in the index. + The operation will timeout unless a new node is brought up in the cluster to host the fourth copy of the shard.

+

It is important to note that this setting greatly reduces the chances of the write operation not writing to the requisite number of shard copies, but it does not completely eliminate the possibility, because this check occurs before the write operation starts. + After the write operation is underway, it is still possible for replication to fail on any number of shard copies but still succeed on the primary. + The _shards section of the API response reveals the number of shard copies on which replication succeeded and failed.

+

No operation (noop) updates

+

When updating a document by using this API, a new version of the document is always created even if the document hasn't changed. + If this isn't acceptable use the _update API with detect_noop set to true. + The detect_noop option isn't available on this API because it doesn’t fetch the old source and isn't able to compare it against the new source.

+

There isn't a definitive rule for when noop updates aren't acceptable. + It's a combination of lots of factors like how frequently your data source sends updates that are actually noops and how many queries per second Elasticsearch runs on the shard receiving the updates.

+

Versioning

+

Each indexed document is given a version number. + By default, internal versioning is used that starts at 1 and increments with each update, deletes included. + Optionally, the version number can be set to an external value (for example, if maintained in a database). + To enable this functionality, version_type should be set to external. + The value provided must be a numeric, long value greater than or equal to 0, and less than around 9.2e+18.

+

NOTE: Versioning is completely real time, and is not affected by the near real time aspects of search operations. + If no version is provided, the operation runs without any version checks.

+

When using the external version type, the system checks to see if the version number passed to the index request is greater than the version of the currently stored document. + If true, the document will be indexed and the new version number used. + If the value provided is less than or equal to the stored document's version number, a version conflict will occur and the index operation will fail. For example:

+ 
PUT my-index-000001/_doc/1?version=2&version_type=external
+          {
+            "user": {
+              "id": "elkbee"
+            }
+          }
+
+          In this example, the operation will succeed since the supplied version of 2 is higher than the current document version of 1.
+          If the document was already updated and its version was set to 2 or higher, the indexing command will fail and result in a conflict (409 HTTP status code).
+
+          A nice side effect is that there is no need to maintain strict ordering of async indexing operations run as a result of changes to a source database, as long as version numbers from the source database are used.
+          Even the simple case of updating the Elasticsearch index using data from a database is simplified if external versioning is used, as only the latest version will be used if the index operations arrive out of order.
+
+ + + ``_ + + :param index: The name of the data stream or index to target. If the target doesn't + exist and matches the name or wildcard (`*`) pattern of an index template + with a `data_stream` definition, this request creates the data stream. If + the target doesn't exist and doesn't match a data stream template, this request + creates the index. You can check for existing targets with the resolve index + API. :param document: - :param id: Unique identifier for the document. + :param id: A unique identifier for the document. To automatically generate a + document ID, use the `POST //_doc/` request format and omit this + parameter. :param if_primary_term: Only perform the operation if the document has this primary term. :param if_seq_no: Only perform the operation if the document has this sequence number. - :param op_type: Set to create to only index the document if it does not already + :param include_source_on_error: True or false if to include the document source + in the error message in case of parsing errors. + :param op_type: Set to `create` to only index the document if it does not already exist (put if absent). If a document with the specified `_id` already exists, - the indexing operation will fail. Same as using the `/_create` endpoint. - Valid values: `index`, `create`. If document id is specified, it defaults - to `index`. Otherwise, it defaults to `create`. - :param pipeline: ID of the pipeline to use to preprocess incoming documents. + the indexing operation will fail. The behavior is the same as using the `/_create` + endpoint. If a document ID is specified, this paramater defaults to `index`. + Otherwise, it defaults to `create`. If the request targets a data stream, + an `op_type` of `create` is required. + :param pipeline: The ID of the pipeline to use to preprocess incoming documents. If the index has a default ingest pipeline specified, then setting the value to `_none` disables the default ingest pipeline for this request. If a final pipeline is configured it will always run, regardless of the value of this parameter. :param refresh: If `true`, Elasticsearch refreshes the affected shards to make - this operation visible to search, if `wait_for` then wait for a refresh to - make this operation visible to search, if `false` do nothing with refreshes. - Valid values: `true`, `false`, `wait_for`. + this operation visible to search. If `wait_for`, it waits for a refresh to + make this operation visible to search. If `false`, it does nothing with refreshes. :param require_alias: If `true`, the destination must be an index alias. - :param routing: Custom value used to route operations to a specific shard. - :param timeout: Period the request waits for the following operations: automatic - index creation, dynamic mapping updates, waiting for active shards. - :param version: Explicit version number for concurrency control. The specified - version must match the current version of the document for the request to - succeed. - :param version_type: Specific version type: `external`, `external_gte`. + :param routing: A custom value that is used to route operations to a specific + shard. + :param timeout: The period the request waits for the following operations: automatic + index creation, dynamic mapping updates, waiting for active shards. This + parameter is useful for situations where the primary shard assigned to perform + the operation might not be available when the operation runs. Some reasons + for this might be that the primary shard is currently recovering from a gateway + or undergoing relocation. By default, the operation will wait on the primary + shard to become available for at least 1 minute before failing and responding + with an error. The actual wait time could be longer, particularly when multiple + waits occur. + :param version: An explicit version number for concurrency control. It must be + a non-negative long number. + :param version_type: The version type. :param wait_for_active_shards: The number of shard copies that must be active - before proceeding with the operation. Set to all or any positive integer - up to the total number of shards in the index (`number_of_replicas+1`). + before proceeding with the operation. You can set it to `all` or any positive + integer up to the total number of shards in the index (`number_of_replicas+1`). + The default value of `1` means it waits for each primary shard to be active. """ if index in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'index'") @@ -2082,6 +2617,8 @@ def index( __query["if_primary_term"] = if_primary_term if if_seq_no is not None: __query["if_seq_no"] = if_seq_no + if include_source_on_error is not None: + __query["include_source_on_error"] = include_source_on_error if op_type is not None: __query["op_type"] = op_type if pipeline is not None: @@ -2124,9 +2661,13 @@ def info( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Get cluster info. Get basic build, version, and cluster information. + .. raw:: html + +

Get cluster info. + Get basic build, version, and cluster information.

- ``_ + + ``_ """ __path_parts: t.Dict[str, str] = {} __path = "/" @@ -2179,12 +2720,23 @@ def mget( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Get multiple documents. Get multiple JSON documents by ID from one or more indices. - If you specify an index in the request URI, you only need to specify the document - IDs in the request body. To ensure fast responses, this multi get (mget) API - responds with partial results if one or more shards fail. + .. raw:: html + +

Get multiple documents.

+

Get multiple JSON documents by ID from one or more indices. + If you specify an index in the request URI, you only need to specify the document IDs in the request body. + To ensure fast responses, this multi get (mget) API responds with partial results if one or more shards fail.

+

Filter source fields

+

By default, the _source field is returned for every document (if stored). + Use the _source and _source_include or source_exclude attributes to filter what fields are returned for a particular document. + You can include the _source, _source_includes, and _source_excludes query parameters in the request URI to specify the defaults to use when there are no per-document instructions.

+

Get stored fields

+

Use the stored_fields attribute to specify the set of stored fields you want to retrieve. + Any requested fields that are not stored are ignored. + You can include the stored_fields query parameter in the request URI to specify the defaults to use when there are no per-document instructions.

- ``_ + + ``_ :param index: Name of the index to retrieve documents from when `ids` are specified, or when a document in the `docs` array does not specify an index. @@ -2303,15 +2855,23 @@ def msearch( typed_keys: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Run multiple searches. The format of the request is similar to the bulk API format - and makes use of the newline delimited JSON (NDJSON) format. The structure is - as follows: ``` header\\n body\\n header\\n body\\n ``` This structure is specifically - optimized to reduce parsing if a specific search ends up redirected to another - node. IMPORTANT: The final line of data must end with a newline character `\\n`. - Each newline character may be preceded by a carriage return `\\r`. When sending - requests to this endpoint the `Content-Type` header should be set to `application/x-ndjson`. + .. raw:: html + +

Run multiple searches.

+

The format of the request is similar to the bulk API format and makes use of the newline delimited JSON (NDJSON) format. + The structure is as follows:

+ 
header\\n
+          body\\n
+          header\\n
+          body\\n
+
+

This structure is specifically optimized to reduce parsing if a specific search ends up redirected to another node.

+

IMPORTANT: The final line of data must end with a newline character \\n. + Each newline character may be preceded by a carriage return \\r. + When sending requests to this endpoint the Content-Type header should be set to application/x-ndjson.

- ``_ + + ``_ :param searches: :param index: Comma-separated list of data streams, indices, and index aliases @@ -2441,22 +3001,35 @@ def msearch_template( typed_keys: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Run multiple templated searches. + .. raw:: html + +

Run multiple templated searches.

+

Run multiple templated searches with a single request. + If you are providing a text file or text input to curl, use the --data-binary flag instead of -d to preserve newlines. + For example:

+ 
$ cat requests
+          { "index": "my-index" }
+          { "id": "my-search-template", "params": { "query_string": "hello world", "from": 0, "size": 10 }}
+          { "index": "my-other-index" }
+          { "id": "my-other-search-template", "params": { "query_type": "match_all" }}
 
-        ``_
+          $ curl -H "Content-Type: application/x-ndjson" -XGET localhost:9200/_msearch/template --data-binary "@requests"; echo
+
+ + + ``_ :param search_templates: - :param index: Comma-separated list of data streams, indices, and aliases to search. - Supports wildcards (`*`). To search all data streams and indices, omit this - parameter or use `*`. + :param index: A comma-separated list of data streams, indices, and aliases to + search. It supports wildcards (`*`). To search all data streams and indices, + omit this parameter or use `*`. :param ccs_minimize_roundtrips: If `true`, network round-trips are minimized for cross-cluster search requests. - :param max_concurrent_searches: Maximum number of concurrent searches the API - can run. + :param max_concurrent_searches: The maximum number of concurrent searches the + API can run. :param rest_total_hits_as_int: If `true`, the response returns `hits.total` as an integer. If `false`, it returns `hits.total` as an object. - :param search_type: The type of the search operation. Available options: `query_then_fetch`, - `dfs_query_then_fetch`. + :param search_type: The type of the search operation. :param typed_keys: If `true`, the response prefixes aggregation and suggester names with their respective types. """ @@ -2536,34 +3109,41 @@ def mtermvectors( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Get multiple term vectors. You can specify existing documents by index and ID - or provide artificial documents in the body of the request. You can specify the - index in the request body or request URI. The response contains a `docs` array - with all the fetched termvectors. Each element has the structure provided by - the termvectors API. + .. raw:: html + +

Get multiple term vectors.

+

Get multiple term vectors with a single request. + You can specify existing documents by index and ID or provide artificial documents in the body of the request. + You can specify the index in the request body or request URI. + The response contains a docs array with all the fetched termvectors. + Each element has the structure provided by the termvectors API.

+

Artificial documents

+

You can also use mtermvectors to generate term vectors for artificial documents provided in the body of the request. + The mapping used is determined by the specified _index.

- ``_ - :param index: Name of the index that contains the documents. - :param docs: Array of existing or artificial documents. + ``_ + + :param index: The name of the index that contains the documents. + :param docs: An array of existing or artificial documents. :param field_statistics: If `true`, the response includes the document count, sum of document frequencies, and sum of total term frequencies. - :param fields: Comma-separated list or wildcard expressions of fields to include - in the statistics. Used as the default list unless a specific field list - is provided in the `completion_fields` or `fielddata_fields` parameters. - :param ids: Simplified syntax to specify documents by their ID if they're in + :param fields: A comma-separated list or wildcard expressions of fields to include + in the statistics. It is used as the default list unless a specific field + list is provided in the `completion_fields` or `fielddata_fields` parameters. + :param ids: A simplified syntax to specify documents by their ID if they're in the same index. :param offsets: If `true`, the response includes term offsets. :param payloads: If `true`, the response includes term payloads. :param positions: If `true`, the response includes term positions. - :param preference: Specifies the node or shard the operation should be performed - on. Random by default. + :param preference: The node or shard the operation should be performed on. It + is random by default. :param realtime: If true, the request is real-time as opposed to near-real-time. - :param routing: Custom value used to route operations to a specific shard. + :param routing: A custom value used to route operations to a specific shard. :param term_statistics: If true, the response includes term frequency and document frequency. :param version: If `true`, returns the document version as part of a hit. - :param version_type: Specific version type. + :param version_type: The version type. """ __path_parts: t.Dict[str, str] if index not in SKIP_IN_PATH: @@ -2652,36 +3232,59 @@ def open_point_in_time( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - 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. - - ``_ + .. raw:: html + +

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.

+

A subsequent search request with the pit parameter must not specify index, routing, or preference values as these parameters are copied from the point in time.

+

Just like regular searches, you can use from and size to page through point in time search results, up to the first 10,000 hits. + If you want to retrieve more hits, use PIT with search_after.

+

IMPORTANT: The open point in time request and each subsequent search request can return different identifiers; always use the most recently received ID for the next search request.

+

When a PIT that contains shard failures is used in a search request, the missing are always reported in the search response as a NoShardAvailableActionException exception. + To get rid of these exceptions, a new PIT needs to be created so that shards missing from the previous PIT can be handled, assuming they become available in the meantime.

+

Keeping point in time alive

+

The keep_alive parameter, which is passed to a open point in time request and search request, extends the time to live of the corresponding point in time. + The value does not need to be long enough to process all data — it just needs to be long enough for the next request.

+

Normally, the background merge process optimizes the index by merging together smaller segments to create new, bigger segments. + Once the smaller segments are no longer needed they are deleted. + However, open point-in-times prevent the old segments from being deleted since they are still in use.

+

TIP: Keeping older segments alive means that more disk space and file handles are needed. + Ensure that you have configured your nodes to have ample free file handles.

+

Additionally, if a segment contains deleted or updated documents then the point in time must keep track of whether each document in the segment was live at the time of the initial search request. + Ensure that your nodes have sufficient heap space if you have many open point-in-times on an index that is subject to ongoing deletes or updates. + Note that a point-in-time doesn't prevent its associated indices from being deleted. + You can check how many point-in-times (that is, search contexts) are open with the nodes stats API.

+ + + ``_ :param index: A comma-separated list of index names to open point in time; use `_all` or empty string to perform the operation on all indices - :param keep_alive: Extends the time to live of the corresponding point in time. - :param allow_partial_search_results: If `false`, creating a point in time request - when a shard is missing or unavailable will throw an exception. If `true`, - the point in time will contain all the shards that are available at the time - of the request. - :param expand_wildcards: Type of index that wildcard patterns can match. If the - request can target data streams, this argument determines whether wildcard - expressions match hidden data streams. Supports comma-separated values, such - as `open,hidden`. Valid values are: `all`, `open`, `closed`, `hidden`, `none`. + :param keep_alive: Extend the length of time that the point in time persists. + :param allow_partial_search_results: Indicates whether the point in time tolerates + unavailable shards or shard failures when initially creating the PIT. If + `false`, creating a point in time request when a shard is missing or unavailable + will throw an exception. If `true`, the point in time will contain all the + shards that are available at the time of the request. + :param expand_wildcards: The type of index that wildcard patterns can match. + If the request can target data streams, this argument determines whether + wildcard expressions match hidden data streams. It supports comma-separated + values, such as `open,hidden`. Valid values are: `all`, `open`, `closed`, + `hidden`, `none`. :param ignore_unavailable: If `false`, the request returns an error if it targets a missing or closed index. - :param index_filter: Allows to filter indices if the provided query rewrites - to `match_none` on every shard. - :param preference: Specifies the node or shard the operation should be performed - on. Random by default. - :param routing: Custom value used to route operations to a specific shard. + :param index_filter: Filter indices if the provided query rewrites to `match_none` + on every shard. + :param preference: The node or shard the operation should be performed on. By + default, it is random. + :param routing: A custom value that is used to route operations to a specific + shard. """ if index in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'index'") @@ -2747,23 +3350,27 @@ def put_script( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Create or update a script or search template. Creates or updates a stored script - or search template. - - ``_ - - :param id: Identifier for the stored script or search template. Must be unique - within the cluster. - :param script: Contains the script or search template, its parameters, and its - language. - :param context: Context in which the script or search template should run. To - prevent errors, the API immediately compiles the script or template in this - context. - :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 timeout: Period to wait for a response. If no response is received before - the timeout expires, the request fails and returns an error. + .. raw:: html + +

Create or update a script or search template. + Creates or updates a stored script or search template.

+ + + ``_ + + :param id: The identifier for the stored script or search template. It must be + unique within the cluster. + :param script: The script or search template, its parameters, and its language. + :param context: The context in which the script or search template should run. + To prevent errors, the API immediately compiles the script or template in + this context. + :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. It can also be set to `-1` to indicate that the request + should never timeout. + :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. It can + also be set to `-1` to indicate that the request should never timeout. """ if id in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'id'") @@ -2833,14 +3440,17 @@ def rank_eval( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Evaluate ranked search results. Evaluate the quality of ranked search results - over a set of typical search queries. + .. raw:: html - ``_ +

Evaluate ranked search results.

+

Evaluate the quality of ranked search results over a set of typical search queries.

+ + + ``_ :param requests: A set of typical search requests, together with their provided ratings. - :param index: Comma-separated list of data streams, indices, and index aliases + :param index: A comma-separated list of data streams, indices, and index aliases used to limit the request. Wildcard (`*`) expressions are supported. To target all data streams and indices in a cluster, omit this parameter or use `_all` or `*`. @@ -2928,33 +3538,187 @@ def reindex( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Reindex documents. Copies documents from a source to a destination. The source - can be any existing index, alias, or data stream. The destination must differ - from the source. For example, you cannot reindex a data stream into itself. - - ``_ + .. raw:: html + +

Reindex documents.

+

Copy documents from a source to a destination. + You can copy all documents to the destination index or reindex a subset of the documents. + The source can be any existing index, alias, or data stream. + The destination must differ from the source. + For example, you cannot reindex a data stream into itself.

+

IMPORTANT: Reindex requires _source to be enabled for all documents in the source. + The destination should be configured as wanted before calling the reindex API. + Reindex does not copy the settings from the source or its associated template. + Mappings, shard counts, and replicas, for example, must be configured ahead of time.

+

If the Elasticsearch security features are enabled, you must have the following security privileges:

+
    +
  • The read index privilege for the source data stream, index, or alias.
    • +
  • The write index privilege for the destination data stream, index, or index alias.
    • +
  • To automatically create a data stream or index with a reindex API request, you must have the auto_configure, create_index, or manage index privilege for the destination data stream, index, or alias.
    • +
  • If reindexing from a remote cluster, the source.remote.user must have the monitor cluster privilege and the read index privilege for the source data stream, index, or alias.
    • +
+

If reindexing from a remote cluster, you must explicitly allow the remote host in the reindex.remote.whitelist setting. + Automatic data stream creation requires a matching index template with data stream enabled.

+

The dest element can be configured like the index API to control optimistic concurrency control. + Omitting version_type or setting it to internal causes Elasticsearch to blindly dump documents into the destination, overwriting any that happen to have the same ID.

+

Setting version_type to external causes Elasticsearch to preserve the version from the source, create any documents that are missing, and update any documents that have an older version in the destination than they do in the source.

+

Setting op_type to create causes the reindex API to create only missing documents in the destination. + All existing documents will cause a version conflict.

+

IMPORTANT: Because data streams are append-only, any reindex request to a destination data stream must have an op_type of create. + A reindex can only add new documents to a destination data stream. + It cannot update existing documents in a destination data stream.

+

By default, version conflicts abort the reindex process. + To continue reindexing if there are conflicts, set the conflicts request body property to proceed. + In this case, the response includes a count of the version conflicts that were encountered. + Note that the handling of other error types is unaffected by the conflicts property. + Additionally, if you opt to count version conflicts, the operation could attempt to reindex more documents from the source than max_docs until it has successfully indexed max_docs documents into the target or it has gone through every document in the source query.

+

NOTE: The reindex API makes no effort to handle ID collisions. + The last document written will "win" but the order isn't usually predictable so it is not a good idea to rely on this behavior. + Instead, make sure that IDs are unique by using a script.

+

Running reindex asynchronously

+

If the request contains wait_for_completion=false, Elasticsearch performs some preflight checks, launches the request, and returns a task you can use to cancel or get the status of the task. + Elasticsearch creates a record of this task as a document at _tasks/<task_id>.

+

Reindex from multiple sources

+

If you have many sources to reindex it is generally better to reindex them one at a time rather than using a glob pattern to pick up multiple sources. + That way you can resume the process if there are any errors by removing the partially completed source and starting over. + It also makes parallelizing the process fairly simple: split the list of sources to reindex and run each list in parallel.

+

For example, you can use a bash script like this:

+ 
for index in i1 i2 i3 i4 i5; do
+            curl -HContent-Type:application/json -XPOST localhost:9200/_reindex?pretty -d'{
+              "source": {
+                "index": "'$index'"
+              },
+              "dest": {
+                "index": "'$index'-reindexed"
+              }
+            }'
+          done
+
+

Throttling

+

Set requests_per_second to any positive decimal number (1.4, 6, 1000, for example) to throttle the rate at which reindex issues batches of index operations. + Requests are throttled by padding each batch with a wait time. + To turn off throttling, set requests_per_second to -1.

+

The throttling is done by waiting between batches so that the scroll that reindex uses internally can be given a timeout that takes into account the padding. + The padding time is the difference between the batch size divided by the requests_per_second and the time spent writing. + By default the batch size is 1000, so if requests_per_second is set to 500:

+ 
target_time = 1000 / 500 per second = 2 seconds
+          wait_time = target_time - write_time = 2 seconds - .5 seconds = 1.5 seconds
+
+

Since the batch is issued as a single bulk request, large batch sizes cause Elasticsearch to create many requests and then wait for a while before starting the next set. + This is "bursty" instead of "smooth".

+

Slicing

+

Reindex supports sliced scroll to parallelize the reindexing process. + This parallelization can improve efficiency and provide a convenient way to break the request down into smaller parts.

+

NOTE: Reindexing from remote clusters does not support manual or automatic slicing.

+

You can slice a reindex request manually by providing a slice ID and total number of slices to each request. + You can also let reindex automatically parallelize by using sliced scroll to slice on _id. + The slices parameter specifies the number of slices to use.

+

Adding slices to the reindex request just automates the manual process, creating sub-requests which means it has some quirks:

+
    +
  • You can see these requests in the tasks API. These sub-requests are "child" tasks of the task for the request with slices.
    • +
  • Fetching the status of the task for the request with slices only contains the status of completed slices.
    • +
  • These sub-requests are individually addressable for things like cancellation and rethrottling.
    • +
  • Rethrottling the request with slices will rethrottle the unfinished sub-request proportionally.
    • +
  • Canceling the request with slices will cancel each sub-request.
    • +
  • Due to the nature of slices, each sub-request won't get a perfectly even portion of the documents. All documents will be addressed, but some slices may be larger than others. Expect larger slices to have a more even distribution.
    • +
  • Parameters like requests_per_second and max_docs on a request with slices are distributed proportionally to each sub-request. Combine that with the previous point about distribution being uneven and you should conclude that using max_docs with slices might not result in exactly max_docs documents being reindexed.
    • +
  • Each sub-request gets a slightly different snapshot of the source, though these are all taken at approximately the same time.
    • +
+

If slicing automatically, setting slices to auto will choose a reasonable number for most indices. + If slicing manually or otherwise tuning automatic slicing, use the following guidelines.

+

Query performance is most efficient when the number of slices is equal to the number of shards in the index. + If that number is large (for example, 500), choose a lower number as too many slices will hurt performance. + Setting slices higher than the number of shards generally does not improve efficiency and adds overhead.

+

Indexing performance scales linearly across available resources with the number of slices.

+

Whether query or indexing performance dominates the runtime depends on the documents being reindexed and cluster resources.

+

Modify documents during reindexing

+

Like _update_by_query, reindex operations support a script that modifies the document. + Unlike _update_by_query, the script is allowed to modify the document's metadata.

+

Just as in _update_by_query, you can set ctx.op to change the operation that is run on the destination. + For example, set ctx.op to noop if your script decides that the document doesn’t have to be indexed in the destination. This "no operation" will be reported in the noop counter in the response body. + Set ctx.op to delete if your script decides that the document must be deleted from the destination. + The deletion will be reported in the deleted counter in the response body. + Setting ctx.op to anything else will return an error, as will setting any other field in ctx.

+

Think of the possibilities! Just be careful; you are able to change:

+
    +
  • _id
    • +
  • _index
    • +
  • _version
    • +
  • _routing
    • +
+

Setting _version to null or clearing it from the ctx map is just like not sending the version in an indexing request. + It will cause the document to be overwritten in the destination regardless of the version on the target or the version type you use in the reindex API.

+

Reindex from remote

+

Reindex supports reindexing from a remote Elasticsearch cluster. + The host parameter must contain a scheme, host, port, and optional path. + The username and password parameters are optional and when they are present the reindex operation will connect to the remote Elasticsearch node using basic authentication. + Be sure to use HTTPS when using basic authentication or the password will be sent in plain text. + There are a range of settings available to configure the behavior of the HTTPS connection.

+

When using Elastic Cloud, it is also possible to authenticate against the remote cluster through the use of a valid API key. + Remote hosts must be explicitly allowed with the reindex.remote.whitelist setting. + It can be set to a comma delimited list of allowed remote host and port combinations. + Scheme is ignored; only the host and port are used. + For example:

+ 
reindex.remote.whitelist: [otherhost:9200, another:9200, 127.0.10.*:9200, localhost:*"]
+
+

The list of allowed hosts must be configured on any nodes that will coordinate the reindex. + This feature should work with remote clusters of any version of Elasticsearch. + This should enable you to upgrade from any version of Elasticsearch to the current version by reindexing from a cluster of the old version.

+

WARNING: Elasticsearch does not support forward compatibility across major versions. + For example, you cannot reindex from a 7.x cluster into a 6.x cluster.

+

To enable queries sent to older versions of Elasticsearch, the query parameter is sent directly to the remote host without validation or modification.

+

NOTE: Reindexing from remote clusters does not support manual or automatic slicing.

+

Reindexing from a remote server uses an on-heap buffer that defaults to a maximum size of 100mb. + If the remote index includes very large documents you'll need to use a smaller batch size. + It is also possible to set the socket read timeout on the remote connection with the socket_timeout field and the connection timeout with the connect_timeout field. + Both default to 30 seconds.

+

Configuring SSL parameters

+

Reindex from remote supports configurable SSL settings. + These must be specified in the elasticsearch.yml file, with the exception of the secure settings, which you add in the Elasticsearch keystore. + It is not possible to configure SSL in the body of the reindex request.

+ + + ``_ :param dest: The destination you are copying to. :param source: The source you are copying from. - :param conflicts: Set to proceed to continue reindexing even if there are conflicts. - :param max_docs: The maximum number of documents to reindex. + :param conflicts: Indicates whether to continue reindexing even when there are + conflicts. + :param max_docs: The maximum number of documents to reindex. By default, all + documents are reindexed. If it is a value less then or equal to `scroll_size`, + a scroll will not be used to retrieve the results for the operation. If `conflicts` + is set to `proceed`, the reindex operation could attempt to reindex more + documents from the source than `max_docs` until it has successfully indexed + `max_docs` documents into the target or it has gone through every document + in the source query. :param refresh: If `true`, the request refreshes affected shards to make this operation visible to search. :param requests_per_second: The throttle for this request in sub-requests per - second. Defaults to no throttle. + second. By default, there is no throttle. :param require_alias: If `true`, the destination must be an index alias. :param script: The script to run to update the document source or metadata when reindexing. - :param scroll: Specifies how long a consistent view of the index should be maintained - for scrolled search. + :param scroll: The period of time that a consistent view of the index should + be maintained for scrolled search. :param size: - :param slices: The number of slices this task should be divided into. Defaults - to 1 slice, meaning the task isn’t sliced into subtasks. - :param timeout: Period each indexing waits for automatic index creation, dynamic - mapping updates, and waiting for active shards. + :param slices: The number of slices this task should be divided into. It defaults + to one slice, which means the task isn't sliced into subtasks. Reindex supports + sliced scroll to parallelize the reindexing process. This parallelization + can improve efficiency and provide a convenient way to break the request + down into smaller parts. NOTE: Reindexing from remote clusters does not support + manual or automatic slicing. If set to `auto`, Elasticsearch chooses the + number of slices to use. This setting will use one slice per shard, up to + a certain limit. If there are multiple sources, it will choose the number + of slices based on the index or backing index with the smallest number of + shards. + :param timeout: The period each indexing waits for automatic index creation, + dynamic mapping updates, and waiting for active shards. By default, Elasticsearch + waits for at least one minute before failing. The actual wait time could + be longer, particularly when multiple waits occur. :param wait_for_active_shards: The number of shard copies that must be active - before proceeding with the operation. Set to `all` or any positive integer - up to the total number of shards in the index (`number_of_replicas+1`). + before proceeding with the operation. Set it to `all` or any positive integer + up to the total number of shards in the index (`number_of_replicas+1`). The + default value is one, which means it waits for each primary shard to be active. :param wait_for_completion: If `true`, the request blocks until the operation is complete. """ @@ -3032,17 +3796,21 @@ def render_search_template( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Render a search template. Render a search template as a search request body. + .. raw:: html + +

Render a search template.

+

Render a search template as a search request body.

- ``_ - :param id: ID of the search template to render. If no `source` is specified, + ``_ + + :param id: The ID of the search template to render. If no `source` is specified, this or the `id` request body parameter is required. :param file: :param params: Key-value pairs used to replace Mustache variables in the template. The key is the variable name. The value is the variable value. - :param source: An inline search template. Supports the same parameters as the - search API's request body. These parameters also support Mustache variables. + :param source: An inline search template. It supports the same parameters as + the search API's request body. These parameters also support Mustache variables. If no `id` or `` is specified, this parameter is required. """ __path_parts: t.Dict[str, str] @@ -3091,7 +3859,24 @@ def render_search_template( def scripts_painless_execute( self, *, - context: t.Optional[str] = None, + context: t.Optional[ + t.Union[ + str, + t.Literal[ + "boolean_field", + "composite_field", + "date_field", + "double_field", + "filter", + "geo_point_field", + "ip_field", + "keyword_field", + "long_field", + "painless_test", + "score", + ], + ] + ] = None, context_setup: t.Optional[t.Mapping[str, t.Any]] = None, error_trace: t.Optional[bool] = None, filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, @@ -3101,13 +3886,24 @@ def scripts_painless_execute( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Run a script. Runs a script and returns a result. + .. raw:: html + +

Run a script.

+

Runs a script and returns a result. + Use this API to build and test scripts, such as when defining a script for a runtime field. + This API requires very few dependencies and is especially useful if you don't have permissions to write documents on a cluster.

+

The API uses several contexts, which control how scripts are run, what variables are available at runtime, and what the return type is.

+

Each context requires a script, but additional parameters depend on the context you're using for that script.

+ ``_ - :param context: The context that the script should run in. - :param context_setup: Additional parameters for the `context`. - :param script: The Painless script to execute. + :param context: The context that the script should run in. NOTE: Result ordering + in the field contexts is not guaranteed. + :param context_setup: Additional parameters for the `context`. NOTE: This parameter + is required for all contexts except `painless_test`, which is the default + if no value is provided for `context`. + :param script: The Painless script to run. """ __path_parts: t.Dict[str, str] = {} __path = "/_scripts/painless/_execute" @@ -3159,30 +3955,27 @@ def scroll( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Run a scrolling search. IMPORTANT: The scroll API is no longer recommend for - deep pagination. If you need to preserve the index state while paging through - more than 10,000 hits, use the `search_after` parameter with a point in time - (PIT). The scroll API gets large sets of results from a single scrolling search - request. To get the necessary scroll ID, submit a search API request that includes - an argument for the `scroll` query parameter. The `scroll` parameter indicates - how long Elasticsearch should retain the search context for the request. The - search response returns a scroll ID in the `_scroll_id` response body parameter. - You can then use the scroll ID with the scroll API to retrieve the next batch - of results for the request. If the Elasticsearch security features are enabled, - the access to the results of a specific scroll ID is restricted to the user or - API key that submitted the search. You can also use the scroll API to specify - a new scroll parameter that extends or shortens the retention period for the - search context. IMPORTANT: Results from a scrolling search reflect the state - of the index at the time of the initial search request. Subsequent indexing or - document changes only affect later search and scroll requests. - - ``_ - - :param scroll_id: Scroll ID of the search. + .. raw:: html + +

Run a scrolling search.

+

IMPORTANT: The scroll API is no longer recommend for deep pagination. If you need to preserve the index state while paging through more than 10,000 hits, use the search_after parameter with a point in time (PIT).

+

The scroll API gets large sets of results from a single scrolling search request. + To get the necessary scroll ID, submit a search API request that includes an argument for the scroll query parameter. + The scroll parameter indicates how long Elasticsearch should retain the search context for the request. + The search response returns a scroll ID in the _scroll_id response body parameter. + You can then use the scroll ID with the scroll API to retrieve the next batch of results for the request. + If the Elasticsearch security features are enabled, the access to the results of a specific scroll ID is restricted to the user or API key that submitted the search.

+

You can also use the scroll API to specify a new scroll parameter that extends or shortens the retention period for the search context.

+

IMPORTANT: Results from a scrolling search reflect the state of the index at the time of the initial search request. Subsequent indexing or document changes only affect later search and scroll requests.

+ + + ``_ + + :param scroll_id: The scroll ID of the search. :param rest_total_hits_as_int: If true, the API response’s hit.total property is returned as an integer. If false, the API response’s hit.total property is returned as an object. - :param scroll: Period to retain the search context for scrolling. + :param scroll: The period to retain the search context for scrolling. """ if scroll_id is None and body is None: raise ValueError("Empty value passed for parameter 'scroll_id'") @@ -3328,7 +4121,7 @@ def search( script_fields: t.Optional[t.Mapping[str, t.Mapping[str, t.Any]]] = None, scroll: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, search_after: t.Optional[ - t.Sequence[t.Union[None, bool, float, int, str, t.Any]] + t.Sequence[t.Union[None, bool, float, int, str]] ] = None, search_type: t.Optional[ t.Union[str, t.Literal["dfs_query_then_fetch", "query_then_fetch"]] @@ -3363,15 +4156,29 @@ def search( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - 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. - - ``_ - - :param index: Comma-separated list of data streams, indices, and aliases to search. - Supports wildcards (`*`). To search all data streams and indices, omit this - parameter or use `*` or `_all`. + .. raw:: html + +

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.

+

If the Elasticsearch security features are enabled, you must have the read index privilege for the target data stream, index, or alias. For cross-cluster search, refer to the documentation about configuring CCS privileges. + To search a point in time (PIT) for an alias, you must have the read index privilege for the alias's data streams or indices.

+

Search slicing

+

When paging through a large number of documents, it can be helpful to split the search into multiple slices to consume them independently with the slice and pit properties. + By default the splitting is done first on the shards, then locally on each shard. + The local splitting partitions the shard into contiguous ranges based on Lucene document IDs.

+

For instance if the number of shards is equal to 2 and you request 4 slices, the slices 0 and 2 are assigned to the first shard and the slices 1 and 3 are assigned to the second shard.

+

IMPORTANT: The same point-in-time ID should be used for all slices. + If different PIT IDs are used, slices can overlap and miss documents. + This situation can occur because the splitting criterion is based on Lucene document IDs, which are not stable across changes to the index.

+ + + ``_ + + :param index: A comma-separated list of data streams, indices, and aliases to + search. It supports wildcards (`*`). To search all data streams and indices, + omit this parameter or use `*` or `_all`. :param aggregations: Defines the aggregations that are run as part of the search request. :param aggs: Defines the aggregations that are run as part of the search request. @@ -3380,45 +4187,46 @@ def search( This behavior applies even if the request targets other open indices. For example, a request targeting `foo*,bar*` returns an error if an index starts with `foo` but no index starts with `bar`. - :param allow_partial_search_results: If true, returns partial results if there - are shard request timeouts or shard failures. If false, returns an error - with no partial results. - :param analyze_wildcard: If true, wildcard and prefix queries are analyzed. This - parameter can only be used when the q query string parameter is specified. - :param analyzer: Analyzer to use for the query string. This parameter can only - be used when the q query string parameter is specified. + :param allow_partial_search_results: If `true` and there are shard request timeouts + or shard failures, the request returns partial results. If `false`, it returns + an error with no partial results. To override the default behavior, you can + set the `search.default_allow_partial_results` cluster setting to `false`. + :param analyze_wildcard: If `true`, wildcard and prefix queries are analyzed. + This parameter can be used only when the `q` query string parameter is specified. + :param analyzer: The analyzer to use for the query string. This parameter can + be used only when the `q` query string parameter is specified. :param batched_reduce_size: The number of shard results that should be reduced - at once on the coordinating node. This value should be used as a protection - mechanism to reduce the memory overhead per search request if the potential - number of shards in the request can be large. - :param ccs_minimize_roundtrips: If true, network round-trips between the coordinating - node and the remote clusters are minimized when executing cross-cluster search + at once on the coordinating node. If the potential number of shards in the + request can be large, this value should be used as a protection mechanism + to reduce the memory overhead per search request. + :param ccs_minimize_roundtrips: If `true`, network round-trips between the coordinating + node and the remote clusters are minimized when running cross-cluster search (CCS) requests. :param collapse: Collapses search results the values of the specified field. - :param default_operator: The default operator for query string query: AND or - OR. This parameter can only be used when the `q` query string parameter is - specified. - :param df: Field to use as default where no field prefix is given in the query - string. This parameter can only be used when the q query string parameter + :param default_operator: The default operator for the query string query: `AND` + or `OR`. This parameter can be used only when the `q` query string parameter is specified. - :param docvalue_fields: Array of wildcard (`*`) patterns. The request returns - doc values for field names matching these patterns in the `hits.fields` property - of the response. - :param expand_wildcards: Type of index that wildcard patterns can match. If the - request can target data streams, this argument determines whether wildcard - expressions match hidden data streams. Supports comma-separated values, such - as `open,hidden`. - :param explain: If true, returns detailed information about score computation - as part of a hit. + :param df: The field to use as a default when no field prefix is given in the + query string. This parameter can be used only when the `q` query string parameter + is specified. + :param docvalue_fields: An array of wildcard (`*`) field patterns. The request + returns doc values for field names matching these patterns in the `hits.fields` + property of the response. + :param expand_wildcards: The type of index that wildcard patterns can match. + If the request can target data streams, this argument determines whether + wildcard expressions match hidden data streams. It supports comma-separated + values such as `open,hidden`. + :param explain: If `true`, the request returns detailed information about score + computation as part of a hit. :param ext: Configuration of search extensions defined by Elasticsearch plugins. - :param fields: Array of wildcard (`*`) patterns. The request returns values for - field names matching these patterns in the `hits.fields` property of the - response. + :param fields: An array of wildcard (`*`) field patterns. The request returns + values for field names matching these patterns in the `hits.fields` property + of the response. :param force_synthetic_source: Should this request force synthetic _source? Use this to test if the mapping supports synthetic _source and to get a sense of the worst case performance. Fetches with this enabled will be slower the enabling synthetic source natively in the index. - :param from_: Starting document offset. Needs to be non-negative. By default, + :param from_: The starting document offset, which must be non-negative. By default, you cannot page through more than 10,000 hits using the `from` and `size` parameters. To page through more hits, use the `search_after` parameter. :param highlight: Specifies the highlighter to use for retrieving highlighted @@ -3427,93 +4235,100 @@ def search( be ignored when frozen. :param ignore_unavailable: If `false`, the request returns an error if it targets a missing or closed index. - :param include_named_queries_score: Indicates whether hit.matched_queries should - be rendered as a map that includes the name of the matched query associated - with its score (true) or as an array containing the name of the matched queries - (false) This functionality reruns each named query on every hit in a search - response. Typically, this adds a small overhead to a request. However, using - computationally expensive named queries on a large number of hits may add - significant overhead. - :param indices_boost: Boosts the _score of documents from specified indices. - :param knn: Defines the approximate kNN search to run. + :param include_named_queries_score: If `true`, the response includes the score + contribution from any named queries. This functionality reruns each named + query on every hit in a search response. Typically, this adds a small overhead + to a request. However, using computationally expensive named queries on a + large number of hits may add significant overhead. + :param indices_boost: Boost the `_score` of documents from specified indices. + The boost value is the factor by which scores are multiplied. A boost value + greater than `1.0` increases the score. A boost value between `0` and `1.0` + decreases the score. + :param knn: The approximate kNN search to run. :param lenient: If `true`, format-based query failures (such as providing text to a numeric field) in the query string will be ignored. This parameter can - only be used when the `q` query string parameter is specified. - :param max_concurrent_shard_requests: Defines the number of concurrent shard - requests per node this search executes concurrently. This value should be - used to limit the impact of the search on the cluster in order to limit the - number of concurrent shard requests. - :param min_score: Minimum `_score` for matching documents. Documents with a lower - `_score` are not included in the search results. - :param pit: Limits the search to a point in time (PIT). If you provide a PIT, + be used only when the `q` query string parameter is specified. + :param max_concurrent_shard_requests: The number of concurrent shard requests + per node that the search runs concurrently. This value should be used to + limit the impact of the search on the cluster in order to limit the number + of concurrent shard requests. + :param min_score: The minimum `_score` for matching documents. Documents with + a lower `_score` are not included in the search results. + :param pit: Limit the search to a point in time (PIT). If you provide a PIT, you cannot specify an `` in the request path. :param post_filter: Use the `post_filter` parameter to filter search results. The search hits are filtered after the aggregations are calculated. A post filter has no impact on the aggregation results. - :param pre_filter_shard_size: Defines a threshold that enforces a pre-filter - roundtrip to prefilter search shards based on query rewriting if the number - of shards the search request expands to exceeds the threshold. This filter - roundtrip can limit the number of shards significantly if for instance a - shard can not match any documents based on its rewrite method (if date filters - are mandatory to match but the shard bounds and the query are disjoint). - When unspecified, the pre-filter phase is executed if any of these conditions - is met: the request targets more than 128 shards; the request targets one - or more read-only index; the primary sort of the query targets an indexed + :param pre_filter_shard_size: A threshold that enforces a pre-filter roundtrip + to prefilter search shards based on query rewriting if the number of shards + the search request expands to exceeds the threshold. This filter roundtrip + can limit the number of shards significantly if for instance a shard can + not match any documents based on its rewrite method (if date filters are + mandatory to match but the shard bounds and the query are disjoint). When + unspecified, the pre-filter phase is executed if any of these conditions + is met: * The request targets more than 128 shards. * The request targets + one or more read-only index. * The primary sort of the query targets an indexed field. - :param preference: Nodes and shards used for the search. By default, Elasticsearch + :param preference: The nodes and shards used for the search. By default, Elasticsearch selects from eligible nodes and shards using adaptive replica selection, - accounting for allocation awareness. Valid values are: `_only_local` to run - the search only on shards on the local node; `_local` to, if possible, run - the search on shards on the local node, or if not, select shards using the - default method; `_only_nodes:,` to run the search on only - the specified nodes IDs, where, if suitable shards exist on more than one - selected node, use shards on those nodes using the default method, or if - none of the specified nodes are available, select shards from any available - node using the default method; `_prefer_nodes:,` to if - possible, run the search on the specified nodes IDs, or if not, select shards - using the default method; `_shards:,` to run the search only - on the specified shards; `` (any string that does not start - with `_`) to route searches with the same `` to the same shards - in the same order. + accounting for allocation awareness. Valid values are: * `_only_local` to + run the search only on shards on the local node. * `_local` to, if possible, + run the search on shards on the local node, or if not, select shards using + the default method. * `_only_nodes:,` to run the search + on only the specified nodes IDs. If suitable shards exist on more than one + selected node, use shards on those nodes using the default method. If none + of the specified nodes are available, select shards from any available node + using the default method. * `_prefer_nodes:,` to if possible, + run the search on the specified nodes IDs. If not, select shards using the + default method. `_shards:,` to run the search only on the specified + shards. You can combine this value with other `preference` values. However, + the `_shards` value must come first. For example: `_shards:2,3|_local`. `` + (any string that does not start with `_`) to route searches with the same + `` to the same shards in the same order. :param profile: Set to `true` to return detailed timing information about the execution of individual components in a search request. NOTE: This is a debugging tool and adds significant overhead to search execution. - :param q: Query in the Lucene query string syntax using query parameter search. - Query parameter searches do not support the full Elasticsearch Query DSL - but are handy for testing. - :param query: Defines the search definition using the Query DSL. - :param rank: Defines the Reciprocal Rank Fusion (RRF) to use. + :param q: A query in the Lucene query string syntax. Query parameter searches + do not support the full Elasticsearch Query DSL but are handy for testing. + IMPORTANT: This parameter overrides the query parameter in the request body. + If both parameters are specified, documents matching the query request body + parameter are not returned. + :param query: The search definition using the Query DSL. + :param rank: The Reciprocal Rank Fusion (RRF) to use. :param request_cache: If `true`, the caching of search results is enabled for - requests where `size` is `0`. Defaults to index level settings. + requests where `size` is `0`. It defaults to index level settings. :param rescore: Can be used to improve precision by reordering just the top (for example 100 - 500) documents returned by the `query` and `post_filter` phases. :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 retriever: A retriever is a specification to describe top documents returned from a search. A retriever replaces other elements of the search API that - also return top documents such as query and knn. - :param routing: Custom value used to route operations to a specific shard. - :param runtime_mappings: Defines one or more runtime fields in the search request. - These fields take precedence over mapped fields with the same name. + also return top documents such as `query` and `knn`. + :param routing: A custom value that is used to route operations to a specific + shard. + :param runtime_mappings: One or more runtime fields in the search request. These + fields take precedence over mapped fields with the same name. :param script_fields: Retrieve a script evaluation (based on different fields) for each hit. - :param scroll: Period to retain the search context for scrolling. See Scroll - search results. By default, this value cannot exceed `1d` (24 hours). You - can change this limit using the `search.max_keep_alive` cluster-level setting. + :param scroll: The period to retain the search context for scrolling. By default, + this value cannot exceed `1d` (24 hours). You can change this limit by using + the `search.max_keep_alive` cluster-level setting. :param search_after: Used to retrieve the next page of hits using a set of sort values from the previous page. - :param search_type: How distributed term frequencies are calculated for relevance - scoring. - :param seq_no_primary_term: If `true`, returns sequence number and primary term - of the last modification of each hit. - :param size: The number of hits to return. By default, you cannot page through - more than 10,000 hits using the `from` and `size` parameters. To page through - more hits, use the `search_after` parameter. - :param slice: Can be used to split a scrolled search into multiple slices that - can be consumed independently. + :param search_type: Indicates how distributed term frequencies are calculated + for relevance scoring. + :param seq_no_primary_term: If `true`, the request returns sequence number and + primary term of the last modification of each hit. + :param size: The number of hits to return, which must not be negative. By default, + you cannot page through more than 10,000 hits using the `from` and `size` + parameters. To page through more hits, use the `search_after` property. + :param slice: Split a scrolled search into multiple slices that can be consumed + independently. :param sort: A comma-separated list of : pairs. - :param source: Indicates which source fields are returned for matching documents. - These fields are returned in the hits._source property of the search response. + :param source: The source fields that are returned for matching documents. These + fields are returned in the `hits._source` property of the search response. + If the `stored_fields` property is specified, the `_source` property defaults + to `false`. Otherwise, it defaults to `true`. :param source_excludes: A comma-separated list of source fields to exclude from the response. You can also use this parameter to exclude fields from the subset specified in `_source_includes` query parameter. If the `_source` @@ -3523,45 +4338,46 @@ def search( returned. You can exclude fields from this subset using the `_source_excludes` query parameter. If the `_source` parameter is `false`, this parameter is ignored. - :param stats: Stats groups to associate with the search. Each group maintains + :param stats: The stats groups to associate with the search. Each group maintains a statistics aggregation for its associated searches. You can retrieve these stats using the indices stats API. - :param stored_fields: List of stored fields to return as part of a hit. If no - fields are specified, no stored fields are included in the response. If this - field is specified, the `_source` parameter defaults to `false`. You can - pass `_source: true` to return both source fields and stored fields in the - search response. + :param stored_fields: A comma-separated list of stored fields to return as part + of a hit. If no fields are specified, no stored fields are included in the + response. If this field is specified, the `_source` property defaults to + `false`. You can pass `_source: true` to return both source fields and stored + fields in the search response. :param suggest: Defines a suggester that provides similar looking terms based on a provided text. - :param suggest_field: Specifies which field to use for suggestions. - :param suggest_mode: Specifies the suggest mode. This parameter can only be used - when the `suggest_field` and `suggest_text` query string parameters are specified. - :param suggest_size: Number of suggestions to return. This parameter can only - be used when the `suggest_field` and `suggest_text` query string parameters + :param suggest_field: The field to use for suggestions. + :param suggest_mode: The suggest mode. This parameter can be used only when the + `suggest_field` and `suggest_text` query string parameters are specified. + :param suggest_size: The number of suggestions to return. This parameter can + be used only when the `suggest_field` and `suggest_text` query string parameters are specified. :param suggest_text: The source text for which the suggestions should be returned. - This parameter can only be used when the `suggest_field` and `suggest_text` + This parameter can be used only when the `suggest_field` and `suggest_text` query string parameters are specified. - :param terminate_after: Maximum number of documents to collect for each shard. + :param terminate_after: The maximum number of documents to collect for each shard. If a query reaches this limit, Elasticsearch terminates the query early. - Elasticsearch collects documents before sorting. Use with caution. Elasticsearch - applies this parameter to each shard handling the request. When possible, - let Elasticsearch perform early termination automatically. Avoid specifying - this parameter for requests that target data streams with backing indices - across multiple data tiers. If set to `0` (default), the query does not terminate - early. - :param timeout: Specifies the period of time to wait for a response from each - shard. If no response is received before the timeout expires, the request - fails and returns an error. Defaults to no timeout. - :param track_scores: If true, calculate and return document scores, even if the - scores are not used for sorting. + Elasticsearch collects documents before sorting. IMPORTANT: Use with caution. + Elasticsearch applies this property to each shard handling the request. When + possible, let Elasticsearch perform early termination automatically. Avoid + specifying this property for requests that target data streams with backing + indices across multiple data tiers. If set to `0` (default), the query does + not terminate early. + :param timeout: The period of time to wait for a response from each shard. If + no response is received before the timeout expires, the request fails and + returns an error. Defaults to no timeout. + :param track_scores: If `true`, calculate and return document scores, even if + the scores are not used for sorting. :param track_total_hits: Number of hits matching the query to count accurately. If `true`, the exact number of hits is returned at the cost of some performance. If `false`, the response does not include the total number of hits matching the query. :param typed_keys: If `true`, aggregation and suggester names are be prefixed by their respective types in the response. - :param version: If true, returns document version as part of a hit. + :param version: If `true`, the request returns the document version as part of + a hit. """ __path_parts: t.Dict[str, str] if index not in SKIP_IN_PATH: @@ -3791,52 +4607,376 @@ def search_mvt( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> BinaryApiResponse: """ - Search a vector tile. Search a vector tile for geospatial values. - - ``_ + .. raw:: html + +

Search a vector tile.

+

Search a vector tile for geospatial values. + Before using this API, you should be familiar with the Mapbox vector tile specification. + The API returns results as a binary mapbox vector tile.

+

Internally, Elasticsearch translates a vector tile search API request into a search containing:

+
    +
  • A geo_bounding_box query on the <field>. The query uses the <zoom>/<x>/<y> tile as a bounding box.
    • +
  • A geotile_grid or geohex_grid aggregation on the <field>. The grid_agg parameter determines the aggregation type. The aggregation uses the <zoom>/<x>/<y> tile as a bounding box.
    • +
  • Optionally, a geo_bounds aggregation on the <field>. The search only includes this aggregation if the exact_bounds parameter is true.
    • +
  • If the optional parameter with_labels is true, the internal search will include a dynamic runtime field that calls the getLabelPosition function of the geometry doc value. This enables the generation of new point features containing suggested geometry labels, so that, for example, multi-polygons will have only one label.
    • +
+

For example, Elasticsearch may translate a vector tile search API request with a grid_agg argument of geotile and an exact_bounds argument of true into the following search

+ 
GET my-index/_search
+          {
+            "size": 10000,
+            "query": {
+              "geo_bounding_box": {
+                "my-geo-field": {
+                  "top_left": {
+                    "lat": -40.979898069620134,
+                    "lon": -45
+                  },
+                  "bottom_right": {
+                    "lat": -66.51326044311186,
+                    "lon": 0
+                  }
+                }
+              }
+            },
+            "aggregations": {
+              "grid": {
+                "geotile_grid": {
+                  "field": "my-geo-field",
+                  "precision": 11,
+                  "size": 65536,
+                  "bounds": {
+                    "top_left": {
+                      "lat": -40.979898069620134,
+                      "lon": -45
+                    },
+                    "bottom_right": {
+                      "lat": -66.51326044311186,
+                      "lon": 0
+                    }
+                  }
+                }
+              },
+              "bounds": {
+                "geo_bounds": {
+                  "field": "my-geo-field",
+                  "wrap_longitude": false
+                }
+              }
+            }
+          }
+
+

The API returns results as a binary Mapbox vector tile. + Mapbox vector tiles are encoded as Google Protobufs (PBF). By default, the tile contains three layers:

+
    +
  • A hits layer containing a feature for each <field> value matching the geo_bounding_box query.
    • +
  • An aggs layer containing a feature for each cell of the geotile_grid or geohex_grid. The layer only contains features for cells with matching data.
    • +
  • A meta layer containing: +
      +
    • A feature containing a bounding box. By default, this is the bounding box of the tile.
      • +
    • Value ranges for any sub-aggregations on the geotile_grid or geohex_grid.
      • +
    • Metadata for the search.
      • +
    +
    • +
+

The API only returns features that can display at its zoom level. + For example, if a polygon feature has no area at its zoom level, the API omits it. + The API returns errors as UTF-8 encoded JSON.

+

IMPORTANT: You can specify several options for this API as either a query parameter or request body parameter. + If you specify both parameters, the query parameter takes precedence.

+

Grid precision for geotile

+

For a grid_agg of geotile, you can use cells in the aggs layer as tiles for lower zoom levels. + grid_precision represents the additional zoom levels available through these cells. The final precision is computed by as follows: <zoom> + grid_precision. + For example, if <zoom> is 7 and grid_precision is 8, then the geotile_grid aggregation will use a precision of 15. + The maximum final precision is 29. + The grid_precision also determines the number of cells for the grid as follows: (2^grid_precision) x (2^grid_precision). + For example, a value of 8 divides the tile into a grid of 256 x 256 cells. + The aggs layer only contains features for cells with matching data.

+

Grid precision for geohex

+

For a grid_agg of geohex, Elasticsearch uses <zoom> and grid_precision to calculate a final precision as follows: <zoom> + grid_precision.

+

This precision determines the H3 resolution of the hexagonal cells produced by the geohex aggregation. + The following table maps the H3 resolution for each precision. + For example, if <zoom> is 3 and grid_precision is 3, the precision is 6. + At a precision of 6, hexagonal cells have an H3 resolution of 2. + If <zoom> is 3 and grid_precision is 4, the precision is 7. + At a precision of 7, hexagonal cells have an H3 resolution of 3.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PrecisionUnique tile binsH3 resolutionUnique hex binsRatio
14012230.5
21601227.625
364184213.15625
425618423.2890625
51024258825.744140625
64096258821.436035156
7163843411622.512329102
8655363411620.6280822754
926214442881221.099098206
10104857642881220.2747745514
114194304520168420.4808526039
12167772166141178820.8414913416
13671088646141178820.2103728354
142684354567988251620.3681524172
15107374182486917761220.644266719
16429496729686917761220.1610666797
1717179869184948424328420.2818666889
186871947673610338970298820.4932667053
19274877906944112372792091620.8632167343
201099511627776112372792091620.2158041836
2143980465111041216609544641220.3776573213
221759218604441613116266812488420.6609003122
237036874417766413116266812488420.165225078
2428147497671065614813867687418820.2891438866
251125899906842620155697073811931620.5060018015
264503599627370500155697073811931620.1265004504
2718014398509482000155697073811931620.03162511259
2872057594037927900155697073811931620.007906278149
29288230376151712000155697073811931620.001976569537
+

Hexagonal cells don't align perfectly on a vector tile. + Some cells may intersect more than one vector tile. + To compute the H3 resolution for each precision, Elasticsearch compares the average density of hexagonal bins at each resolution with the average density of tile bins at each zoom level. + Elasticsearch uses the H3 resolution that is closest to the corresponding geotile density.

+ + + ``_ :param index: Comma-separated list of data streams, indices, or aliases to search :param field: Field containing geospatial data to return :param zoom: Zoom level for the vector tile to search :param x: X coordinate for the vector tile to search :param y: Y coordinate for the vector tile to search - :param aggs: Sub-aggregations for the geotile_grid. Supports the following aggregation - types: - avg - cardinality - max - min - sum - :param buffer: Size, in pixels, of a clipping buffer outside the tile. This allows - renderers to avoid outline artifacts from geometries that extend past the - extent of the tile. - :param exact_bounds: If false, the meta layer’s feature is the bounding box of - the tile. If true, the meta layer’s feature is a bounding box resulting from - a geo_bounds aggregation. The aggregation runs on values that intersect - the // tile with wrap_longitude set to false. The resulting bounding - box may be larger than the vector tile. - :param extent: Size, in pixels, of a side of the tile. Vector tiles are square + :param aggs: Sub-aggregations for the geotile_grid. It supports the following + aggregation types: - `avg` - `boxplot` - `cardinality` - `extended stats` + - `max` - `median absolute deviation` - `min` - `percentile` - `percentile-rank` + - `stats` - `sum` - `value count` The aggregation names can't start with + `_mvt_`. The `_mvt_` prefix is reserved for internal aggregations. + :param buffer: The size, in pixels, of a clipping buffer outside the tile. This + allows renderers to avoid outline artifacts from geometries that extend past + the extent of the tile. + :param exact_bounds: If `false`, the meta layer's feature is the bounding box + of the tile. If `true`, the meta layer's feature is a bounding box resulting + from a `geo_bounds` aggregation. The aggregation runs on values that + intersect the `//` tile with `wrap_longitude` set to `false`. + The resulting bounding box may be larger than the vector tile. + :param extent: The size, in pixels, of a side of the tile. Vector tiles are square with equal sides. - :param fields: Fields to return in the `hits` layer. Supports wildcards (`*`). - This parameter does not support fields with array values. Fields with array - values may return inconsistent results. - :param grid_agg: Aggregation used to create a grid for the `field`. + :param fields: The fields to return in the `hits` layer. It supports wildcards + (`*`). This parameter does not support fields with array values. Fields with + array values may return inconsistent results. + :param grid_agg: The aggregation used to create a grid for the `field`. :param grid_precision: Additional zoom levels available through the aggs layer. - For example, if is 7 and grid_precision is 8, you can zoom in up to - level 15. Accepts 0-8. If 0, results don’t include the aggs layer. + For example, if `` is `7` and `grid_precision` is `8`, you can zoom + in up to level 15. Accepts 0-8. If 0, results don't include the aggs layer. :param grid_type: Determines the geometry type for features in the aggs layer. - In the aggs layer, each feature represents a geotile_grid cell. If 'grid' - each feature is a Polygon of the cells bounding box. If 'point' each feature + In the aggs layer, each feature represents a `geotile_grid` cell. If `grid, + each feature is a polygon of the cells bounding box. If `point`, each feature is a Point that is the centroid of the cell. - :param query: Query DSL used to filter documents for the search. + :param query: The query DSL used to filter documents for the search. :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 size: Maximum number of features to return in the hits layer. Accepts - 0-10000. If 0, results don’t include the hits layer. - :param sort: Sorts features in the hits layer. By default, the API calculates - a bounding box for each feature. It sorts features based on this box’s diagonal + :param size: The maximum number of features to return in the hits layer. Accepts + 0-10000. If 0, results don't include the hits layer. + :param sort: Sort the features in the hits layer. By default, the API calculates + a bounding box for each feature. It sorts features based on this box's diagonal length, from longest to shortest. - :param track_total_hits: Number of hits matching the query to count accurately. + :param track_total_hits: The number of hits matching the query to count accurately. If `true`, the exact number of hits is returned at the cost of some performance. If `false`, the response does not include the total number of hits matching the query. :param with_labels: If `true`, the hits and aggs layers will contain additional point features representing suggested label positions for the original features. + * `Point` and `MultiPoint` features will have one of the points selected. + * `Polygon` and `MultiPolygon` features will have a single point generated, + either the centroid, if it is within the polygon, or another point within + the polygon selected from the sorted triangle-tree. * `LineString` features + will likewise provide a roughly central point selected from the triangle-tree. + * The aggregation results will provide one central point for each aggregation + bucket. All attributes from the original features will also be copied to + the new label features. In addition, the new features will be distinguishable + using the tag `_mvt_label_position`. """ if index in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'index'") @@ -3961,12 +5101,15 @@ def search_template( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Run a search with a search template. + .. raw:: html + +

Run a search with a search template.

- ``_ - :param index: Comma-separated list of data streams, indices, and aliases to search. - Supports wildcards (*). + ``_ + + :param index: A comma-separated list of data streams, indices, and aliases to + search. It supports wildcards (`*`). :param allow_no_indices: If `false`, the request returns an error if any wildcard expression, index alias, or `_all` value targets only missing or closed indices. This behavior applies even if the request targets other open indices. For @@ -3974,32 +5117,34 @@ def search_template( with `foo` but no index starts with `bar`. :param ccs_minimize_roundtrips: If `true`, network round-trips are minimized for cross-cluster search requests. - :param expand_wildcards: Type of index that wildcard patterns can match. If the - request can target data streams, this argument determines whether wildcard - expressions match hidden data streams. Supports comma-separated values, such - as `open,hidden`. Valid values are: `all`, `open`, `closed`, `hidden`, `none`. + :param expand_wildcards: The type of index that wildcard patterns can match. + If the request can target data streams, this argument determines whether + wildcard expressions match hidden data streams. Supports comma-separated + values, such as `open,hidden`. Valid values are: `all`, `open`, `closed`, + `hidden`, `none`. :param explain: If `true`, returns detailed information about score calculation - as part of each hit. - :param id: ID of the search template to use. If no source is specified, this - parameter is required. + as part of each hit. If you specify both this and the `explain` query parameter, + the API uses only the query parameter. + :param id: The ID of the search template to use. If no `source` is specified, + this parameter is required. :param ignore_throttled: If `true`, specified concrete, expanded, or aliased indices are not included in the response when throttled. :param ignore_unavailable: If `false`, the request returns an error if it targets a missing or closed index. :param params: Key-value pairs used to replace Mustache variables in the template. The key is the variable name. The value is the variable value. - :param preference: Specifies the node or shard the operation should be performed - on. Random by default. + :param preference: The node or shard the operation should be performed on. It + is random by default. :param profile: If `true`, the query execution is profiled. - :param rest_total_hits_as_int: If true, hits.total are rendered as an integer - in the response. - :param routing: Custom value used to route operations to a specific shard. + :param rest_total_hits_as_int: If `true`, `hits.total` is rendered as an integer + in the response. If `false`, it is rendered as an object. + :param routing: A custom value used to route operations to a specific shard. :param scroll: Specifies how long a consistent view of the index should be maintained for scrolled search. :param search_type: The type of the search operation. :param source: An inline search template. Supports the same parameters as the - search API's request body. Also supports Mustache variables. If no id is - specified, this parameter is required. + search API's request body. It also supports Mustache variables. If no `id` + is specified, this parameter is required. :param typed_keys: If `true`, the response prefixes aggregation and suggester names with their respective types. """ @@ -4093,34 +5238,39 @@ def terms_enum( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Get terms in an index. Discover terms that match a partial string in an index. - This "terms enum" API is designed for low-latency look-ups used in auto-complete - scenarios. If the `complete` property in the response is false, the returned - terms set may be incomplete and should be treated as approximate. This can occur - due to a few reasons, such as a request timeout or a node error. NOTE: The terms - enum API may return terms from deleted documents. Deleted documents are initially - only marked as deleted. It is not until their segments are merged that documents - are actually deleted. Until that happens, the terms enum API will return terms - from these documents. - - ``_ + .. raw:: html - :param index: Comma-separated list of data streams, indices, and index aliases - to search. Wildcard (*) expressions are supported. +

Get terms in an index.

+

Discover terms that match a partial string in an index. + This API is designed for low-latency look-ups used in auto-complete scenarios.

+
+

info + The terms enum API may return terms from deleted documents. Deleted documents are initially only marked as deleted. It is not until their segments are merged that documents are actually deleted. Until that happens, the terms enum API will return terms from these documents.

+
+ + + ``_ + + :param index: A comma-separated list of data streams, indices, and index aliases + to search. Wildcard (`*`) expressions are supported. To search all data streams + or indices, omit this parameter or use `*` or `_all`. :param field: The string to match at the start of indexed terms. If not provided, all terms in the field are considered. - :param case_insensitive: When true the provided search string is matched against + :param case_insensitive: When `true`, the provided search string is matched against index terms without case sensitivity. - :param index_filter: Allows to filter an index shard if the provided query rewrites - to match_none. - :param search_after: - :param size: How many matching terms to return. - :param string: The string after which terms in the index should be returned. - Allows for a form of pagination if the last result from one request is passed - as the search_after parameter for a subsequent request. - :param timeout: The maximum length of time to spend collecting results. Defaults - to "1s" (one second). If the timeout is exceeded the complete flag set to - false in the response and the results may be partial or empty. + :param index_filter: Filter an index shard if the provided query rewrites to + `match_none`. + :param search_after: The string after which terms in the index should be returned. + It allows for a form of pagination if the last result from one request is + passed as the `search_after` parameter for a subsequent request. + :param size: The number of matching terms to return. + :param string: The string to match at the start of indexed terms. If it is not + provided, all terms in the field are considered. > info > The prefix string + cannot be larger than the largest possible keyword value, which is Lucene's + term byte-length limit of 32766. + :param timeout: The maximum length of time to spend collecting results. If the + timeout is exceeded the `complete` flag set to `false` in the response and + the results may be partial or empty. """ if index in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'index'") @@ -4199,33 +5349,77 @@ def termvectors( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Get term vector information. Get information and statistics about terms in the - fields of a particular document. - - ``_ - - :param index: Name of the index that contains the document. - :param id: Unique identifier of the document. + .. raw:: html + +

Get term vector information.

+

Get information and statistics about terms in the fields of a particular document.

+

You can retrieve term vectors for documents stored in the index or for artificial documents passed in the body of the request. + You can specify the fields you are interested in through the fields parameter or by adding the fields to the request body. + For example:

+ 
GET /my-index-000001/_termvectors/1?fields=message
+
+

Fields can be specified using wildcards, similar to the multi match query.

+

Term vectors are real-time by default, not near real-time. + This can be changed by setting realtime parameter to false.

+

You can request three types of values: term information, term statistics, and field statistics. + By default, all term information and field statistics are returned for all fields but term statistics are excluded.

+

Term information

+
    +
  • term frequency in the field (always returned)
    • +
  • term positions (positions: true)
    • +
  • start and end offsets (offsets: true)
    • +
  • term payloads (payloads: true), as base64 encoded bytes
    • +
+

If the requested information wasn't stored in the index, it will be computed on the fly if possible. + Additionally, term vectors could be computed for documents not even existing in the index, but instead provided by the user.

+
+

warn + Start and end offsets assume UTF-16 encoding is being used. If you want to use these offsets in order to get the original text that produced this token, you should make sure that the string you are taking a sub-string of is also encoded using UTF-16.

+
+

Behaviour

+

The term and field statistics are not accurate. + Deleted documents are not taken into account. + The information is only retrieved for the shard the requested document resides in. + The term and field statistics are therefore only useful as relative measures whereas the absolute numbers have no meaning in this context. + By default, when requesting term vectors of artificial documents, a shard to get the statistics from is randomly selected. + Use routing only to hit a particular shard.

+ + + ``_ + + :param index: The name of the index that contains the document. + :param id: A unique identifier for the document. :param doc: An artificial document (a document not present in the index) for which you want to retrieve term vectors. - :param field_statistics: If `true`, the response includes the document count, - sum of document frequencies, and sum of total term frequencies. - :param fields: Comma-separated list or wildcard expressions of fields to include - in the statistics. Used as the default list unless a specific field list - is provided in the `completion_fields` or `fielddata_fields` parameters. - :param filter: Filter terms based on their tf-idf scores. + :param field_statistics: If `true`, the response includes: * The document count + (how many documents contain this field). * The sum of document frequencies + (the sum of document frequencies for all terms in this field). * The sum + of total term frequencies (the sum of total term frequencies of each term + in this field). + :param fields: A comma-separated list or wildcard expressions of fields to include + in the statistics. It is used as the default list unless a specific field + list is provided in the `completion_fields` or `fielddata_fields` parameters. + :param filter: Filter terms based on their tf-idf scores. This could be useful + in order find out a good characteristic vector of a document. This feature + works in a similar manner to the second phase of the More Like This Query. :param offsets: If `true`, the response includes term offsets. :param payloads: If `true`, the response includes term payloads. - :param per_field_analyzer: Overrides the default per-field analyzer. + :param per_field_analyzer: Override the default per-field analyzer. This is useful + in order to generate term vectors in any fashion, especially when using artificial + documents. When providing an analyzer for a field that already stores term + vectors, the term vectors will be regenerated. :param positions: If `true`, the response includes term positions. - :param preference: Specifies the node or shard the operation should be performed - on. Random by default. + :param preference: The node or shard the operation should be performed on. It + is random by default. :param realtime: If true, the request is real-time as opposed to near-real-time. - :param routing: Custom value used to route operations to a specific shard. - :param term_statistics: If `true`, the response includes term frequency and document - frequency. + :param routing: A custom value that is used to route operations to a specific + shard. + :param term_statistics: If `true`, the response includes: * The total term frequency + (how often a term occurs in all documents). * The document frequency (the + number of documents containing the current term). By default these values + are not returned since term statistics can have a serious performance impact. :param version: If `true`, returns the document version as part of a hit. - :param version_type: Specific version type. + :param version_type: The version type. """ if index in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'index'") @@ -4321,6 +5515,7 @@ def update( human: t.Optional[bool] = None, if_primary_term: t.Optional[int] = None, if_seq_no: t.Optional[int] = None, + include_source_on_error: t.Optional[bool] = None, lang: t.Optional[str] = None, pretty: t.Optional[bool] = None, refresh: t.Optional[ @@ -4342,46 +5537,67 @@ def update( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Update a document. Updates a document by running a script or passing a partial - document. - - ``_ - - :param index: The name of the index - :param id: Document ID - :param detect_noop: Set to false to disable setting 'result' in the response - to 'noop' if no change to the document occurred. - :param doc: A partial update to an existing document. - :param doc_as_upsert: Set to true to use the contents of 'doc' as the value of - 'upsert' + .. raw:: html + +

Update a document.

+

Update a document by running a script or passing a partial document.

+

If the Elasticsearch security features are enabled, you must have the index or write index privilege for the target index or index alias.

+

The script can update, delete, or skip modifying the document. + The API also supports passing a partial document, which is merged into the existing document. + To fully replace an existing document, use the index API. + This operation:

+
    +
  • Gets the document (collocated with the shard) from the index.
    • +
  • Runs the specified script.
    • +
  • Indexes the result.
    • +
+

The document must still be reindexed, but using this API removes some network roundtrips and reduces chances of version conflicts between the GET and the index operation.

+

The _source field must be enabled to use this API. + In addition to _source, you can access the following variables through the ctx map: _index, _type, _id, _version, _routing, and _now (the current timestamp).

+ + + ``_ + + :param index: The name of the target index. By default, the index is created + automatically if it doesn't exist. + :param id: A unique identifier for the document to be updated. + :param detect_noop: If `true`, the `result` in the response is set to `noop` + (no operation) when there are no changes to the document. + :param doc: A partial update to an existing document. If both `doc` and `script` + are specified, `doc` is ignored. + :param doc_as_upsert: If `true`, use the contents of 'doc' as the value of 'upsert'. + NOTE: Using ingest pipelines with `doc_as_upsert` is not supported. :param if_primary_term: Only perform the operation if the document has this primary term. :param if_seq_no: Only perform the operation if the document has this sequence number. + :param include_source_on_error: True or false if to include the document source + in the error message in case of parsing errors. :param lang: The script language. :param refresh: If 'true', Elasticsearch refreshes the affected shards to make - this operation visible to search, if 'wait_for' then wait for a refresh to - make this operation visible to search, if 'false' do nothing with refreshes. - :param require_alias: If true, the destination must be an index alias. - :param retry_on_conflict: Specify how many times should the operation be retried + this operation visible to search. If 'wait_for', it waits for a refresh to + make this operation visible to search. If 'false', it does nothing with refreshes. + :param require_alias: If `true`, the destination must be an index alias. + :param retry_on_conflict: The number of times the operation should be retried when a conflict occurs. - :param routing: Custom value used to route operations to a specific shard. - :param script: Script to execute to update the document. - :param scripted_upsert: Set to true to execute the script whether or not the - document exists. - :param source: Set to false to disable source retrieval. You can also specify - a comma-separated list of the fields you want to retrieve. - :param source_excludes: Specify the source fields you want to exclude. - :param source_includes: Specify the source fields you want to retrieve. - :param timeout: Period to wait for dynamic mapping updates and active shards. - This guarantees Elasticsearch waits for at least the timeout before failing. - The actual wait time could be longer, particularly when multiple waits occur. + :param routing: A custom value used to route operations to a specific shard. + :param script: The script to run to update the document. + :param scripted_upsert: If `true`, run the script whether or not the document + exists. + :param source: If `false`, turn off source retrieval. You can also specify a + comma-separated list of the fields you want to retrieve. + :param source_excludes: The source fields you want to exclude. + :param source_includes: The source fields you want to retrieve. + :param timeout: The period to wait for the following operations: dynamic mapping + updates and waiting for active shards. Elasticsearch waits for at least the + timeout period before failing. The actual wait time could be longer, particularly + when multiple waits occur. :param upsert: If the document does not already exist, the contents of 'upsert' - are inserted as a new document. If the document exists, the 'script' is executed. - :param wait_for_active_shards: The number of shard copies that must be active - before proceeding with the operations. Set to 'all' or any positive integer - up to the total number of shards in the index (number_of_replicas+1). Defaults - to 1 meaning the primary shard. + are inserted as a new document. If the document exists, the 'script' is run. + :param wait_for_active_shards: The number of copies of each shard that must be + active before proceeding with the operation. Set to 'all' or any positive + integer up to the total number of shards in the index (`number_of_replicas`+1). + The default value of `1` means it waits for each primary shard to be active. """ if index in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'index'") @@ -4401,6 +5617,8 @@ def update( __query["if_primary_term"] = if_primary_term if if_seq_no is not None: __query["if_seq_no"] = if_seq_no + if include_source_on_error is not None: + __query["include_source_on_error"] = include_source_on_error if lang is not None: __query["lang"] = lang if pretty is not None: @@ -4507,82 +5725,166 @@ def update_by_query( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Update documents. Updates documents that match the specified query. If no query - is specified, performs an update on every document in the data stream or index - without modifying the source, which is useful for picking up mapping changes. - - ``_ - - :param index: Comma-separated list of data streams, indices, and aliases to search. - Supports wildcards (`*`). To search all data streams or indices, omit this - parameter or use `*` or `_all`. + .. raw:: html + +

Update documents. + Updates documents that match the specified query. + If no query is specified, performs an update on every document in the data stream or index without modifying the source, which is useful for picking up mapping changes.

+

If the Elasticsearch security features are enabled, you must have the following index privileges for the target data stream, index, or alias:

+
    +
  • read
    • +
  • index or write
    • +
+

You can specify the query criteria in the request URI or the request body using the same syntax as the search API.

+

When you submit an update by query request, Elasticsearch gets a snapshot of the data stream or index when it begins processing the request and updates matching documents using internal versioning. + When the versions match, the document is updated and the version number is incremented. + If a document changes between the time that the snapshot is taken and the update operation is processed, it results in a version conflict and the operation fails. + You can opt to count version conflicts instead of halting and returning by setting conflicts to proceed. + Note that if you opt to count version conflicts, the operation could attempt to update more documents from the source than max_docs until it has successfully updated max_docs documents or it has gone through every document in the source query.

+

NOTE: Documents with a version equal to 0 cannot be updated using update by query because internal versioning does not support 0 as a valid version number.

+

While processing an update by query request, Elasticsearch performs multiple search requests sequentially to find all of the matching documents. + A bulk update request is performed for each batch of matching documents. + Any query or update failures cause the update by query request to fail and the failures are shown in the response. + Any update requests that completed successfully still stick, they are not rolled back.

+

Throttling update requests

+

To control the rate at which update by query issues batches of update operations, you can set requests_per_second to any positive decimal number. + This pads each batch with a wait time to throttle the rate. + Set requests_per_second to -1 to turn off throttling.

+

Throttling uses a wait time between batches so that the internal scroll requests can be given a timeout that takes the request padding into account. + The padding time is the difference between the batch size divided by the requests_per_second and the time spent writing. + By default the batch size is 1000, so if requests_per_second is set to 500:

+ 
target_time = 1000 / 500 per second = 2 seconds
+          wait_time = target_time - write_time = 2 seconds - .5 seconds = 1.5 seconds
+
+

Since the batch is issued as a single _bulk request, large batch sizes cause Elasticsearch to create many requests and wait before starting the next set. + This is "bursty" instead of "smooth".

+

Slicing

+

Update by query supports sliced scroll to parallelize the update process. + This can improve efficiency and provide a convenient way to break the request down into smaller parts.

+

Setting slices to auto chooses a reasonable number for most data streams and indices. + This setting will use one slice per shard, up to a certain limit. + If there are multiple source data streams or indices, it will choose the number of slices based on the index or backing index with the smallest number of shards.

+

Adding slices to _update_by_query just automates the manual process of creating sub-requests, which means it has some quirks:

+
    +
  • You can see these requests in the tasks APIs. These sub-requests are "child" tasks of the task for the request with slices.
    • +
  • Fetching the status of the task for the request with slices only contains the status of completed slices.
    • +
  • These sub-requests are individually addressable for things like cancellation and rethrottling.
    • +
  • Rethrottling the request with slices will rethrottle the unfinished sub-request proportionally.
    • +
  • Canceling the request with slices will cancel each sub-request.
    • +
  • Due to the nature of slices each sub-request won't get a perfectly even portion of the documents. All documents will be addressed, but some slices may be larger than others. Expect larger slices to have a more even distribution.
    • +
  • Parameters like requests_per_second and max_docs on a request with slices are distributed proportionally to each sub-request. Combine that with the point above about distribution being uneven and you should conclude that using max_docs with slices might not result in exactly max_docs documents being updated.
    • +
  • Each sub-request gets a slightly different snapshot of the source data stream or index though these are all taken at approximately the same time.
    • +
+

If you're slicing manually or otherwise tuning automatic slicing, keep in mind that:

+
    +
  • Query performance is most efficient when the number of slices is equal to the number of shards in the index or backing index. If that number is large (for example, 500), choose a lower number as too many slices hurts performance. Setting slices higher than the number of shards generally does not improve efficiency and adds overhead.
    • +
  • Update performance scales linearly across available resources with the number of slices.
    • +
+

Whether query or update performance dominates the runtime depends on the documents being reindexed and cluster resources.

+

Update the document source

+

Update by query supports scripts to update the document source. + As with the update API, you can set ctx.op to change the operation that is performed.

+

Set ctx.op = "noop" if your script decides that it doesn't have to make any changes. + The update by query operation skips updating the document and increments the noop counter.

+

Set ctx.op = "delete" if your script decides that the document should be deleted. + The update by query operation deletes the document and increments the deleted counter.

+

Update by query supports only index, noop, and delete. + Setting ctx.op to anything else is an error. + Setting any other field in ctx is an error. + This API enables you to only modify the source of matching documents; you cannot move them.

+ + + ``_ + + :param index: A comma-separated list of data streams, indices, and aliases to + search. It supports wildcards (`*`). To search all data streams or indices, + omit this parameter or use `*` or `_all`. :param allow_no_indices: If `false`, the request returns an error if any wildcard expression, index alias, or `_all` value targets only missing or closed indices. This behavior applies even if the request targets other open indices. For example, a request targeting `foo*,bar*` returns an error if an index starts with `foo` but no index starts with `bar`. :param analyze_wildcard: If `true`, wildcard and prefix queries are analyzed. - :param analyzer: Analyzer to use for the query string. - :param conflicts: What to do if update by query hits version conflicts: `abort` - or `proceed`. + This parameter can be used only when the `q` query string parameter is specified. + :param analyzer: The analyzer to use for the query string. This parameter can + be used only when the `q` query string parameter is specified. + :param conflicts: The preferred behavior when update by query hits version conflicts: + `abort` or `proceed`. :param default_operator: The default operator for query string query: `AND` or - `OR`. - :param df: Field to use as default where no field prefix is given in the query - string. - :param expand_wildcards: Type of index that wildcard patterns can match. If the - request can target data streams, this argument determines whether wildcard - expressions match hidden data streams. Supports comma-separated values, such - as `open,hidden`. Valid values are: `all`, `open`, `closed`, `hidden`, `none`. + `OR`. This parameter can be used only when the `q` query string parameter + is specified. + :param df: The field to use as default where no field prefix is given in the + query string. This parameter can be used only when the `q` query string parameter + is specified. + :param expand_wildcards: The type of index that wildcard patterns can match. + If the request can target data streams, this argument determines whether + wildcard expressions match hidden data streams. It supports comma-separated + values, such as `open,hidden`. Valid values are: `all`, `open`, `closed`, + `hidden`, `none`. :param from_: Starting offset (default: 0) :param ignore_unavailable: If `false`, the request returns an error if it targets a missing or closed index. :param lenient: If `true`, format-based query failures (such as providing text - to a numeric field) in the query string will be ignored. + to a numeric field) in the query string will be ignored. This parameter can + be used only when the `q` query string parameter is specified. :param max_docs: The maximum number of documents to update. - :param pipeline: ID of the pipeline to use to preprocess incoming documents. + :param pipeline: The ID of the pipeline to use to preprocess incoming documents. If the index has a default ingest pipeline specified, then setting the value to `_none` disables the default ingest pipeline for this request. If a final pipeline is configured it will always run, regardless of the value of this parameter. - :param preference: Specifies the node or shard the operation should be performed - on. Random by default. - :param q: Query in the Lucene query string syntax. - :param query: Specifies the documents to update using the Query DSL. + :param preference: The node or shard the operation should be performed on. It + is random by default. + :param q: A query in the Lucene query string syntax. + :param query: The documents to update using the Query DSL. :param refresh: If `true`, Elasticsearch refreshes affected shards to make the - operation visible to search. + operation visible to search after the request completes. This is different + than the update API's `refresh` parameter, which causes just the shard that + received the request to be refreshed. :param request_cache: If `true`, the request cache is used for this request. + It defaults to the index-level setting. :param requests_per_second: The throttle for this request in sub-requests per second. - :param routing: Custom value used to route operations to a specific shard. + :param routing: A custom value used to route operations to a specific shard. :param script: The script to run to update the document source or metadata when updating. - :param scroll: Period to retain the search context for scrolling. - :param scroll_size: Size of the scroll request that powers the operation. - :param search_timeout: Explicit timeout for each search request. - :param search_type: The type of the search operation. Available options: `query_then_fetch`, - `dfs_query_then_fetch`. + :param scroll: The period to retain the search context for scrolling. + :param scroll_size: The size of the scroll request that powers the operation. + :param search_timeout: An explicit timeout for each search request. By default, + there is no timeout. + :param search_type: The type of the search operation. Available options include + `query_then_fetch` and `dfs_query_then_fetch`. :param slice: Slice the request manually using the provided slice ID and total number of slices. :param slices: The number of slices this task should be divided into. :param sort: A comma-separated list of : pairs. - :param stats: Specific `tag` of the request for logging and statistical purposes. - :param terminate_after: Maximum number of documents to collect for each shard. + :param stats: The specific `tag` of the request for logging and statistical purposes. + :param terminate_after: The maximum number of documents to collect for each shard. If a query reaches this limit, Elasticsearch terminates the query early. - Elasticsearch collects documents before sorting. Use with caution. Elasticsearch - applies this parameter to each shard handling the request. When possible, - let Elasticsearch perform early termination automatically. Avoid specifying - this parameter for requests that target data streams with backing indices - across multiple data tiers. - :param timeout: Period each update request waits for the following operations: - dynamic mapping updates, waiting for active shards. + Elasticsearch collects documents before sorting. IMPORTANT: Use with caution. + Elasticsearch applies this parameter to each shard handling the request. + When possible, let Elasticsearch perform early termination automatically. + Avoid specifying this parameter for requests that target data streams with + backing indices across multiple data tiers. + :param timeout: The period each update request waits for the following operations: + dynamic mapping updates, waiting for active shards. By default, it is one + minute. This guarantees Elasticsearch waits for at least the timeout before + failing. The actual wait time could be longer, particularly when multiple + waits occur. :param version: If `true`, returns the document version as part of a hit. :param version_type: Should the document increment the version number (internal) on hit or not (reindex) :param wait_for_active_shards: The number of shard copies that must be active before proceeding with the operation. Set to `all` or any positive integer - up to the total number of shards in the index (`number_of_replicas+1`). + up to the total number of shards in the index (`number_of_replicas+1`). The + `timeout` parameter controls how long each write request waits for unavailable + shards to become available. Both work exactly the way they work in the bulk + API. :param wait_for_completion: If `true`, the request blocks until the operation - is complete. + is complete. If `false`, Elasticsearch performs some preflight checks, launches + the request, and returns a task ID that you can use to cancel or get the + status of the task. Elasticsearch creates a record of this task as a document + at `.tasks/task/${taskId}`. """ if index in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'index'") diff --git a/elasticsearch_serverless/_sync/client/async_search.py b/elasticsearch_serverless/_sync/client/async_search.py index 96138d2..7ee7f44 100644 --- a/elasticsearch_serverless/_sync/client/async_search.py +++ b/elasticsearch_serverless/_sync/client/async_search.py @@ -36,13 +36,15 @@ def delete( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Delete an async search. If the asynchronous search is still running, it is cancelled. - Otherwise, the saved search results are deleted. If the Elasticsearch security - features are enabled, the deletion of a specific async search is restricted to: - the authenticated user that submitted the original search request; users that - have the `cancel_task` cluster privilege. + .. raw:: html - ``_ +

Delete an async search.

+

If the asynchronous search is still running, it is cancelled. + Otherwise, the saved search results are deleted. + If the Elasticsearch security features are enabled, the deletion of a specific async search is restricted to: the authenticated user that submitted the original search request; users that have the cancel_task cluster privilege.

+ + + ``_ :param id: A unique identifier for the async search. """ @@ -85,16 +87,18 @@ def get( ] = None, ) -> ObjectApiResponse[t.Any]: """ - Get async search results. Retrieve the results of a previously submitted asynchronous - search request. If the Elasticsearch security features are enabled, access to - the results of a specific async search is restricted to the user or API key that - submitted it. + .. raw:: html + +

Get async search results.

+

Retrieve the results of a previously submitted asynchronous search request. + If the Elasticsearch security features are enabled, access to the results of a specific async search is restricted to the user or API key that submitted it.

+ - ``_ + ``_ :param id: A unique identifier for the async search. - :param keep_alive: Specifies how long the async search should be available in - the cluster. When not specified, the `keep_alive` set with the corresponding + :param keep_alive: The length of time that the async search should be available + in the cluster. When not specified, the `keep_alive` set with the corresponding submit async request will be used. Otherwise, it is possible to override the value and extend the validity of the request. When this period expires, the search, if still running, is cancelled. If the search is completed, its @@ -149,15 +153,21 @@ def status( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - 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. + .. raw:: html - ``_ +

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, the access to the status of a specific async search is restricted to:

+
    +
  • The user or API key that submitted the original async search request.
    • +
  • Users that have the monitor cluster privilege or greater privileges.
    • +
+ + + ``_ :param id: A unique identifier for the async search. - :param keep_alive: Specifies how long the async search needs to be available. + :param keep_alive: The length of time that the async search needs to be available. Ongoing async searches and any saved search results are deleted after this period. """ @@ -264,6 +274,7 @@ def submit( ignore_throttled: t.Optional[bool] = None, ignore_unavailable: t.Optional[bool] = None, indices_boost: t.Optional[t.Sequence[t.Mapping[str, float]]] = None, + keep_alive: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, keep_on_completion: t.Optional[bool] = None, knn: t.Optional[ t.Union[t.Mapping[str, t.Any], t.Sequence[t.Mapping[str, t.Any]]] @@ -287,7 +298,7 @@ def submit( runtime_mappings: t.Optional[t.Mapping[str, t.Mapping[str, t.Any]]] = None, script_fields: t.Optional[t.Mapping[str, t.Mapping[str, t.Any]]] = None, search_after: t.Optional[ - t.Sequence[t.Union[None, bool, float, int, str, t.Any]] + t.Sequence[t.Union[None, bool, float, int, str]] ] = None, search_type: t.Optional[ t.Union[str, t.Literal["dfs_query_then_fetch", "query_then_fetch"]] @@ -325,17 +336,16 @@ def submit( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Run an async search. When the primary sort of the results is an indexed field, - shards get sorted based on minimum and maximum value that they hold for that - field. Partial results become available following the sort criteria that was - requested. Warning: Asynchronous search does not support scroll or search requests - that include only the suggest section. By default, Elasticsearch does not allow - you to store an async search response larger than 10Mb and an attempt to do this - results in an error. The maximum allowed size for a stored async search response - can be set by changing the `search.max_async_search_response_size` cluster level - setting. + .. raw:: html - ``_ +

Run an async search.

+

When the primary sort of the results is an indexed field, shards get sorted based on minimum and maximum value that they hold for that field. Partial results become available following the sort criteria that was requested.

+

Warning: Asynchronous search does not support scroll or search requests that include only the suggest section.

+

By default, Elasticsearch does not allow you to store an async search response larger than 10Mb and an attempt to do this results in an error. + The maximum allowed size for a stored async search response can be set by changing the search.max_async_search_response_size cluster level setting.

+ + + ``_ :param index: A comma-separated list of index names to search; use `_all` or empty string to perform the operation on all indices @@ -378,6 +388,9 @@ def submit( :param ignore_unavailable: Whether specified concrete indices should be ignored when unavailable (missing or closed) :param indices_boost: Boosts the _score of documents from specified indices. + :param keep_alive: Specifies how long the async search needs to be available. + Ongoing async searches and any saved search results are deleted after this + period. :param keep_on_completion: If `true`, results are stored for later retrieval when the search completes within the `wait_for_completion_timeout`. :param knn: Defines the approximate kNN search to run. @@ -503,6 +516,8 @@ def submit( __query["ignore_throttled"] = ignore_throttled if ignore_unavailable is not None: __query["ignore_unavailable"] = ignore_unavailable + if keep_alive is not None: + __query["keep_alive"] = keep_alive if keep_on_completion is not None: __query["keep_on_completion"] = keep_on_completion if lenient is not None: diff --git a/elasticsearch_serverless/_sync/client/cat.py b/elasticsearch_serverless/_sync/client/cat.py index b42df20..8e12098 100644 --- a/elasticsearch_serverless/_sync/client/cat.py +++ b/elasticsearch_serverless/_sync/client/cat.py @@ -50,24 +50,31 @@ def aliases( v: t.Optional[bool] = None, ) -> t.Union[ObjectApiResponse[t.Any], TextApiResponse]: """ - Get aliases. Retrieves the cluster’s index aliases, including filter and routing - information. The API does not return data stream aliases. CAT APIs are only intended - for human consumption using the command line or the Kibana console. They are - not intended for use by applications. For application consumption, use the aliases - API. + .. raw:: html - ``_ +

Get aliases.

+

Get the cluster's index aliases, including filter and routing information. + This API does not return data stream aliases.

+

IMPORTANT: CAT APIs are only intended for human consumption using the command line or the Kibana console. They are not intended for use by applications. For application consumption, use the aliases API.

+ + + ``_ :param name: A comma-separated list of aliases to retrieve. Supports wildcards (`*`). To retrieve all aliases, omit this parameter or use `*` or `_all`. - :param expand_wildcards: Whether to expand wildcard expression to concrete indices - that are open, closed or both. + :param expand_wildcards: The type of index that wildcard patterns can match. + If the request can target data streams, this argument determines whether + wildcard expressions match hidden data streams. It supports comma-separated + values, such as `open,hidden`. :param format: Specifies the format to return the columnar data in, can be set to `text`, `json`, `cbor`, `yaml`, or `smile`. :param h: List of columns to appear in the response. Supports simple wildcards. :param help: When set to `true` will output available columns. This option can't be combined with any other query string option. - :param master_timeout: Period to wait for a connection to the master node. + :param master_timeout: The period to wait for a connection to the master node. + If the master node is not available before the timeout expires, the request + fails and returns an error. To indicated that the request should never timeout, + you can set it to `-1`. :param s: List of columns that determine how the table should be sorted. Sorting defaults to ascending and can be changed by setting `:asc` or `:desc` as a suffix to the column name. @@ -131,17 +138,19 @@ def component_templates( v: t.Optional[bool] = None, ) -> t.Union[ObjectApiResponse[t.Any], TextApiResponse]: """ - Get component templates. Returns information about component templates in a cluster. - Component templates are building blocks for constructing index templates that - specify index mappings, settings, and aliases. CAT APIs are only intended for - human consumption using the command line or Kibana console. They are not intended - for use by applications. For application consumption, use the get component template - API. + .. raw:: html - ``_ +

Get component templates.

+

Get information about component templates in a cluster. + Component templates are building blocks for constructing index templates that specify index mappings, settings, and aliases.

+

IMPORTANT: CAT APIs are only intended for human consumption using the command line or Kibana console. + They are not intended for use by applications. For application consumption, use the get component template API.

- :param name: The name of the component template. Accepts wildcard expressions. - If omitted, all component templates are returned. + + ``_ + + :param name: The name of the component template. It accepts wildcard expressions. + If it is omitted, all component templates are returned. :param format: Specifies the format to return the columnar data in, can be set to `text`, `json`, `cbor`, `yaml`, or `smile`. :param h: List of columns to appear in the response. Supports simple wildcards. @@ -151,7 +160,7 @@ def component_templates( the local cluster state. If `false` the list of selected nodes are computed from the cluster state of the master node. In both cases the coordinating node will send requests for further information to each selected node. - :param master_timeout: Period to wait for a connection to the master node. + :param master_timeout: The period to wait for a connection to the master node. :param s: List of columns that determine how the table should be sorted. Sorting defaults to ascending and can be changed by setting `:asc` or `:desc` as a suffix to the column name. @@ -213,17 +222,19 @@ def count( v: t.Optional[bool] = None, ) -> t.Union[ObjectApiResponse[t.Any], TextApiResponse]: """ - Get a document count. Provides quick access to a document count for a data stream, - an index, or an entire cluster. The document count only includes live documents, - not deleted documents which have not yet been removed by the merge process. CAT - APIs are only intended for human consumption using the command line or Kibana - console. They are not intended for use by applications. For application consumption, - use the count API. + .. raw:: html - ``_ +

Get a document count.

+

Get quick access to a document count for a data stream, an index, or an entire cluster. + The document count only includes live documents, not deleted documents which have not yet been removed by the merge process.

+

IMPORTANT: CAT APIs are only intended for human consumption using the command line or Kibana console. + They are not intended for use by applications. For application consumption, use the count API.

- :param index: Comma-separated list of data streams, indices, and aliases used - to limit the request. Supports wildcards (`*`). To target all data streams + + ``_ + + :param index: A comma-separated list of data streams, indices, and aliases used + to limit the request. It supports wildcards (`*`). To target all data streams and indices, omit this parameter or use `*` or `_all`. :param format: Specifies the format to return the columnar data in, can be set to `text`, `json`, `cbor`, `yaml`, or `smile`. @@ -274,9 +285,13 @@ def count( @_rewrite_parameters() def help(self) -> TextApiResponse: """ - Get CAT help. Returns help for the CAT APIs. + .. raw:: html + +

Get CAT help.

+

Get help for the CAT APIs.

+ - ``_ + ``_ """ __path_parts: t.Dict[str, str] = {} __path = "/_cat" @@ -325,18 +340,25 @@ def indices( v: t.Optional[bool] = None, ) -> t.Union[ObjectApiResponse[t.Any], TextApiResponse]: """ - Get index information. Returns high-level information about indices in a cluster, - including backing indices for data streams. Use this request to get the following - information for each index in a cluster: - shard count - document count - deleted - document count - primary store size - total store size of all shards, including - shard replicas These metrics are retrieved directly from Lucene, which Elasticsearch - uses internally to power indexing and search. As a result, all document counts - include hidden nested documents. To get an accurate count of Elasticsearch documents, - use the cat count or count APIs. CAT APIs are only intended for human consumption - using the command line or Kibana console. They are not intended for use by applications. - For application consumption, use an index endpoint. + .. raw:: html - ``_ +

Get index information.

+

Get high-level information about indices in a cluster, including backing indices for data streams.

+

Use this request to get the following information for each index in a cluster:

+
    +
  • shard count
    • +
  • document count
    • +
  • deleted document count
    • +
  • primary store size
    • +
  • total store size of all shards, including shard replicas
    • +
+

These metrics are retrieved directly from Lucene, which Elasticsearch uses internally to power indexing and search. As a result, all document counts include hidden nested documents. + To get an accurate count of Elasticsearch documents, use the cat count or count APIs.

+

CAT APIs are only intended for human consumption using the command line or Kibana console. + They are not intended for use by applications. For application consumption, use an index endpoint.

+ + + ``_ :param index: Comma-separated list of data streams, indices, and aliases used to limit the request. Supports wildcards (`*`). To target all data streams @@ -527,13 +549,16 @@ def ml_data_frame_analytics( v: t.Optional[bool] = None, ) -> t.Union[ObjectApiResponse[t.Any], TextApiResponse]: """ - Get data frame analytics jobs. Returns configuration and usage information about - data frame analytics jobs. CAT APIs are only intended for human consumption using - the Kibana console or command line. They are not intended for use by applications. - For application consumption, use the get data frame analytics jobs statistics - API. + .. raw:: html + +

Get data frame analytics jobs.

+

Get configuration and usage information about data frame analytics jobs.

+

IMPORTANT: CAT APIs are only intended for human consumption using the Kibana + console or command line. They are not intended for use by applications. For + application consumption, use the get data frame analytics jobs statistics API.

- ``_ + + ``_ :param id: The ID of the data frame analytics to fetch :param allow_no_match: Whether to ignore if a wildcard expression matches no @@ -689,14 +714,19 @@ def ml_datafeeds( v: t.Optional[bool] = None, ) -> t.Union[ObjectApiResponse[t.Any], TextApiResponse]: """ - Get datafeeds. Returns configuration and usage information about datafeeds. This - API returns a maximum of 10,000 datafeeds. If the Elasticsearch security features - are enabled, you must have `monitor_ml`, `monitor`, `manage_ml`, or `manage` - cluster privileges to use this API. CAT APIs are only intended for human consumption - using the Kibana console or command line. They are not intended for use by applications. - For application consumption, use the get datafeed statistics API. + .. raw:: html + +

Get datafeeds.

+

Get configuration and usage information about datafeeds. + This API returns a maximum of 10,000 datafeeds. + If the Elasticsearch security features are enabled, you must have monitor_ml, monitor, manage_ml, or manage + cluster privileges to use this API.

+

IMPORTANT: CAT APIs are only intended for human consumption using the Kibana + console or command line. They are not intended for use by applications. For + application consumption, use the get datafeed statistics API.

+ - ``_ + ``_ :param datafeed_id: A numerical character string that uniquely identifies the datafeed. @@ -1050,15 +1080,19 @@ def ml_jobs( v: t.Optional[bool] = None, ) -> t.Union[ObjectApiResponse[t.Any], TextApiResponse]: """ - Get anomaly detection jobs. Returns configuration and usage information for anomaly - detection jobs. This API returns a maximum of 10,000 jobs. If the Elasticsearch - security features are enabled, you must have `monitor_ml`, `monitor`, `manage_ml`, - or `manage` cluster privileges to use this API. CAT APIs are only intended for - human consumption using the Kibana console or command line. They are not intended - for use by applications. For application consumption, use the get anomaly detection - job statistics API. + .. raw:: html - ``_ +

Get anomaly detection jobs.

+

Get configuration and usage information for anomaly detection jobs. + This API returns a maximum of 10,000 jobs. + If the Elasticsearch security features are enabled, you must have monitor_ml, + monitor, manage_ml, or manage cluster privileges to use this API.

+

IMPORTANT: CAT APIs are only intended for human consumption using the Kibana + console or command line. They are not intended for use by applications. For + application consumption, use the get anomaly detection job statistics API.

+ + + ``_ :param job_id: Identifier for the anomaly detection job. :param allow_no_match: Specifies what to do when the request: * Contains wildcard @@ -1234,12 +1268,16 @@ def ml_trained_models( v: t.Optional[bool] = None, ) -> t.Union[ObjectApiResponse[t.Any], TextApiResponse]: """ - Get trained models. Returns configuration and usage information about inference - trained models. CAT APIs are only intended for human consumption using the Kibana - console or command line. They are not intended for use by applications. For application - consumption, use the get trained models statistics API. + .. raw:: html + +

Get trained models.

+

Get configuration and usage information about inference trained models.

+

IMPORTANT: CAT APIs are only intended for human consumption using the Kibana + console or command line. They are not intended for use by applications. For + application consumption, use the get trained models statistics API.

- ``_ + + ``_ :param model_id: A unique identifier for the trained model. :param allow_no_match: Specifies what to do when the request: contains wildcard @@ -1494,12 +1532,16 @@ def transforms( v: t.Optional[bool] = None, ) -> t.Union[ObjectApiResponse[t.Any], TextApiResponse]: """ - Get transform information. Get configuration and usage information about transforms. - CAT APIs are only intended for human consumption using the Kibana console or - command line. They are not intended for use by applications. For application - consumption, use the get transform statistics API. + .. raw:: html + +

Get transform information.

+

Get configuration and usage information about transforms.

+

CAT APIs are only intended for human consumption using the Kibana + console or command line. They are not intended for use by applications. For + application consumption, use the get transform statistics API.

+ - ``_ + ``_ :param transform_id: A transform identifier or a wildcard expression. If you do not specify one of these options, the API returns information for all diff --git a/elasticsearch_serverless/_sync/client/cluster.py b/elasticsearch_serverless/_sync/client/cluster.py index 622b30a..6453dea 100644 --- a/elasticsearch_serverless/_sync/client/cluster.py +++ b/elasticsearch_serverless/_sync/client/cluster.py @@ -38,10 +38,13 @@ def delete_component_template( timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, ) -> ObjectApiResponse[t.Any]: """ - Delete component templates. Component templates are building blocks for constructing - index templates that specify index mappings, settings, and aliases. + .. raw:: html - ``_ +

Delete component templates. + Component templates are building blocks for constructing index templates that specify index mappings, settings, and aliases.

+ + + ``_ :param name: Comma-separated list or wildcard expression of component template names used to limit the request. @@ -91,10 +94,13 @@ def exists_component_template( pretty: t.Optional[bool] = None, ) -> HeadApiResponse: """ - Check component templates. Returns information about whether a particular component - template exists. + .. raw:: html + +

Check component templates. + Returns information about whether a particular component template exists.

- ``_ + + ``_ :param name: Comma-separated list of component template names used to limit the request. Wildcard (*) expressions are supported. @@ -147,9 +153,13 @@ def get_component_template( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Get component templates. Get information about component templates. + .. raw:: html + +

Get component templates. + Get information about component templates.

- ``_ + + ``_ :param name: Comma-separated list of component template names used to limit the request. Wildcard (`*`) expressions are supported. @@ -214,9 +224,13 @@ def info( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Get cluster info. Returns basic information about the cluster. + .. raw:: html + +

Get cluster info. + Returns basic information about the cluster.

+ - ``_ + ``_ :param target: Limits the information returned to the specific target. Supports a comma-separated list, such as http,ingest. @@ -265,23 +279,25 @@ def put_component_template( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Create or update a component template. Component templates are building blocks - for constructing index templates that specify index mappings, settings, and aliases. - An index template can be composed of multiple component templates. To use a component - template, specify it in an index template’s `composed_of` list. Component templates - are only applied to new data streams and indices as part of a matching index - template. Settings and mappings specified directly in the index template or the - create index request override any settings or mappings specified in a component - template. Component templates are only used during index creation. For data streams, - this includes data stream creation and the creation of a stream’s backing indices. - Changes to component templates do not affect existing indices, including a stream’s - backing indices. You can use C-style `/* *\\/` block comments in component templates. - You can include comments anywhere in the request body except before the opening - curly bracket. **Applying component templates** You cannot directly apply a component - template to a data stream or index. To be applied, a component template must - be included in an index template's `composed_of` list. + .. raw:: html + +

Create or update a component template. + Component templates are building blocks for constructing index templates that specify index mappings, settings, and aliases.

+

An index template can be composed of multiple component templates. + To use a component template, specify it in an index template’s composed_of list. + Component templates are only applied to new data streams and indices as part of a matching index template.

+

Settings and mappings specified directly in the index template or the create index request override any settings or mappings specified in a component template.

+

Component templates are only used during index creation. + For data streams, this includes data stream creation and the creation of a stream’s backing indices. + Changes to component templates do not affect existing indices, including a stream’s backing indices.

+

You can use C-style /* *\\/ block comments in component templates. + You can include comments anywhere in the request body except before the opening curly bracket.

+

Applying component templates

+

You cannot directly apply a component template to a data stream or index. + To be applied, a component template must be included in an index template's composed_of list.

+ - ``_ + ``_ :param name: Name of the component template to create. Elasticsearch includes the following built-in component templates: `logs-mappings`; `logs-settings`; diff --git a/elasticsearch_serverless/_sync/client/connector.py b/elasticsearch_serverless/_sync/client/connector.py index 1f30c53..16c6e14 100644 --- a/elasticsearch_serverless/_sync/client/connector.py +++ b/elasticsearch_serverless/_sync/client/connector.py @@ -43,10 +43,13 @@ def check_in( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Check in a connector. Update the `last_seen` field in the connector and set it - to the current timestamp. + .. raw:: html - ``_ +

Check in a connector.

+

Update the last_seen field in the connector and set it to the current timestamp.

+ + + ``_ :param connector_id: The unique identifier of the connector to be checked in """ @@ -82,20 +85,26 @@ def delete( delete_sync_jobs: t.Optional[bool] = None, error_trace: t.Optional[bool] = None, filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, + hard: t.Optional[bool] = None, human: t.Optional[bool] = None, pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Delete a connector. Removes a connector and associated sync jobs. This is a destructive - action that is not recoverable. NOTE: This action doesn’t delete any API keys, - ingest pipelines, or data indices associated with the connector. These need to - be removed manually. + .. raw:: html + +

Delete a connector.

+

Removes a connector and associated sync jobs. + This is a destructive action that is not recoverable. + NOTE: This action doesn’t delete any API keys, ingest pipelines, or data indices associated with the connector. + These need to be removed manually.

- ``_ + + ``_ :param connector_id: The unique identifier of the connector to be deleted :param delete_sync_jobs: A flag indicating if associated sync jobs should be also removed. Defaults to false. + :param hard: A flag indicating if the connector should be hard deleted. """ if connector_id in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'connector_id'") @@ -108,6 +117,8 @@ def delete( __query["error_trace"] = error_trace if filter_path is not None: __query["filter_path"] = filter_path + if hard is not None: + __query["hard"] = hard if human is not None: __query["human"] = human if pretty is not None: @@ -131,14 +142,21 @@ def get( error_trace: t.Optional[bool] = None, filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, human: t.Optional[bool] = None, + include_deleted: t.Optional[bool] = None, pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Get a connector. Get the details about a connector. + .. raw:: html + +

Get a connector.

+

Get the details about a connector.

+ - ``_ + ``_ :param connector_id: The unique identifier of the connector + :param include_deleted: A flag to indicate if the desired connector should be + fetched, even if it was soft-deleted. """ if connector_id in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'connector_id'") @@ -151,6 +169,8 @@ def get( __query["filter_path"] = filter_path if human is not None: __query["human"] = human + if include_deleted is not None: + __query["include_deleted"] = include_deleted if pretty is not None: __query["pretty"] = pretty __headers = {"accept": "application/json"} @@ -175,6 +195,7 @@ def list( filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, from_: t.Optional[int] = None, human: t.Optional[bool] = None, + include_deleted: t.Optional[bool] = None, index_name: t.Optional[t.Union[str, t.Sequence[str]]] = None, pretty: t.Optional[bool] = None, query: t.Optional[str] = None, @@ -182,13 +203,19 @@ def list( size: t.Optional[int] = None, ) -> ObjectApiResponse[t.Any]: """ - Get all connectors. Get information about all connectors. + .. raw:: html - ``_ +

Get all connectors.

+

Get information about all connectors.

+ + + ``_ :param connector_name: A comma-separated list of connector names to fetch connector documents for :param from_: Starting offset (default: 0) + :param include_deleted: A flag to indicate if the desired connector should be + fetched, even if it was soft-deleted. :param index_name: A comma-separated list of connector index names to fetch connector documents for :param query: A wildcard query string that filters connectors with matching name, @@ -210,6 +237,8 @@ def list( __query["from"] = from_ if human is not None: __query["human"] = human + if include_deleted is not None: + __query["include_deleted"] = include_deleted if index_name is not None: __query["index_name"] = index_name if pretty is not None: @@ -257,13 +286,15 @@ def post( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Create a connector. Connectors are Elasticsearch integrations that bring content - from third-party data sources, which can be deployed on Elastic Cloud or hosted - on your own infrastructure. Elastic managed connectors (Native connectors) are - a managed service on Elastic Cloud. Self-managed connectors (Connector clients) - are self-managed on your infrastructure. + .. raw:: html + +

Create a connector.

+

Connectors are Elasticsearch integrations that bring content from third-party data sources, which can be deployed on Elastic Cloud or hosted on your own infrastructure. + Elastic managed connectors (Native connectors) are a managed service on Elastic Cloud. + Self-managed connectors (Connector clients) are self-managed on your infrastructure.

- ``_ + + ``_ :param description: :param index_name: @@ -340,9 +371,12 @@ def put( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Create or update a connector. + .. raw:: html + +

Create or update a connector.

+ - ``_ + ``_ :param connector_id: The unique identifier of the connector to be created or updated. ID is auto-generated if not provided. @@ -410,12 +444,14 @@ def sync_job_cancel( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Cancel a connector sync job. Cancel a connector sync job, which sets the status - to cancelling and updates `cancellation_requested_at` to the current time. The - connector service is then responsible for setting the status of connector sync - jobs to cancelled. + .. raw:: html - ``_ +

Cancel a connector sync job.

+

Cancel a connector sync job, which sets the status to cancelling and updates cancellation_requested_at to the current time. + The connector service is then responsible for setting the status of connector sync jobs to cancelled.

+ + + ``_ :param connector_sync_job_id: The unique identifier of the connector sync job """ @@ -458,10 +494,14 @@ def sync_job_delete( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Delete a connector sync job. Remove a connector sync job and its associated data. - This is a destructive action that is not recoverable. + .. raw:: html + +

Delete a connector sync job.

+

Remove a connector sync job and its associated data. + This is a destructive action that is not recoverable.

- ``_ + + ``_ :param connector_sync_job_id: The unique identifier of the connector sync job to be deleted @@ -503,9 +543,12 @@ def sync_job_get( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Get a connector sync job. + .. raw:: html + +

Get a connector sync job.

+ - ``_ + ``_ :param connector_sync_job_id: The unique identifier of the connector sync job """ @@ -572,10 +615,13 @@ def sync_job_list( ] = None, ) -> ObjectApiResponse[t.Any]: """ - Get all connector sync jobs. Get information about all stored connector sync - jobs listed by their creation date in ascending order. + .. raw:: html - ``_ +

Get all connector sync jobs.

+

Get information about all stored connector sync jobs listed by their creation date in ascending order.

+ + + ``_ :param connector_id: A connector id to fetch connector sync jobs for :param from_: Starting offset (default: 0) @@ -635,10 +681,13 @@ def sync_job_post( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Create a connector sync job. Create a connector sync job document in the internal - index and initialize its counters and timestamps with default values. + .. raw:: html + +

Create a connector sync job.

+

Create a connector sync job document in the internal index and initialize its counters and timestamps with default values.

- ``_ + + ``_ :param id: The id of the associated connector :param job_type: @@ -688,10 +737,13 @@ def update_active_filtering( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Activate the connector draft filter. Activates the valid draft filtering for - a connector. + .. raw:: html + +

Activate the connector draft filter.

+

Activates the valid draft filtering for a connector.

+ - ``_ + ``_ :param connector_id: The unique identifier of the connector to be updated """ @@ -735,13 +787,16 @@ def update_api_key_id( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Update the connector API key ID. Update the `api_key_id` and `api_key_secret_id` - fields of a connector. You can specify the ID of the API key used for authorization - and the ID of the connector secret where the API key is stored. The connector - secret ID is required only for Elastic managed (native) connectors. Self-managed - connectors (connector clients) do not use this field. + .. raw:: html - ``_ +

Update the connector API key ID.

+

Update the api_key_id and api_key_secret_id fields of a connector. + You can specify the ID of the API key used for authorization and the ID of the connector secret where the API key is stored. + The connector secret ID is required only for Elastic managed (native) connectors. + Self-managed connectors (connector clients) do not use this field.

+ + + ``_ :param connector_id: The unique identifier of the connector to be updated :param api_key_id: @@ -794,10 +849,13 @@ def update_configuration( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Update the connector configuration. Update the configuration field in the connector - document. + .. raw:: html + +

Update the connector configuration.

+

Update the configuration field in the connector document.

- ``_ + + ``_ :param connector_id: The unique identifier of the connector to be updated :param configuration: @@ -849,12 +907,15 @@ def update_error( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Update the connector error field. Set the error field for the connector. If the - error provided in the request body is non-null, the connector’s status is updated - to error. Otherwise, if the error is reset to null, the connector status is updated - to connected. + .. raw:: html + +

Update the connector error field.

+

Set the error field for the connector. + If the error provided in the request body is non-null, the connector’s status is updated to error. + Otherwise, if the error is reset to null, the connector status is updated to connected.

+ - ``_ + ``_ :param connector_id: The unique identifier of the connector to be updated :param error: @@ -907,12 +968,15 @@ def update_filtering( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Update the connector filtering. Update the draft filtering configuration of a - connector and marks the draft validation state as edited. The filtering draft - is activated once validated by the running Elastic connector service. The filtering - property is used to configure sync rules (both basic and advanced) for a connector. + .. raw:: html - ``_ +

Update the connector filtering.

+

Update the draft filtering configuration of a connector and marks the draft validation state as edited. + The filtering draft is activated once validated by the running Elastic connector service. + The filtering property is used to configure sync rules (both basic and advanced) for a connector.

+ + + ``_ :param connector_id: The unique identifier of the connector to be updated :param advanced_snippet: @@ -967,8 +1031,11 @@ def update_filtering_validation( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Update the connector draft filtering validation. Update the draft filtering validation - info for a connector. + .. raw:: html + +

Update the connector draft filtering validation.

+

Update the draft filtering validation info for a connector.

+ ``_ @@ -1021,10 +1088,13 @@ def update_index_name( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Update the connector index name. Update the `index_name` field of a connector, - specifying the index where the data ingested by the connector is stored. + .. raw:: html + +

Update the connector index name.

+

Update the index_name field of a connector, specifying the index where the data ingested by the connector is stored.

+ - ``_ + ``_ :param connector_id: The unique identifier of the connector to be updated :param index_name: @@ -1076,9 +1146,12 @@ def update_name( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Update the connector name and description. + .. raw:: html - ``_ +

Update the connector name and description.

+ + + ``_ :param connector_id: The unique identifier of the connector to be updated :param description: @@ -1130,7 +1203,10 @@ def update_native( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Update the connector is_native flag. + .. raw:: html + +

Update the connector is_native flag.

+ ``_ @@ -1183,10 +1259,13 @@ def update_pipeline( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Update the connector pipeline. When you create a new connector, the configuration - of an ingest pipeline is populated with default settings. + .. raw:: html + +

Update the connector pipeline.

+

When you create a new connector, the configuration of an ingest pipeline is populated with default settings.

+ - ``_ + ``_ :param connector_id: The unique identifier of the connector to be updated :param pipeline: @@ -1237,9 +1316,12 @@ def update_scheduling( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Update the connector scheduling. + .. raw:: html - ``_ +

Update the connector scheduling.

+ + + ``_ :param connector_id: The unique identifier of the connector to be updated :param scheduling: @@ -1290,9 +1372,12 @@ def update_service_type( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Update the connector service type. + .. raw:: html + +

Update the connector service type.

- ``_ + + ``_ :param connector_id: The unique identifier of the connector to be updated :param service_type: @@ -1350,9 +1435,12 @@ def update_status( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Update the connector status. + .. raw:: html + +

Update the connector status.

+ - ``_ + ``_ :param connector_id: The unique identifier of the connector to be updated :param status: diff --git a/elasticsearch_serverless/_sync/client/enrich.py b/elasticsearch_serverless/_sync/client/enrich.py index 3114828..0abd123 100644 --- a/elasticsearch_serverless/_sync/client/enrich.py +++ b/elasticsearch_serverless/_sync/client/enrich.py @@ -37,9 +37,13 @@ def delete_policy( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Delete an enrich policy. Deletes an existing enrich policy and its enrich index. + .. raw:: html - ``_ +

Delete an enrich policy. + Deletes an existing enrich policy and its enrich index.

+ + + ``_ :param name: Enrich policy to delete. :param master_timeout: Period to wait for a connection to the master node. @@ -82,9 +86,13 @@ def execute_policy( wait_for_completion: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Run an enrich policy. Create the enrich index for an existing enrich policy. + .. raw:: html + +

Run an enrich policy. + Create the enrich index for an existing enrich policy.

+ - ``_ + ``_ :param name: Enrich policy to execute. :param master_timeout: Period to wait for a connection to the master node. @@ -130,9 +138,13 @@ def get_policy( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Get an enrich policy. Returns information about an enrich policy. + .. raw:: html - ``_ +

Get an enrich policy. + Returns information about an enrich policy.

+ + + ``_ :param name: Comma-separated list of enrich policy names used to limit the request. To return information for all enrich policies, omit this parameter. @@ -184,9 +196,13 @@ def put_policy( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Create an enrich policy. Creates an enrich policy. + .. raw:: html + +

Create an enrich policy. + Creates an enrich policy.

+ - ``_ + ``_ :param name: Name of the enrich policy to create or update. :param geo_match: Matches enrich data to incoming documents based on a `geo_shape` diff --git a/elasticsearch_serverless/_sync/client/eql.py b/elasticsearch_serverless/_sync/client/eql.py index 28b161f..274cdff 100644 --- a/elasticsearch_serverless/_sync/client/eql.py +++ b/elasticsearch_serverless/_sync/client/eql.py @@ -36,10 +36,14 @@ def delete( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Delete an async EQL search. Delete an async EQL search or a stored synchronous - EQL search. The API also deletes results for the search. + .. raw:: html - ``_ +

Delete an async EQL search. + Delete an async EQL search or a stored synchronous EQL search. + The API also deletes results for the search.

+ + + ``_ :param id: Identifier for the search to delete. A search ID is provided in the EQL search API's response for an async search. A search ID is also provided @@ -83,10 +87,13 @@ def get( ] = None, ) -> ObjectApiResponse[t.Any]: """ - Get async EQL search results. Get the current status and available results for - an async EQL search or a stored synchronous EQL search. + .. raw:: html + +

Get async EQL search results. + Get the current status and available results for an async EQL search or a stored synchronous EQL search.

+ - ``_ + ``_ :param id: Identifier for the search. :param keep_alive: Period for which the search and its results are stored on @@ -134,10 +141,13 @@ def get_status( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Get the async EQL status. Get the current status for an async EQL search or a - stored synchronous EQL search without returning results. + .. raw:: html - ``_ +

Get the async EQL status. + Get the current status for an async EQL search or a stored synchronous EQL search without returning results.

+ + + ``_ :param id: Identifier for the search. """ @@ -229,17 +239,27 @@ def search( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Get EQL search results. Returns search results for an Event Query Language (EQL) - query. EQL assumes each document in a data stream or index corresponds to an - event. + .. raw:: html + +

Get EQL search results. + Returns search results for an Event Query Language (EQL) query. + EQL assumes each document in a data stream or index corresponds to an event.

+ - ``_ + ``_ :param index: The name of the index to scope the operation :param query: EQL query you wish to run. :param allow_no_indices: - :param allow_partial_search_results: - :param allow_partial_sequence_results: + :param allow_partial_search_results: Allow query execution also in case of shard + failures. If true, the query will keep running and will return results based + on the available shards. For sequences, the behavior can be further refined + using allow_partial_sequence_results + :param allow_partial_sequence_results: This flag applies only to sequences and + has effect only if allow_partial_search_results=true. If true, the sequence + query will return results based on the available shards, ignoring the others. + If false, the sequence query will return successfully, but will always have + empty results. :param case_sensitive: :param event_category_field: Field containing the event classification, such as process, file, or network. diff --git a/elasticsearch_serverless/_sync/client/esql.py b/elasticsearch_serverless/_sync/client/esql.py index 6670f26..678d093 100644 --- a/elasticsearch_serverless/_sync/client/esql.py +++ b/elasticsearch_serverless/_sync/client/esql.py @@ -30,6 +30,7 @@ class EsqlClient(NamespacedClient): "query", "columnar", "filter", + "include_ccs_metadata", "locale", "params", "profile", @@ -56,10 +57,9 @@ def query( ] ] = None, human: t.Optional[bool] = None, + include_ccs_metadata: t.Optional[bool] = None, locale: t.Optional[str] = None, - params: t.Optional[ - t.Sequence[t.Union[None, bool, float, int, str, t.Any]] - ] = None, + params: t.Optional[t.Sequence[t.Union[None, bool, float, int, str]]] = None, pretty: t.Optional[bool] = None, profile: t.Optional[bool] = None, tables: t.Optional[ @@ -68,8 +68,11 @@ def query( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Run an ES|QL query. Get search results for an ES|QL (Elasticsearch query language) - query. + .. raw:: html + +

Run an ES|QL query. + Get search results for an ES|QL (Elasticsearch query language) query.

+ ``_ @@ -88,6 +91,10 @@ def query( :param filter: Specify a Query DSL query in the filter parameter to filter the set of documents that an ES|QL query runs on. :param format: A short version of the Accept header, e.g. json, yaml. + :param include_ccs_metadata: When set to `true` and performing a cross-cluster + query, the response will include an extra `_clusters` object with information + about the clusters that participated in the search along with info such as + shards count. :param locale: :param params: To avoid any attempts of hacking or code injection, extract the values in a separate list of parameters. Use question mark placeholders (?) @@ -126,6 +133,8 @@ def query( __body["columnar"] = columnar if filter is not None: __body["filter"] = filter + if include_ccs_metadata is not None: + __body["include_ccs_metadata"] = include_ccs_metadata if locale is not None: __body["locale"] = locale if params is not None: diff --git a/elasticsearch_serverless/_sync/client/graph.py b/elasticsearch_serverless/_sync/client/graph.py index 82b9509..735917b 100644 --- a/elasticsearch_serverless/_sync/client/graph.py +++ b/elasticsearch_serverless/_sync/client/graph.py @@ -45,16 +45,17 @@ def explore( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Explore graph analytics. Extract and summarize information about the documents - and terms in an Elasticsearch data stream or index. The easiest way to understand - the behavior of this API is to use the Graph UI to explore connections. An initial - request to the `_explore` API contains a seed query that identifies the documents - of interest and specifies the fields that define the vertices and connections - you want to include in the graph. Subsequent requests enable you to spider out - from one more vertices of interest. You can exclude vertices that have already - been returned. + .. raw:: html - ``_ +

Explore graph analytics. + Extract and summarize information about the documents and terms in an Elasticsearch data stream or index. + The easiest way to understand the behavior of this API is to use the Graph UI to explore connections. + An initial request to the _explore API contains a seed query that identifies the documents of interest and specifies the fields that define the vertices and connections you want to include in the graph. + Subsequent requests enable you to spider out from one more vertices of interest. + You can exclude vertices that have already been returned.

+ + + ``_ :param index: Name of the index. :param connections: Specifies or more fields from which you want to extract terms diff --git a/elasticsearch_serverless/_sync/client/indices.py b/elasticsearch_serverless/_sync/client/indices.py index 23d81bc..20d274e 100644 --- a/elasticsearch_serverless/_sync/client/indices.py +++ b/elasticsearch_serverless/_sync/client/indices.py @@ -49,22 +49,42 @@ def add_block( timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, ) -> ObjectApiResponse[t.Any]: """ - Add an index block. Limits the operations allowed on an index by blocking specific - operation types. - - ``_ - - :param index: A comma separated list of indices to add a block to - :param block: The block to add (one of read, write, read_only or metadata) - :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) - :param expand_wildcards: Whether to expand wildcard expression to concrete indices - that are open, closed or both. - :param ignore_unavailable: Whether specified concrete indices should be ignored - when unavailable (missing or closed) - :param master_timeout: Specify timeout for connection to master - :param timeout: Explicit operation timeout + .. raw:: html + +

Add an index block.

+

Add an index block to an index. + Index blocks limit the operations allowed on an index by blocking specific operation types.

+ + + ``_ + + :param index: A comma-separated list or wildcard expression of index names used + to limit the request. By default, you must explicitly name the indices you + are adding blocks to. To allow the adding of blocks to indices with `_all`, + `*`, or other wildcard expressions, change the `action.destructive_requires_name` + setting to `false`. You can update this setting in the `elasticsearch.yml` + file or by using the cluster update settings API. + :param block: The block type to add to the index. + :param allow_no_indices: If `false`, the request returns an error if any wildcard + expression, index alias, or `_all` value targets only missing or closed indices. + This behavior applies even if the request targets other open indices. For + example, a request targeting `foo*,bar*` returns an error if an index starts + with `foo` but no index starts with `bar`. + :param expand_wildcards: The type of index that wildcard patterns can match. + If the request can target data streams, this argument determines whether + wildcard expressions match hidden data streams. It supports comma-separated + values, such as `open,hidden`. + :param ignore_unavailable: If `false`, the request returns an error if it targets + a missing or closed index. + :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. It can also be set to `-1` to indicate that the request should + never timeout. + :param timeout: The period to wait for a response from all relevant nodes in + the cluster after updating the cluster metadata. If no response is received + before the timeout expires, the cluster metadata update still applies but + the response will indicate that it was not completely acknowledged. It can + also be set to `-1` to indicate that the request should never timeout. """ if index in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'index'") @@ -137,14 +157,17 @@ def analyze( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Get tokens from text analysis. The analyze API performs analysis on a text string - and returns the resulting tokens. Generating excessive amount of tokens may cause - a node to run out of memory. The `index.analyze.max_token_count` setting enables - you to limit the number of tokens that can be produced. If more than this limit - of tokens gets generated, an error occurs. The `_analyze` endpoint without a - specified index will always use `10000` as its limit. + .. raw:: html - ``_ +

Get tokens from text analysis. + The analyze API performs analysis on a text string and returns the resulting tokens.

+

Generating excessive amount of tokens may cause a node to run out of memory. + The index.analyze.max_token_count setting enables you to limit the number of tokens that can be produced. + If more than this limit of tokens gets generated, an error occurs. + The _analyze endpoint without a specified index will always use 10000 as its limit.

+ + + ``_ :param index: Index used to derive the analyzer. If specified, the `analyzer` or field parameter overrides this value. If no index is specified or the @@ -240,28 +263,29 @@ def create( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Create an index. You can use the create index API to add a new index to an Elasticsearch - cluster. When creating an index, you can specify the following: * Settings for - the index. * Mappings for fields in the index. * Index aliases **Wait for active - shards** By default, index creation will only return a response to the client - when the primary copies of each shard have been started, or the request times - out. The index creation response will indicate what happened. For example, `acknowledged` - indicates whether the index was successfully created in the cluster, `while shards_acknowledged` - indicates whether the requisite number of shard copies were started for each - shard in the index before timing out. Note that it is still possible for either - `acknowledged` or `shards_acknowledged` to be `false`, but for the index creation - to be successful. These values simply indicate whether the operation completed - before the timeout. If `acknowledged` is false, the request timed out before - the cluster state was updated with the newly created index, but it probably will - be created sometime soon. If `shards_acknowledged` is false, then the request - timed out before the requisite number of shards were started (by default just - the primaries), even if the cluster state was successfully updated to reflect - the newly created index (that is to say, `acknowledged` is `true`). You can change - the default of only waiting for the primary shards to start through the index - setting `index.write.wait_for_active_shards`. Note that changing this setting - will also affect the `wait_for_active_shards` value on all subsequent write operations. - - ``_ + .. raw:: html + +

Create an index. + You can use the create index API to add a new index to an Elasticsearch cluster. + When creating an index, you can specify the following:

+
    +
  • Settings for the index.
    • +
  • Mappings for fields in the index.
    • +
  • Index aliases
    • +
+

Wait for active shards

+

By default, index creation will only return a response to the client when the primary copies of each shard have been started, or the request times out. + The index creation response will indicate what happened. + For example, acknowledged indicates whether the index was successfully created in the cluster, while shards_acknowledged indicates whether the requisite number of shard copies were started for each shard in the index before timing out. + Note that it is still possible for either acknowledged or shards_acknowledged to be false, but for the index creation to be successful. + These values simply indicate whether the operation completed before the timeout. + If acknowledged is false, the request timed out before the cluster state was updated with the newly created index, but it probably will be created sometime soon. + If shards_acknowledged is false, then the request timed out before the requisite number of shards were started (by default just the primaries), even if the cluster state was successfully updated to reflect the newly created index (that is to say, acknowledged is true).

+

You can change the default of only waiting for the primary shards to start through the index setting index.write.wait_for_active_shards. + Note that changing this setting will also affect the wait_for_active_shards value on all subsequent write operations.

+ + + ``_ :param index: Name of the index you wish to create. :param aliases: Aliases for the index. @@ -332,10 +356,13 @@ def create_data_stream( timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, ) -> ObjectApiResponse[t.Any]: """ - Create a data stream. Creates a data stream. You must have a matching index template - with data stream enabled. + .. raw:: html - ``_ +

Create a data stream.

+

You must have a matching index template with data stream enabled.

+ + + ``_ :param name: Name of the data stream, which must meet the following criteria: Lowercase only; Cannot include `\\`, `/`, `*`, `?`, `"`, `<`, `>`, `|`, `,`, @@ -398,13 +425,17 @@ def delete( timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, ) -> ObjectApiResponse[t.Any]: """ - Delete indices. Deleting an index deletes its documents, shards, and metadata. - It does not delete related Kibana components, such as data views, visualizations, - or dashboards. You cannot delete the current write index of a data stream. To - delete the index, you must roll over the data stream so a new write index is - created. You can then use the delete index API to delete the previous write index. + .. raw:: html + +

Delete indices. + Deleting an index deletes its documents, shards, and metadata. + It does not delete related Kibana components, such as data views, visualizations, or dashboards.

+

You cannot delete the current write index of a data stream. + To delete the index, you must roll over the data stream so a new write index is created. + You can then use the delete index API to delete the previous write index.

- ``_ + + ``_ :param index: Comma-separated list of indices to delete. You cannot specify index aliases. By default, this parameter does not support wildcards (`*`) or `_all`. @@ -472,9 +503,13 @@ def delete_alias( timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, ) -> ObjectApiResponse[t.Any]: """ - Delete an alias. Removes a data stream or index from an alias. + .. raw:: html + +

Delete an alias. + Removes a data stream or index from an alias.

+ - ``_ + ``_ :param index: Comma-separated list of data streams or indices used to limit the request. Supports wildcards (`*`). @@ -535,9 +570,13 @@ def delete_data_stream( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Delete data streams. Deletes one or more data streams and their backing indices. + .. raw:: html + +

Delete data streams. + Deletes one or more data streams and their backing indices.

- ``_ + + ``_ :param name: Comma-separated list of data streams to delete. Wildcard (`*`) expressions are supported. @@ -587,12 +626,15 @@ def delete_index_template( timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, ) -> ObjectApiResponse[t.Any]: """ - Delete an index template. The provided may contain multiple - template names separated by a comma. If multiple template names are specified - then there is no wildcard support and the provided names should match completely - with existing templates. + .. raw:: html + +

Delete an index template. + The provided may contain multiple template names separated by a comma. If multiple template + names are specified then there is no wildcard support and the provided names should match completely with + existing templates.

+ - ``_ + ``_ :param name: Comma-separated list of index template names used to limit the request. Wildcard (*) expressions are supported. @@ -653,9 +695,13 @@ def exists( pretty: t.Optional[bool] = None, ) -> HeadApiResponse: """ - Check indices. Check if one or more indices, index aliases, or data streams exist. + .. raw:: html - ``_ +

Check indices. + Check if one or more indices, index aliases, or data streams exist.

+ + + ``_ :param index: Comma-separated list of data streams, indices, and aliases. Supports wildcards (`*`). @@ -731,9 +777,13 @@ def exists_alias( pretty: t.Optional[bool] = None, ) -> HeadApiResponse: """ - Check aliases. Checks if one or more data stream or index aliases exist. + .. raw:: html - ``_ +

Check aliases.

+

Check if one or more data stream or index aliases exist.

+ + + ``_ :param name: Comma-separated list of aliases to check. Supports wildcards (`*`). :param index: Comma-separated list of data streams or indices used to limit the @@ -802,9 +852,13 @@ def exists_index_template( pretty: t.Optional[bool] = None, ) -> HeadApiResponse: """ - Check index templates. Check whether index templates exist. + .. raw:: html + +

Check index templates.

+

Check whether index templates exist.

- ``_ + + ``_ :param name: Comma-separated list of index template names used to limit the request. Wildcard (*) expressions are supported. @@ -850,12 +904,13 @@ def explain_data_lifecycle( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Get the status for a data stream lifecycle. Get information about an index or - data stream's current data stream lifecycle status, such as time since index - creation, time since rollover, the lifecycle configuration managing the index, - or any errors encountered during lifecycle execution. + .. raw:: html + +

Get the status for a data stream lifecycle. + Get information about an index or data stream's current data stream lifecycle status, such as time since index creation, time since rollover, the lifecycle configuration managing the index, or any errors encountered during lifecycle execution.

- ``_ + + ``_ :param index: The name of the index to explain :param include_defaults: indicates if the API should return the default values @@ -920,10 +975,14 @@ def get( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Get index information. Get information about one or more indices. For data streams, - the API returns information about the stream’s backing indices. + .. raw:: html + +

Get index information. + Get information about one or more indices. For data streams, the API returns information about the + stream’s backing indices.

+ - ``_ + ``_ :param index: Comma-separated list of data streams, indices, and index aliases used to limit the request. Wildcard expressions (*) are supported. @@ -1010,7 +1069,13 @@ def get_alias( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Get aliases. Retrieves information for one or more data stream or index aliases. + .. raw:: html + +

Get aliases. + Retrieves information for one or more data stream or index aliases.

+ + + ``_ :param index: Comma-separated list of data streams or indices used to limit the request. Supports wildcards (`*`). To target all data streams and indices, @@ -1091,10 +1156,13 @@ def get_data_lifecycle( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Get data stream lifecycles. Retrieves the data stream lifecycle configuration - of one or more data streams. + .. raw:: html - ``_ +

Get data stream lifecycles.

+

Get the data stream lifecycle configuration of one or more data streams.

+ + + ``_ :param name: Comma-separated list of data streams to limit the request. Supports wildcards (`*`). To target all data streams, omit this parameter or use `*` @@ -1158,9 +1226,13 @@ def get_data_stream( verbose: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Get data streams. Retrieves information about one or more data streams. + .. raw:: html - ``_ +

Get data streams.

+

Get information about one or more data streams.

+ + + ``_ :param name: Comma-separated list of data stream names used to limit the request. Wildcard (`*`) expressions are supported. If omitted, all data streams are @@ -1224,9 +1296,13 @@ def get_index_template( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Get index templates. Get information about one or more index templates. + .. raw:: html - ``_ +

Get index templates. + Get information about one or more index templates.

+ + + ``_ :param name: Comma-separated list of index template names used to limit the request. Wildcard (*) expressions are supported. @@ -1297,10 +1373,13 @@ def get_mapping( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Get mapping definitions. For data streams, the API retrieves mappings for the - stream’s backing indices. + .. raw:: html + +

Get mapping definitions. + For data streams, the API retrieves mappings for the stream’s backing indices.

- ``_ + + ``_ :param index: Comma-separated list of data streams, indices, and aliases used to limit the request. Supports wildcards (`*`). To target all data streams @@ -1382,10 +1461,14 @@ def get_settings( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Get index settings. Get setting information for one or more indices. For data - streams, it returns setting information for the stream's backing indices. + .. raw:: html + +

Get index settings. + Get setting information for one or more indices. + For data streams, it returns setting information for the stream's backing indices.

+ - ``_ + ``_ :param index: Comma-separated list of data streams, indices, and aliases used to limit the request. Supports wildcards (`*`). To target all data streams @@ -1469,14 +1552,20 @@ def migrate_to_data_stream( timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, ) -> ObjectApiResponse[t.Any]: """ - Convert an index alias to a data stream. Converts an index alias to a data stream. - You must have a matching index template that is data stream enabled. The alias - must meet the following criteria: The alias must have a write index; All indices - for the alias must have a `@timestamp` field mapping of a `date` or `date_nanos` - field type; The alias must not have any filters; The alias must not use custom - routing. If successful, the request removes the alias and creates a data stream - with the same name. The indices for the alias become hidden backing indices for - the stream. The write index for the alias becomes the write index for the stream. + .. raw:: html + +

Convert an index alias to a data stream. + Converts an index alias to a data stream. + You must have a matching index template that is data stream enabled. + The alias must meet the following criteria: + The alias must have a write index; + All indices for the alias must have a @timestamp field mapping of a date or date_nanos field type; + The alias must not have any filters; + The alias must not use custom routing. + If successful, the request removes the alias and creates a data stream with the same name. + The indices for the alias become hidden backing indices for the stream. + The write index for the alias becomes the write index for the stream.

+ ``_ @@ -1528,8 +1617,11 @@ def modify_data_stream( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Update data streams. Performs one or more data stream modification actions in - a single atomic operation. + .. raw:: html + +

Update data streams. + Performs one or more data stream modification actions in a single atomic operation.

+ ``_ @@ -1591,7 +1683,11 @@ def put_alias( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Create or update an alias. Adds a data stream or index to an alias. + .. raw:: html + +

Create or update an alias. + Adds a data stream or index to an alias.

+ ``_ @@ -1668,14 +1764,15 @@ def put_alias( ) @_rewrite_parameters( - body_name="lifecycle", + body_fields=("data_retention", "downsampling", "enabled"), ) def put_data_lifecycle( self, *, name: t.Union[str, t.Sequence[str]], - lifecycle: t.Optional[t.Mapping[str, t.Any]] = None, - body: t.Optional[t.Mapping[str, t.Any]] = None, + data_retention: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, + downsampling: t.Optional[t.Mapping[str, t.Any]] = None, + enabled: t.Optional[bool] = None, error_trace: t.Optional[bool] = None, expand_wildcards: t.Optional[ t.Union[ @@ -1690,16 +1787,28 @@ def put_data_lifecycle( master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, pretty: t.Optional[bool] = None, timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, + body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Update data stream lifecycles. Update the data stream lifecycle of the specified - data streams. + .. raw:: html + +

Update data stream lifecycles. + Update the data stream lifecycle of the specified data streams.

+ ``_ :param name: Comma-separated list of data streams used to limit the request. Supports wildcards (`*`). To target all data streams use `*` or `_all`. - :param lifecycle: + :param data_retention: If defined, every document added to this data stream will + be stored at least for this time frame. Any time after this duration the + document could be deleted. When empty, every document in this data stream + will be stored indefinitely. + :param downsampling: The downsampling configuration to execute for the managed + backing index after rollover. + :param enabled: If defined, it turns data stream lifecycle on/off (`true`/`false`) + for this data stream. A data stream lifecycle that's disabled (enabled: `false`) + will have no effect on the data stream. :param expand_wildcards: Type of data stream that wildcard patterns can match. Supports comma-separated values, such as `open,hidden`. Valid values are: `all`, `hidden`, `open`, `closed`, `none`. @@ -1711,15 +1820,10 @@ def put_data_lifecycle( """ if name in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'name'") - if lifecycle is None and body is None: - raise ValueError( - "Empty value passed for parameters 'lifecycle' and 'body', one of them should be set." - ) - elif lifecycle is not None and body is not None: - raise ValueError("Cannot set both 'lifecycle' and 'body'") __path_parts: t.Dict[str, str] = {"name": _quote(name)} __path = f'/_data_stream/{__path_parts["name"]}/_lifecycle' __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 expand_wildcards is not None: @@ -1734,8 +1838,18 @@ def put_data_lifecycle( __query["pretty"] = pretty if timeout is not None: __query["timeout"] = timeout - __body = lifecycle if lifecycle is not None else body - __headers = {"accept": "application/json", "content-type": "application/json"} + if not __body: + if data_retention is not None: + __body["data_retention"] = data_retention + if downsampling is not None: + __body["downsampling"] = downsampling + if enabled is not None: + __body["enabled"] = enabled + if not __body: + __body = None # type: ignore[assignment] + __headers = {"accept": "application/json"} + if __body is not None: + __headers["content-type"] = "application/json" return self.perform_request( # type: ignore[return-value] "PUT", __path, @@ -1785,34 +1899,30 @@ def put_index_template( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Create or update an index template. Index templates define settings, mappings, - and aliases that can be applied automatically to new indices. Elasticsearch applies - templates to new indices based on an wildcard pattern that matches the index - name. Index templates are applied during data stream or index creation. For data - streams, these settings and mappings are applied when the stream's backing indices - are created. Settings and mappings specified in a create index API request override - any settings or mappings specified in an index template. Changes to index templates - do not affect existing indices, including the existing backing indices of a data - stream. You can use C-style `/* *\\/` block comments in index templates. You - can include comments anywhere in the request body, except before the opening - curly bracket. **Multiple matching templates** If multiple index templates match - the name of a new index or data stream, the template with the highest priority - is used. Multiple templates with overlapping index patterns at the same priority - are not allowed and an error will be thrown when attempting to create a template - matching an existing index template at identical priorities. **Composing aliases, - mappings, and settings** When multiple component templates are specified in the - `composed_of` field for an index template, they are merged in the order specified, - meaning that later component templates override earlier component templates. - Any mappings, settings, or aliases from the parent index template are merged - in next. Finally, any configuration on the index request itself is merged. Mapping - definitions are merged recursively, which means that later mapping components - can introduce new field mappings and update the mapping configuration. If a field - mapping is already contained in an earlier component, its definition will be - completely overwritten by the later one. This recursive merging strategy applies - not only to field mappings, but also root options like `dynamic_templates` and - `meta`. If an earlier component contains a `dynamic_templates` block, then by - default new `dynamic_templates` entries are appended onto the end. If an entry - already exists with the same key, then it is overwritten by the new definition. + .. raw:: html + +

Create or update an index template. + Index templates define settings, mappings, and aliases that can be applied automatically to new indices.

+

Elasticsearch applies templates to new indices based on an wildcard pattern that matches the index name. + Index templates are applied during data stream or index creation. + For data streams, these settings and mappings are applied when the stream's backing indices are created. + Settings and mappings specified in a create index API request override any settings or mappings specified in an index template. + Changes to index templates do not affect existing indices, including the existing backing indices of a data stream.

+

You can use C-style /* *\\/ block comments in index templates. + You can include comments anywhere in the request body, except before the opening curly bracket.

+

Multiple matching templates

+

If multiple index templates match the name of a new index or data stream, the template with the highest priority is used.

+

Multiple templates with overlapping index patterns at the same priority are not allowed and an error will be thrown when attempting to create a template matching an existing index template at identical priorities.

+

Composing aliases, mappings, and settings

+

When multiple component templates are specified in the composed_of field for an index template, they are merged in the order specified, meaning that later component templates override earlier component templates. + Any mappings, settings, or aliases from the parent index template are merged in next. + Finally, any configuration on the index request itself is merged. + Mapping definitions are merged recursively, which means that later mapping components can introduce new field mappings and update the mapping configuration. + If a field mapping is already contained in an earlier component, its definition will be completely overwritten by the later one. + This recursive merging strategy applies not only to field mappings, but also root options like dynamic_templates and meta. + If an earlier component contains a dynamic_templates block, then by default new dynamic_templates entries are appended onto the end. + If an entry already exists with the same key, then it is overwritten by the new definition.

+ ``_ @@ -1945,10 +2055,7 @@ def put_mapping( ] = None, dynamic_date_formats: t.Optional[t.Sequence[str]] = None, dynamic_templates: t.Optional[ - t.Union[ - t.Mapping[str, t.Mapping[str, t.Any]], - t.Sequence[t.Mapping[str, t.Mapping[str, t.Any]]], - ] + t.Sequence[t.Mapping[str, t.Mapping[str, t.Any]]] ] = None, error_trace: t.Optional[bool] = None, expand_wildcards: t.Optional[ @@ -1976,29 +2083,31 @@ def put_mapping( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Update field mappings. Add new fields to an existing data stream or index. You - can also use this API to change the search settings of existing fields and add - new properties to existing object fields. For data streams, these changes are - applied to all backing indices by default. **Add multi-fields to an existing - field** Multi-fields let you index the same field in different ways. You can - use this API to update the fields mapping parameter and enable multi-fields for - an existing field. WARNING: If an index (or data stream) contains documents when - you add a multi-field, those documents will not have values for the new multi-field. - You can populate the new multi-field with the update by query API. **Change supported - mapping parameters for an existing field** The documentation for each mapping - parameter indicates whether you can update it for an existing field using this - API. For example, you can use the update mapping API to update the `ignore_above` - parameter. **Change the mapping of an existing field** Except for supported mapping - parameters, you can't change the mapping or field type of an existing field. - Changing an existing field could invalidate data that's already indexed. If you - need to change the mapping of a field in a data stream's backing indices, refer - to documentation about modifying data streams. If you need to change the mapping - of a field in other indices, create a new index with the correct mapping and - reindex your data into that index. **Rename a field** Renaming a field would - invalidate data already indexed under the old field name. Instead, add an alias - field to create an alternate field name. - - ``_ + .. raw:: html + +

Update field mappings. + Add new fields to an existing data stream or index. + You can also use this API to change the search settings of existing fields and add new properties to existing object fields. + For data streams, these changes are applied to all backing indices by default.

+

Add multi-fields to an existing field

+

Multi-fields let you index the same field in different ways. + You can use this API to update the fields mapping parameter and enable multi-fields for an existing field. + WARNING: If an index (or data stream) contains documents when you add a multi-field, those documents will not have values for the new multi-field. + You can populate the new multi-field with the update by query API.

+

Change supported mapping parameters for an existing field

+

The documentation for each mapping parameter indicates whether you can update it for an existing field using this API. + For example, you can use the update mapping API to update the ignore_above parameter.

+

Change the mapping of an existing field

+

Except for supported mapping parameters, you can't change the mapping or field type of an existing field. + Changing an existing field could invalidate data that's already indexed.

+

If you need to change the mapping of a field in a data stream's backing indices, refer to documentation about modifying data streams. + If you need to change the mapping of a field in other indices, create a new index with the correct mapping and reindex your data into that index.

+

Rename a field

+

Renaming a field would invalidate data already indexed under the old field name. + Instead, add an alias field to create an alternate field name.

+ + + ``_ :param index: A comma-separated list of index names the mapping should be added to (supports wildcards); use `_all` or omit to add the mapping on all indices. @@ -2125,23 +2234,25 @@ def put_settings( timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, ) -> ObjectApiResponse[t.Any]: """ - Update index settings. Changes dynamic index settings in real time. For data - streams, index setting changes are applied to all backing indices by default. - To revert a setting to the default value, use a null value. The list of per-index - settings that can be updated dynamically on live indices can be found in index - module documentation. To preserve existing settings from being updated, set the - `preserve_existing` parameter to `true`. NOTE: You can only define new analyzers - on closed indices. To add an analyzer, you must close the index, define the analyzer, - and reopen the index. You cannot close the write index of a data stream. To update - the analyzer for a data stream's write index and future backing indices, update - the analyzer in the index template used by the stream. Then roll over the data - stream to apply the new analyzer to the stream's write index and future backing - indices. This affects searches and any new data added to the stream after the - rollover. However, it does not affect the data stream's backing indices or their - existing data. To change the analyzer for existing backing indices, you must - create a new data stream and reindex your data into it. - - ``_ + .. raw:: html + +

Update index settings. + Changes dynamic index settings in real time. + For data streams, index setting changes are applied to all backing indices by default.

+

To revert a setting to the default value, use a null value. + The list of per-index settings that can be updated dynamically on live indices can be found in index module documentation. + To preserve existing settings from being updated, set the preserve_existing parameter to true.

+

NOTE: You can only define new analyzers on closed indices. + To add an analyzer, you must close the index, define the analyzer, and reopen the index. + You cannot close the write index of a data stream. + To update the analyzer for a data stream's write index and future backing indices, update the analyzer in the index template used by the stream. + Then roll over the data stream to apply the new analyzer to the stream's write index and future backing indices. + This affects searches and any new data added to the stream after the rollover. + However, it does not affect the data stream's backing indices or their existing data. + To change the analyzer for existing backing indices, you must create a new data stream and reindex your data into it.

+ + + ``_ :param settings: :param index: Comma-separated list of data streams, indices, and aliases used @@ -2234,21 +2345,21 @@ def refresh( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Refresh an index. A refresh makes recent operations performed on one or more - indices available for search. For data streams, the API runs the refresh operation - on the stream’s backing indices. By default, Elasticsearch periodically refreshes - indices every second, but only on indices that have received one search request - or more in the last 30 seconds. You can change this default interval with the - `index.refresh_interval` setting. Refresh requests are synchronous and do not - return a response until the refresh operation completes. Refreshes are resource-intensive. - To ensure good cluster performance, it's recommended to wait for Elasticsearch's - periodic refresh rather than performing an explicit refresh when possible. If - your application workflow indexes documents and then runs a search to retrieve - the indexed document, it's recommended to use the index API's `refresh=wait_for` - query parameter option. This option ensures the indexing operation waits for - a periodic refresh before running the search. - - ``_ + .. raw:: html + +

Refresh an index. + A refresh makes recent operations performed on one or more indices available for search. + For data streams, the API runs the refresh operation on the stream’s backing indices.

+

By default, Elasticsearch periodically refreshes indices every second, but only on indices that have received one search request or more in the last 30 seconds. + You can change this default interval with the index.refresh_interval setting.

+

Refresh requests are synchronous and do not return a response until the refresh operation completes.

+

Refreshes are resource-intensive. + To ensure good cluster performance, it's recommended to wait for Elasticsearch's periodic refresh rather than performing an explicit refresh when possible.

+

If your application workflow indexes documents and then runs a search to retrieve the indexed document, it's recommended to use the index API's refresh=wait_for query parameter option. + This option ensures the indexing operation waits for a periodic refresh before running the search.

+ + + ``_ :param index: Comma-separated list of data streams, indices, and aliases used to limit the request. Supports wildcards (`*`). To target all data streams @@ -2316,10 +2427,14 @@ def resolve_index( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Resolve indices. Resolve the names and/or index patterns for indices, aliases, - and data streams. Multiple patterns and remote clusters are supported. + .. raw:: html + +

Resolve indices. + Resolve the names and/or index patterns for indices, aliases, and data streams. + Multiple patterns and remote clusters are supported.

+ - ``_ + ``_ :param name: Comma-separated name(s) or index pattern(s) of the indices, aliases, and data streams to resolve. Resources on remote clusters can be specified @@ -2390,35 +2505,37 @@ def rollover( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Roll over to a new index. TIP: It is recommended to use the index lifecycle rollover - action to automate rollovers. The rollover API creates a new index for a data - stream or index alias. The API behavior depends on the rollover target. **Roll - over a data stream** If you roll over a data stream, the API creates a new write - index for the stream. The stream's previous write index becomes a regular backing - index. A rollover also increments the data stream's generation. **Roll over an - index alias with a write index** TIP: Prior to Elasticsearch 7.9, you'd typically - use an index alias with a write index to manage time series data. Data streams - replace this functionality, require less maintenance, and automatically integrate - with data tiers. If an index alias points to multiple indices, one of the indices - must be a write index. The rollover API creates a new write index for the alias - with `is_write_index` set to `true`. The API also `sets is_write_index` to `false` - for the previous write index. **Roll over an index alias with one index** If - you roll over an index alias that points to only one index, the API creates a - new index for the alias and removes the original index from the alias. NOTE: - A rollover creates a new index and is subject to the `wait_for_active_shards` - setting. **Increment index names for an alias** When you roll over an index alias, - you can specify a name for the new index. If you don't specify a name and the - current index ends with `-` and a number, such as `my-index-000001` or `my-index-3`, - the new index name increments that number. For example, if you roll over an alias - with a current index of `my-index-000001`, the rollover creates a new index named - `my-index-000002`. This number is always six characters and zero-padded, regardless - of the previous index's name. If you use an index alias for time series data, - you can use date math in the index name to track the rollover date. For example, - you can create an alias that points to an index named ``. - If you create the index on May 6, 2099, the index's name is `my-index-2099.05.06-000001`. - If you roll over the alias on May 7, 2099, the new index's name is `my-index-2099.05.07-000002`. - - ``_ + .. raw:: html + +

Roll over to a new index. + TIP: It is recommended to use the index lifecycle rollover action to automate rollovers.

+

The rollover API creates a new index for a data stream or index alias. + The API behavior depends on the rollover target.

+

Roll over a data stream

+

If you roll over a data stream, the API creates a new write index for the stream. + The stream's previous write index becomes a regular backing index. + A rollover also increments the data stream's generation.

+

Roll over an index alias with a write index

+

TIP: Prior to Elasticsearch 7.9, you'd typically use an index alias with a write index to manage time series data. + Data streams replace this functionality, require less maintenance, and automatically integrate with data tiers.

+

If an index alias points to multiple indices, one of the indices must be a write index. + The rollover API creates a new write index for the alias with is_write_index set to true. + The API also sets is_write_index to false for the previous write index.

+

Roll over an index alias with one index

+

If you roll over an index alias that points to only one index, the API creates a new index for the alias and removes the original index from the alias.

+

NOTE: A rollover creates a new index and is subject to the wait_for_active_shards setting.

+

Increment index names for an alias

+

When you roll over an index alias, you can specify a name for the new index. + If you don't specify a name and the current index ends with - and a number, such as my-index-000001 or my-index-3, the new index name increments that number. + For example, if you roll over an alias with a current index of my-index-000001, the rollover creates a new index named my-index-000002. + This number is always six characters and zero-padded, regardless of the previous index's name.

+

If you use an index alias for time series data, you can use date math in the index name to track the rollover date. + For example, you can create an alias that points to an index named <my-index-{now/d}-000001>. + If you create the index on May 6, 2099, the index's name is my-index-2099.05.06-000001. + If you roll over the alias on May 7, 2099, the new index's name is my-index-2099.05.07-000002.

+ + + ``_ :param alias: Name of the data stream or index alias to roll over. :param new_index: Name of the index to create. Supports date math. Data streams @@ -2512,10 +2629,13 @@ def simulate_index_template( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Simulate an index. Get the index configuration that would be applied to the specified - index from an existing index template. + .. raw:: html - ``_ +

Simulate an index. + Get the index configuration that would be applied to the specified index from an existing index template.

+ + + ``_ :param name: Name of the index to simulate :param include_defaults: If true, returns all relevant default configurations @@ -2590,10 +2710,13 @@ def simulate_template( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Simulate an index template. Get the index configuration that would be applied - by a particular index template. + .. raw:: html + +

Simulate an index template. + Get the index configuration that would be applied by a particular index template.

- ``_ + + ``_ :param name: Name of the index template to simulate. To test a template configuration before you add it to the cluster, omit this parameter and specify the template @@ -2716,7 +2839,11 @@ def update_aliases( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Create or update an alias. Adds a data stream or index to an alias. + .. raw:: html + +

Create or update an alias. + Adds a data stream or index to an alias.

+ ``_ @@ -2791,7 +2918,11 @@ def validate_query( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Validate a query. Validates a query without running it. + .. raw:: html + +

Validate a query. + Validates a query without running it.

+ ``_ diff --git a/elasticsearch_serverless/_sync/client/inference.py b/elasticsearch_serverless/_sync/client/inference.py index 39e8617..5f455b9 100644 --- a/elasticsearch_serverless/_sync/client/inference.py +++ b/elasticsearch_serverless/_sync/client/inference.py @@ -44,16 +44,19 @@ def delete( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Delete an inference endpoint + .. raw:: html - ``_ +

Delete an inference endpoint

- :param inference_id: The inference Id + + ``_ + + :param inference_id: The inference identifier. :param task_type: The task type - :param dry_run: When true, the endpoint is not deleted, and a list of ingest - processors which reference this endpoint is returned + :param dry_run: When true, the endpoint is not deleted and a list of ingest processors + which reference this endpoint is returned. :param force: When true, the inference endpoint is forcefully deleted even if - it is still being used by ingest processors or semantic text fields + it is still being used by ingest processors or semantic text fields. """ if inference_id in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'inference_id'") @@ -109,9 +112,12 @@ def get( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Get an inference endpoint + .. raw:: html - ``_ +

Get an inference endpoint

+ + + ``_ :param task_type: The task type :param inference_id: The inference Id @@ -172,17 +178,31 @@ def inference( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Perform inference on the service + .. raw:: html - ``_ +

Perform inference on the service.

+

This API enables you to use machine learning models to perform specific tasks on data that you provide as an input. + It returns a response with the results of the tasks. + The inference endpoint you use can perform one specific task that has been defined when the endpoint was created with the create inference API.

+
+

info + The inference APIs enable you to use certain services, such as built-in machine learning models (ELSER, E5), models uploaded through Eland, Cohere, OpenAI, Azure, Google AI Studio, Google Vertex AI, Anthropic, Watsonx.ai, or Hugging Face. For built-in models and models uploaded through Eland, the inference APIs offer an alternative way to use and manage trained models. However, if you do not plan to use the inference APIs to use these models or if you want to use non-NLP models, use the machine learning trained model APIs.

+
- :param inference_id: The inference Id - :param input: Inference input. Either a string or an array of strings. - :param task_type: The task type - :param query: Query input, required for rerank task. Not required for other tasks. - :param task_settings: Optional task settings - :param timeout: Specifies the amount of time to wait for the inference request - to complete. + + ``_ + + :param inference_id: The unique identifier for the inference endpoint. + :param input: The text on which you want to perform the inference task. It can + be a single string or an array. > info > Inference endpoints for the `completion` + task type currently only support a single string as input. + :param task_type: The type of inference task that the model performs. + :param query: The query input, which is required only for the `rerank` task. + It is not required for other tasks. + :param task_settings: Task settings for the individual inference request. These + settings are specific to the task type you specified and override the task + settings specified when initializing the service. + :param timeout: The amount of time to wait for the inference request to complete. """ if inference_id in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'inference_id'") @@ -255,23 +275,20 @@ def put( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Create an inference endpoint. When you create an inference endpoint, the associated - machine learning model is automatically deployed if it is not already running. - After creating the endpoint, wait for the model deployment to complete before - using it. To verify the deployment status, use the get trained model statistics - API. Look for `"state": "fully_allocated"` in the response and ensure that the - `"allocation_count"` matches the `"target_allocation_count"`. Avoid creating - multiple endpoints for the same model unless required, as each endpoint consumes - significant resources. IMPORTANT: The inference APIs enable you to use certain - services, such as built-in machine learning models (ELSER, E5), models uploaded - through Eland, Cohere, OpenAI, Mistral, Azure OpenAI, Google AI Studio, Google - Vertex AI, Anthropic, Watsonx.ai, or Hugging Face. For built-in models and models - uploaded through Eland, the inference APIs offer an alternative way to use and - manage trained models. However, if you do not plan to use the inference APIs - to use these models or if you want to use non-NLP models, use the machine learning - trained model APIs. + .. raw:: html + +

Create an inference endpoint. + When you create an inference endpoint, the associated machine learning model is automatically deployed if it is not already running. + After creating the endpoint, wait for the model deployment to complete before using it. + To verify the deployment status, use the get trained model statistics API. + Look for "state": "fully_allocated" in the response and ensure that the "allocation_count" matches the "target_allocation_count". + Avoid creating multiple endpoints for the same model unless required, as each endpoint consumes significant resources.

+

IMPORTANT: The inference APIs enable you to use certain services, such as built-in machine learning models (ELSER, E5), models uploaded through Eland, Cohere, OpenAI, Mistral, Azure OpenAI, Google AI Studio, Google Vertex AI, Anthropic, Watsonx.ai, or Hugging Face. + For built-in models and models uploaded through Eland, the inference APIs offer an alternative way to use and manage trained models. + However, if you do not plan to use the inference APIs to use these models or if you want to use non-NLP models, use the machine learning trained model APIs.

+ - ``_ + ``_ :param inference_id: The inference Id :param inference_config: diff --git a/elasticsearch_serverless/_sync/client/ingest.py b/elasticsearch_serverless/_sync/client/ingest.py index 0eac9d5..79408e5 100644 --- a/elasticsearch_serverless/_sync/client/ingest.py +++ b/elasticsearch_serverless/_sync/client/ingest.py @@ -38,9 +38,13 @@ def delete_pipeline( timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, ) -> ObjectApiResponse[t.Any]: """ - Delete pipelines. Delete one or more ingest pipelines. + .. raw:: html - ``_ +

Delete pipelines. + Delete one or more ingest pipelines.

+ + + ``_ :param id: Pipeline ID or wildcard expression of pipeline IDs used to limit the request. To delete all ingest pipelines in a cluster, use a value of `*`. @@ -90,10 +94,14 @@ def get_pipeline( summary: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Get pipelines. Get information about one or more ingest pipelines. This API returns - a local reference of the pipeline. + .. raw:: html + +

Get pipelines.

+

Get information about one or more ingest pipelines. + This API returns a local reference of the pipeline.

- ``_ + + ``_ :param id: Comma-separated list of pipeline IDs to retrieve. Wildcard (`*`) expressions are supported. To get all ingest pipelines, omit this parameter or use `*`. @@ -142,10 +150,13 @@ def processor_grok( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Run a grok processor. Extract structured fields out of a single text field within - a document. You must choose which field to extract matched fields from, as well - as the grok pattern you expect will match. A grok pattern is like a regular expression - that supports aliased expressions that can be reused. + .. raw:: html + +

Run a grok processor. + Extract structured fields out of a single text field within a document. + You must choose which field to extract matched fields from, as well as the grok pattern you expect will match. + A grok pattern is like a regular expression that supports aliased expressions that can be reused.

+ ``_ """ @@ -201,7 +212,11 @@ def put_pipeline( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Create or update a pipeline. Changes made using this API take effect immediately. + .. raw:: html + +

Create or update a pipeline. + Changes made using this API take effect immediately.

+ ``_ @@ -293,16 +308,19 @@ def simulate( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Simulate a pipeline. Run an ingest pipeline against a set of provided documents. - You can either specify an existing pipeline to use with the provided documents - or supply a pipeline definition in the body of the request. + .. raw:: html + +

Simulate a pipeline.

+

Run an ingest pipeline against a set of provided documents. + You can either specify an existing pipeline to use with the provided documents or supply a pipeline definition in the body of the request.

+ - ``_ + ``_ :param docs: Sample documents to test in the pipeline. - :param id: Pipeline to test. If you don’t specify a `pipeline` in the request + :param id: The pipeline to test. If you don't specify a `pipeline` in the request body, this parameter is required. - :param pipeline: Pipeline to test. If you don’t specify the `pipeline` request + :param pipeline: The pipeline to test. If you don't specify the `pipeline` request path parameter, this parameter is required. If you specify both this and the request path parameter, the API only uses the request path parameter. :param verbose: If `true`, the response includes output data for each processor diff --git a/elasticsearch_serverless/_sync/client/license.py b/elasticsearch_serverless/_sync/client/license.py index 24e09fb..3a277cd 100644 --- a/elasticsearch_serverless/_sync/client/license.py +++ b/elasticsearch_serverless/_sync/client/license.py @@ -37,13 +37,18 @@ def get( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Get license information. Get information about your Elastic license including - its type, its status, when it was issued, and when it expires. NOTE: If the master - node is generating a new cluster state, the get license API may return a `404 - Not Found` response. If you receive an unexpected 404 response after cluster - startup, wait a short period and retry the request. + .. raw:: html - ``_ +

Get license information.

+

Get information about your Elastic license including its type, its status, when it was issued, and when it expires.

+
+

info + If the master node is generating a new cluster state, the get license API may return a 404 Not Found response. + If you receive an unexpected 404 response after cluster startup, wait a short period and retry the request.

+
+ + + ``_ :param accept_enterprise: If `true`, this parameter returns enterprise for Enterprise license types. If `false`, this parameter returns platinum for both platinum diff --git a/elasticsearch_serverless/_sync/client/logstash.py b/elasticsearch_serverless/_sync/client/logstash.py index b006c34..f8abefa 100644 --- a/elasticsearch_serverless/_sync/client/logstash.py +++ b/elasticsearch_serverless/_sync/client/logstash.py @@ -36,11 +36,14 @@ def delete_pipeline( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Delete a Logstash pipeline. Delete a pipeline that is used for Logstash Central - Management. If the request succeeds, you receive an empty response with an appropriate - status code. + .. raw:: html - ``_ +

Delete a Logstash pipeline. + Delete a pipeline that is used for Logstash Central Management. + If the request succeeds, you receive an empty response with an appropriate status code.

+ + + ``_ :param id: An identifier for the pipeline. """ @@ -78,9 +81,13 @@ def get_pipeline( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Get Logstash pipelines. Get pipelines that are used for Logstash Central Management. + .. raw:: html + +

Get Logstash pipelines. + Get pipelines that are used for Logstash Central Management.

- ``_ + + ``_ :param id: A comma-separated list of pipeline identifiers. """ @@ -125,10 +132,14 @@ def put_pipeline( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Create or update a Logstash pipeline. Create a pipeline that is used for Logstash - Central Management. If the specified pipeline exists, it is replaced. + .. raw:: html + +

Create or update a Logstash pipeline.

+

Create a pipeline that is used for Logstash Central Management. + If the specified pipeline exists, it is replaced.

+ - ``_ + ``_ :param id: An identifier for the pipeline. :param pipeline: diff --git a/elasticsearch_serverless/_sync/client/ml.py b/elasticsearch_serverless/_sync/client/ml.py index 6dfa9b4..6a15802 100644 --- a/elasticsearch_serverless/_sync/client/ml.py +++ b/elasticsearch_serverless/_sync/client/ml.py @@ -48,21 +48,16 @@ def close_job( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Close anomaly detection jobs. A job can be opened and closed multiple times throughout - its lifecycle. A closed job cannot receive data or perform analysis operations, - but you can still explore and navigate results. When you close a job, it runs - housekeeping tasks such as pruning the model history, flushing buffers, calculating - final results and persisting the model snapshots. Depending upon the size of - the job, it could take several minutes to close and the equivalent time to re-open. - After it is closed, the job has a minimal overhead on the cluster except for - maintaining its meta data. Therefore it is a best practice to close jobs that - are no longer required to process data. If you close an anomaly detection job - whose datafeed is running, the request first tries to stop the datafeed. This - behavior is equivalent to calling stop datafeed API with the same timeout and - force parameters as the close job request. When a datafeed that has a specified - end date stops, it automatically closes its associated job. - - ``_ + .. raw:: html + +

Close anomaly detection jobs.

+

A job can be opened and closed multiple times throughout its lifecycle. A closed job cannot receive data or perform analysis operations, but you can still explore and navigate results. + When you close a job, it runs housekeeping tasks such as pruning the model history, flushing buffers, calculating final results and persisting the model snapshots. Depending upon the size of the job, it could take several minutes to close and the equivalent time to re-open. After it is closed, the job has a minimal overhead on the cluster except for maintaining its meta data. Therefore it is a best practice to close jobs that are no longer required to process data. + If you close an anomaly detection job whose datafeed is running, the request first tries to stop the datafeed. This behavior is equivalent to calling stop datafeed API with the same timeout and force parameters as the close job request. + When a datafeed that has a specified end date stops, it automatically closes its associated job.

+ + + ``_ :param job_id: Identifier for the anomaly detection job. It can be a job identifier, a group name, or a wildcard expression. You can close multiple anomaly detection @@ -121,10 +116,13 @@ def delete_calendar( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Delete a calendar. Removes all scheduled events from a calendar, then deletes - it. + .. raw:: html + +

Delete a calendar.

+

Remove all scheduled events from a calendar, then delete it.

- ``_ + + ``_ :param calendar_id: A string that uniquely identifies a calendar. """ @@ -163,9 +161,12 @@ def delete_calendar_event( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Delete events from a calendar. + .. raw:: html + +

Delete events from a calendar.

- ``_ + + ``_ :param calendar_id: A string that uniquely identifies a calendar. :param event_id: Identifier for the scheduled event. You can obtain this identifier @@ -211,9 +212,12 @@ def delete_calendar_job( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Delete anomaly jobs from a calendar. + .. raw:: html + +

Delete anomaly jobs from a calendar.

- ``_ + + ``_ :param calendar_id: A string that uniquely identifies a calendar. :param job_id: An identifier for the anomaly detection jobs. It can be a job @@ -260,9 +264,12 @@ def delete_data_frame_analytics( timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, ) -> ObjectApiResponse[t.Any]: """ - Delete a data frame analytics job. + .. raw:: html + +

Delete a data frame analytics job.

- ``_ + + ``_ :param id: Identifier for the data frame analytics job. :param force: If `true`, it deletes a job that is not stopped; this method is @@ -308,9 +315,12 @@ def delete_datafeed( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Delete a datafeed. + .. raw:: html + +

Delete a datafeed.

- ``_ + + ``_ :param datafeed_id: A numerical character string that uniquely identifies the datafeed. This identifier can contain lowercase alphanumeric characters (a-z @@ -355,11 +365,14 @@ def delete_filter( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Delete a filter. If an anomaly detection job references the filter, you cannot - delete the filter. You must update or delete the job before you can delete the - filter. + .. raw:: html + +

Delete a filter.

+

If an anomaly detection job references the filter, you cannot delete the + filter. You must update or delete the job before you can delete the filter.

+ - ``_ + ``_ :param filter_id: A string that uniquely identifies a filter. """ @@ -400,14 +413,18 @@ def delete_job( wait_for_completion: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Delete an anomaly detection job. All job configuration, model state and results - are deleted. It is not currently possible to delete multiple jobs using wildcards - or a comma separated list. If you delete a job that has a datafeed, the request - first tries to delete the datafeed. This behavior is equivalent to calling the - delete datafeed API with the same timeout and force parameters as the delete - job request. + .. raw:: html - ``_ +

Delete an anomaly detection job.

+

All job configuration, model state and results are deleted. + It is not currently possible to delete multiple jobs using wildcards or a + comma separated list. If you delete a job that has a datafeed, the request + first tries to delete the datafeed. This behavior is equivalent to calling + the delete datafeed API with the same timeout and force parameters as the + delete job request.

+ + + ``_ :param job_id: Identifier for the anomaly detection job. :param delete_user_annotations: Specifies whether annotations that have been @@ -460,10 +477,13 @@ def delete_trained_model( timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, ) -> ObjectApiResponse[t.Any]: """ - Delete an unreferenced trained model. The request deletes a trained inference - model that is not referenced by an ingest pipeline. + .. raw:: html + +

Delete an unreferenced trained model.

+

The request deletes a trained inference model that is not referenced by an ingest pipeline.

+ - ``_ + ``_ :param model_id: The unique identifier of the trained model. :param force: Forcefully deletes a trained model that is referenced by ingest @@ -510,11 +530,15 @@ def delete_trained_model_alias( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Delete a trained model alias. This API deletes an existing model alias that refers - to a trained model. If the model alias is missing or refers to a model other - than the one identified by the `model_id`, this API returns an error. + .. raw:: html - ``_ +

Delete a trained model alias.

+

This API deletes an existing model alias that refers to a trained model. If + the model alias is missing or refers to a model other than the one identified + by the model_id, this API returns an error.

+ + + ``_ :param model_id: The trained model ID to which the model alias refers. :param model_alias: The model alias to delete. @@ -567,11 +591,15 @@ def estimate_model_memory( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Estimate job model memory usage. Makes an estimation of the memory usage for - an anomaly detection job model. It is based on analysis configuration details - for the job and cardinality estimates for the fields it references. + .. raw:: html + +

Estimate job model memory usage.

+

Make an estimation of the memory usage for an anomaly detection job model. + The estimate is based on analysis configuration details for the job and cardinality + estimates for the fields it references.

- ``_ + + ``_ :param analysis_config: For a list of the properties that you can specify in the `analysis_config` component of the body of this API. @@ -634,12 +662,16 @@ def evaluate_data_frame( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Evaluate data frame analytics. The API packages together commonly used evaluation - metrics for various types of machine learning features. This has been designed - for use on indexes created by data frame analytics. Evaluation requires both - a ground truth field and an analytics result field to be present. + .. raw:: html + +

Evaluate data frame analytics.

+

The API packages together commonly used evaluation metrics for various types + of machine learning features. This has been designed for use on indexes + created by data frame analytics. Evaluation requires both a ground truth + field and an analytics result field to be present.

- ``_ + + ``_ :param evaluation: Defines the type of evaluation you want to perform. :param index: Defines the `index` in which the evaluation will be performed. @@ -699,16 +731,20 @@ def flush_job( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Force buffered data to be processed. The flush jobs API is only applicable when - sending data for analysis using the post data API. Depending on the content of - the buffer, then it might additionally calculate new results. Both flush and - close operations are similar, however the flush is more efficient if you are - expecting to send more data for analysis. When flushing, the job remains open - and is available to continue analyzing data. A close operation additionally prunes - and persists the model state to disk and the job must be opened again before - analyzing further data. + .. raw:: html + +

Force buffered data to be processed. + The flush jobs API is only applicable when sending data for analysis using + the post data API. Depending on the content of the buffer, then it might + additionally calculate new results. Both flush and close operations are + similar, however the flush is more efficient if you are expecting to send + more data for analysis. When flushing, the job remains open and is available + to continue analyzing data. A close operation additionally prunes and + persists the model state to disk and the job must be opened again before + analyzing further data.

- ``_ + + ``_ :param job_id: Identifier for the anomaly detection job. :param advance_time: Refer to the description for the `advance_time` query parameter. @@ -775,9 +811,12 @@ def get_calendar_events( start: t.Optional[t.Union[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Get info about events in calendars. + .. raw:: html + +

Get info about events in calendars.

+ - ``_ + ``_ :param calendar_id: A string that uniquely identifies a calendar. You can get information for multiple calendars by using a comma-separated list of ids @@ -841,9 +880,12 @@ def get_calendars( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Get calendar configuration info. + .. raw:: html - ``_ +

Get calendar configuration info.

+ + + ``_ :param calendar_id: A string that uniquely identifies a calendar. You can get information for multiple calendars by using a comma-separated list of ids @@ -911,11 +953,15 @@ def get_data_frame_analytics( size: t.Optional[int] = None, ) -> ObjectApiResponse[t.Any]: """ - Get data frame analytics job configuration info. You can get information for - multiple data frame analytics jobs in a single API request by using a comma-separated - list of data frame analytics jobs or a wildcard expression. + .. raw:: html + +

Get data frame analytics job configuration info. + You can get information for multiple data frame analytics jobs in a single + API request by using a comma-separated list of data frame analytics jobs or a + wildcard expression.

+ - ``_ + ``_ :param id: Identifier for the data frame analytics job. If you do not specify this option, the API returns information for the first hundred data frame @@ -985,9 +1031,12 @@ def get_data_frame_analytics_stats( verbose: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Get data frame analytics jobs usage info. + .. raw:: html - ``_ +

Get data frame analytics jobs usage info.

+ + + ``_ :param id: Identifier for the data frame analytics job. If you do not specify this option, the API returns information for the first hundred data frame @@ -1050,14 +1099,18 @@ def get_datafeed_stats( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Get datafeeds usage info. You can get statistics for multiple datafeeds in a - single API request by using a comma-separated list of datafeeds or a wildcard - expression. You can get statistics for all datafeeds by using `_all`, by specifying - `*` as the ``, or by omitting the ``. If the datafeed is stopped, - the only information you receive is the `datafeed_id` and the `state`. This API - returns a maximum of 10,000 datafeeds. + .. raw:: html + +

Get datafeeds usage info. + You can get statistics for multiple datafeeds in a single API request by + using a comma-separated list of datafeeds or a wildcard expression. You can + get statistics for all datafeeds by using _all, by specifying * as the + <feed_id>, or by omitting the <feed_id>. If the datafeed is stopped, the + only information you receive is the datafeed_id and the state. + This API returns a maximum of 10,000 datafeeds.

- ``_ + + ``_ :param datafeed_id: Identifier for the datafeed. It can be a datafeed identifier or a wildcard expression. If you do not specify one of these options, the @@ -1111,13 +1164,17 @@ def get_datafeeds( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Get datafeeds configuration info. You can get information for multiple datafeeds - in a single API request by using a comma-separated list of datafeeds or a wildcard - expression. You can get information for all datafeeds by using `_all`, by specifying - `*` as the ``, or by omitting the ``. This API returns a maximum - of 10,000 datafeeds. + .. raw:: html + +

Get datafeeds configuration info. + You can get information for multiple datafeeds in a single API request by + using a comma-separated list of datafeeds or a wildcard expression. You can + get information for all datafeeds by using _all, by specifying * as the + <feed_id>, or by omitting the <feed_id>. + This API returns a maximum of 10,000 datafeeds.

- ``_ + + ``_ :param datafeed_id: Identifier for the datafeed. It can be a datafeed identifier or a wildcard expression. If you do not specify one of these options, the @@ -1178,9 +1235,13 @@ def get_filters( size: t.Optional[int] = None, ) -> ObjectApiResponse[t.Any]: """ - Get filters. You can get a single filter or all filters. + .. raw:: html + +

Get filters. + You can get a single filter or all filters.

- ``_ + + ``_ :param filter_id: A string that uniquely identifies a filter. :param from_: Skips the specified number of filters. @@ -1228,9 +1289,12 @@ def get_job_stats( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Get anomaly detection jobs usage info. + .. raw:: html + +

Get anomaly detection jobs usage info.

+ - ``_ + ``_ :param job_id: Identifier for the anomaly detection job. It can be a job identifier, a group name, a comma-separated list of jobs, or a wildcard expression. If @@ -1285,13 +1349,16 @@ def get_jobs( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Get anomaly detection jobs configuration info. You can get information for multiple - anomaly detection jobs in a single API request by using a group name, a comma-separated - list of jobs, or a wildcard expression. You can get information for all anomaly - detection jobs by using `_all`, by specifying `*` as the ``, or by omitting - the ``. + .. raw:: html - ``_ +

Get anomaly detection jobs configuration info. + You can get information for multiple anomaly detection jobs in a single API + request by using a group name, a comma-separated list of jobs, or a wildcard + expression. You can get information for all anomaly detection jobs by using + _all, by specifying * as the <job_id>, or by omitting the <job_id>.

+ + + ``_ :param job_id: Identifier for the anomaly detection job. It can be a job identifier, a group name, or a wildcard expression. If you do not specify one of these @@ -1366,21 +1433,28 @@ def get_overall_buckets( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Get overall bucket results. Retrievs overall bucket results that summarize the - bucket results of multiple anomaly detection jobs. The `overall_score` is calculated - by combining the scores of all the buckets within the overall bucket span. First, - the maximum `anomaly_score` per anomaly detection job in the overall bucket is - calculated. Then the `top_n` of those scores are averaged to result in the `overall_score`. - This means that you can fine-tune the `overall_score` so that it is more or less - sensitive to the number of jobs that detect an anomaly at the same time. For - example, if you set `top_n` to `1`, the `overall_score` is the maximum bucket - score in the overall bucket. Alternatively, if you set `top_n` to the number - of jobs, the `overall_score` is high only when all jobs detect anomalies in that - overall bucket. If you set the `bucket_span` parameter (to a value greater than - its default), the `overall_score` is the maximum `overall_score` of the overall - buckets that have a span equal to the jobs' largest bucket span. - - ``_ + .. raw:: html + +

Get overall bucket results.

+

Retrievs overall bucket results that summarize the bucket results of + multiple anomaly detection jobs.

+

The overall_score is calculated by combining the scores of all the + buckets within the overall bucket span. First, the maximum + anomaly_score per anomaly detection job in the overall bucket is + calculated. Then the top_n of those scores are averaged to result in + the overall_score. This means that you can fine-tune the + overall_score so that it is more or less sensitive to the number of + jobs that detect an anomaly at the same time. For example, if you set + top_n to 1, the overall_score is the maximum bucket score in the + overall bucket. Alternatively, if you set top_n to the number of jobs, + the overall_score is high only when all jobs detect anomalies in that + overall bucket. If you set the bucket_span parameter (to a value + greater than its default), the overall_score is the maximum + overall_score of the overall buckets that have a span equal to the + jobs' largest bucket span.

+ + + ``_ :param job_id: Identifier for the anomaly detection job. It can be a job identifier, a group name, a comma-separated list of jobs or groups, or a wildcard expression. @@ -1475,9 +1549,12 @@ def get_trained_models( tags: t.Optional[t.Union[str, t.Sequence[str]]] = None, ) -> ObjectApiResponse[t.Any]: """ - Get trained model configuration info. + .. raw:: html + +

Get trained model configuration info.

+ - ``_ + ``_ :param model_id: The unique identifier of the trained model or a model alias. You can get information for multiple trained models in a single API request @@ -1561,11 +1638,14 @@ def get_trained_models_stats( size: t.Optional[int] = None, ) -> ObjectApiResponse[t.Any]: """ - Get trained models usage info. You can get usage information for multiple trained - models in a single API request by using a comma-separated list of model IDs or - a wildcard expression. + .. raw:: html - ``_ +

Get trained models usage info. + You can get usage information for multiple trained + models in a single API request by using a comma-separated list of model IDs or a wildcard expression.

+ + + ``_ :param model_id: The unique identifier of the trained model or a model alias. It can be a comma-separated list or a wildcard expression. @@ -1626,9 +1706,12 @@ def infer_trained_model( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Evaluate a trained model. + .. raw:: html + +

Evaluate a trained model.

- ``_ + + ``_ :param model_id: The unique identifier of the trained model. :param docs: An array of objects to pass to the model for inference. The objects @@ -1688,14 +1771,18 @@ def open_job( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Open anomaly detection jobs. An anomaly detection job must be opened to be ready - to receive and analyze data. It can be opened and closed multiple times throughout - its lifecycle. When you open a new job, it starts with an empty model. When you - open an existing job, the most recent model state is automatically loaded. The - job is ready to resume its analysis from where it left off, once new data is - received. + .. raw:: html + +

Open anomaly detection jobs.

+

An anomaly detection job must be opened to be ready to receive and analyze + data. It can be opened and closed multiple times throughout its lifecycle. + When you open a new job, it starts with an empty model. + When you open an existing job, the most recent model state is automatically + loaded. The job is ready to resume its analysis from where it left off, once + new data is received.

- ``_ + + ``_ :param job_id: Identifier for the anomaly detection job. :param timeout: Refer to the description for the `timeout` query parameter. @@ -1747,9 +1834,12 @@ def post_calendar_events( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Add scheduled events to the calendar. + .. raw:: html + +

Add scheduled events to the calendar.

- ``_ + + ``_ :param calendar_id: A string that uniquely identifies a calendar. :param events: A list of one of more scheduled events. The event’s start and @@ -1801,10 +1891,13 @@ def preview_data_frame_analytics( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Preview features used by data frame analytics. Previews the extracted features - used by a data frame analytics config. + .. raw:: html + +

Preview features used by data frame analytics. + Preview the extracted features used by a data frame analytics config.

+ - ``_ + ``_ :param id: Identifier for the data frame analytics job. :param config: A data frame analytics config as described in create data frame @@ -1864,17 +1957,20 @@ def preview_datafeed( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Preview a datafeed. This API returns the first "page" of search results from - a datafeed. You can preview an existing datafeed or provide configuration details - for a datafeed and anomaly detection job in the API. The preview shows the structure - of the data that will be passed to the anomaly detection engine. IMPORTANT: When - Elasticsearch security features are enabled, the preview uses the credentials - of the user that called the API. However, when the datafeed starts it uses the - roles of the last user that created or updated the datafeed. To get a preview - that accurately reflects the behavior of the datafeed, use the appropriate credentials. - You can also use secondary authorization headers to supply the credentials. + .. raw:: html - ``_ +

Preview a datafeed. + This API returns the first "page" of search results from a datafeed. + You can preview an existing datafeed or provide configuration details for a datafeed + and anomaly detection job in the API. The preview shows the structure of the data + that will be passed to the anomaly detection engine. + IMPORTANT: When Elasticsearch security features are enabled, the preview uses the credentials of the user that + called the API. However, when the datafeed starts it uses the roles of the last user that created or updated the + datafeed. To get a preview that accurately reflects the behavior of the datafeed, use the appropriate credentials. + You can also use secondary authorization headers to supply the credentials.

+ + + ``_ :param datafeed_id: A numerical character string that uniquely identifies the datafeed. This identifier can contain lowercase alphanumeric characters (a-z @@ -1948,9 +2044,12 @@ def put_calendar( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Create a calendar. + .. raw:: html + +

Create a calendar.

+ - ``_ + ``_ :param calendar_id: A string that uniquely identifies a calendar. :param description: A description of the calendar. @@ -2002,9 +2101,12 @@ def put_calendar_job( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Add anomaly detection job to calendar. + .. raw:: html - ``_ +

Add anomaly detection job to calendar.

+ + + ``_ :param calendar_id: A string that uniquely identifies a calendar. :param job_id: An identifier for the anomaly detection jobs. It can be a job @@ -2077,15 +2179,17 @@ def put_data_frame_analytics( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Create a data frame analytics job. This API creates a data frame analytics job - that performs an analysis on the source indices and stores the outcome in a destination - index. By default, the query used in the source configuration is `{"match_all": - {}}`. If the destination index does not exist, it is created automatically when - you start the job. If you supply only a subset of the regression or classification - parameters, hyperparameter optimization occurs. It determines a value for each - of the undefined parameters. + .. raw:: html + +

Create a data frame analytics job. + This API creates a data frame analytics job that performs an analysis on the + source indices and stores the outcome in a destination index. + By default, the query used in the source configuration is {"match_all": {}}.

+

If the destination index does not exist, it is created automatically when you start the job.

+

If you supply only a subset of the regression or classification parameters, hyperparameter optimization occurs. It determines a value for each of the undefined parameters.

- ``_ + + ``_ :param id: Identifier for the data frame analytics job. This identifier can contain lowercase alphanumeric characters (a-z and 0-9), hyphens, and underscores. @@ -2256,20 +2360,21 @@ def put_datafeed( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Create a datafeed. Datafeeds retrieve data from Elasticsearch for analysis by - an anomaly detection job. You can associate only one datafeed with each anomaly - detection job. The datafeed contains a query that runs at a defined interval - (`frequency`). If you are concerned about delayed data, you can add a delay (`query_delay') - at each interval. By default, the datafeed uses the following query: `{"match_all": - {"boost": 1}}`. When Elasticsearch security features are enabled, your datafeed - remembers which roles the user who created it had at the time of creation and - runs the query using those same roles. If you provide secondary authorization - headers, those credentials are used instead. You must use Kibana, this API, or - the create anomaly detection jobs API to create a datafeed. Do not add a datafeed - directly to the `.ml-config` index. Do not give users `write` privileges on the - `.ml-config` index. - - ``_ + .. raw:: html + +

Create a datafeed. + Datafeeds retrieve data from Elasticsearch for analysis by an anomaly detection job. + You can associate only one datafeed with each anomaly detection job. + The datafeed contains a query that runs at a defined interval (frequency). + If you are concerned about delayed data, you can add a delay (query_delay') at each interval. By default, the datafeed uses the following query: {"match_all": {"boost": 1}}`.

+

When Elasticsearch security features are enabled, your datafeed remembers which roles the user who created it had + at the time of creation and runs the query using those same roles. If you provide secondary authorization headers, + those credentials are used instead. + You must use Kibana, this API, or the create anomaly detection jobs API to create a datafeed. Do not add a datafeed + directly to the .ml-config index. Do not give users write privileges on the .ml-config index.

+ + + ``_ :param datafeed_id: A numerical character string that uniquely identifies the datafeed. This identifier can contain lowercase alphanumeric characters (a-z @@ -2424,11 +2529,14 @@ def put_filter( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Create a filter. A filter contains a list of strings. It can be used by one or - more anomaly detection jobs. Specifically, filters are referenced in the `custom_rules` - property of detector configuration objects. + .. raw:: html - ``_ +

Create a filter. + A filter contains a list of strings. It can be used by one or more anomaly detection jobs. + Specifically, filters are referenced in the custom_rules property of detector configuration objects.

+ + + ``_ :param filter_id: A string that uniquely identifies a filter. :param description: A description of the filter. @@ -2523,11 +2631,14 @@ def put_job( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Create an anomaly detection job. If you include a `datafeed_config`, you must - have read index privileges on the source index. If you include a `datafeed_config` - but do not provide a query, the datafeed uses `{"match_all": {"boost": 1}}`. + .. raw:: html + +

Create an anomaly detection job.

+

If you include a datafeed_config, you must have read index privileges on the source index. + If you include a datafeed_config but do not provide a query, the datafeed uses {"match_all": {"boost": 1}}.

- ``_ + + ``_ :param job_id: The identifier for the anomaly detection job. This identifier can contain lowercase alphanumeric characters (a-z and 0-9), hyphens, and @@ -2729,10 +2840,13 @@ def put_trained_model( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Create a trained model. Enable you to supply a trained model that is not created - by data frame analytics. + .. raw:: html + +

Create a trained model. + Enable you to supply a trained model that is not created by data frame analytics.

- ``_ + + ``_ :param model_id: The unique identifier of the trained model. :param compressed_definition: The compressed (GZipped and Base64 encoded) inference @@ -2832,21 +2946,28 @@ def put_trained_model_alias( reassign: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Create or update a trained model alias. A trained model alias is a logical name - used to reference a single trained model. You can use aliases instead of trained - model identifiers to make it easier to reference your models. For example, you - can use aliases in inference aggregations and processors. An alias must be unique - and refer to only a single trained model. However, you can have multiple aliases - for each trained model. If you use this API to update an alias such that it references - a different trained model ID and the model uses a different type of data frame - analytics, an error occurs. For example, this situation occurs if you have a - trained model for regression analysis and a trained model for classification - analysis; you cannot reassign an alias from one type of trained model to another. - If you use this API to update an alias and there are very few input fields in - common between the old and new trained models for the model alias, the API returns - a warning. - - ``_ + .. raw:: html + +

Create or update a trained model alias. + A trained model alias is a logical name used to reference a single trained + model. + You can use aliases instead of trained model identifiers to make it easier to + reference your models. For example, you can use aliases in inference + aggregations and processors. + An alias must be unique and refer to only a single trained model. However, + you can have multiple aliases for each trained model. + If you use this API to update an alias such that it references a different + trained model ID and the model uses a different type of data frame analytics, + an error occurs. For example, this situation occurs if you have a trained + model for regression analysis and a trained model for classification + analysis; you cannot reassign an alias from one type of trained model to + another. + If you use this API to update an alias and there are very few input fields in + common between the old and new trained models for the model alias, the API + returns a warning.

+ + + ``_ :param model_id: The identifier for the trained model that the alias refers to. :param model_alias: The alias to create or update. This value cannot end in numbers. @@ -2902,9 +3023,12 @@ def put_trained_model_definition_part( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Create part of a trained model definition. + .. raw:: html + +

Create part of a trained model definition.

- ``_ + + ``_ :param model_id: The unique identifier of the trained model. :param part: The definition part number. When the definition is loaded for inference @@ -2979,11 +3103,14 @@ def put_trained_model_vocabulary( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Create a trained model vocabulary. This API is supported only for natural language - processing (NLP) models. The vocabulary is stored in the index as described in - `inference_config.*.vocabulary` of the trained model definition. + .. raw:: html + +

Create a trained model vocabulary. + This API is supported only for natural language processing (NLP) models. + The vocabulary is stored in the index as described in inference_config.*.vocabulary of the trained model definition.

+ - ``_ + ``_ :param model_id: The unique identifier of the trained model. :param vocabulary: The model vocabulary, which must not be empty. @@ -3037,11 +3164,16 @@ def reset_job( wait_for_completion: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Reset an anomaly detection job. All model state and results are deleted. The - job is ready to start over as if it had just been created. It is not currently - possible to reset multiple jobs using wildcards or a comma separated list. + .. raw:: html - ``_ +

Reset an anomaly detection job. + All model state and results are deleted. The job is ready to start over as if + it had just been created. + It is not currently possible to reset multiple jobs using wildcards or a + comma separated list.

+ + + ``_ :param job_id: The ID of the job to reset. :param delete_user_annotations: Specifies whether annotations that have been @@ -3089,18 +3221,23 @@ def start_data_frame_analytics( timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, ) -> ObjectApiResponse[t.Any]: """ - Start a data frame analytics job. A data frame analytics job can be started and - stopped multiple times throughout its lifecycle. If the destination index does - not exist, it is created automatically the first time you start the data frame - analytics job. The `index.number_of_shards` and `index.number_of_replicas` settings - for the destination index are copied from the source index. If there are multiple - source indices, the destination index copies the highest setting values. The - mappings for the destination index are also copied from the source indices. If - there are any mapping conflicts, the job fails to start. If the destination index - exists, it is used as is. You can therefore set up the destination index in advance - with custom settings and mappings. + .. raw:: html + +

Start a data frame analytics job. + A data frame analytics job can be started and stopped multiple times + throughout its lifecycle. + If the destination index does not exist, it is created automatically the + first time you start the data frame analytics job. The + index.number_of_shards and index.number_of_replicas settings for the + destination index are copied from the source index. If there are multiple + source indices, the destination index copies the highest setting values. The + mappings for the destination index are also copied from the source indices. + If there are any mapping conflicts, the job fails to start. + If the destination index exists, it is used as is. You can therefore set up + the destination index in advance with custom settings and mappings.

+ - ``_ + ``_ :param id: Identifier for the data frame analytics job. This identifier can contain lowercase alphanumeric characters (a-z and 0-9), hyphens, and underscores. @@ -3150,19 +3287,20 @@ def start_datafeed( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Start datafeeds. A datafeed must be started in order to retrieve data from Elasticsearch. - A datafeed can be started and stopped multiple times throughout its lifecycle. - Before you can start a datafeed, the anomaly detection job must be open. Otherwise, - an error occurs. If you restart a stopped datafeed, it continues processing input - data from the next millisecond after it was stopped. If new data was indexed - for that exact millisecond between stopping and starting, it will be ignored. - When Elasticsearch security features are enabled, your datafeed remembers which - roles the last user to create or update it had at the time of creation or update - and runs the query using those same roles. If you provided secondary authorization - headers when you created or updated the datafeed, those credentials are used - instead. + .. raw:: html - ``_ +

Start datafeeds.

+

A datafeed must be started in order to retrieve data from Elasticsearch. A datafeed can be started and stopped + multiple times throughout its lifecycle.

+

Before you can start a datafeed, the anomaly detection job must be open. Otherwise, an error occurs.

+

If you restart a stopped datafeed, it continues processing input data from the next millisecond after it was stopped. + If new data was indexed for that exact millisecond between stopping and starting, it will be ignored.

+

When Elasticsearch security features are enabled, your datafeed remembers which roles the last user to create or + update it had at the time of creation or update and runs the query using those same roles. If you provided secondary + authorization headers when you created or updated the datafeed, those credentials are used instead.

+ + + ``_ :param datafeed_id: A numerical character string that uniquely identifies the datafeed. This identifier can contain lowercase alphanumeric characters (a-z @@ -3208,11 +3346,14 @@ def start_datafeed( path_parts=__path_parts, ) - @_rewrite_parameters() + @_rewrite_parameters( + body_fields=("adaptive_allocations",), + ) def start_trained_model_deployment( self, *, model_id: str, + adaptive_allocations: t.Optional[t.Mapping[str, t.Any]] = None, cache_size: t.Optional[t.Union[int, str]] = None, deployment_id: t.Optional[str] = None, error_trace: t.Optional[bool] = None, @@ -3227,15 +3368,22 @@ def start_trained_model_deployment( wait_for: t.Optional[ t.Union[str, t.Literal["fully_allocated", "started", "starting"]] ] = None, + body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Start a trained model deployment. It allocates the model to every machine learning - node. + .. raw:: html + +

Start a trained model deployment. + It allocates the model to every machine learning node.

- ``_ + + ``_ :param model_id: The unique identifier of the trained model. Currently, only PyTorch models are supported. + :param adaptive_allocations: Adaptive allocations configuration. When enabled, + the number of allocations is set based on the current load. If adaptive_allocations + is enabled, do not set the number of allocations manually. :param cache_size: The inference cache size (in memory outside the JVM heap) per node for the model. The default value is the same size as the `model_size_bytes`. To disable the cache, `0b` can be provided. @@ -3245,7 +3393,8 @@ def start_trained_model_deployment( model in memory but use a separate set of threads to evaluate the model. Increasing this value generally increases the throughput. If this setting is greater than the number of hardware threads it will automatically be changed - to a value less than the number of hardware threads. + to a value less than the number of hardware threads. If adaptive_allocations + is enabled, do not set this value, because it’s automatically set. :param priority: The deployment priority. :param queue_capacity: Specifies the number of inference requests that are allowed in the queue. After the number of requests exceeds this value, new requests @@ -3265,6 +3414,7 @@ def start_trained_model_deployment( __path_parts: t.Dict[str, str] = {"model_id": _quote(model_id)} __path = f'/_ml/trained_models/{__path_parts["model_id"]}/deployment/_start' __query: t.Dict[str, t.Any] = {} + __body: t.Dict[str, t.Any] = body if body is not None else {} if cache_size is not None: __query["cache_size"] = cache_size if deployment_id is not None: @@ -3289,12 +3439,20 @@ def start_trained_model_deployment( __query["timeout"] = timeout if wait_for is not None: __query["wait_for"] = wait_for + if not __body: + if adaptive_allocations is not None: + __body["adaptive_allocations"] = adaptive_allocations + if not __body: + __body = None # type: ignore[assignment] __headers = {"accept": "application/json"} + if __body is not None: + __headers["content-type"] = "application/json" return self.perform_request( # type: ignore[return-value] "POST", __path, params=__query, headers=__headers, + body=__body, endpoint_id="ml.start_trained_model_deployment", path_parts=__path_parts, ) @@ -3313,10 +3471,14 @@ def stop_data_frame_analytics( timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, ) -> ObjectApiResponse[t.Any]: """ - Stop data frame analytics jobs. A data frame analytics job can be started and - stopped multiple times throughout its lifecycle. + .. raw:: html + +

Stop data frame analytics jobs. + A data frame analytics job can be started and stopped multiple times + throughout its lifecycle.

+ - ``_ + ``_ :param id: Identifier for the data frame analytics job. This identifier can contain lowercase alphanumeric characters (a-z and 0-9), hyphens, and underscores. @@ -3379,10 +3541,14 @@ def stop_datafeed( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Stop datafeeds. A datafeed that is stopped ceases to retrieve data from Elasticsearch. - A datafeed can be started and stopped multiple times throughout its lifecycle. + .. raw:: html - ``_ +

Stop datafeeds. + A datafeed that is stopped ceases to retrieve data from Elasticsearch. A datafeed can be started and stopped + multiple times throughout its lifecycle.

+ + + ``_ :param datafeed_id: Identifier for the datafeed. You can stop multiple datafeeds in a single API request by using a comma-separated list of datafeeds or a @@ -3442,9 +3608,12 @@ def stop_trained_model_deployment( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Stop a trained model deployment. + .. raw:: html + +

Stop a trained model deployment.

+ - ``_ + ``_ :param model_id: The unique identifier of the trained model. :param allow_no_match: Specifies what to do when the request: contains wildcard @@ -3507,9 +3676,12 @@ def update_data_frame_analytics( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Update a data frame analytics job. + .. raw:: html - ``_ +

Update a data frame analytics job.

+ + + ``_ :param id: Identifier for the data frame analytics job. This identifier can contain lowercase alphanumeric characters (a-z and 0-9), hyphens, and underscores. @@ -3615,13 +3787,16 @@ def update_datafeed( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Update a datafeed. You must stop and start the datafeed for the changes to be - applied. When Elasticsearch security features are enabled, your datafeed remembers - which roles the user who updated it had at the time of the update and runs the - query using those same roles. If you provide secondary authorization headers, - those credentials are used instead. + .. raw:: html + +

Update a datafeed. + You must stop and start the datafeed for the changes to be applied. + When Elasticsearch security features are enabled, your datafeed remembers which roles the user who updated it had at + the time of the update and runs the query using those same roles. If you provide secondary authorization headers, + those credentials are used instead.

- ``_ + + ``_ :param datafeed_id: A numerical character string that uniquely identifies the datafeed. This identifier can contain lowercase alphanumeric characters (a-z @@ -3782,10 +3957,13 @@ def update_filter( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Update a filter. Updates the description of a filter, adds items, or removes - items from the list. + .. raw:: html + +

Update a filter. + Updates the description of a filter, adds items, or removes items from the list.

- ``_ + + ``_ :param filter_id: A string that uniquely identifies a filter. :param add_items: The items to add to the filter. @@ -3873,10 +4051,13 @@ def update_job( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Update an anomaly detection job. Updates certain properties of an anomaly detection - job. + .. raw:: html + +

Update an anomaly detection job. + Updates certain properties of an anomaly detection job.

- ``_ + + ``_ :param job_id: Identifier for the job. :param allow_lazy_open: Advanced configuration option. Specifies whether this @@ -3986,13 +4167,14 @@ def update_job( ) @_rewrite_parameters( - body_fields=("number_of_allocations",), + body_fields=("adaptive_allocations", "number_of_allocations"), ) @_stability_warning(Stability.BETA) def update_trained_model_deployment( self, *, model_id: str, + adaptive_allocations: t.Optional[t.Mapping[str, t.Any]] = None, error_trace: t.Optional[bool] = None, filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, human: t.Optional[bool] = None, @@ -4001,18 +4183,25 @@ def update_trained_model_deployment( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Update a trained model deployment. + .. raw:: html + +

Update a trained model deployment.

+ - ``_ + ``_ :param model_id: The unique identifier of the trained model. Currently, only PyTorch models are supported. + :param adaptive_allocations: Adaptive allocations configuration. When enabled, + the number of allocations is set based on the current load. If adaptive_allocations + is enabled, do not set the number of allocations manually. :param number_of_allocations: The number of model allocations on each node where the model is deployed. All allocations on a node share the same copy of the model in memory but use a separate set of threads to evaluate the model. Increasing this value generally increases the throughput. If this setting is greater than the number of hardware threads it will automatically be changed - to a value less than the number of hardware threads. + to a value less than the number of hardware threads. If adaptive_allocations + is enabled, do not set this value, because it’s automatically set. """ if model_id in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'model_id'") @@ -4029,6 +4218,8 @@ def update_trained_model_deployment( if pretty is not None: __query["pretty"] = pretty if not __body: + if adaptive_allocations is not None: + __body["adaptive_allocations"] = adaptive_allocations if number_of_allocations is not None: __body["number_of_allocations"] = number_of_allocations if not __body: diff --git a/elasticsearch_serverless/_sync/client/query_rules.py b/elasticsearch_serverless/_sync/client/query_rules.py index fa1e742..6f402e8 100644 --- a/elasticsearch_serverless/_sync/client/query_rules.py +++ b/elasticsearch_serverless/_sync/client/query_rules.py @@ -38,11 +38,14 @@ def delete_rule( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - 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. + .. raw:: html - ``_ +

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.

+ + + ``_ :param ruleset_id: The unique identifier of the query ruleset containing the rule to delete @@ -88,10 +91,14 @@ def delete_ruleset( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Delete a query ruleset. Remove a query ruleset and its associated data. This - is a destructive action that is not recoverable. + .. raw:: html + +

Delete a query ruleset. + Remove a query ruleset and its associated data. + This is a destructive action that is not recoverable.

+ - ``_ + ``_ :param ruleset_id: The unique identifier of the query ruleset to delete """ @@ -130,9 +137,13 @@ def get_rule( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Get a query rule. Get details about a query rule within a query ruleset. + .. raw:: html - ``_ +

Get a query rule. + Get details about a query rule within a query ruleset.

+ + + ``_ :param ruleset_id: The unique identifier of the query ruleset containing the rule to retrieve @@ -178,9 +189,13 @@ def get_ruleset( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Get a query ruleset. Get details about a query ruleset. + .. raw:: html + +

Get a query ruleset. + Get details about a query ruleset.

+ - ``_ + ``_ :param ruleset_id: The unique identifier of the query ruleset """ @@ -221,9 +236,13 @@ def list_rulesets( size: t.Optional[int] = None, ) -> ObjectApiResponse[t.Any]: """ - Get all query rulesets. Get summarized information about the query rulesets. + .. raw:: html - ``_ +

Get all query rulesets. + Get summarized information about the query rulesets.

+ + + ``_ :param from_: The offset from the first result to fetch. :param size: The maximum number of results to retrieve. @@ -274,15 +293,17 @@ def put_rule( 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. - 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. + .. raw:: html + +

Create or update a query rule. + Create or update a query rule within a query ruleset.

+

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.

+ - ``_ + ``_ :param ruleset_id: The unique identifier of the query ruleset containing the rule to be created or updated. @@ -358,16 +379,18 @@ def put_ruleset( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Create or update a query ruleset. There is a limit of 100 rules per ruleset. - This limit can be increased by using the `xpack.applications.rules.max_rules_per_ruleset` - cluster setting. IMPORTANT: Due to limitations within pinned queries, you can - only select 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. + .. raw:: html - ``_ +

Create or update a query ruleset. + There is a limit of 100 rules per ruleset. + This limit can be increased by using the xpack.applications.rules.max_rules_per_ruleset cluster setting.

+

IMPORTANT: Due to limitations within pinned queries, you can only select 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.

+ + + ``_ :param ruleset_id: The unique identifier of the query ruleset to be created or updated. @@ -418,10 +441,13 @@ def test( 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 + +

Test a query ruleset. + Evaluate match criteria against a query ruleset to identify the rules that would match that criteria.

+ - ``_ + ``_ :param ruleset_id: The unique identifier of the query ruleset to be created or updated diff --git a/elasticsearch_serverless/_sync/client/search_application.py b/elasticsearch_serverless/_sync/client/search_application.py index 62c2eee..8db6d81 100644 --- a/elasticsearch_serverless/_sync/client/search_application.py +++ b/elasticsearch_serverless/_sync/client/search_application.py @@ -43,12 +43,15 @@ def delete( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Delete a search application. Remove a search application and its associated alias. - Indices attached to the search application are not removed. + .. raw:: html - ``_ +

Delete a search application.

+

Remove a search application and its associated alias. Indices attached to the search application are not removed.

- :param name: The name of the search application to delete + + ``_ + + :param name: The name of the search application to delete. """ if name in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'name'") @@ -85,10 +88,13 @@ def delete_behavioral_analytics( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Delete a behavioral analytics collection. The associated data stream is also - deleted. + .. raw:: html + +

Delete a behavioral analytics collection. + The associated data stream is also deleted.

+ - ``_ + ``_ :param name: The name of the analytics collection to be deleted """ @@ -127,9 +133,12 @@ def get( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Get search application details. + .. raw:: html - ``_ +

Get search application details.

+ + + ``_ :param name: The name of the search application """ @@ -168,9 +177,12 @@ def get_behavioral_analytics( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Get behavioral analytics collections. + .. raw:: html + +

Get behavioral analytics collections.

+ - ``_ + ``_ :param name: A list of analytics collections to limit the returned information """ @@ -216,9 +228,13 @@ def list( size: t.Optional[int] = None, ) -> ObjectApiResponse[t.Any]: """ - Get search applications. Get information about search applications. + .. raw:: html - ``_ +

Get search applications. + Get information about search applications.

+ + + ``_ :param from_: Starting offset. :param q: Query in the Lucene query string syntax. @@ -268,9 +284,12 @@ def put( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Create or update a search application. + .. raw:: html + +

Create or update a search application.

+ - ``_ + ``_ :param name: The name of the search application to be created or updated. :param search_application: @@ -322,9 +341,12 @@ def put_behavioral_analytics( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Create a behavioral analytics collection. + .. raw:: html - ``_ +

Create a behavioral analytics collection.

+ + + ``_ :param name: The name of the analytics collection to be created or updated. """ @@ -369,12 +391,14 @@ def search( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Run a search application search. Generate and run an Elasticsearch query that - uses the specified query parameteter and the search template associated with - the search application or default template. Unspecified template parameters are - assigned their default values if applicable. + .. raw:: html + +

Run a search application search. + Generate and run an Elasticsearch query that uses the specified query parameteter and the search template associated with the search application or default template. + Unspecified template parameters are assigned their default values if applicable.

+ - ``_ + ``_ :param name: The name of the search application to be searched. :param params: Query parameters specific to this request, which will override diff --git a/elasticsearch_serverless/_sync/client/security.py b/elasticsearch_serverless/_sync/client/security.py index 0050d31..908b8fb 100644 --- a/elasticsearch_serverless/_sync/client/security.py +++ b/elasticsearch_serverless/_sync/client/security.py @@ -35,14 +35,16 @@ def authenticate( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Authenticate a user. Authenticates a user and returns information about the authenticated - user. Include the user information in a [basic auth header](https://en.wikipedia.org/wiki/Basic_access_authentication). - A successful call returns a JSON structure that shows user information such as - their username, the roles that are assigned to the user, any assigned metadata, - and information about the realms that authenticated and authorized the user. - If the user cannot be authenticated, this API returns a 401 status code. + .. raw:: html - ``_ +

Authenticate a user.

+

Authenticates a user and returns information about the authenticated user. + Include the user information in a basic auth header. + A successful call returns a JSON structure that shows user information such as their username, the roles that are assigned to the user, any assigned metadata, and information about the realms that authenticated and authorized the user. + If the user cannot be authenticated, this API returns a 401 status code.

+ + + ``_ """ __path_parts: t.Dict[str, str] = {} __path = "/_security/_authenticate" @@ -85,31 +87,43 @@ def create_api_key( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Create an API key. Create an API key for access without requiring basic authentication. - A successful request returns a JSON structure that contains the API key, its - unique id, and its name. If applicable, it also returns expiration information - for the API key in milliseconds. NOTE: By default, API keys never expire. You - can specify expiration information when you create the API keys. + .. raw:: html + +

Create an API key.

+

Create an API key for access without requiring basic authentication.

+

IMPORTANT: If the credential that is used to authenticate this request is an API key, the derived API key cannot have any privileges. + If you specify privileges, the API returns an error.

+

A successful request returns a JSON structure that contains the API key, its unique id, and its name. + If applicable, it also returns expiration information for the API key in milliseconds.

+

NOTE: By default, API keys never expire. You can specify expiration information when you create the API keys.

+

The API keys are created by the Elasticsearch API key service, which is automatically enabled. + To configure or turn off the API key service, refer to API key service setting documentation.

+ - ``_ + ``_ - :param expiration: Expiration time for the API key. By default, API keys never - expire. + :param expiration: The expiration time for the API key. By default, API keys + never expire. :param metadata: Arbitrary metadata that you want to associate with the API key. It supports nested data structure. Within the metadata object, keys beginning with `_` are reserved for system usage. - :param name: Specifies the name for this API key. + :param name: A name for the API key. :param refresh: If `true` (the default) then refresh the affected shards to make this operation visible to search, if `wait_for` then wait for a refresh to make this operation visible to search, if `false` then do nothing with refreshes. - :param role_descriptors: An array of role descriptors for this API key. This - parameter is optional. When it is not specified or is an empty array, then - the API key will have a point in time snapshot of permissions of the authenticated - user. If you supply role descriptors then the resultant permissions would - be an intersection of API keys permissions and authenticated user’s permissions - thereby limiting the access scope for API keys. The structure of role descriptor - is the same as the request for create role API. For more details, see create - or update roles API. + :param role_descriptors: An array of role descriptors for this API key. When + it is not specified or it is an empty array, the API key will have a point + in time snapshot of permissions of the authenticated user. If you supply + role descriptors, the resultant permissions are an intersection of API keys + permissions and the authenticated user's permissions thereby limiting the + access scope for API keys. The structure of role descriptor is the same as + the request for the create role API. For more details, refer to the create + or update roles API. NOTE: Due to the way in which this permission intersection + is calculated, it is not possible to create an API key that is a child of + another API key, unless the derived key is created without any privileges. + In this case, you must explicitly specify a role descriptor with no privileges. + The derived API key can be used for authentication; it will not have authority + to call Elasticsearch APIs. """ __path_parts: t.Dict[str, str] = {} __path = "/_security/api_key" @@ -159,11 +173,17 @@ def delete_role( ] = None, ) -> ObjectApiResponse[t.Any]: """ - Delete roles. Delete roles in the native realm. + .. raw:: html - ``_ +

Delete roles.

+

Delete roles in the native realm. + The role management APIs are generally the preferred way to manage roles, rather than using file-based role management. + The delete roles API cannot remove roles that are defined in roles files.

- :param name: Role name + + ``_ + + :param name: The name of the role. :param refresh: If `true` (the default) then refresh the affected shards to make this operation visible to search, if `wait_for` then wait for a refresh to make this operation visible to search, if `false` then do nothing with refreshes. @@ -211,13 +231,15 @@ def get_api_key( with_profile_uid: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Get API key information. Retrieves information for one or more API keys. NOTE: - If you have only the `manage_own_api_key` privilege, this API returns only the - API keys that you own. If you have `read_security`, `manage_api_key` or greater - privileges (including `manage_security`), this API returns all API keys regardless - of ownership. + .. raw:: html + +

Get API key information.

+

Retrieves information for one or more API keys. + NOTE: If you have only the manage_own_api_key privilege, this API returns only the API keys that you own. + If you have read_security, manage_api_key or greater privileges (including manage_security), this API returns all API keys regardless of ownership.

+ - ``_ + ``_ :param active_only: A boolean flag that can be used to query API keys that are currently active. An API key is considered active if it is neither invalidated, @@ -289,10 +311,13 @@ def get_builtin_privileges( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Get builtin privileges. Get the list of cluster privileges and index privileges - that are available in this version of Elasticsearch. + .. raw:: html - ``_ +

Get builtin privileges.

+

Get the list of cluster privileges and index privileges that are available in this version of Elasticsearch.

+ + + ``_ """ __path_parts: t.Dict[str, str] = {} __path = "/_security/privilege/_builtin" @@ -326,9 +351,15 @@ def get_role( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Get roles. Get roles in the native realm. + .. raw:: html + +

Get roles.

+

Get roles in the native realm. + The role management APIs are generally the preferred way to manage roles, rather than using file-based role management. + The get roles API cannot retrieve roles that are defined in roles files.

+ - ``_ + ``_ :param name: The name of the role. You can specify multiple roles as a comma-separated list. If you do not specify this parameter, the API returns information about @@ -444,10 +475,15 @@ def has_privileges( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Check user privileges. Determine whether the specified user has a specified list - of privileges. + .. raw:: html - ``_ +

Check user privileges.

+

Determine whether the specified user has a specified list of privileges. + All users can use this API, but only to determine their own privileges. + To check the privileges of other users, you must use the run as feature.

+ + + ``_ :param user: Username :param application: @@ -508,33 +544,39 @@ def invalidate_api_key( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Invalidate API keys. This API invalidates API keys created by the create API - key or grant API key APIs. Invalidated API keys fail authentication, but they - can still be viewed using the get API key information and query API key information - APIs, for at least the configured retention period, until they are automatically - deleted. The `manage_api_key` privilege allows deleting any API keys. The `manage_own_api_key` - only allows deleting API keys that are owned by the user. In addition, with the - `manage_own_api_key` privilege, an invalidation request must be issued in one - of the three formats: - Set the parameter `owner=true`. - Or, set both `username` - and `realm_name` to match the user’s identity. - Or, if the request is issued - by an API key, that is to say an API key invalidates itself, specify its ID in - the `ids` field. + .. raw:: html + +

Invalidate API keys.

+

This API invalidates API keys created by the create API key or grant API key APIs. + Invalidated API keys fail authentication, but they can still be viewed using the get API key information and query API key information APIs, for at least the configured retention period, until they are automatically deleted.

+

To use this API, you must have at least the manage_security, manage_api_key, or manage_own_api_key cluster privileges. + The manage_security privilege allows deleting any API key, including both REST and cross cluster API keys. + The manage_api_key privilege allows deleting any REST API key, but not cross cluster API keys. + The manage_own_api_key only allows deleting REST API keys that are owned by the user. + In addition, with the manage_own_api_key privilege, an invalidation request must be issued in one of the three formats:

+
    +
  • Set the parameter owner=true.
    • +
  • Or, set both username and realm_name to match the user's identity.
    • +
  • Or, if the request is issued by an API key, that is to say an API key invalidates itself, specify its ID in the ids field.
    • +
+ - ``_ + ``_ :param id: :param ids: A list of API key ids. This parameter cannot be used with any of `name`, `realm_name`, or `username`. :param name: An API key name. This parameter cannot be used with any of `ids`, `realm_name` or `username`. - :param owner: Can be used to query API keys owned by the currently authenticated - user. The `realm_name` or `username` parameters cannot be specified when - this parameter is set to `true` as they are assumed to be the currently authenticated - ones. + :param owner: Query API keys owned by the currently authenticated user. The `realm_name` + or `username` parameters cannot be specified when this parameter is set to + `true` as they are assumed to be the currently authenticated ones. NOTE: + At least one of `ids`, `name`, `username`, and `realm_name` must be specified + if `owner` is `false`. :param realm_name: The name of an authentication realm. This parameter cannot be used with either `ids` or `name`, or when `owner` flag is set to `true`. :param username: The username of a user. This parameter cannot be used with either - `ids` or `name`, or when `owner` flag is set to `true`. + `ids` or `name` or when `owner` flag is set to `true`. """ __path_parts: t.Dict[str, str] = {} __path = "/_security/api_key" @@ -678,12 +720,15 @@ def put_role( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Create or update roles. The role management APIs are generally the preferred - way to manage roles in the native realm, rather than using file-based role management. - The create or update roles API cannot update roles that are defined in roles - files. File-based role management is not available in Elastic Serverless. + .. raw:: html - ``_ +

Create or update roles.

+

The role management APIs are generally the preferred way to manage roles in the native realm, rather than using file-based role management. + The create or update roles API cannot update roles that are defined in roles files. + File-based role management is not available in Elastic Serverless.

+ + + ``_ :param name: The name of the role that is being created or updated. On Elasticsearch Serverless, the role name must begin with a letter or digit and can only @@ -703,7 +748,10 @@ def put_role( this operation visible to search, if `wait_for` then wait for a refresh to make this operation visible to search, if `false` then do nothing with refreshes. :param remote_cluster: A list of remote cluster permissions entries. - :param remote_indices: A list of remote indices permissions entries. + :param remote_indices: A list of remote indices permissions entries. NOTE: Remote + indices are effective for remote clusters configured with the API key based + model. They have no effect for remote clusters configured with the certificate + based model. :param run_as: A list of users that the owners of this role can impersonate. *Note*: in Serverless, the run-as feature is disabled. For API compatibility, you can still specify an empty `run_as` field, but a non-empty list will @@ -787,7 +835,7 @@ def query_api_keys( pretty: t.Optional[bool] = None, query: t.Optional[t.Mapping[str, t.Any]] = None, search_after: t.Optional[ - t.Sequence[t.Union[None, bool, float, int, str, t.Any]] + t.Sequence[t.Union[None, bool, float, int, str]] ] = None, size: t.Optional[int] = None, sort: t.Optional[ @@ -802,10 +850,17 @@ def query_api_keys( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Find API keys with a query. Get a paginated list of API keys and their information. - You can optionally filter the results with a query. + .. raw:: html + +

Find API keys with a query.

+

Get a paginated list of API keys and their information. + You can optionally filter the results with a query.

+

To use this API, you must have at least the manage_own_api_key or the read_security cluster privileges. + If you have only the manage_own_api_key privilege, this API returns only the API keys that you own. + If you have the read_security, manage_api_key, or greater privileges (including manage_security), this API returns all API keys regardless of ownership.

+ - ``_ + ``_ :param aggregations: Any aggregations to run over the corpus of returned API keys. Aggregations and queries work together. Aggregations are computed only @@ -819,30 +874,39 @@ def query_api_keys( `terms`, `range`, `date_range`, `missing`, `cardinality`, `value_count`, `composite`, `filter`, and `filters`. Additionally, aggregations only run over the same subset of fields that query works with. - :param from_: Starting document offset. By default, you cannot page through more - than 10,000 hits using the from and size parameters. To page through more - hits, use the `search_after` parameter. + :param from_: The starting document offset. It must not be negative. By default, + you cannot page through more than 10,000 hits using the `from` and `size` + parameters. To page through more hits, use the `search_after` parameter. :param query: A query to filter which API keys to return. If the query parameter is missing, it is equivalent to a `match_all` query. The query supports a subset of query types, including `match_all`, `bool`, `term`, `terms`, `match`, `ids`, `prefix`, `wildcard`, `exists`, `range`, and `simple_query_string`. You can query the following public information associated with an API key: `id`, `type`, `name`, `creation`, `expiration`, `invalidated`, `invalidation`, - `username`, `realm`, and `metadata`. - :param search_after: Search after definition - :param size: The number of hits to return. By default, you cannot page through - more than 10,000 hits using the `from` and `size` parameters. To page through - more hits, use the `search_after` parameter. - :param sort: Other than `id`, all public fields of an API key are eligible for - sorting. In addition, sort can also be applied to the `_doc` field to sort - by index order. + `username`, `realm`, and `metadata`. NOTE: The queryable string values associated + with API keys are internally mapped as keywords. Consequently, if no `analyzer` + parameter is specified for a `match` query, then the provided match query + string is interpreted as a single keyword value. Such a match query is hence + equivalent to a `term` query. + :param search_after: The search after definition. + :param size: The number of hits to return. It must not be negative. The `size` + parameter can be set to `0`, in which case no API key matches are returned, + only the aggregation results. By default, you cannot page through more than + 10,000 hits using the `from` and `size` parameters. To page through more + hits, use the `search_after` parameter. + :param sort: The sort definition. Other than `id`, all public fields of an API + key are eligible for sorting. In addition, sort can also be applied to the + `_doc` field to sort by index order. :param typed_keys: Determines whether aggregation names are prefixed by their respective types in the response. :param with_limited_by: Return the snapshot of the owner user's role descriptors associated with the API key. An API key's actual permission is the intersection - of its assigned role descriptors and the owner user's role descriptors. - :param with_profile_uid: Determines whether to also retrieve the profile uid, - for the API key owner principal, if it exists. + of its assigned role descriptors and the owner user's role descriptors (effectively + limited by it). An API key cannot retrieve any API key’s limited-by role + descriptors (including itself) unless it has `manage_api_key` or higher privileges. + :param with_profile_uid: Determines whether to also retrieve the profile UID + for the API key owner principal. If it exists, the profile UID is returned + under the `profile_uid` response field for each API key. """ __path_parts: t.Dict[str, str] = {} __path = "/_security/_query/api_key" @@ -917,7 +981,7 @@ def query_role( pretty: t.Optional[bool] = None, query: t.Optional[t.Mapping[str, t.Any]] = None, search_after: t.Optional[ - t.Sequence[t.Union[None, bool, float, int, str, t.Any]] + t.Sequence[t.Union[None, bool, float, int, str]] ] = None, size: t.Optional[int] = None, sort: t.Optional[ @@ -929,26 +993,34 @@ def query_role( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Find roles with a query. Get roles in a paginated manner. You can optionally - filter the results with a query. + .. raw:: html - ``_ +

Find roles with a query.

+

Get roles in a paginated manner. + The role management APIs are generally the preferred way to manage roles, rather than using file-based role management. + The query roles API does not retrieve roles that are defined in roles files, nor built-in ones. + You can optionally filter the results with a query. + Also, the results can be paginated and sorted.

- :param from_: Starting document offset. By default, you cannot page through more - than 10,000 hits using the from and size parameters. To page through more - hits, use the `search_after` parameter. + + ``_ + + :param from_: The starting document offset. It must not be negative. By default, + you cannot page through more than 10,000 hits using the `from` and `size` + parameters. To page through more hits, use the `search_after` parameter. :param query: A query to filter which roles to return. If the query parameter is missing, it is equivalent to a `match_all` query. The query supports a subset of query types, including `match_all`, `bool`, `term`, `terms`, `match`, `ids`, `prefix`, `wildcard`, `exists`, `range`, and `simple_query_string`. You can query the following information associated with roles: `name`, `description`, - `metadata`, `applications.application`, `applications.privileges`, `applications.resources`. - :param search_after: Search after definition - :param size: The number of hits to return. By default, you cannot page through - more than 10,000 hits using the `from` and `size` parameters. To page through - more hits, use the `search_after` parameter. - :param sort: All public fields of a role are eligible for sorting. In addition, - sort can also be applied to the `_doc` field to sort by index order. + `metadata`, `applications.application`, `applications.privileges`, and `applications.resources`. + :param search_after: The search after definition. + :param size: The number of hits to return. It must not be negative. By default, + you cannot page through more than 10,000 hits using the `from` and `size` + parameters. To page through more hits, use the `search_after` parameter. + :param sort: The sort definition. You can sort on `username`, `roles`, or `enabled`. + In addition, sort can also be applied to the `_doc` field to sort by index + order. """ __path_parts: t.Dict[str, str] = {} __path = "/_security/_query/role" @@ -1005,38 +1077,43 @@ def update_api_key( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Update an API key. Updates attributes of an existing API key. Users can only - update API keys that they created or that were granted to them. Use this API - to update API keys created by the create API Key or grant API Key APIs. If you - need to apply the same update to many API keys, you can use bulk update API Keys - to reduce overhead. It’s not possible to update expired API keys, or API keys - that have been invalidated by invalidate API Key. This API supports updates to - an API key’s access scope and metadata. The access scope of an API key is derived - from the `role_descriptors` you specify in the request, and a snapshot of the - owner user’s permissions at the time of the request. The snapshot of the owner’s - permissions is updated automatically on every call. If you don’t specify `role_descriptors` - in the request, a call to this API might still change the API key’s access scope. - This change can occur if the owner user’s permissions have changed since the - API key was created or last modified. To update another user’s API key, use the - `run_as` feature to submit a request on behalf of another user. IMPORTANT: It’s - not possible to use an API key as the authentication credential for this API. - To update an API key, the owner user’s credentials are required. + .. raw:: html - ``_ +

Update an API key.

+

Update attributes of an existing API key. + This API supports updates to an API key's access scope, expiration, and metadata.

+

To use this API, you must have at least the manage_own_api_key cluster privilege. + Users can only update API keys that they created or that were granted to them. + To update another user’s API key, use the run_as feature to submit a request on behalf of another user.

+

IMPORTANT: It's not possible to use an API key as the authentication credential for this API. The owner user’s credentials are required.

+

Use this API to update API keys created by the create API key or grant API Key APIs. + If you need to apply the same update to many API keys, you can use the bulk update API keys API to reduce overhead. + It's not possible to update expired API keys or API keys that have been invalidated by the invalidate API key API.

+

The access scope of an API key is derived from the role_descriptors you specify in the request and a snapshot of the owner user's permissions at the time of the request. + The snapshot of the owner's permissions is updated automatically on every call.

+

IMPORTANT: If you don't specify role_descriptors in the request, a call to this API might still change the API key's access scope. + This change can occur if the owner user's permissions have changed since the API key was created or last modified.

+ + + ``_ :param id: The ID of the API key to update. - :param expiration: Expiration time for the API key. + :param expiration: The expiration time for the API key. By default, API keys + never expire. This property can be omitted to leave the expiration unchanged. :param metadata: Arbitrary metadata that you want to associate with the API key. - It supports nested data structure. Within the metadata object, keys beginning - with _ are reserved for system usage. - :param role_descriptors: An array of role descriptors for this API key. This - parameter is optional. When it is not specified or is an empty array, then - the API key will have a point in time snapshot of permissions of the authenticated - user. If you supply role descriptors then the resultant permissions would - be an intersection of API keys permissions and authenticated user’s permissions - thereby limiting the access scope for API keys. The structure of role descriptor - is the same as the request for create role API. For more details, see create - or update roles API. + It supports a nested data structure. Within the metadata object, keys beginning + with `_` are reserved for system usage. When specified, this value fully + replaces the metadata previously associated with the API key. + :param role_descriptors: The role descriptors to assign to this API key. The + API key's effective permissions are an intersection of its assigned privileges + and the point in time snapshot of permissions of the owner user. You can + assign new privileges by specifying them in this parameter. To remove assigned + privileges, you can supply an empty `role_descriptors` parameter, that is + to say, an empty object `{}`. If an API key has no assigned privileges, it + inherits the owner user's full permissions. The snapshot of the owner's permissions + is always updated, whether you supply the `role_descriptors` parameter or + not. The structure of a role descriptor is the same as the request for the + create API keys API. """ if id in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'id'") diff --git a/elasticsearch_serverless/_sync/client/sql.py b/elasticsearch_serverless/_sync/client/sql.py index 9ab4f94..90cb016 100644 --- a/elasticsearch_serverless/_sync/client/sql.py +++ b/elasticsearch_serverless/_sync/client/sql.py @@ -39,9 +39,12 @@ def clear_cursor( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Clear an SQL search cursor. + .. raw:: html - ``_ +

Clear an SQL search cursor.

+ + + ``_ :param cursor: Cursor to clear. """ @@ -84,13 +87,19 @@ def delete_async( 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. If the Elasticsearch - security features are enabled, only the following users can use this API to delete - a search: * Users with the `cancel_task` cluster privilege. * The user who first - submitted the search. + .. raw:: html + +

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.

+

If the Elasticsearch security features are enabled, only the following users can use this API to delete a search:

+
    +
  • Users with the cancel_task cluster privilege.
    • +
  • The user who first submitted the search.
    • +
- ``_ + + ``_ :param id: The identifier for the search. """ @@ -134,12 +143,14 @@ def get_async( ] = 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. If the Elasticsearch security - features are enabled, only the user who first submitted the SQL search can retrieve - the search using this API. + .. raw:: html + +

Get async SQL search results. + Get the current status and available results for an async SQL search or stored synchronous SQL search.

+

If the Elasticsearch security features are enabled, only the user who first submitted the SQL search can retrieve the search using this API.

+ - ``_ + ``_ :param id: The identifier for the search. :param delimiter: The separator for CSV results. The API supports this parameter @@ -195,10 +206,13 @@ def get_async_status( 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 - ``_ +

Get the async SQL search status. + Get the current status of an async SQL search or a stored synchronous SQL search.

+ + + ``_ :param id: The identifier for the search. """ @@ -281,9 +295,13 @@ def query( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Get SQL search results. Run an SQL request. + .. raw:: html + +

Get SQL search results. + Run an SQL request.

- ``_ + + ``_ :param allow_partial_search_results: If `true`, the response has partial results when there are shard request timeouts or shard failures. If `false`, the @@ -402,11 +420,14 @@ def translate( 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. It accepts the same request body parameters - as the SQL search API, excluding `cursor`. + .. raw:: html + +

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 cursor.

+ - ``_ + ``_ :param query: The SQL query to run. :param fetch_size: The maximum number of rows (or entries) to return in one response. diff --git a/elasticsearch_serverless/_sync/client/synonyms.py b/elasticsearch_serverless/_sync/client/synonyms.py index a13c3ba..1c96131 100644 --- a/elasticsearch_serverless/_sync/client/synonyms.py +++ b/elasticsearch_serverless/_sync/client/synonyms.py @@ -36,23 +36,24 @@ def delete_synonym( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - 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. - - ``_ + .. raw:: html + +

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.

+ + + ``_ :param id: The synonyms set identifier to delete. """ @@ -91,9 +92,13 @@ def delete_synonym_rule( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Delete a synonym rule. Delete a synonym rule from a synonym set. + .. raw:: html + +

Delete a synonym rule. + Delete a synonym rule from a synonym set.

- ``_ + + ``_ :param set_id: The ID of the synonym set to update. :param rule_id: The ID of the synonym rule to delete. @@ -141,9 +146,12 @@ def get_synonym( size: t.Optional[int] = None, ) -> ObjectApiResponse[t.Any]: """ - Get a synonym set. + .. raw:: html + +

Get a synonym set.

- ``_ + + ``_ :param id: The synonyms set identifier to retrieve. :param from_: The starting offset for query rules to retrieve. @@ -188,9 +196,13 @@ def get_synonym_rule( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Get a synonym rule. Get a synonym rule from a synonym set. + .. raw:: html + +

Get a synonym rule. + Get a synonym rule from a synonym set.

- ``_ + + ``_ :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. @@ -237,9 +249,13 @@ def get_synonyms_sets( size: t.Optional[int] = None, ) -> ObjectApiResponse[t.Any]: """ - Get all synonym sets. Get a summary of all defined synonym sets. + .. raw:: html + +

Get all synonym sets. + Get a summary of all defined synonym sets.

- ``_ + + ``_ :param from_: The starting offset for synonyms sets to retrieve. :param size: The maximum number of synonyms sets to retrieve. @@ -286,14 +302,16 @@ def put_synonym( 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. 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. + .. raw:: html + +

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.

+

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.

- ``_ + + ``_ :param id: The ID of the synonyms set to be created or updated. :param synonyms_set: The synonym rules definitions for the synonyms set. @@ -344,12 +362,15 @@ def put_synonym_rule( 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. 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. + .. raw:: html + +

Create or update a synonym rule. + Create or update a synonym rule in a synonym 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.

+ - ``_ + ``_ :param set_id: The ID of the synonym set. :param rule_id: The ID of the synonym rule to be updated or created. diff --git a/elasticsearch_serverless/_sync/client/tasks.py b/elasticsearch_serverless/_sync/client/tasks.py index 1f5b610..c9731c2 100644 --- a/elasticsearch_serverless/_sync/client/tasks.py +++ b/elasticsearch_serverless/_sync/client/tasks.py @@ -45,13 +45,20 @@ def get( wait_for_completion: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Get task information. Get information about a task currently running in the cluster. + .. raw:: html - ``_ +

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.

- :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. """ diff --git a/elasticsearch_serverless/_sync/client/transform.py b/elasticsearch_serverless/_sync/client/transform.py index f1c8c34..54b4361 100644 --- a/elasticsearch_serverless/_sync/client/transform.py +++ b/elasticsearch_serverless/_sync/client/transform.py @@ -39,9 +39,12 @@ def delete_transform( timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, ) -> ObjectApiResponse[t.Any]: """ - Delete a transform. Deletes a transform. + .. raw:: html - ``_ +

Delete a transform.

+ + + ``_ :param transform_id: Identifier for the transform. :param delete_dest_index: If this value is true, the destination index is deleted @@ -99,9 +102,13 @@ def get_transform( size: t.Optional[int] = None, ) -> ObjectApiResponse[t.Any]: """ - Get transforms. Retrieves configuration information for transforms. + .. raw:: html + +

Get transforms. + Get configuration information for transforms.

- ``_ + + ``_ :param transform_id: Identifier for the transform. It can be a transform identifier or a wildcard expression. You can get information for all transforms by using @@ -168,9 +175,13 @@ def get_transform_stats( timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, ) -> ObjectApiResponse[t.Any]: """ - Get transform stats. Retrieves usage information for transforms. + .. raw:: html + +

Get transform stats.

+

Get usage information for transforms.

- ``_ + + ``_ :param transform_id: Identifier for the transform. It can be a transform identifier or a wildcard expression. You can get information for all transforms by using @@ -249,14 +260,16 @@ def preview_transform( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Preview a transform. Generates a preview of the results that you will get when - you create a transform with the same configuration. It returns a maximum of 100 - results. The calculations are based on all the current data in the source index. - It also generates a list of mappings and settings for the destination index. - These values are determined based on the field types of the source index and - the transform aggregations. + .. raw:: html + +

Preview a transform. + Generates a preview of the results that you will get when you create a transform with the same configuration.

+

It returns a maximum of 100 results. The calculations are based on all the current data in the source index. It also + generates a list of mappings and settings for the destination index. These values are determined based on the field + types of the source index and the transform aggregations.

- ``_ + + ``_ :param transform_id: Identifier for the transform to preview. If you specify this path parameter, you cannot provide transform configuration details in @@ -371,29 +384,29 @@ def put_transform( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Create a transform. Creates a transform. A transform copies data from source - indices, transforms it, and persists it into an entity-centric destination index. - You can also think of the destination index as a two-dimensional tabular data - structure (known as a data frame). The ID for each document in the data frame - is generated from a hash of the entity, so there is a unique row per entity. - You must choose either the latest or pivot method for your transform; you cannot - use both in a single transform. If you choose to use the pivot method for your - transform, the entities are defined by the set of `group_by` fields in the pivot - object. If you choose to use the latest method, the entities are defined by the - `unique_key` field values in the latest object. You must have `create_index`, - `index`, and `read` privileges on the destination index and `read` and `view_index_metadata` - privileges on the source indices. When Elasticsearch security features are enabled, - the transform remembers which roles the user that created it had at the time - of creation and uses those same roles. If those roles do not have the required - privileges on the source and destination indices, the transform fails when it - attempts unauthorized operations. NOTE: You must use Kibana or this API to create - a transform. Do not add a transform directly into any `.transform-internal*` - indices using the Elasticsearch index API. If Elasticsearch security features - are enabled, do not give users any privileges on `.transform-internal*` indices. - If you used transforms prior to 7.5, also do not give users any privileges on - `.data-frame-internal*` indices. - - ``_ + .. raw:: html + +

Create a transform. + Creates a transform.

+

A transform copies data from source indices, transforms it, and persists it into an entity-centric destination index. You can also think of the destination index as a two-dimensional tabular data structure (known as + a data frame). The ID for each document in the data frame is generated from a hash of the entity, so there is a + unique row per entity.

+

You must choose either the latest or pivot method for your transform; you cannot use both in a single transform. If + you choose to use the pivot method for your transform, the entities are defined by the set of group_by fields in + the pivot object. If you choose to use the latest method, the entities are defined by the unique_key field values + in the latest object.

+

You must have create_index, index, and read privileges on the destination index and read and + view_index_metadata privileges on the source indices. When Elasticsearch security features are enabled, the + transform remembers which roles the user that created it had at the time of creation and uses those same roles. If + those roles do not have the required privileges on the source and destination indices, the transform fails when it + attempts unauthorized operations.

+

NOTE: You must use Kibana or this API to create a transform. Do not add a transform directly into any + .transform-internal* indices using the Elasticsearch index API. If Elasticsearch security features are enabled, do + not give users any privileges on .transform-internal* indices. If you used transforms prior to 7.5, also do not + give users any privileges on .data-frame-internal* indices.

+ + + ``_ :param transform_id: Identifier for the transform. This identifier can contain lowercase alphanumeric characters (a-z and 0-9), hyphens, and underscores. @@ -492,11 +505,14 @@ def reset_transform( timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, ) -> ObjectApiResponse[t.Any]: """ - Reset a transform. Resets a transform. Before you can reset it, you must stop - it; alternatively, use the `force` query parameter. If the destination index - was created by the transform, it is deleted. + .. raw:: html + +

Reset a transform.

+

Before you can reset it, you must stop it; alternatively, use the force query parameter. + If the destination index was created by the transform, it is deleted.

- ``_ + + ``_ :param transform_id: Identifier for the transform. This identifier can contain lowercase alphanumeric characters (a-z and 0-9), hyphens, and underscores. @@ -546,13 +562,17 @@ def schedule_now_transform( timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, ) -> ObjectApiResponse[t.Any]: """ - Schedule a transform to start now. Instantly runs a transform to process data. - If you _schedule_now a transform, it will process the new data instantly, without - waiting for the configured frequency interval. After _schedule_now API is called, - the transform will be processed again at now + frequency unless _schedule_now - API is called again in the meantime. + .. raw:: html + +

Schedule a transform to start now.

+

Instantly run a transform to process data. + If you run this API, the transform will process the new data instantly, + without waiting for the configured frequency interval. After the API is called, + the transform will be processed again at now + frequency unless the API + is called again in the meantime.

- ``_ + + ``_ :param transform_id: Identifier for the transform. :param timeout: Controls the time to wait for the scheduling to take place @@ -597,26 +617,25 @@ def start_transform( timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, ) -> ObjectApiResponse[t.Any]: """ - Start a transform. Starts a transform. When you start a transform, it creates - the destination index if it does not already exist. The `number_of_shards` is - set to `1` and the `auto_expand_replicas` is set to `0-1`. If it is a pivot transform, - it deduces the mapping definitions for the destination index from the source - indices and the transform aggregations. If fields in the destination index are - derived from scripts (as in the case of `scripted_metric` or `bucket_script` - aggregations), the transform uses dynamic mappings unless an index template exists. - If it is a latest transform, it does not deduce mapping definitions; it uses - dynamic mappings. To use explicit mappings, create the destination index before - you start the transform. Alternatively, you can create an index template, though - it does not affect the deduced mappings in a pivot transform. When the transform - starts, a series of validations occur to ensure its success. If you deferred - validation when you created the transform, they occur when you start the transform—​with - the exception of privilege checks. When Elasticsearch security features are enabled, - the transform remembers which roles the user that created it had at the time - of creation and uses those same roles. If those roles do not have the required - privileges on the source and destination indices, the transform fails when it - attempts unauthorized operations. - - ``_ + .. raw:: html + +

Start a transform.

+

When you start a transform, it creates the destination index if it does not already exist. The number_of_shards is + set to 1 and the auto_expand_replicas is set to 0-1. If it is a pivot transform, it deduces the mapping + definitions for the destination index from the source indices and the transform aggregations. If fields in the + destination index are derived from scripts (as in the case of scripted_metric or bucket_script aggregations), + the transform uses dynamic mappings unless an index template exists. If it is a latest transform, it does not deduce + mapping definitions; it uses dynamic mappings. To use explicit mappings, create the destination index before you + start the transform. Alternatively, you can create an index template, though it does not affect the deduced mappings + in a pivot transform.

+

When the transform starts, a series of validations occur to ensure its success. If you deferred validation when you + created the transform, they occur when you start the transform—​with the exception of privilege checks. When + Elasticsearch security features are enabled, the transform remembers which roles the user that created it had at the + time of creation and uses those same roles. If those roles do not have the required privileges on the source and + destination indices, the transform fails when it attempts unauthorized operations.

+ + + ``_ :param transform_id: Identifier for the transform. :param from_: Restricts the set of transformed entities to those changed after @@ -668,9 +687,13 @@ def stop_transform( wait_for_completion: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Stop transforms. Stops one or more transforms. + .. raw:: html + +

Stop transforms. + Stops one or more transforms.

- ``_ + + ``_ :param transform_id: Identifier for the transform. To stop multiple transforms, use a comma-separated list or a wildcard expression. To stop all transforms, @@ -761,16 +784,18 @@ def update_transform( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Update a transform. Updates certain properties of a transform. All updated properties - except `description` do not take effect until after the transform starts the - next checkpoint, thus there is data consistency in each checkpoint. To use this - API, you must have `read` and `view_index_metadata` privileges for the source - indices. You must also have `index` and `read` privileges for the destination - index. When Elasticsearch security features are enabled, the transform remembers - which roles the user who updated it had at the time of update and runs with those - privileges. - - ``_ + .. raw:: html + +

Update a transform. + Updates certain properties of a transform.

+

All updated properties except description do not take effect until after the transform starts the next checkpoint, + thus there is data consistency in each checkpoint. To use this API, you must have read and view_index_metadata + privileges for the source indices. You must also have index and read privileges for the destination index. When + Elasticsearch security features are enabled, the transform remembers which roles the user who updated it had at the + time of update and runs with those privileges.

+ + + ``_ :param transform_id: Identifier for the transform. :param defer_validation: When true, deferrable validations are not run. This From 1602d6bbcf541dd8fb1f26e0d5096bcf03a66364 Mon Sep 17 00:00:00 2001 From: Quentin Pradet Date: Thu, 6 Mar 2025 11:46:58 +0400 Subject: [PATCH 2/6] Add sphinx.configuration --- .readthedocs.yml | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/.readthedocs.yml b/.readthedocs.yml index 8f6285f..2db8e85 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -10,3 +10,7 @@ python: - path: . extra_requirements: - "docs" + +sphinx: + configuration: docs/sphinx/conf.py + fail_on_warning: true \ No newline at end of file From 5e643e997d8f0cb97976df5861448c4622c49e30 Mon Sep 17 00:00:00 2001 From: Quentin Pradet Date: Thu, 6 Mar 2025 12:16:24 +0400 Subject: [PATCH 3/6] Fix all warnings in docs --- docs/sphinx/api.rst | 150 +++++-------------------- docs/sphinx/api/async-search.rst | 10 ++ docs/sphinx/api/cat.rst | 9 ++ docs/sphinx/api/cluster.rst | 9 ++ docs/sphinx/api/connector.rst | 9 ++ docs/sphinx/api/elasticsearch.rst | 9 ++ docs/sphinx/api/enrich-policies.rst | 9 ++ docs/sphinx/api/eql.rst | 9 ++ docs/sphinx/api/esql.rst | 9 ++ docs/sphinx/api/indices.rst | 9 ++ docs/sphinx/api/inference.rst | 9 ++ docs/sphinx/api/ingest-pipelines.rst | 9 ++ docs/sphinx/api/license.rst | 9 ++ docs/sphinx/api/logstash.rst | 9 ++ docs/sphinx/api/ml.rst | 9 ++ docs/sphinx/api/nodes.rst | 9 ++ docs/sphinx/api/query-rules.rst | 9 ++ docs/sphinx/api/search-application.rst | 9 ++ docs/sphinx/api/security.rst | 9 ++ docs/sphinx/api/sql.rst | 9 ++ docs/sphinx/api/synonyms.rst | 9 ++ docs/sphinx/api/tasks.rst | 9 ++ docs/sphinx/api/transforms.rst | 9 ++ docs/sphinx/async.rst | 4 + docs/sphinx/exceptions.rst | 1 + 25 files changed, 229 insertions(+), 125 deletions(-) create mode 100644 docs/sphinx/api/async-search.rst create mode 100644 docs/sphinx/api/cat.rst create mode 100644 docs/sphinx/api/cluster.rst create mode 100644 docs/sphinx/api/connector.rst create mode 100644 docs/sphinx/api/elasticsearch.rst create mode 100644 docs/sphinx/api/enrich-policies.rst create mode 100644 docs/sphinx/api/eql.rst create mode 100644 docs/sphinx/api/esql.rst create mode 100644 docs/sphinx/api/indices.rst create mode 100644 docs/sphinx/api/inference.rst create mode 100644 docs/sphinx/api/ingest-pipelines.rst create mode 100644 docs/sphinx/api/license.rst create mode 100644 docs/sphinx/api/logstash.rst create mode 100644 docs/sphinx/api/ml.rst create mode 100644 docs/sphinx/api/nodes.rst create mode 100644 docs/sphinx/api/query-rules.rst create mode 100644 docs/sphinx/api/search-application.rst create mode 100644 docs/sphinx/api/security.rst create mode 100644 docs/sphinx/api/sql.rst create mode 100644 docs/sphinx/api/synonyms.rst create mode 100644 docs/sphinx/api/tasks.rst create mode 100644 docs/sphinx/api/transforms.rst diff --git a/docs/sphinx/api.rst b/docs/sphinx/api.rst index 7405ca9..9092836 100644 --- a/docs/sphinx/api.rst +++ b/docs/sphinx/api.rst @@ -14,129 +14,29 @@ arguments are required for all aliased as ``from_``. -Elasticsearch -------------- -.. py:module:: elasticsearch_serverless - -.. autoclass:: Elasticsearch - :members: - -.. py:module:: elasticsearch_serverless.client - -Async Search ------------- - -.. autoclass:: AsyncSearchClient - :members: - -Cat ---- - -.. autoclass:: CatClient - :members: - -Cluster -------- - -.. autoclass:: ClusterClient - :members: - -Connector ---------- -.. py:module:: elasticsearch.client - :noindex: - -.. autoclass:: ConnectorClient - :members: - -Enrich Policies ---------------- - -.. autoclass:: EnrichClient - :members: - -Event Query Language (EQL) --------------------------- - -.. autoclass:: EqlClient - :members: - - -ES|QL ------ - -.. autoclass:: EqlClient - :members: - -Graph Explore -------------- - -.. autoclass:: GraphClient - :members: - -Indices -------- - -.. autoclass:: IndicesClient - :members: - -Inference ---------- - -.. autoclass:: InferenceClient - :members: - -Ingest Pipelines ----------------- - -.. autoclass:: IngestClient - :members: - -License -------- - -.. autoclass:: LicenseClient - :members: - -Logstash --------- - -.. autoclass:: LogstashClient - :members: - -Machine Learning (ML) ---------------------- - -.. autoclass:: MlClient - :members: - -Monitoring ----------- - -.. autoclass:: MonitoringClient - :members: - -Security --------- - -.. autoclass:: SecurityClient - :members: - -SQL ---- - -.. autoclass:: SqlClient - :members: - -Tasks ------ - -.. autoclass:: TasksClient - :members: - -Transforms ----------- - -.. autoclass:: TransformClient - :members: +.. toctree:: + :maxdepth: 1 + + api/elasticsearch + api/async-search + api/cat + api/cluster + api/connector + api/enrich-policies + api/eql + api/esql + api/indices + api/inference + api/ingest-pipelines + api/license + api/logstash + api/ml + api/nodes + api/query-rules + api/search-application + api/security + api/sql + api/synonyms + api/tasks + api/transforms diff --git a/docs/sphinx/api/async-search.rst b/docs/sphinx/api/async-search.rst new file mode 100644 index 0000000..f67334e --- /dev/null +++ b/docs/sphinx/api/async-search.rst @@ -0,0 +1,10 @@ +.. _async_search: + +Async Search +------------ + +.. py:module:: elasticsearch_serverless.client + :no-index: + +.. autoclass:: AsyncSearchClient + :members: diff --git a/docs/sphinx/api/cat.rst b/docs/sphinx/api/cat.rst new file mode 100644 index 0000000..9ef56b7 --- /dev/null +++ b/docs/sphinx/api/cat.rst @@ -0,0 +1,9 @@ +.. _cat: + +Cat +--- +.. py:module:: elasticsearch_serverless.client + :no-index: + +.. autoclass:: CatClient + :members: \ No newline at end of file diff --git a/docs/sphinx/api/cluster.rst b/docs/sphinx/api/cluster.rst new file mode 100644 index 0000000..6d6ce42 --- /dev/null +++ b/docs/sphinx/api/cluster.rst @@ -0,0 +1,9 @@ +.. _cluster: + +Cluster +------- +.. py:module:: elasticsearch_serverless.client + :no-index: + +.. autoclass:: ClusterClient + :members: \ No newline at end of file diff --git a/docs/sphinx/api/connector.rst b/docs/sphinx/api/connector.rst new file mode 100644 index 0000000..e4958a5 --- /dev/null +++ b/docs/sphinx/api/connector.rst @@ -0,0 +1,9 @@ +.. _connector: + +Connector +--------- +.. py:module:: elasticsearch_serverless.client + :no-index: + +.. autoclass:: ConnectorClient + :members: diff --git a/docs/sphinx/api/elasticsearch.rst b/docs/sphinx/api/elasticsearch.rst new file mode 100644 index 0000000..a6b430f --- /dev/null +++ b/docs/sphinx/api/elasticsearch.rst @@ -0,0 +1,9 @@ +.. _elasticsearch: + +Elasticsearch +------------- + +.. py:module:: elasticsearch_serverless + +.. autoclass:: Elasticsearch + :members: diff --git a/docs/sphinx/api/enrich-policies.rst b/docs/sphinx/api/enrich-policies.rst new file mode 100644 index 0000000..60290a2 --- /dev/null +++ b/docs/sphinx/api/enrich-policies.rst @@ -0,0 +1,9 @@ +.. _enrich-policies: + +Enrich Policies +--------------- +.. py:module:: elasticsearch_serverless.client + :no-index: + +.. autoclass:: EnrichClient + :members: \ No newline at end of file diff --git a/docs/sphinx/api/eql.rst b/docs/sphinx/api/eql.rst new file mode 100644 index 0000000..5eee334 --- /dev/null +++ b/docs/sphinx/api/eql.rst @@ -0,0 +1,9 @@ +.. _eql: + +Event Query Language (EQL) +-------------------------- +.. py:module:: elasticsearch_serverless.client + :no-index: + +.. autoclass:: EqlClient + :members: \ No newline at end of file diff --git a/docs/sphinx/api/esql.rst b/docs/sphinx/api/esql.rst new file mode 100644 index 0000000..af5da0a --- /dev/null +++ b/docs/sphinx/api/esql.rst @@ -0,0 +1,9 @@ +.. _esql: + +ES|QL +----- +.. py:module:: elasticsearch_serverless.client + :no-index: + +.. autoclass:: EsqlClient + :members: \ No newline at end of file diff --git a/docs/sphinx/api/indices.rst b/docs/sphinx/api/indices.rst new file mode 100644 index 0000000..096e249 --- /dev/null +++ b/docs/sphinx/api/indices.rst @@ -0,0 +1,9 @@ +.. _indices: + +Indices +------- +.. py:module:: elasticsearch_serverless.client + :no-index: + +.. autoclass:: IndicesClient + :members: \ No newline at end of file diff --git a/docs/sphinx/api/inference.rst b/docs/sphinx/api/inference.rst new file mode 100644 index 0000000..3751bba --- /dev/null +++ b/docs/sphinx/api/inference.rst @@ -0,0 +1,9 @@ +.. _inference: + +Inference +--------- +.. py:module:: elasticsearch_serverless.client + :no-index: + +.. autoclass:: InferenceClient + :members: diff --git a/docs/sphinx/api/ingest-pipelines.rst b/docs/sphinx/api/ingest-pipelines.rst new file mode 100644 index 0000000..a71d902 --- /dev/null +++ b/docs/sphinx/api/ingest-pipelines.rst @@ -0,0 +1,9 @@ +.. _ingest-pipelines: + +Ingest Pipelines +---------------- +.. py:module:: elasticsearch_serverless.client + :no-index: + +.. autoclass:: IngestClient + :members: \ No newline at end of file diff --git a/docs/sphinx/api/license.rst b/docs/sphinx/api/license.rst new file mode 100644 index 0000000..948029d --- /dev/null +++ b/docs/sphinx/api/license.rst @@ -0,0 +1,9 @@ +.. _license: + +License +------- +.. py:module:: elasticsearch_serverless.client + :no-index: + +.. autoclass:: LicenseClient + :members: \ No newline at end of file diff --git a/docs/sphinx/api/logstash.rst b/docs/sphinx/api/logstash.rst new file mode 100644 index 0000000..78cf641 --- /dev/null +++ b/docs/sphinx/api/logstash.rst @@ -0,0 +1,9 @@ +.. _logstash: + +Logstash +-------- +.. py:module:: elasticsearch_serverless.client + :no-index: + +.. autoclass:: LogstashClient + :members: \ No newline at end of file diff --git a/docs/sphinx/api/ml.rst b/docs/sphinx/api/ml.rst new file mode 100644 index 0000000..437d824 --- /dev/null +++ b/docs/sphinx/api/ml.rst @@ -0,0 +1,9 @@ +.. _ml: + +Machine Learning (ML) +--------------------- +.. py:module:: elasticsearch_serverless.client + :no-index: + +.. autoclass:: MlClient + :members: \ No newline at end of file diff --git a/docs/sphinx/api/nodes.rst b/docs/sphinx/api/nodes.rst new file mode 100644 index 0000000..b338545 --- /dev/null +++ b/docs/sphinx/api/nodes.rst @@ -0,0 +1,9 @@ +.. _nodes: + +Nodes +----- +.. py:module:: elasticsearch_serverless.client + :no-index: + +.. autoclass:: NodesClient + :members: \ No newline at end of file diff --git a/docs/sphinx/api/query-rules.rst b/docs/sphinx/api/query-rules.rst new file mode 100644 index 0000000..7839fd1 --- /dev/null +++ b/docs/sphinx/api/query-rules.rst @@ -0,0 +1,9 @@ +.. _query-rules: + +Query rules +----------- +.. py:module:: elasticsearch_serverless.client + :no-index: + +.. autoclass:: QueryRulesClient + :members: diff --git a/docs/sphinx/api/search-application.rst b/docs/sphinx/api/search-application.rst new file mode 100644 index 0000000..daf6053 --- /dev/null +++ b/docs/sphinx/api/search-application.rst @@ -0,0 +1,9 @@ +.. _search-application: + +Search Applications +------------------- +.. py:module:: elasticsearch_serverless.client + :no-index: + +.. autoclass:: SearchApplicationClient + :members: \ No newline at end of file diff --git a/docs/sphinx/api/security.rst b/docs/sphinx/api/security.rst new file mode 100644 index 0000000..f511db2 --- /dev/null +++ b/docs/sphinx/api/security.rst @@ -0,0 +1,9 @@ +.. _security: + +Security +-------- +.. py:module:: elasticsearch_serverless.client + :no-index: + +.. autoclass:: SecurityClient + :members: \ No newline at end of file diff --git a/docs/sphinx/api/sql.rst b/docs/sphinx/api/sql.rst new file mode 100644 index 0000000..24fa383 --- /dev/null +++ b/docs/sphinx/api/sql.rst @@ -0,0 +1,9 @@ +.. _sql: + +SQL +--- +.. py:module:: elasticsearch_serverless.client + :no-index: + +.. autoclass:: SqlClient + :members: \ No newline at end of file diff --git a/docs/sphinx/api/synonyms.rst b/docs/sphinx/api/synonyms.rst new file mode 100644 index 0000000..e4aab7b --- /dev/null +++ b/docs/sphinx/api/synonyms.rst @@ -0,0 +1,9 @@ +.. _synonyms: + +Synonyms +-------- +.. py:module:: elasticsearch_serverless.client + :no-index: + +.. autoclass:: SynonymsClient + :members: \ No newline at end of file diff --git a/docs/sphinx/api/tasks.rst b/docs/sphinx/api/tasks.rst new file mode 100644 index 0000000..2bd52b7 --- /dev/null +++ b/docs/sphinx/api/tasks.rst @@ -0,0 +1,9 @@ +.. _tasks: + +Tasks +----- +.. py:module:: elasticsearch_serverless.client + :no-index: + +.. autoclass:: TasksClient + :members: \ No newline at end of file diff --git a/docs/sphinx/api/transforms.rst b/docs/sphinx/api/transforms.rst new file mode 100644 index 0000000..2d53f3d --- /dev/null +++ b/docs/sphinx/api/transforms.rst @@ -0,0 +1,9 @@ +.. _transforms: + +Transforms +---------- +.. py:module:: elasticsearch_serverless.client + :no-index: + +.. autoclass:: TransformClient + :members: \ No newline at end of file diff --git a/docs/sphinx/async.rst b/docs/sphinx/async.rst index 095cd3c..dc42914 100644 --- a/docs/sphinx/async.rst +++ b/docs/sphinx/async.rst @@ -2,6 +2,7 @@ Using Asyncio with Elasticsearch ================================ .. py:module:: elasticsearch + :noindex: For Python 3.6+ the ``elasticsearch_serverless`` package supports async/await with `Asyncio `_ and `Aiohttp `_. @@ -117,6 +118,7 @@ All async helpers that accept an iterator or generator also accept async iterato and async generators. .. py:module:: elasticsearch_serverless.helpers + :noindex: Bulk and Streaming Bulk ~~~~~~~~~~~~~~~~~~~~~~~ @@ -206,6 +208,8 @@ API Reference ------------- .. py:module:: elasticsearch_serverless + :noindex: + The API of :class:`~elasticsearch_serverless.AsyncElasticsearch` is nearly identical to the API of :class:`~elasticsearch_serverless.Elasticsearch` with the exception that diff --git a/docs/sphinx/exceptions.rst b/docs/sphinx/exceptions.rst index 914c64b..1b8d99a 100644 --- a/docs/sphinx/exceptions.rst +++ b/docs/sphinx/exceptions.rst @@ -4,6 +4,7 @@ Exceptions & Warnings ===================== .. py:module:: elasticsearch_serverless + :noindex: API Errors ---------- From 731fcf1af52ca2ad9e5fbdfdbe7e78b7220238f3 Mon Sep 17 00:00:00 2001 From: Quentin Pradet Date: Thu, 6 Mar 2025 12:18:53 +0400 Subject: [PATCH 4/6] Replace no-index with noindex --- docs/sphinx/api/async-search.rst | 2 +- docs/sphinx/api/cat.rst | 2 +- docs/sphinx/api/cluster.rst | 2 +- docs/sphinx/api/connector.rst | 2 +- docs/sphinx/api/enrich-policies.rst | 2 +- docs/sphinx/api/eql.rst | 2 +- docs/sphinx/api/esql.rst | 2 +- docs/sphinx/api/indices.rst | 2 +- docs/sphinx/api/inference.rst | 2 +- docs/sphinx/api/ingest-pipelines.rst | 2 +- docs/sphinx/api/license.rst | 2 +- docs/sphinx/api/logstash.rst | 2 +- docs/sphinx/api/ml.rst | 2 +- docs/sphinx/api/nodes.rst | 2 +- docs/sphinx/api/query-rules.rst | 2 +- docs/sphinx/api/search-application.rst | 2 +- docs/sphinx/api/security.rst | 2 +- docs/sphinx/api/sql.rst | 2 +- docs/sphinx/api/synonyms.rst | 2 +- docs/sphinx/api/tasks.rst | 2 +- docs/sphinx/api/transforms.rst | 2 +- 21 files changed, 21 insertions(+), 21 deletions(-) diff --git a/docs/sphinx/api/async-search.rst b/docs/sphinx/api/async-search.rst index f67334e..f5815dd 100644 --- a/docs/sphinx/api/async-search.rst +++ b/docs/sphinx/api/async-search.rst @@ -4,7 +4,7 @@ Async Search ------------ .. py:module:: elasticsearch_serverless.client - :no-index: + :noindex: .. autoclass:: AsyncSearchClient :members: diff --git a/docs/sphinx/api/cat.rst b/docs/sphinx/api/cat.rst index 9ef56b7..a0f0a0d 100644 --- a/docs/sphinx/api/cat.rst +++ b/docs/sphinx/api/cat.rst @@ -3,7 +3,7 @@ Cat --- .. py:module:: elasticsearch_serverless.client - :no-index: + :noindex: .. autoclass:: CatClient :members: \ No newline at end of file diff --git a/docs/sphinx/api/cluster.rst b/docs/sphinx/api/cluster.rst index 6d6ce42..2cb7859 100644 --- a/docs/sphinx/api/cluster.rst +++ b/docs/sphinx/api/cluster.rst @@ -3,7 +3,7 @@ Cluster ------- .. py:module:: elasticsearch_serverless.client - :no-index: + :noindex: .. autoclass:: ClusterClient :members: \ No newline at end of file diff --git a/docs/sphinx/api/connector.rst b/docs/sphinx/api/connector.rst index e4958a5..627779b 100644 --- a/docs/sphinx/api/connector.rst +++ b/docs/sphinx/api/connector.rst @@ -3,7 +3,7 @@ Connector --------- .. py:module:: elasticsearch_serverless.client - :no-index: + :noindex: .. autoclass:: ConnectorClient :members: diff --git a/docs/sphinx/api/enrich-policies.rst b/docs/sphinx/api/enrich-policies.rst index 60290a2..223fac4 100644 --- a/docs/sphinx/api/enrich-policies.rst +++ b/docs/sphinx/api/enrich-policies.rst @@ -3,7 +3,7 @@ Enrich Policies --------------- .. py:module:: elasticsearch_serverless.client - :no-index: + :noindex: .. autoclass:: EnrichClient :members: \ No newline at end of file diff --git a/docs/sphinx/api/eql.rst b/docs/sphinx/api/eql.rst index 5eee334..c49a256 100644 --- a/docs/sphinx/api/eql.rst +++ b/docs/sphinx/api/eql.rst @@ -3,7 +3,7 @@ Event Query Language (EQL) -------------------------- .. py:module:: elasticsearch_serverless.client - :no-index: + :noindex: .. autoclass:: EqlClient :members: \ No newline at end of file diff --git a/docs/sphinx/api/esql.rst b/docs/sphinx/api/esql.rst index af5da0a..e824c2c 100644 --- a/docs/sphinx/api/esql.rst +++ b/docs/sphinx/api/esql.rst @@ -3,7 +3,7 @@ ES|QL ----- .. py:module:: elasticsearch_serverless.client - :no-index: + :noindex: .. autoclass:: EsqlClient :members: \ No newline at end of file diff --git a/docs/sphinx/api/indices.rst b/docs/sphinx/api/indices.rst index 096e249..95965af 100644 --- a/docs/sphinx/api/indices.rst +++ b/docs/sphinx/api/indices.rst @@ -3,7 +3,7 @@ Indices ------- .. py:module:: elasticsearch_serverless.client - :no-index: + :noindex: .. autoclass:: IndicesClient :members: \ No newline at end of file diff --git a/docs/sphinx/api/inference.rst b/docs/sphinx/api/inference.rst index 3751bba..c58afec 100644 --- a/docs/sphinx/api/inference.rst +++ b/docs/sphinx/api/inference.rst @@ -3,7 +3,7 @@ Inference --------- .. py:module:: elasticsearch_serverless.client - :no-index: + :noindex: .. autoclass:: InferenceClient :members: diff --git a/docs/sphinx/api/ingest-pipelines.rst b/docs/sphinx/api/ingest-pipelines.rst index a71d902..93af714 100644 --- a/docs/sphinx/api/ingest-pipelines.rst +++ b/docs/sphinx/api/ingest-pipelines.rst @@ -3,7 +3,7 @@ Ingest Pipelines ---------------- .. py:module:: elasticsearch_serverless.client - :no-index: + :noindex: .. autoclass:: IngestClient :members: \ No newline at end of file diff --git a/docs/sphinx/api/license.rst b/docs/sphinx/api/license.rst index 948029d..c482aea 100644 --- a/docs/sphinx/api/license.rst +++ b/docs/sphinx/api/license.rst @@ -3,7 +3,7 @@ License ------- .. py:module:: elasticsearch_serverless.client - :no-index: + :noindex: .. autoclass:: LicenseClient :members: \ No newline at end of file diff --git a/docs/sphinx/api/logstash.rst b/docs/sphinx/api/logstash.rst index 78cf641..a46e332 100644 --- a/docs/sphinx/api/logstash.rst +++ b/docs/sphinx/api/logstash.rst @@ -3,7 +3,7 @@ Logstash -------- .. py:module:: elasticsearch_serverless.client - :no-index: + :noindex: .. autoclass:: LogstashClient :members: \ No newline at end of file diff --git a/docs/sphinx/api/ml.rst b/docs/sphinx/api/ml.rst index 437d824..c72b3d3 100644 --- a/docs/sphinx/api/ml.rst +++ b/docs/sphinx/api/ml.rst @@ -3,7 +3,7 @@ Machine Learning (ML) --------------------- .. py:module:: elasticsearch_serverless.client - :no-index: + :noindex: .. autoclass:: MlClient :members: \ No newline at end of file diff --git a/docs/sphinx/api/nodes.rst b/docs/sphinx/api/nodes.rst index b338545..ce80fce 100644 --- a/docs/sphinx/api/nodes.rst +++ b/docs/sphinx/api/nodes.rst @@ -3,7 +3,7 @@ Nodes ----- .. py:module:: elasticsearch_serverless.client - :no-index: + :noindex: .. autoclass:: NodesClient :members: \ No newline at end of file diff --git a/docs/sphinx/api/query-rules.rst b/docs/sphinx/api/query-rules.rst index 7839fd1..773bfee 100644 --- a/docs/sphinx/api/query-rules.rst +++ b/docs/sphinx/api/query-rules.rst @@ -3,7 +3,7 @@ Query rules ----------- .. py:module:: elasticsearch_serverless.client - :no-index: + :noindex: .. autoclass:: QueryRulesClient :members: diff --git a/docs/sphinx/api/search-application.rst b/docs/sphinx/api/search-application.rst index daf6053..65fb1fe 100644 --- a/docs/sphinx/api/search-application.rst +++ b/docs/sphinx/api/search-application.rst @@ -3,7 +3,7 @@ Search Applications ------------------- .. py:module:: elasticsearch_serverless.client - :no-index: + :noindex: .. autoclass:: SearchApplicationClient :members: \ No newline at end of file diff --git a/docs/sphinx/api/security.rst b/docs/sphinx/api/security.rst index f511db2..ce18981 100644 --- a/docs/sphinx/api/security.rst +++ b/docs/sphinx/api/security.rst @@ -3,7 +3,7 @@ Security -------- .. py:module:: elasticsearch_serverless.client - :no-index: + :noindex: .. autoclass:: SecurityClient :members: \ No newline at end of file diff --git a/docs/sphinx/api/sql.rst b/docs/sphinx/api/sql.rst index 24fa383..0f33f9f 100644 --- a/docs/sphinx/api/sql.rst +++ b/docs/sphinx/api/sql.rst @@ -3,7 +3,7 @@ SQL --- .. py:module:: elasticsearch_serverless.client - :no-index: + :noindex: .. autoclass:: SqlClient :members: \ No newline at end of file diff --git a/docs/sphinx/api/synonyms.rst b/docs/sphinx/api/synonyms.rst index e4aab7b..b3edb7f 100644 --- a/docs/sphinx/api/synonyms.rst +++ b/docs/sphinx/api/synonyms.rst @@ -3,7 +3,7 @@ Synonyms -------- .. py:module:: elasticsearch_serverless.client - :no-index: + :noindex: .. autoclass:: SynonymsClient :members: \ No newline at end of file diff --git a/docs/sphinx/api/tasks.rst b/docs/sphinx/api/tasks.rst index 2bd52b7..e74085f 100644 --- a/docs/sphinx/api/tasks.rst +++ b/docs/sphinx/api/tasks.rst @@ -3,7 +3,7 @@ Tasks ----- .. py:module:: elasticsearch_serverless.client - :no-index: + :noindex: .. autoclass:: TasksClient :members: \ No newline at end of file diff --git a/docs/sphinx/api/transforms.rst b/docs/sphinx/api/transforms.rst index 2d53f3d..45e0b22 100644 --- a/docs/sphinx/api/transforms.rst +++ b/docs/sphinx/api/transforms.rst @@ -3,7 +3,7 @@ Transforms ---------- .. py:module:: elasticsearch_serverless.client - :no-index: + :noindex: .. autoclass:: TransformClient :members: \ No newline at end of file From cd733731955877136af062f2b43bf6278a75cb86 Mon Sep 17 00:00:00 2001 From: Quentin Pradet Date: Thu, 6 Mar 2025 12:23:48 +0400 Subject: [PATCH 5/6] Fix more warnings --- docs/sphinx/api.rst | 1 - docs/sphinx/api/nodes.rst | 9 --------- elasticsearch_serverless/client.py | 3 +++ 3 files changed, 3 insertions(+), 10 deletions(-) delete mode 100644 docs/sphinx/api/nodes.rst diff --git a/docs/sphinx/api.rst b/docs/sphinx/api.rst index 9092836..c58b70a 100644 --- a/docs/sphinx/api.rst +++ b/docs/sphinx/api.rst @@ -32,7 +32,6 @@ arguments are required for all api/license api/logstash api/ml - api/nodes api/query-rules api/search-application api/security diff --git a/docs/sphinx/api/nodes.rst b/docs/sphinx/api/nodes.rst deleted file mode 100644 index ce80fce..0000000 --- a/docs/sphinx/api/nodes.rst +++ /dev/null @@ -1,9 +0,0 @@ -.. _nodes: - -Nodes ------ -.. py:module:: elasticsearch_serverless.client - :noindex: - -.. autoclass:: NodesClient - :members: \ No newline at end of file diff --git a/elasticsearch_serverless/client.py b/elasticsearch_serverless/client.py index e79a217..a2383bf 100644 --- a/elasticsearch_serverless/client.py +++ b/elasticsearch_serverless/client.py @@ -35,6 +35,9 @@ from ._sync.client.logstash import LogstashClient as LogstashClient # noqa: F401 from ._sync.client.ml import MlClient as MlClient # noqa: F401 from ._sync.client.query_rules import QueryRulesClient as QueryRulesClient # noqa: F401 +from ._sync.client.search_application import ( + SearchApplicationClient as SearchApplicationClient, +) # noqa: F401 from ._sync.client.security import SecurityClient as SecurityClient # noqa: F401 from ._sync.client.sql import SqlClient as SqlClient # noqa: F401 from ._sync.client.synonyms import SynonymsClient as SynonymsClient # noqa: F401 From 4600df14f9af0ce8ef058c9a728ae1eda6c6ca18 Mon Sep 17 00:00:00 2001 From: Quentin Pradet Date: Thu, 6 Mar 2025 12:26:43 +0400 Subject: [PATCH 6/6] Fix lint --- elasticsearch_serverless/client.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/elasticsearch_serverless/client.py b/elasticsearch_serverless/client.py index a2383bf..4f7161b 100644 --- a/elasticsearch_serverless/client.py +++ b/elasticsearch_serverless/client.py @@ -35,9 +35,9 @@ from ._sync.client.logstash import LogstashClient as LogstashClient # noqa: F401 from ._sync.client.ml import MlClient as MlClient # noqa: F401 from ._sync.client.query_rules import QueryRulesClient as QueryRulesClient # noqa: F401 -from ._sync.client.search_application import ( +from ._sync.client.search_application import ( # noqa: F401 SearchApplicationClient as SearchApplicationClient, -) # noqa: F401 +) from ._sync.client.security import SecurityClient as SecurityClient # noqa: F401 from ._sync.client.sql import SqlClient as SqlClient # noqa: F401 from ._sync.client.synonyms import SynonymsClient as SynonymsClient # noqa: F401