diff --git a/elasticsearch/_async/client/__init__.py b/elasticsearch/_async/client/__init__.py index caf342a07..d4524deda 100644 --- a/elasticsearch/_async/client/__init__.py +++ b/elasticsearch/_async/client/__init__.py @@ -646,41 +646,125 @@ 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. + 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 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( @@ -760,7 +844,7 @@ async def clear_scroll( ``_ - :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" @@ -884,46 +968,62 @@ 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. + Count search results. Get the number of documents matching a query. The query + can either be provided using a simple query string as a parameter or using the + Query DSL defined within the request body. The latter must be nested in a `query` + key, which is the same as the search API. 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. + :param query: Defines the search definition using the Query DSL. The query is + optional, and when not provided, it will use `match_all` to count all the + docs. + :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: @@ -2491,9 +2591,9 @@ async def info( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Get cluster info. Returns basic information about the cluster. + Get cluster info. Get basic build, version, and cluster information. - ``_ + ``_ """ __path_parts: t.Dict[str, str] = {} __path = "/" @@ -4464,6 +4564,7 @@ async def search_shards( human: t.Optional[bool] = None, ignore_unavailable: t.Optional[bool] = None, local: t.Optional[bool] = None, + master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, preference: t.Optional[str] = None, pretty: t.Optional[bool] = None, routing: t.Optional[str] = None, @@ -4491,6 +4592,7 @@ async def search_shards( a missing or closed index. :param local: If `true`, the request retrieves information from the local node only. + :param master_timeout: Period to wait for a connection to the master node. :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. @@ -4517,6 +4619,8 @@ async def search_shards( __query["ignore_unavailable"] = ignore_unavailable if local is not None: __query["local"] = local + if master_timeout is not None: + __query["master_timeout"] = master_timeout if preference is not None: __query["preference"] = preference if pretty is not None: diff --git a/elasticsearch/_async/client/ccr.py b/elasticsearch/_async/client/ccr.py index a86dca8f7..c95f62bfd 100644 --- a/elasticsearch/_async/client/ccr.py +++ b/elasticsearch/_async/client/ccr.py @@ -33,6 +33,7 @@ async def delete_auto_follow_pattern( error_trace: t.Optional[bool] = None, filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, human: t.Optional[bool] = None, + master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ @@ -42,6 +43,7 @@ async def delete_auto_follow_pattern( ``_ :param name: The name of the auto follow pattern. + :param master_timeout: Period to wait for a connection to the master node. """ if name in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'name'") @@ -54,6 +56,8 @@ async def delete_auto_follow_pattern( __query["filter_path"] = filter_path if human is not None: __query["human"] = human + if master_timeout is not None: + __query["master_timeout"] = master_timeout if pretty is not None: __query["pretty"] = pretty __headers = {"accept": "application/json"} @@ -94,6 +98,7 @@ async def follow( error_trace: t.Optional[bool] = None, filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, human: t.Optional[bool] = None, + master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, max_outstanding_read_requests: t.Optional[int] = None, max_outstanding_write_requests: t.Optional[int] = None, max_read_request_operation_count: t.Optional[int] = None, @@ -124,6 +129,7 @@ async def follow( :param remote_cluster: The remote cluster containing the leader index. :param data_stream_name: If the leader index is part of a data stream, the name to which the local data stream for the followed index should be renamed. + :param master_timeout: Period to wait for a connection to the master node. :param max_outstanding_read_requests: The maximum number of outstanding reads requests from the remote cluster. :param max_outstanding_write_requests: The maximum number of outstanding write @@ -174,6 +180,8 @@ async def follow( __query["filter_path"] = filter_path if human is not None: __query["human"] = human + if master_timeout is not None: + __query["master_timeout"] = master_timeout if pretty is not None: __query["pretty"] = pretty if wait_for_active_shards is not None: @@ -232,6 +240,7 @@ async def follow_info( error_trace: t.Optional[bool] = None, filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, human: t.Optional[bool] = None, + master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ @@ -244,6 +253,7 @@ async def follow_info( :param index: A comma-separated list of index patterns; use `_all` to perform the operation on all indices + :param master_timeout: Period to wait for a connection to the master node. """ if index in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'index'") @@ -256,6 +266,8 @@ async def follow_info( __query["filter_path"] = filter_path if human is not None: __query["human"] = human + if master_timeout is not None: + __query["master_timeout"] = master_timeout if pretty is not None: __query["pretty"] = pretty __headers = {"accept": "application/json"} @@ -277,6 +289,7 @@ async def follow_stats( filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, human: t.Optional[bool] = None, pretty: t.Optional[bool] = None, + timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, ) -> ObjectApiResponse[t.Any]: """ Get follower stats. Get cross-cluster replication follower stats. The API returns @@ -287,6 +300,8 @@ async def follow_stats( :param index: A comma-separated list of index patterns; use `_all` to perform the operation on all indices + :param timeout: Period to wait for a response. If no response is received before + the timeout expires, the request fails and returns an error. """ if index in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'index'") @@ -301,6 +316,8 @@ async def follow_stats( __query["human"] = human if pretty is not None: __query["pretty"] = pretty + if timeout is not None: + __query["timeout"] = timeout __headers = {"accept": "application/json"} return await self.perform_request( # type: ignore[return-value] "GET", @@ -331,6 +348,7 @@ async def forget_follower( human: t.Optional[bool] = None, leader_remote_cluster: t.Optional[str] = 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]: """ @@ -360,6 +378,8 @@ async def forget_follower( :param follower_index: :param follower_index_uuid: :param leader_remote_cluster: + :param timeout: Period to wait for a response. If no response is received before + the timeout expires, the request fails and returns an error. """ if index in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'index'") @@ -375,6 +395,8 @@ async def forget_follower( __query["human"] = human if pretty is not None: __query["pretty"] = pretty + if timeout is not None: + __query["timeout"] = timeout if not __body: if follower_cluster is not None: __body["follower_cluster"] = follower_cluster @@ -403,6 +425,7 @@ async def get_auto_follow_pattern( error_trace: t.Optional[bool] = None, filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, human: t.Optional[bool] = None, + master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ @@ -412,6 +435,7 @@ async def get_auto_follow_pattern( :param name: Specifies the auto-follow pattern collection that you want to retrieve. If you do not specify a name, the API returns information for all collections. + :param master_timeout: Period to wait for a connection to the master node. """ __path_parts: t.Dict[str, str] if name not in SKIP_IN_PATH: @@ -427,6 +451,8 @@ async def get_auto_follow_pattern( __query["filter_path"] = filter_path if human is not None: __query["human"] = human + if master_timeout is not None: + __query["master_timeout"] = master_timeout if pretty is not None: __query["pretty"] = pretty __headers = {"accept": "application/json"} @@ -447,6 +473,7 @@ async def pause_auto_follow_pattern( error_trace: t.Optional[bool] = None, filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, human: t.Optional[bool] = None, + master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ @@ -463,6 +490,7 @@ async def pause_auto_follow_pattern( :param name: The name of the auto follow pattern that should pause discovering new indices to follow. + :param master_timeout: Period to wait for a connection to the master node. """ if name in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'name'") @@ -475,6 +503,8 @@ async def pause_auto_follow_pattern( __query["filter_path"] = filter_path if human is not None: __query["human"] = human + if master_timeout is not None: + __query["master_timeout"] = master_timeout if pretty is not None: __query["pretty"] = pretty __headers = {"accept": "application/json"} @@ -495,6 +525,7 @@ async def pause_follow( error_trace: t.Optional[bool] = None, filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, human: t.Optional[bool] = None, + master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ @@ -507,6 +538,7 @@ async def pause_follow( :param index: The name of the follower index that should pause following its leader index. + :param master_timeout: Period to wait for a connection to the master node. """ if index in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'index'") @@ -519,6 +551,8 @@ async def pause_follow( __query["filter_path"] = filter_path if human is not None: __query["human"] = human + if master_timeout is not None: + __query["master_timeout"] = master_timeout if pretty is not None: __query["pretty"] = pretty __headers = {"accept": "application/json"} @@ -561,6 +595,7 @@ async def put_auto_follow_pattern( human: t.Optional[bool] = None, leader_index_exclusion_patterns: t.Optional[t.Sequence[str]] = None, leader_index_patterns: t.Optional[t.Sequence[str]] = None, + master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, max_outstanding_read_requests: t.Optional[int] = None, max_outstanding_write_requests: t.Optional[int] = None, max_read_request_operation_count: t.Optional[int] = None, @@ -600,6 +635,7 @@ async def put_auto_follow_pattern( or more leader_index_exclusion_patterns won’t be followed. :param leader_index_patterns: An array of simple index patterns to match against indices in the remote cluster specified by the remote_cluster field. + :param master_timeout: Period to wait for a connection to the master node. :param max_outstanding_read_requests: The maximum number of outstanding reads requests from the remote cluster. :param max_outstanding_write_requests: The maximum number of outstanding reads @@ -644,6 +680,8 @@ async def put_auto_follow_pattern( __query["filter_path"] = filter_path if human is not None: __query["human"] = human + if master_timeout is not None: + __query["master_timeout"] = master_timeout if pretty is not None: __query["pretty"] = pretty if not __body: @@ -704,6 +742,7 @@ async def resume_auto_follow_pattern( error_trace: t.Optional[bool] = None, filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, human: t.Optional[bool] = None, + master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ @@ -717,6 +756,7 @@ async def resume_auto_follow_pattern( :param name: The name of the auto follow pattern to resume discovering new indices to follow. + :param master_timeout: Period to wait for a connection to the master node. """ if name in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'name'") @@ -729,6 +769,8 @@ async def resume_auto_follow_pattern( __query["filter_path"] = filter_path if human is not None: __query["human"] = human + if master_timeout is not None: + __query["master_timeout"] = master_timeout if pretty is not None: __query["pretty"] = pretty __headers = {"accept": "application/json"} @@ -762,6 +804,7 @@ async def resume_follow( error_trace: t.Optional[bool] = None, filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, human: t.Optional[bool] = None, + master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, max_outstanding_read_requests: t.Optional[int] = None, max_outstanding_write_requests: t.Optional[int] = None, max_read_request_operation_count: t.Optional[int] = None, @@ -785,6 +828,7 @@ async def resume_follow( ``_ :param index: The name of the follow index to resume following. + :param master_timeout: Period to wait for a connection to the master node. :param max_outstanding_read_requests: :param max_outstanding_write_requests: :param max_read_request_operation_count: @@ -808,6 +852,8 @@ async def resume_follow( __query["filter_path"] = filter_path if human is not None: __query["human"] = human + if master_timeout is not None: + __query["master_timeout"] = master_timeout if pretty is not None: __query["pretty"] = pretty if not __body: @@ -859,13 +905,19 @@ async def stats( error_trace: t.Optional[bool] = None, filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, human: t.Optional[bool] = None, + 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, ) -> ObjectApiResponse[t.Any]: """ Get cross-cluster replication stats. This API returns stats about auto-following and the same shard-level stats as the get follower stats API. ``_ + + :param master_timeout: Period to wait for a connection to the master node. + :param timeout: Period to wait for a response. If no response is received before + the timeout expires, the request fails and returns an error. """ __path_parts: t.Dict[str, str] = {} __path = "/_ccr/stats" @@ -876,8 +928,12 @@ async def stats( __query["filter_path"] = filter_path if human is not None: __query["human"] = human + if master_timeout is not None: + __query["master_timeout"] = master_timeout if pretty is not None: __query["pretty"] = pretty + if timeout is not None: + __query["timeout"] = timeout __headers = {"accept": "application/json"} return await self.perform_request( # type: ignore[return-value] "GET", @@ -896,6 +952,7 @@ async def unfollow( error_trace: t.Optional[bool] = None, filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, human: t.Optional[bool] = None, + master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ @@ -911,6 +968,7 @@ async def unfollow( :param index: The name of the follower index that should be turned into a regular index. + :param master_timeout: Period to wait for a connection to the master node. """ if index in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'index'") @@ -923,6 +981,8 @@ async def unfollow( __query["filter_path"] = filter_path if human is not None: __query["human"] = human + if master_timeout is not None: + __query["master_timeout"] = master_timeout if pretty is not None: __query["pretty"] = pretty __headers = {"accept": "application/json"} diff --git a/elasticsearch/_async/client/cluster.py b/elasticsearch/_async/client/cluster.py index 0ccd6ba5d..5d25c29a1 100644 --- a/elasticsearch/_async/client/cluster.py +++ b/elasticsearch/_async/client/cluster.py @@ -38,6 +38,7 @@ async def allocation_explain( include_disk_info: t.Optional[bool] = None, include_yes_decisions: t.Optional[bool] = None, index: t.Optional[str] = None, + master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, pretty: t.Optional[bool] = None, primary: t.Optional[bool] = None, shard: t.Optional[int] = None, @@ -61,6 +62,7 @@ async def allocation_explain( :param include_yes_decisions: If true, returns YES decisions in explanation. :param index: Specifies the name of the index that you would like an explanation for. + :param master_timeout: Period to wait for a connection to the master node. :param primary: If true, returns explanation for the primary shard for the given shard ID. :param shard: Specifies the ID of the shard that you would like an explanation @@ -80,6 +82,8 @@ async def allocation_explain( __query["include_disk_info"] = include_disk_info if include_yes_decisions is not None: __query["include_yes_decisions"] = include_yes_decisions + if master_timeout is not None: + __query["master_timeout"] = master_timeout if pretty is not None: __query["pretty"] = pretty if not __body: @@ -119,9 +123,8 @@ async def delete_component_template( timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, ) -> ObjectApiResponse[t.Any]: """ - Delete component templates. Deletes component templates. Component templates - are building blocks for constructing index templates that specify index mappings, - settings, and aliases. + Delete component templates. Component templates are building blocks for constructing + index templates that specify index mappings, settings, and aliases. ``_ @@ -167,6 +170,7 @@ async def delete_voting_config_exclusions( error_trace: t.Optional[bool] = None, filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, human: t.Optional[bool] = None, + master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, pretty: t.Optional[bool] = None, wait_for_removal: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: @@ -176,6 +180,7 @@ async def delete_voting_config_exclusions( ``_ + :param master_timeout: Period to wait for a connection to the master node. :param wait_for_removal: Specifies whether to wait for all excluded nodes to be removed from the cluster before clearing the voting configuration exclusions list. Defaults to true, meaning that all excluded nodes must be removed from @@ -192,6 +197,8 @@ async def delete_voting_config_exclusions( __query["filter_path"] = filter_path if human is not None: __query["human"] = human + if master_timeout is not None: + __query["master_timeout"] = master_timeout if pretty is not None: __query["pretty"] = pretty if wait_for_removal is not None: @@ -275,7 +282,7 @@ async def get_component_template( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Get component templates. Retrieves information about component templates. + Get component templates. Get information about component templates. ``_ @@ -625,6 +632,7 @@ async def post_voting_config_exclusions( error_trace: t.Optional[bool] = None, filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, human: t.Optional[bool] = None, + master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, node_ids: t.Optional[t.Union[str, t.Sequence[str]]] = None, node_names: t.Optional[t.Union[str, t.Sequence[str]]] = None, pretty: t.Optional[bool] = None, @@ -661,6 +669,7 @@ async def post_voting_config_exclusions( ``_ + :param master_timeout: Period to wait for a connection to the master node. :param node_ids: A comma-separated list of the persistent ids of the nodes to exclude from the voting configuration. If specified, you may not also specify node_names. @@ -680,6 +689,8 @@ async def post_voting_config_exclusions( __query["filter_path"] = filter_path if human is not None: __query["human"] = human + if master_timeout is not None: + __query["master_timeout"] = master_timeout if node_ids is not None: __query["node_ids"] = node_ids if node_names is not None: @@ -719,20 +730,21 @@ async def put_component_template( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Create or update a component template. Creates or updates 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. + 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. + 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. ``_ @@ -755,8 +767,8 @@ async def put_component_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 meta: Optional user metadata about the component template. May have any - contents. This map is not automatically generated by Elasticsearch. This + :param meta: Optional user metadata about the component template. It may have + any contents. This map is not automatically generated by Elasticsearch. This information is stored in the cluster state, so keeping it short is preferable. To unset `_meta`, replace the template without specifying this information. :param version: Version number used to manage component templates externally. diff --git a/elasticsearch/_async/client/connector.py b/elasticsearch/_async/client/connector.py index d65ef97f8..58d77a778 100644 --- a/elasticsearch/_async/client/connector.py +++ b/elasticsearch/_async/client/connector.py @@ -996,6 +996,106 @@ async def sync_job_post( path_parts=__path_parts, ) + @_rewrite_parameters( + body_fields=( + "deleted_document_count", + "indexed_document_count", + "indexed_document_volume", + "last_seen", + "metadata", + "total_document_count", + ), + ) + @_stability_warning(Stability.EXPERIMENTAL) + async def sync_job_update_stats( + self, + *, + connector_sync_job_id: str, + deleted_document_count: t.Optional[int] = None, + indexed_document_count: t.Optional[int] = None, + indexed_document_volume: t.Optional[int] = None, + error_trace: t.Optional[bool] = None, + filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, + human: t.Optional[bool] = None, + last_seen: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, + metadata: t.Optional[t.Mapping[str, t.Any]] = None, + pretty: t.Optional[bool] = None, + total_document_count: t.Optional[int] = None, + body: t.Optional[t.Dict[str, t.Any]] = None, + ) -> ObjectApiResponse[t.Any]: + """ + Set the connector sync job stats. Stats include: `deleted_document_count`, `indexed_document_count`, + `indexed_document_volume`, and `total_document_count`. You can also update `last_seen`. + This API is mainly used by the connector service for updating sync job information. + To sync data using self-managed connectors, you need to deploy the Elastic connector + service on your own infrastructure. This service runs automatically on Elastic + Cloud for Elastic managed connectors. + + ``_ + + :param connector_sync_job_id: The unique identifier of the connector sync job. + :param deleted_document_count: The number of documents the sync job deleted. + :param indexed_document_count: The number of documents the sync job indexed. + :param indexed_document_volume: The total size of the data (in MiB) the sync + job indexed. + :param last_seen: The timestamp to use in the `last_seen` property for the connector + sync job. + :param metadata: The connector-specific metadata. + :param total_document_count: The total number of documents in the target index + after the sync job finished. + """ + if connector_sync_job_id in SKIP_IN_PATH: + raise ValueError("Empty value passed for parameter 'connector_sync_job_id'") + if deleted_document_count is None and body is None: + raise ValueError( + "Empty value passed for parameter 'deleted_document_count'" + ) + if indexed_document_count is None and body is None: + raise ValueError( + "Empty value passed for parameter 'indexed_document_count'" + ) + if indexed_document_volume is None and body is None: + raise ValueError( + "Empty value passed for parameter 'indexed_document_volume'" + ) + __path_parts: t.Dict[str, str] = { + "connector_sync_job_id": _quote(connector_sync_job_id) + } + __path = f'/_connector/_sync_job/{__path_parts["connector_sync_job_id"]}/_stats' + __query: t.Dict[str, t.Any] = {} + __body: t.Dict[str, t.Any] = body if body is not None else {} + if error_trace is not None: + __query["error_trace"] = error_trace + if filter_path is not None: + __query["filter_path"] = filter_path + if human is not None: + __query["human"] = human + if pretty is not None: + __query["pretty"] = pretty + if not __body: + if deleted_document_count is not None: + __body["deleted_document_count"] = deleted_document_count + if indexed_document_count is not None: + __body["indexed_document_count"] = indexed_document_count + if indexed_document_volume is not None: + __body["indexed_document_volume"] = indexed_document_volume + if last_seen is not None: + __body["last_seen"] = last_seen + if metadata is not None: + __body["metadata"] = metadata + if total_document_count is not None: + __body["total_document_count"] = total_document_count + __headers = {"accept": "application/json", "content-type": "application/json"} + return await self.perform_request( # type: ignore[return-value] + "PUT", + __path, + params=__query, + headers=__headers, + body=__body, + endpoint_id="connector.sync_job_update_stats", + path_parts=__path_parts, + ) + @_rewrite_parameters() @_stability_warning(Stability.EXPERIMENTAL) async def update_active_filtering( diff --git a/elasticsearch/_async/client/dangling_indices.py b/elasticsearch/_async/client/dangling_indices.py index 59cc838fa..50289bc71 100644 --- a/elasticsearch/_async/client/dangling_indices.py +++ b/elasticsearch/_async/client/dangling_indices.py @@ -44,7 +44,7 @@ async def delete_dangling_index( For example, this can happen if you delete more than `cluster.indices.tombstones.size` indices while an Elasticsearch node is offline. - ``_ + ``_ :param index_uuid: The UUID of the index to delete. Use the get dangling indices API to find the UUID. @@ -103,7 +103,7 @@ async def import_dangling_index( For example, this can happen if you delete more than `cluster.indices.tombstones.size` indices while an Elasticsearch node is offline. - ``_ + ``_ :param index_uuid: The UUID of the index to import. Use the get dangling indices API to locate the UUID. @@ -162,7 +162,7 @@ async def list_dangling_indices( indices while an Elasticsearch node is offline. Use this API to list dangling indices, which you can then import or delete. - ``_ + ``_ """ __path_parts: t.Dict[str, str] = {} __path = "/_dangling" diff --git a/elasticsearch/_async/client/enrich.py b/elasticsearch/_async/client/enrich.py index 59edfeed9..792349b3a 100644 --- a/elasticsearch/_async/client/enrich.py +++ b/elasticsearch/_async/client/enrich.py @@ -33,6 +33,7 @@ async def delete_policy( error_trace: t.Optional[bool] = None, filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, human: t.Optional[bool] = None, + master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ @@ -41,6 +42,7 @@ async def delete_policy( ``_ :param name: Enrich policy to delete. + :param master_timeout: Period to wait for a connection to the master node. """ if name in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'name'") @@ -53,6 +55,8 @@ async def delete_policy( __query["filter_path"] = filter_path if human is not None: __query["human"] = human + if master_timeout is not None: + __query["master_timeout"] = master_timeout if pretty is not None: __query["pretty"] = pretty __headers = {"accept": "application/json"} @@ -73,6 +77,7 @@ async def execute_policy( error_trace: t.Optional[bool] = None, filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, human: t.Optional[bool] = None, + master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, pretty: t.Optional[bool] = None, wait_for_completion: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: @@ -82,6 +87,7 @@ async def execute_policy( ``_ :param name: Enrich policy to execute. + :param master_timeout: Period to wait for a connection to the master node. :param wait_for_completion: If `true`, the request blocks other enrich policy execution requests until complete. """ @@ -96,6 +102,8 @@ async def execute_policy( __query["filter_path"] = filter_path if human is not None: __query["human"] = human + if master_timeout is not None: + __query["master_timeout"] = master_timeout if pretty is not None: __query["pretty"] = pretty if wait_for_completion is not None: @@ -118,6 +126,7 @@ async def get_policy( error_trace: t.Optional[bool] = None, filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, human: t.Optional[bool] = None, + master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ @@ -127,6 +136,7 @@ async def get_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. + :param master_timeout: Period to wait for a connection to the master node. """ __path_parts: t.Dict[str, str] if name not in SKIP_IN_PATH: @@ -142,6 +152,8 @@ async def get_policy( __query["filter_path"] = filter_path if human is not None: __query["human"] = human + if master_timeout is not None: + __query["master_timeout"] = master_timeout if pretty is not None: __query["pretty"] = pretty __headers = {"accept": "application/json"} @@ -165,6 +177,7 @@ async def put_policy( filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, geo_match: t.Optional[t.Mapping[str, t.Any]] = None, human: t.Optional[bool] = None, + master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, match: t.Optional[t.Mapping[str, t.Any]] = None, pretty: t.Optional[bool] = None, range: t.Optional[t.Mapping[str, t.Any]] = None, @@ -178,6 +191,7 @@ async def put_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` query. + :param master_timeout: Period to wait for a connection to the master node. :param match: Matches enrich data to incoming documents based on a `term` query. :param range: Matches a number, date, or IP address in incoming documents to a range in the enrich index based on a `term` query. @@ -194,6 +208,8 @@ async def put_policy( __query["filter_path"] = filter_path if human is not None: __query["human"] = human + if master_timeout is not None: + __query["master_timeout"] = master_timeout if pretty is not None: __query["pretty"] = pretty if not __body: @@ -221,6 +237,7 @@ async def stats( error_trace: t.Optional[bool] = None, filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, human: t.Optional[bool] = None, + master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ @@ -228,6 +245,8 @@ async def stats( enrich policies that are currently executing. ``_ + + :param master_timeout: Period to wait for a connection to the master node. """ __path_parts: t.Dict[str, str] = {} __path = "/_enrich/_stats" @@ -238,6 +257,8 @@ async def stats( __query["filter_path"] = filter_path if human is not None: __query["human"] = human + if master_timeout is not None: + __query["master_timeout"] = master_timeout if pretty is not None: __query["pretty"] = pretty __headers = {"accept": "application/json"} diff --git a/elasticsearch/_async/client/esql.py b/elasticsearch/_async/client/esql.py index 43b14a964..5eedde8c7 100644 --- a/elasticsearch/_async/client/esql.py +++ b/elasticsearch/_async/client/esql.py @@ -20,11 +20,274 @@ from elastic_transport import ObjectApiResponse from ._base import NamespacedClient -from .utils import _rewrite_parameters +from .utils import SKIP_IN_PATH, _quote, _rewrite_parameters class EsqlClient(NamespacedClient): + @_rewrite_parameters( + body_fields=( + "query", + "columnar", + "filter", + "locale", + "params", + "profile", + "tables", + ), + ignore_deprecated_options={"params"}, + ) + async def async_query( + self, + *, + query: t.Optional[str] = None, + columnar: t.Optional[bool] = None, + delimiter: t.Optional[str] = None, + drop_null_columns: t.Optional[bool] = None, + error_trace: t.Optional[bool] = None, + filter: t.Optional[t.Mapping[str, t.Any]] = None, + filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, + format: t.Optional[ + t.Union[ + str, + t.Literal[ + "arrow", "cbor", "csv", "json", "smile", "tsv", "txt", "yaml" + ], + ] + ] = None, + human: t.Optional[bool] = None, + keep_alive: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, + keep_on_completion: t.Optional[bool] = None, + locale: t.Optional[str] = None, + params: t.Optional[ + t.Sequence[t.Union[None, bool, float, int, str, t.Any]] + ] = None, + pretty: t.Optional[bool] = None, + profile: t.Optional[bool] = None, + tables: t.Optional[ + t.Mapping[str, t.Mapping[str, t.Mapping[str, t.Any]]] + ] = None, + wait_for_completion_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]: + """ + Run an async ES|QL query. Asynchronously run an ES|QL (Elasticsearch query language) + query, monitor its progress, and retrieve results when they become available. + The API accepts the same parameters and request body as the synchronous query + API, along with additional async related properties. + + ``_ + + :param query: The ES|QL query API accepts an ES|QL query string in the query + parameter, runs it, and returns the results. + :param columnar: By default, ES|QL returns results as rows. For example, FROM + returns each individual document as one row. For the JSON, YAML, CBOR and + smile formats, ES|QL can return the results in a columnar fashion where one + row represents all the values of a certain column in the results. + :param delimiter: The character to use between values within a CSV row. It is + valid only for the CSV format. + :param drop_null_columns: Indicates whether columns that are entirely `null` + will be removed from the `columns` and `values` portion of the results. If + `true`, the response will include an extra section under the name `all_columns` + which has the name of all the columns. + :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, for example `json` or `yaml`. + :param keep_alive: The period for which the query and its results are stored + in the cluster. The default period is five days. When this period expires, + the query and its results are deleted, even if the query is still ongoing. + If the `keep_on_completion` parameter is false, Elasticsearch only stores + async queries that do not complete within the period set by the `wait_for_completion_timeout` + parameter, regardless of this value. + :param keep_on_completion: Indicates whether the query and its results are stored + in the cluster. If false, the query and its results are stored in the cluster + only if the request does not complete during the period set by the `wait_for_completion_timeout` + parameter. + :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 (?) + in the query string for each of the parameters. + :param profile: If provided and `true` the response will include an extra `profile` + object with information on how the query was executed. This information is + for human debugging and its format can change at any time but it can give + some insight into the performance of each part of the query. + :param tables: Tables to use with the LOOKUP operation. The top level key is + the table name and the next level key is the column name. + :param wait_for_completion_timeout: The period to wait for the request to finish. + By default, the request waits for 1 second for the query results. If the + query completes during this period, results are returned Otherwise, a query + ID is returned that can later be used to retrieve the results. + """ + if query is None and body is None: + raise ValueError("Empty value passed for parameter 'query'") + __path_parts: t.Dict[str, str] = {} + __path = "/_query/async" + __query: t.Dict[str, t.Any] = {} + __body: t.Dict[str, t.Any] = body if body is not None else {} + if delimiter is not None: + __query["delimiter"] = delimiter + if drop_null_columns is not None: + __query["drop_null_columns"] = drop_null_columns + if error_trace is not None: + __query["error_trace"] = error_trace + if filter_path is not None: + __query["filter_path"] = filter_path + if format is not None: + __query["format"] = format + if human is not None: + __query["human"] = human + 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 pretty is not None: + __query["pretty"] = pretty + if wait_for_completion_timeout is not None: + __query["wait_for_completion_timeout"] = wait_for_completion_timeout + if not __body: + if query is not None: + __body["query"] = query + if columnar is not None: + __body["columnar"] = columnar + if filter is not None: + __body["filter"] = filter + if locale is not None: + __body["locale"] = locale + if params is not None: + __body["params"] = params + if profile is not None: + __body["profile"] = profile + if tables is not None: + __body["tables"] = tables + __headers = {"accept": "application/json", "content-type": "application/json"} + return await self.perform_request( # type: ignore[return-value] + "POST", + __path, + params=__query, + headers=__headers, + body=__body, + endpoint_id="esql.async_query", + path_parts=__path_parts, + ) + + @_rewrite_parameters() + async def async_query_delete( + self, + *, + id: str, + error_trace: t.Optional[bool] = None, + filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, + human: t.Optional[bool] = None, + pretty: t.Optional[bool] = None, + ) -> ObjectApiResponse[t.Any]: + """ + Delete an async ES|QL query. If the query is still running, it is cancelled. + Otherwise, the stored results are deleted. If the Elasticsearch security features + are enabled, only the following users can use this API to delete a query: * The + authenticated user that submitted the original query request * Users with the + `cancel_task` cluster privilege + + ``_ + + :param id: The unique identifier of the query. A query ID is provided in the + ES|QL async query API response for a query that does not complete in the + designated time. A query ID is also provided when the request was submitted + with the `keep_on_completion` parameter set to `true`. + """ + if id in SKIP_IN_PATH: + raise ValueError("Empty value passed for parameter 'id'") + __path_parts: t.Dict[str, str] = {"id": _quote(id)} + __path = f'/_query/async/{__path_parts["id"]}' + __query: t.Dict[str, t.Any] = {} + if error_trace is not None: + __query["error_trace"] = error_trace + if filter_path is not None: + __query["filter_path"] = filter_path + if human is not None: + __query["human"] = human + if pretty is not None: + __query["pretty"] = pretty + __headers = {"accept": "application/json"} + return await self.perform_request( # type: ignore[return-value] + "DELETE", + __path, + params=__query, + headers=__headers, + endpoint_id="esql.async_query_delete", + path_parts=__path_parts, + ) + + @_rewrite_parameters() + async def async_query_get( + self, + *, + id: str, + drop_null_columns: t.Optional[bool] = None, + error_trace: t.Optional[bool] = None, + filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, + human: t.Optional[bool] = None, + keep_alive: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, + pretty: t.Optional[bool] = None, + wait_for_completion_timeout: t.Optional[ + t.Union[str, t.Literal[-1], t.Literal[0]] + ] = None, + ) -> ObjectApiResponse[t.Any]: + """ + Get async ES|QL query results. Get the current status and available results or + stored results for an ES|QL asynchronous query. If the Elasticsearch security + features are enabled, only the user who first submitted the ES|QL query can retrieve + the results using this API. + + ``_ + + :param id: The unique identifier of the query. A query ID is provided in the + ES|QL async query API response for a query that does not complete in the + designated time. A query ID is also provided when the request was submitted + with the `keep_on_completion` parameter set to `true`. + :param drop_null_columns: Indicates whether columns that are entirely `null` + will be removed from the `columns` and `values` portion of the results. If + `true`, the response will include an extra section under the name `all_columns` + which has the name of all the columns. + :param keep_alive: The period for which the query and its results are stored + in the cluster. When this period expires, the query and its results are deleted, + even if the query is still ongoing. + :param wait_for_completion_timeout: The period to wait for the request to finish. + By default, the request waits for complete query results. If the request + completes during the period specified in this parameter, complete query results + are returned. Otherwise, the response returns an `is_running` value of `true` + and no results. + """ + if id in SKIP_IN_PATH: + raise ValueError("Empty value passed for parameter 'id'") + __path_parts: t.Dict[str, str] = {"id": _quote(id)} + __path = f'/_query/async/{__path_parts["id"]}' + __query: t.Dict[str, t.Any] = {} + if drop_null_columns is not None: + __query["drop_null_columns"] = drop_null_columns + if error_trace is not None: + __query["error_trace"] = error_trace + if filter_path is not None: + __query["filter_path"] = filter_path + if human is not None: + __query["human"] = human + if keep_alive is not None: + __query["keep_alive"] = keep_alive + if pretty is not None: + __query["pretty"] = pretty + if wait_for_completion_timeout is not None: + __query["wait_for_completion_timeout"] = wait_for_completion_timeout + __headers = {"accept": "application/json"} + return await self.perform_request( # type: ignore[return-value] + "GET", + __path, + params=__query, + headers=__headers, + endpoint_id="esql.async_query_get", + path_parts=__path_parts, + ) + @_rewrite_parameters( body_fields=( "query", diff --git a/elasticsearch/_async/client/features.py b/elasticsearch/_async/client/features.py index e3fc9f8a1..ee6ca24a1 100644 --- a/elasticsearch/_async/client/features.py +++ b/elasticsearch/_async/client/features.py @@ -32,6 +32,7 @@ async def get_features( error_trace: t.Optional[bool] = None, filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, human: t.Optional[bool] = None, + master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ @@ -48,6 +49,8 @@ async def get_features( the plugin that defines that feature must be installed on the master node. ``_ + + :param master_timeout: Period to wait for a connection to the master node. """ __path_parts: t.Dict[str, str] = {} __path = "/_features" @@ -58,6 +61,8 @@ async def get_features( __query["filter_path"] = filter_path if human is not None: __query["human"] = human + if master_timeout is not None: + __query["master_timeout"] = master_timeout if pretty is not None: __query["pretty"] = pretty __headers = {"accept": "application/json"} @@ -78,6 +83,7 @@ async def reset_features( error_trace: t.Optional[bool] = None, filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, human: t.Optional[bool] = None, + master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ @@ -97,6 +103,8 @@ async def reset_features( individual nodes. ``_ + + :param master_timeout: Period to wait for a connection to the master node. """ __path_parts: t.Dict[str, str] = {} __path = "/_features/_reset" @@ -107,6 +115,8 @@ async def reset_features( __query["filter_path"] = filter_path if human is not None: __query["human"] = human + if master_timeout is not None: + __query["master_timeout"] = master_timeout if pretty is not None: __query["pretty"] = pretty __headers = {"accept": "application/json"} diff --git a/elasticsearch/_async/client/ilm.py b/elasticsearch/_async/client/ilm.py index 912b6ea2a..27d638e09 100644 --- a/elasticsearch/_async/client/ilm.py +++ b/elasticsearch/_async/client/ilm.py @@ -90,7 +90,6 @@ async def explain_lifecycle( only_errors: t.Optional[bool] = None, only_managed: t.Optional[bool] = None, pretty: t.Optional[bool] = None, - timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, ) -> ObjectApiResponse[t.Any]: """ Explain the lifecycle state. Get the current lifecycle status for one or more @@ -112,8 +111,6 @@ async def explain_lifecycle( while executing the policy, or attempting to use a policy that does not exist. :param only_managed: Filters the returned indices to only indices that are managed by ILM. - :param timeout: Period to wait for a response. If no response is received before - the timeout expires, the request fails and returns an error. """ if index in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'index'") @@ -134,8 +131,6 @@ async def explain_lifecycle( __query["only_managed"] = only_managed if pretty is not None: __query["pretty"] = pretty - if timeout is not None: - __query["timeout"] = timeout __headers = {"accept": "application/json"} return await self.perform_request( # type: ignore[return-value] "GET", @@ -341,8 +336,8 @@ async def move_to_step( ``_ :param index: The name of the index whose lifecycle step is to change - :param current_step: - :param next_step: + :param current_step: The step that the index is expected to be in. + :param next_step: The step that you want to run. """ if index in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'index'") @@ -552,8 +547,11 @@ async def start( ``_ - :param master_timeout: - :param timeout: + :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. """ __path_parts: t.Dict[str, str] = {} __path = "/_ilm/start" @@ -601,8 +599,11 @@ async def stop( ``_ - :param master_timeout: - :param timeout: + :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. """ __path_parts: t.Dict[str, str] = {} __path = "/_ilm/stop" diff --git a/elasticsearch/_async/client/indices.py b/elasticsearch/_async/client/indices.py index 788558041..2c279c4ce 100644 --- a/elasticsearch/_async/client/indices.py +++ b/elasticsearch/_async/client/indices.py @@ -143,8 +143,12 @@ 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](https://www.elastic.co/guide/en/elasticsearch/reference/current/analysis.html) - on a text string and returns the resulting tokens. + 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. ``_ @@ -246,7 +250,10 @@ async def clear_cache( ) -> ObjectApiResponse[t.Any]: """ Clear the cache. Clear the cache of one or more indices. For data streams, the - API clears the caches of the stream's backing indices. + API clears the caches of the stream's backing indices. By default, the clear + cache API clears all caches. To clear only specific caches, use the `fielddata`, + `query`, or `request` parameters. To clear the cache only of specific fields, + use the `fields` parameter. ``_ @@ -347,10 +354,28 @@ async def clone( the new index, which is a much more time consuming process. * Finally, it recovers the target index as though it were a closed index which had just been re-opened. IMPORTANT: Indices can only be cloned if they meet the following requirements: + * The index must be marked as read-only and have a cluster health status of green. * The target index must not exist. * The source index must have the same number of primary shards as the target index. * The node handling the clone process must have sufficient free disk space to accommodate a second copy of the existing - index. + index. The current write index on a data stream cannot be cloned. In order to + clone the current write index, the data stream must first be rolled over so that + a new write index is created and then the previous write index can be cloned. + NOTE: Mappings cannot be specified in the `_clone` request. The mappings of the + source index will be used for the target index. **Monitor the cloning process** + The cloning process can be monitored with the cat recovery API or the cluster + health API can be used to wait until all primary shards have been allocated by + setting the `wait_for_status` parameter to `yellow`. The `_clone` API returns + as soon as the target index has been added to the cluster state, before any shards + have been allocated. At this point, all shards are in the state unassigned. If, + for any reason, the target index can't be allocated, its primary shard will remain + unassigned until it can be allocated on that node. Once the primary shard is + allocated, it moves to state initializing, and the clone process begins. When + the clone operation completes, the shard will become active. At that point, Elasticsearch + will try to allocate any replicas and may decide to relocate the primary shard + to another node. **Wait for active shards** Because the clone operation creates + a new index to clone the shards to, the wait for active shards setting on index + creation applies to the clone index action as well. ``_ @@ -536,7 +561,26 @@ async def create( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Create an index. Creates a new index. + 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. ``_ @@ -732,7 +776,11 @@ async def delete( timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, ) -> ObjectApiResponse[t.Any]: """ - Delete indices. Deletes one or more indices. + 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. ``_ @@ -804,7 +852,7 @@ async def delete_alias( """ 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 (`*`). @@ -1034,7 +1082,7 @@ async def delete_template( timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, ) -> ObjectApiResponse[t.Any]: """ - Deletes a legacy index template. + Delete a legacy index template. ``_ @@ -1100,7 +1148,13 @@ async def disk_usage( Analyze the index disk usage. Analyze the disk usage of each field of an index or data stream. This API might not support indices created in previous Elasticsearch versions. The result of a small index can be inaccurate as some parts of an index - might not be analyzed by the API. + might not be analyzed by the API. NOTE: The total size of fields of the analyzed + shards of the index in the response is usually smaller than the index `store_size` + value because some small metadata files are ignored and some parts of data files + might not be scanned by the API. Since stored fields are stored together in a + compressed format, the sizes of stored fields are also estimates and can be inaccurate. + The stored size of the `_id` field is likely underestimated while the `_source` + field is overestimated. ``_ @@ -1249,8 +1303,7 @@ async def exists( pretty: t.Optional[bool] = None, ) -> HeadApiResponse: """ - Check indices. Checks if one or more indices, index aliases, or data streams - exist. + Check indices. Check if one or more indices, index aliases, or data streams exist. ``_ @@ -1448,16 +1501,21 @@ async def exists_template( pretty: t.Optional[bool] = None, ) -> HeadApiResponse: """ - Check existence of index templates. Returns information about whether a particular - index template exists. + Check existence of index templates. Get information about whether index templates + exist. Index templates define settings, mappings, and aliases that can be applied + automatically to new indices. IMPORTANT: This documentation is about legacy index + templates, which are deprecated and will be replaced by the composable templates + introduced in Elasticsearch 7.8. ``_ - :param name: The comma separated names of the index templates - :param flat_settings: Return settings in flat format (default: false) - :param local: Return local information, do not retrieve the state from master - node (default: false) - :param master_timeout: Explicit operation timeout for connection to master node + :param name: A comma-separated list of index template names used to limit the + request. Wildcard (`*`) expressions are supported. + :param flat_settings: Indicates whether to use a flat format for the response. + :param local: Indicates whether to get information from the local node only. + :param master_timeout: The period to wait for the master node. If the master + node is not available before the timeout expires, the request fails and returns + an error. To indicate that the request should never timeout, set it to `-1`. """ if name in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'name'") @@ -1560,9 +1618,7 @@ async def field_usage_stats( filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, human: t.Optional[bool] = None, ignore_unavailable: t.Optional[bool] = None, - 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, wait_for_active_shards: t.Optional[ t.Union[int, t.Union[str, t.Literal["all", "index-setting"]]] ] = None, @@ -1571,7 +1627,10 @@ async def field_usage_stats( Get field usage stats. Get field usage information for each shard and field of an index. Field usage statistics are automatically captured when queries are running on a cluster. A shard-level search request that accesses a given field, - even if multiple times during that request, is counted as a single use. + even if multiple times during that request, is counted as a single use. The response + body reports the per-shard usage count of the data structures that back the fields + in the index. A given request will increment each count by a maximum value of + 1, even if the request accesses the same field multiple times. ``_ @@ -1590,11 +1649,6 @@ async def field_usage_stats( in the statistics. :param ignore_unavailable: If `true`, missing or closed indices are not included in the response. - :param master_timeout: Period to wait for a connection to the master node. If - no response is received before the timeout expires, the request fails and - returns an error. - :param timeout: 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_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`). @@ -1618,12 +1672,8 @@ async def field_usage_stats( __query["human"] = human if ignore_unavailable is not None: __query["ignore_unavailable"] = ignore_unavailable - if master_timeout is not None: - __query["master_timeout"] = master_timeout if pretty is not None: __query["pretty"] = pretty - if timeout is not None: - __query["timeout"] = timeout if wait_for_active_shards is not None: __query["wait_for_active_shards"] = wait_for_active_shards __headers = {"accept": "application/json"} @@ -1771,7 +1821,35 @@ async def forcemerge( merges. So the number of soft-deleted documents can then grow rapidly, resulting in higher disk usage and worse search performance. If you regularly force merge an index receiving writes, this can also make snapshots more expensive, since - the new documents can't be backed up incrementally. + the new documents can't be backed up incrementally. **Blocks during a force merge** + Calls to this API block until the merge is complete (unless request contains + `wait_for_completion=false`). If the client connection is lost before completion + then the force merge process will continue in the background. Any new requests + to force merge the same indices will also block until the ongoing force merge + is complete. **Running force merge 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 get the status of the task. However, you can not cancel + this task as the force merge task is not cancelable. Elasticsearch creates a + record of this task as a document at `_tasks/`. When you are done with + a task, you should delete the task document so Elasticsearch can reclaim the + space. **Force merging multiple indices** You can force merge multiple indices + with a single request by targeting: * One or more data streams that contain multiple + backing indices * Multiple indices * One or more aliases * All data streams and + indices in a cluster Each targeted shard is force-merged separately using the + force_merge threadpool. By default each node only has a single `force_merge` + thread which means that the shards on that node are force-merged one at a time. + If you expand the `force_merge` threadpool on a node then it will force merge + its shards in parallel Force merge makes the storage for the shard being merged + temporarily increase, as it may require free space up to triple its size in case + `max_num_segments parameter` is set to `1`, to rewrite all segments into a new + one. **Data streams and time-based indices** Force-merging is useful for managing + a data stream's older backing indices and other time-based indices, particularly + after a rollover. In these cases, each index only receives indexing traffic for + a certain period of time. Once an index receive no more writes, its shards can + be force-merged to a single segment. This can be a good idea because single-segment + shards can sometimes use simpler and more efficient data structures to perform + searches. For example: ``` POST /.ds-my-data-stream-2099.03.07-000001/_forcemerge?max_num_segments=1 + ``` ``_ @@ -1864,8 +1942,8 @@ async def get( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Get index information. Returns information about one or more indices. For data - streams, the API returns information about the stream’s backing indices. + Get index information. Get information about one or more indices. For data streams, + the API returns information about the stream’s backing indices. ``_ @@ -1956,7 +2034,7 @@ async def get_alias( """ 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, @@ -2082,6 +2160,42 @@ async def get_data_lifecycle( path_parts=__path_parts, ) + @_rewrite_parameters() + async def get_data_lifecycle_stats( + self, + *, + error_trace: t.Optional[bool] = None, + filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, + human: t.Optional[bool] = None, + pretty: t.Optional[bool] = None, + ) -> ObjectApiResponse[t.Any]: + """ + Get data stream lifecycle stats. Get statistics about the data streams that are + managed by a data stream lifecycle. + + ``_ + """ + __path_parts: t.Dict[str, str] = {} + __path = "/_lifecycle/stats" + __query: t.Dict[str, t.Any] = {} + if error_trace is not None: + __query["error_trace"] = error_trace + if filter_path is not None: + __query["filter_path"] = filter_path + if human is not None: + __query["human"] = human + if pretty is not None: + __query["pretty"] = pretty + __headers = {"accept": "application/json"} + return await self.perform_request( # type: ignore[return-value] + "GET", + __path, + params=__query, + headers=__headers, + endpoint_id="indices.get_data_lifecycle_stats", + path_parts=__path_parts, + ) + @_rewrite_parameters() async def get_data_stream( self, @@ -2181,11 +2295,13 @@ async def get_field_mapping( """ Get mapping definitions. Retrieves mapping definitions for one or more fields. For data streams, the API retrieves field mappings for the stream’s backing indices. + This API is useful if you don't need a complete mapping or if an index mapping + contains a large number of fields. ``_ :param fields: Comma-separated list or wildcard expression of fields used to - limit returned information. + limit returned information. Supports wildcards (`*`). :param index: 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`. @@ -2257,7 +2373,7 @@ async def get_index_template( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Get index templates. Returns information about one or more index templates. + Get index templates. Get information about one or more index templates. ``_ @@ -2330,8 +2446,8 @@ async def get_mapping( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Get mapping definitions. Retrieves mapping definitions for one or more indices. - For data streams, the API retrieves mappings for the stream’s backing indices. + Get mapping definitions. For data streams, the API retrieves mappings for the + stream’s backing indices. ``_ @@ -2415,8 +2531,8 @@ async def get_settings( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Get index settings. Returns setting information for one or more indices. For - data streams, returns setting information for the stream’s backing indices. + Get index settings. Get setting information for one or more indices. For data + streams, it returns setting information for the stream's backing indices. ``_ @@ -2503,7 +2619,9 @@ async def get_template( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Get index templates. Retrieves information about one or more index templates. + Get index templates. Get information about one or more index templates. IMPORTANT: + This documentation is about legacy index templates, which are deprecated and + will be replaced by the composable templates introduced in Elasticsearch 7.8. ``_ @@ -2682,7 +2800,27 @@ async def open( ] = None, ) -> ObjectApiResponse[t.Any]: """ - Opens a closed index. For data streams, the API opens any closed backing indices. + Open a closed index. For data streams, the API opens any closed backing indices. + A closed index is blocked for read/write operations and does not allow all operations + that opened indices allow. It is not possible to index documents or to search + for documents in a closed index. This allows closed indices to not have to maintain + internal data structures for indexing or searching documents, resulting in a + smaller overhead on the cluster. When opening or closing an index, the master + is responsible for restarting the index shards to reflect the new state of the + index. The shards will then go through the normal recovery process. The data + of opened or closed indices is automatically replicated by the cluster to ensure + that enough shard copies are safely kept around at all times. You can open and + close multiple indices. An error is thrown if the request explicitly refers to + a missing index. This behavior can be turned off by using the `ignore_unavailable=true` + parameter. By default, you must explicitly name the indices you are opening or + closing. To open or close indices with `_all`, `*`, or other wildcard expressions, + change the `action.destructive_requires_name` setting to `false`. This setting + can also be changed with the cluster update settings API. Closed indices consume + a significant amount of disk-space which can cause problems in managed environments. + Closing indices can be turned off with the cluster settings API by setting `cluster.indices.close.enable` + to `false`. Because opening or closing an index allocates its shards, the `wait_for_active_shards` + setting on index creation applies to the `_open` and `_close` index actions as + well. ``_ @@ -3025,7 +3163,33 @@ async def put_index_template( ) -> ObjectApiResponse[t.Any]: """ Create or update an index template. Index templates define settings, mappings, - and aliases that can be applied automatically to new indices. + 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. ``_ @@ -3055,8 +3219,11 @@ async def put_index_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 meta: Optional user metadata about the index template. May have any contents. - This map is not automatically generated by Elasticsearch. + :param meta: Optional user metadata about the index template. It may have any + contents. It is not automatically generated or used by Elasticsearch. This + user-defined object is stored in the cluster state, so keeping it short is + preferable To unset the metadata, replace the template without specifying + it. :param priority: Priority to determine index template precedence when a new data stream or index is created. The index template with the highest priority is chosen. If no priority is specified the template is treated as though @@ -3065,7 +3232,9 @@ async def put_index_template( :param template: Template to be applied. It may optionally include an `aliases`, `mappings`, or `settings` configuration. :param version: Version number used to manage index templates externally. This - number is not automatically generated by Elasticsearch. + number is not automatically generated by Elasticsearch. External systems + can use these version numbers to simplify template management. To unset a + version, replace the template without specifying one. """ if name in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'name'") @@ -3184,9 +3353,27 @@ async def put_mapping( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Update field mappings. Adds new fields to an existing data stream or index. You - can also use this API to change the search settings of existing fields. For data - streams, these changes are applied to all backing indices by default. + 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. ``_ @@ -3317,6 +3504,19 @@ async def put_settings( """ 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. ``_ @@ -3430,7 +3630,14 @@ async def put_template( according to their order. Index templates are only applied during index creation. Changes to index templates do not affect existing indices. Settings and mappings specified in create index API requests override any settings or mappings specified - in an index template. + in an index template. 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. **Indices matching multiple templates** Multiple index templates + can potentially match an index, in this case, both the settings and mappings + are merged into the final configuration of the index. The order of the merging + can be controlled using the order parameter, with lower order being applied first, + and higher orders overriding them. NOTE: Multiple matching templates with the + same order value will result in a non-deterministic merging order. ``_ @@ -3451,7 +3658,8 @@ async def put_template( with lower values. :param settings: Configuration options for the index. :param version: Version number used to manage index templates externally. This - number is not automatically generated by Elasticsearch. + number is not automatically generated by Elasticsearch. To unset a version, + replace the template without specifying one. """ if name in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'name'") @@ -3512,23 +3720,25 @@ async def recovery( """ Get index recovery information. Get information about ongoing and completed shard recoveries for one or more indices. For data streams, the API returns information - for the stream's backing indices. Shard recovery is the process of initializing - a shard copy, such as restoring a primary shard from a snapshot or creating a - replica shard from a primary shard. When a shard recovery completes, the recovered - shard is available for search and indexing. Recovery automatically occurs during - the following processes: * When creating an index for the first time. * When - a node rejoins the cluster and starts up any missing primary shard copies using - the data that it holds in its data path. * Creation of new replica shard copies - from the primary. * Relocation of a shard copy to a different node in the same - cluster. * A snapshot restore operation. * A clone, shrink, or split operation. - You can determine the cause of a shard recovery using the recovery or cat recovery - APIs. The index recovery API reports information about completed recoveries only - for shard copies that currently exist in the cluster. It only reports the last - recovery for each shard copy and does not report historical information about - earlier recoveries, nor does it report information about the recoveries of shard - copies that no longer exist. This means that if a shard copy completes a recovery - and then Elasticsearch relocates it onto a different node then the information - about the original recovery will not be shown in the recovery API. + for the stream's backing indices. All recoveries, whether ongoing or complete, + are kept in the cluster state and may be reported on at any time. Shard recovery + is the process of initializing a shard copy, such as restoring a primary shard + from a snapshot or creating a replica shard from a primary shard. When a shard + recovery completes, the recovered shard is available for search and indexing. + Recovery automatically occurs during the following processes: * When creating + an index for the first time. * When a node rejoins the cluster and starts up + any missing primary shard copies using the data that it holds in its data path. + * Creation of new replica shard copies from the primary. * Relocation of a shard + copy to a different node in the same cluster. * A snapshot restore operation. + * A clone, shrink, or split operation. You can determine the cause of a shard + recovery using the recovery or cat recovery APIs. The index recovery API reports + information about completed recoveries only for shard copies that currently exist + in the cluster. It only reports the last recovery for each shard copy and does + not report historical information about earlier recoveries, nor does it report + information about the recoveries of shard copies that no longer exist. This means + that if a shard copy completes a recovery and then Elasticsearch relocates it + onto a different node then the information about the original recovery will not + be shown in the recovery API. ``_ @@ -3592,7 +3802,17 @@ async def refresh( """ 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. + 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. ``_ @@ -3754,6 +3974,24 @@ async def resolve_cluster( search is likely to have errors returned when you do the cross-cluster search (including any authorization errors if you do not have permission to query the index). * Cluster version information, including the Elasticsearch server version. + For example, `GET /_resolve/cluster/my-index-*,cluster*:my-index-*` returns information + about the local cluster and all remotely configured clusters that start with + the alias `cluster*`. Each cluster returns information about whether it has any + indices, aliases or data streams that match `my-index-*`. **Advantages of using + this endpoint before a cross-cluster search** You may want to exclude a cluster + or index from a search when: * A remote cluster is not currently connected and + is configured with `skip_unavailable=false`. Running a cross-cluster search under + those conditions will cause the entire search to fail. * A cluster has no matching + indices, aliases or data streams for the index expression (or your user does + not have permissions to search them). For example, suppose your index expression + is `logs*,remote1:logs*` and the remote1 cluster has no indices, aliases or data + streams that match `logs*`. In that case, that cluster will return no results + from that cluster if you include it in a cross-cluster search. * The index expression + (combined with any query parameters you specify) will likely cause an exception + to be thrown when you do the search. In these cases, the "error" field in the + `_resolve/cluster` response will be present. (This is also where security/permission + errors will be shown.) * A remote cluster is an older version that does not support + the feature you want to use in your search. ``_ @@ -3900,7 +4138,33 @@ async def rollover( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Roll over to a new index. Creates a new index for a data stream or index alias. + 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`. ``_ @@ -4267,8 +4531,8 @@ async def simulate_index_template( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Simulate an index. Returns the index configuration that would be applied to the - specified index from an existing index template. + Simulate an index. Get the index configuration that would be applied to the specified + index from an existing index template. ``_ @@ -4345,7 +4609,7 @@ async def simulate_template( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Simulate an index template. Returns the index configuration that would be applied + Simulate an index template. Get the index configuration that would be applied by a particular index template. ``_ @@ -4479,25 +4743,29 @@ async def split( """ Split an index. Split an index into a new index with more primary shards. * Before you can split an index: * The index must be read-only. * The cluster health status - must be green. The number of times the index can be split (and the number of - shards that each original shard can be split into) is determined by the `index.number_of_routing_shards` - setting. The number of routing shards specifies the hashing space that is used - internally to distribute documents across shards with consistent hashing. For - instance, a 5 shard index with `number_of_routing_shards` set to 30 (5 x 2 x - 3) could be split by a factor of 2 or 3. A split operation: * Creates a new target - index with the same definition as the source index, but with a larger number - of primary shards. * Hard-links segments from the source index into the target - index. If the file system doesn't support hard-linking, all segments are copied - into the new index, which is a much more time consuming process. * Hashes all - documents again, after low level files are created, to delete documents that - belong to a different shard. * Recovers the target index as though it were a - closed index which had just been re-opened. IMPORTANT: Indices can only be split - if they satisfy the following requirements: * The target index must not exist. - * The source index must have fewer primary shards than the target index. * The - number of primary shards in the target index must be a multiple of the number - of primary shards in the source index. * The node handling the split process - must have sufficient free disk space to accommodate a second copy of the existing - index. + must be green. You can do make an index read-only with the following request + using the add index block API: ``` PUT /my_source_index/_block/write ``` The + current write index on a data stream cannot be split. In order to split the current + write index, the data stream must first be rolled over so that a new write index + is created and then the previous write index can be split. The number of times + the index can be split (and the number of shards that each original shard can + be split into) is determined by the `index.number_of_routing_shards` setting. + The number of routing shards specifies the hashing space that is used internally + to distribute documents across shards with consistent hashing. For instance, + a 5 shard index with `number_of_routing_shards` set to 30 (5 x 2 x 3) could be + split by a factor of 2 or 3. A split operation: * Creates a new target index + with the same definition as the source index, but with a larger number of primary + shards. * Hard-links segments from the source index into the target index. If + the file system doesn't support hard-linking, all segments are copied into the + new index, which is a much more time consuming process. * Hashes all documents + again, after low level files are created, to delete documents that belong to + a different shard. * Recovers the target index as though it were a closed index + which had just been re-opened. IMPORTANT: Indices can only be split if they satisfy + the following requirements: * The target index must not exist. * The source index + must have fewer primary shards than the target index. * The number of primary + shards in the target index must be a multiple of the number of primary shards + in the source index. * The node handling the split process must have sufficient + free disk space to accommodate a second copy of the existing index. ``_ diff --git a/elasticsearch/_async/client/inference.py b/elasticsearch/_async/client/inference.py index 1e248fc0c..b32cf6b86 100644 --- a/elasticsearch/_async/client/inference.py +++ b/elasticsearch/_async/client/inference.py @@ -317,3 +317,82 @@ async def put( endpoint_id="inference.put", path_parts=__path_parts, ) + + @_rewrite_parameters( + body_name="inference_config", + ) + async def update( + self, + *, + inference_id: str, + inference_config: t.Optional[t.Mapping[str, t.Any]] = None, + body: t.Optional[t.Mapping[str, t.Any]] = None, + task_type: t.Optional[ + t.Union[ + str, + t.Literal["completion", "rerank", "sparse_embedding", "text_embedding"], + ] + ] = None, + error_trace: t.Optional[bool] = None, + filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, + human: t.Optional[bool] = None, + pretty: t.Optional[bool] = None, + ) -> ObjectApiResponse[t.Any]: + """ + Update an inference endpoint. Modify `task_settings`, secrets (within `service_settings`), + or `num_allocations` for an inference endpoint, depending on the specific endpoint + service and `task_type`. 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, 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 unique identifier of the inference endpoint. + :param inference_config: + :param task_type: The type of inference task that the model performs. + """ + if inference_id in SKIP_IN_PATH: + raise ValueError("Empty value passed for parameter 'inference_id'") + if inference_config is None and body is None: + raise ValueError( + "Empty value passed for parameters 'inference_config' and 'body', one of them should be set." + ) + elif inference_config is not None and body is not None: + raise ValueError("Cannot set both 'inference_config' and 'body'") + __path_parts: t.Dict[str, str] + if task_type not in SKIP_IN_PATH and inference_id not in SKIP_IN_PATH: + __path_parts = { + "task_type": _quote(task_type), + "inference_id": _quote(inference_id), + } + __path = f'/_inference/{__path_parts["task_type"]}/{__path_parts["inference_id"]}/_update' + elif inference_id not in SKIP_IN_PATH: + __path_parts = {"inference_id": _quote(inference_id)} + __path = f'/_inference/{__path_parts["inference_id"]}/_update' + else: + raise ValueError("Couldn't find a path for the given parameters") + __query: t.Dict[str, t.Any] = {} + if error_trace is not None: + __query["error_trace"] = error_trace + if filter_path is not None: + __query["filter_path"] = filter_path + if human is not None: + __query["human"] = human + if pretty is not None: + __query["pretty"] = pretty + __body = inference_config if inference_config is not None else body + __headers = {"accept": "application/json", "content-type": "application/json"} + return await self.perform_request( # type: ignore[return-value] + "POST", + __path, + params=__query, + headers=__headers, + body=__body, + endpoint_id="inference.update", + path_parts=__path_parts, + ) diff --git a/elasticsearch/_async/client/ingest.py b/elasticsearch/_async/client/ingest.py index 7c7d870e8..12fcfe688 100644 --- a/elasticsearch/_async/client/ingest.py +++ b/elasticsearch/_async/client/ingest.py @@ -226,7 +226,6 @@ async def get_geoip_database( error_trace: t.Optional[bool] = None, filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, human: t.Optional[bool] = None, - master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ @@ -238,9 +237,6 @@ async def get_geoip_database( :param id: Comma-separated list of database configuration IDs to retrieve. Wildcard (`*`) expressions are supported. To get all database configurations, omit this parameter or use `*`. - :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. """ __path_parts: t.Dict[str, str] if id not in SKIP_IN_PATH: @@ -256,8 +252,6 @@ async def get_geoip_database( __query["filter_path"] = filter_path if human is not None: __query["human"] = human - if master_timeout is not None: - __query["master_timeout"] = master_timeout if pretty is not None: __query["pretty"] = pretty __headers = {"accept": "application/json"} diff --git a/elasticsearch/_async/client/license.py b/elasticsearch/_async/client/license.py index 014bc3e8f..b5f166838 100644 --- a/elasticsearch/_async/client/license.py +++ b/elasticsearch/_async/client/license.py @@ -32,7 +32,9 @@ async def delete( error_trace: t.Optional[bool] = None, filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, human: t.Optional[bool] = None, + 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, ) -> ObjectApiResponse[t.Any]: """ Delete the license. When the license expires, your subscription level reverts @@ -40,6 +42,10 @@ async def delete( can use this API. ``_ + + :param master_timeout: Period to wait for a connection to the master node. + :param timeout: Period to wait for a response. If no response is received before + the timeout expires, the request fails and returns an error. """ __path_parts: t.Dict[str, str] = {} __path = "/_license" @@ -50,8 +56,12 @@ async def delete( __query["filter_path"] = filter_path if human is not None: __query["human"] = human + if master_timeout is not None: + __query["master_timeout"] = master_timeout if pretty is not None: __query["pretty"] = pretty + if timeout is not None: + __query["timeout"] = timeout __headers = {"accept": "application/json"} return await self.perform_request( # type: ignore[return-value] "DELETE", @@ -196,7 +206,9 @@ async def post( human: t.Optional[bool] = None, license: t.Optional[t.Mapping[str, t.Any]] = None, licenses: t.Optional[t.Sequence[t.Mapping[str, t.Any]]] = None, + 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]: """ @@ -215,6 +227,9 @@ async def post( :param license: :param licenses: A sequence of one or more JSON documents containing the license information. + :param master_timeout: Period to wait for a connection to the master node. + :param timeout: Period to wait for a response. If no response is received before + the timeout expires, the request fails and returns an error. """ __path_parts: t.Dict[str, str] = {} __path = "/_license" @@ -228,8 +243,12 @@ async def post( __query["filter_path"] = filter_path if human is not None: __query["human"] = human + if master_timeout is not None: + __query["master_timeout"] = master_timeout if pretty is not None: __query["pretty"] = pretty + if timeout is not None: + __query["timeout"] = timeout if not __body: if license is not None: __body["license"] = license @@ -258,7 +277,9 @@ async def post_start_basic( error_trace: t.Optional[bool] = None, filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, human: t.Optional[bool] = None, + 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, ) -> ObjectApiResponse[t.Any]: """ Start a basic license. Start an indefinite basic license, which gives access @@ -273,6 +294,9 @@ async def post_start_basic( :param acknowledge: whether the user has acknowledged acknowledge messages (default: false) + :param master_timeout: Period to wait for a connection to the master node. + :param timeout: Period to wait for a response. If no response is received before + the timeout expires, the request fails and returns an error. """ __path_parts: t.Dict[str, str] = {} __path = "/_license/start_basic" @@ -285,8 +309,12 @@ async def post_start_basic( __query["filter_path"] = filter_path if human is not None: __query["human"] = human + if master_timeout is not None: + __query["master_timeout"] = master_timeout if pretty is not None: __query["pretty"] = pretty + if timeout is not None: + __query["timeout"] = timeout __headers = {"accept": "application/json"} return await self.perform_request( # type: ignore[return-value] "POST", @@ -305,6 +333,7 @@ async def post_start_trial( error_trace: t.Optional[bool] = None, filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, human: t.Optional[bool] = None, + master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, pretty: t.Optional[bool] = None, type_query_string: t.Optional[str] = None, ) -> ObjectApiResponse[t.Any]: @@ -320,6 +349,7 @@ async def post_start_trial( :param acknowledge: whether the user has acknowledged acknowledge messages (default: false) + :param master_timeout: Period to wait for a connection to the master node. :param type_query_string: """ __path_parts: t.Dict[str, str] = {} @@ -333,6 +363,8 @@ async def post_start_trial( __query["filter_path"] = filter_path if human is not None: __query["human"] = human + if master_timeout is not None: + __query["master_timeout"] = master_timeout if pretty is not None: __query["pretty"] = pretty if type_query_string is not None: diff --git a/elasticsearch/_async/client/logstash.py b/elasticsearch/_async/client/logstash.py index 25e9f82be..406aea309 100644 --- a/elasticsearch/_async/client/logstash.py +++ b/elasticsearch/_async/client/logstash.py @@ -37,7 +37,8 @@ async def delete_pipeline( ) -> ObjectApiResponse[t.Any]: """ Delete a Logstash pipeline. Delete a pipeline that is used for Logstash Central - Management. + Management. If the request succeeds, you receive an empty response with an appropriate + status code. ``_ diff --git a/elasticsearch/_async/client/migration.py b/elasticsearch/_async/client/migration.py index c43441ec3..ad5e6c047 100644 --- a/elasticsearch/_async/client/migration.py +++ b/elasticsearch/_async/client/migration.py @@ -39,7 +39,7 @@ async def deprecations( Get deprecation information. Get information about different cluster, node, and index level settings that use deprecated features that will be removed or changed in the next major version. TIP: This APIs is designed for indirect use by the - Upgrade Assistant. We strongly recommend you use the Upgrade Assistant. + Upgrade Assistant. You are strongly recommended to use the Upgrade Assistant. ``_ @@ -86,9 +86,9 @@ async def get_feature_upgrade_status( to how features store configuration information and data in system indices. Check which features need to be migrated and the status of any migrations that are in progress. TIP: This API is designed for indirect use by the Upgrade Assistant. - We strongly recommend you use the Upgrade Assistant. + You are strongly recommended to use the Upgrade Assistant. - ``_ + ``_ """ __path_parts: t.Dict[str, str] = {} __path = "/_migration/system_features" @@ -127,7 +127,7 @@ async def post_feature_upgrade( unavailable during the migration process. TIP: The API is designed for indirect use by the Upgrade Assistant. We strongly recommend you use the Upgrade Assistant. - ``_ + ``_ """ __path_parts: t.Dict[str, str] = {} __path = "/_migration/system_features" diff --git a/elasticsearch/_async/client/ml.py b/elasticsearch/_async/client/ml.py index 76e0eb18c..cc7f73aac 100644 --- a/elasticsearch/_async/client/ml.py +++ b/elasticsearch/_async/client/ml.py @@ -686,6 +686,7 @@ async def delete_trained_model( force: t.Optional[bool] = None, human: t.Optional[bool] = None, pretty: t.Optional[bool] = None, + 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 @@ -696,6 +697,8 @@ async def delete_trained_model( :param model_id: The unique identifier of the trained model. :param force: Forcefully deletes a trained model that is referenced by ingest pipelines or has a started deployment. + :param timeout: Period to wait for a response. If no response is received before + the timeout expires, the request fails and returns an error. """ if model_id in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'model_id'") @@ -712,6 +715,8 @@ async def delete_trained_model( __query["human"] = human if pretty is not None: __query["pretty"] = pretty + if timeout is not None: + __query["timeout"] = timeout __headers = {"accept": "application/json"} return await self.perform_request( # type: ignore[return-value] "DELETE", @@ -3205,7 +3210,11 @@ async def put_data_frame_analytics( """ 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. + 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. ``_ @@ -3381,8 +3390,9 @@ async def put_datafeed( 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. When Elasticsearch security features are enabled, your datafeed + (`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 @@ -3645,7 +3655,8 @@ async def put_job( ) -> ObjectApiResponse[t.Any]: """ Create an anomaly detection job. If you include a `datafeed_config`, you must - have read index privileges on the source index. + 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}}`. ``_ @@ -5451,7 +5462,7 @@ async def validate( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Validates an anomaly detection job. + Validate an anomaly detection job. ``_ diff --git a/elasticsearch/_async/client/nodes.py b/elasticsearch/_async/client/nodes.py index 589ad8d7d..31ab07888 100644 --- a/elasticsearch/_async/client/nodes.py +++ b/elasticsearch/_async/client/nodes.py @@ -50,9 +50,9 @@ async def clear_repositories_metering_archive( ``_ :param node_id: Comma-separated list of node IDs or names used to limit returned - information. All the nodes selective options are explained [here](https://www.elastic.co/guide/en/elasticsearch/reference/current/cluster.html#cluster-nodes). - :param max_archive_version: Specifies the maximum [archive_version](https://www.elastic.co/guide/en/elasticsearch/reference/current/get-repositories-metering-api.html#get-repositories-metering-api-response-body) - to be cleared from the archive. + information. + :param max_archive_version: Specifies the maximum `archive_version` to be cleared + from the archive. """ if node_id in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'node_id'") @@ -138,7 +138,6 @@ async def hot_threads( human: t.Optional[bool] = None, ignore_idle_threads: t.Optional[bool] = None, interval: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, - master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, pretty: t.Optional[bool] = None, snapshots: t.Optional[int] = None, sort: t.Optional[ @@ -161,9 +160,6 @@ async def hot_threads( :param ignore_idle_threads: If true, known idle threads (e.g. waiting in a socket select, or to get a task from an empty queue) are filtered out. :param interval: The interval to do the second sampling of threads. - :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 snapshots: Number of samples of thread stacktrace. :param sort: The sort order for 'cpu' type (default: total) :param threads: Specifies the number of hot threads to provide information for. @@ -189,8 +185,6 @@ async def hot_threads( __query["ignore_idle_threads"] = ignore_idle_threads if interval is not None: __query["interval"] = interval - if master_timeout is not None: - __query["master_timeout"] = master_timeout if pretty is not None: __query["pretty"] = pretty if snapshots is not None: @@ -223,7 +217,6 @@ async def info( filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, flat_settings: t.Optional[bool] = None, human: t.Optional[bool] = None, - 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, ) -> ObjectApiResponse[t.Any]: @@ -238,9 +231,6 @@ async def info( :param metric: Limits the information returned to the specific metrics. Supports a comma-separated list, such as http,ingest. :param flat_settings: If true, returns settings in flat format. - :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. """ @@ -266,8 +256,6 @@ async def info( __query["flat_settings"] = flat_settings if human is not None: __query["human"] = human - if master_timeout is not None: - __query["master_timeout"] = master_timeout if pretty is not None: __query["pretty"] = pretty if timeout is not None: @@ -374,7 +362,6 @@ async def stats( level: t.Optional[ t.Union[str, t.Literal["cluster", "indices", "shards"]] ] = None, - 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, types: t.Optional[t.Sequence[str]] = None, @@ -406,9 +393,6 @@ async def stats( from segments that are not loaded into memory. :param level: Indicates whether statistics are aggregated at the cluster, index, or shard level. - :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 types: A comma-separated list of document types for the indexing index @@ -467,8 +451,6 @@ async def stats( __query["include_unloaded_segments"] = include_unloaded_segments if level is not None: __query["level"] = level - if master_timeout is not None: - __query["master_timeout"] = master_timeout if pretty is not None: __query["pretty"] = pretty if timeout is not None: diff --git a/elasticsearch/_async/client/query_rules.py b/elasticsearch/_async/client/query_rules.py index a905a1f73..602ce9a6d 100644 --- a/elasticsearch/_async/client/query_rules.py +++ b/elasticsearch/_async/client/query_rules.py @@ -37,7 +37,9 @@ async def delete_rule( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Delete a query rule. Delete a query rule within a query ruleset. + 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. ``_ @@ -85,7 +87,8 @@ async def delete_ruleset( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Delete a query ruleset. + Delete a query ruleset. Remove a query ruleset and its associated data. This + is a destructive action that is not recoverable. ``_ @@ -221,8 +224,8 @@ async def list_rulesets( ``_ - :param from_: Starting offset (default: 0) - :param size: specifies a max number of results to get + :param from_: The offset from the first result to fetch. + :param size: The maximum number of results to retrieve. """ __path_parts: t.Dict[str, str] = {} __path = "/_query_rules" @@ -271,16 +274,25 @@ async def put_rule( ) -> 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. ``_ :param ruleset_id: The unique identifier of the query ruleset containing the - rule to be created or updated + rule to be created or updated. :param rule_id: The unique identifier of the query rule within the specified - ruleset to be created or updated - :param actions: - :param criteria: - :param type: + ruleset to be created or updated. + :param actions: The actions to take when the rule is matched. The format of this + action depends on the rule type. + :param criteria: The criteria that must be met for the rule to be applied. If + multiple criteria are specified for a rule, all criteria must be met for + the rule to be applied. + :param type: The type of rule. :param priority: """ if ruleset_id in SKIP_IN_PATH: @@ -345,12 +357,19 @@ async def put_ruleset( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Create or update a query ruleset. + 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 + updated. :param rules: """ if ruleset_id in SKIP_IN_PATH: @@ -405,7 +424,9 @@ async def test( :param ruleset_id: The unique identifier of the query ruleset to be created or updated - :param match_criteria: + :param match_criteria: The match criteria to apply to rules in the given query + ruleset. Match criteria should match the keys defined in the `criteria.metadata` + field of the rule. """ if ruleset_id in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'ruleset_id'") diff --git a/elasticsearch/_async/client/rollup.py b/elasticsearch/_async/client/rollup.py index e68df368d..de891536d 100644 --- a/elasticsearch/_async/client/rollup.py +++ b/elasticsearch/_async/client/rollup.py @@ -397,14 +397,37 @@ async def rollup_search( rolled-up documents utilize a different document structure than the original data. It rewrites standard Query DSL into a format that matches the rollup documents then takes the response and rewrites it back to what a client would expect given - the original query. + the original query. The request body supports a subset of features from the regular + search API. The following functionality is not available: `size`: Because rollups + work on pre-aggregated data, no search hits can be returned and so size must + be set to zero or omitted entirely. `highlighter`, `suggestors`, `post_filter`, + `profile`, `explain`: These are similarly disallowed. **Searching both historical + rollup and non-rollup data** The rollup search API has the capability to search + across both "live" non-rollup data and the aggregated rollup data. This is done + by simply adding the live indices to the URI. For example: ``` GET sensor-1,sensor_rollup/_rollup_search + { "size": 0, "aggregations": { "max_temperature": { "max": { "field": "temperature" + } } } } ``` The rollup search endpoint does two things when the search runs: + * The original request is sent to the non-rollup index unaltered. * A rewritten + version of the original request is sent to the rollup index. When the two responses + are received, the endpoint rewrites the rollup response and merges the two together. + During the merging process, if there is any overlap in buckets between the two + responses, the buckets from the non-rollup index are used. ``_ - :param index: Enables searching rolled-up data using the standard Query DSL. + :param index: A comma-separated list of data streams and indices used to limit + the request. This parameter has the following rules: * At least one data + stream, index, or wildcard expression must be specified. This target can + include a rollup or non-rollup index. For data streams, the stream's backing + indices can only serve as non-rollup indices. Omitting the parameter or using + `_all` are not permitted. * Multiple non-rollup indices may be specified. + * Only one rollup index may be specified. If more than one are supplied, + an exception occurs. * Wildcard expressions (`*`) may be used. If they match + more than one rollup index, an exception occurs. However, you can use an + expression to match multiple non-rollup indices or data streams. :param aggregations: Specifies aggregations. :param aggs: Specifies aggregations. - :param query: Specifies a DSL query. + :param query: Specifies a DSL query that is subject to some limitations. :param rest_total_hits_as_int: Indicates whether hits.total should be rendered as an integer or an object in the rest search response :param size: Must be zero if set, as rollups work on pre-aggregated data. @@ -506,14 +529,23 @@ async def stop_job( ) -> ObjectApiResponse[t.Any]: """ Stop rollup jobs. If you try to stop a job that does not exist, an exception - occurs. If you try to stop a job that is already stopped, nothing happens. + occurs. If you try to stop a job that is already stopped, nothing happens. Since + only a stopped job can be deleted, it can be useful to block the API until the + indexer has fully stopped. This is accomplished with the `wait_for_completion` + query parameter, and optionally a timeout. For example: ``` POST _rollup/job/sensor/_stop?wait_for_completion=true&timeout=10s + ``` The parameter blocks the API call from returning until either the job has + moved to STOPPED or the specified time has elapsed. If the specified time elapses + without the job moving to STOPPED, a timeout exception occurs. ``_ :param id: Identifier for the rollup job. :param timeout: If `wait_for_completion` is `true`, the API blocks for (at maximum) the specified duration while waiting for the job to stop. If more than `timeout` - time has passed, the API throws a timeout exception. + time has passed, the API throws a timeout exception. NOTE: Even if a timeout + occurs, the stop request is still processing and eventually moves the job + to STOPPED. The timeout simply means the API call itself timed out while + waiting for the status change. :param wait_for_completion: If set to `true`, causes the API to block until the indexer state completely stops. If set to `false`, the API returns immediately and the indexer is stopped asynchronously in the background. diff --git a/elasticsearch/_async/client/searchable_snapshots.py b/elasticsearch/_async/client/searchable_snapshots.py index 645d60d89..cd98cca6f 100644 --- a/elasticsearch/_async/client/searchable_snapshots.py +++ b/elasticsearch/_async/client/searchable_snapshots.py @@ -47,11 +47,9 @@ async def cache_stats( Get cache statistics. Get statistics about the shared cache for partially mounted indices. - ``_ + ``_ - :param node_id: A comma-separated list of node IDs or names to limit the returned - information; use `_local` to return information from the node you're connecting - to, leave empty to get information from all nodes + :param node_id: The names of the nodes in the cluster to target. :param master_timeout: """ __path_parts: t.Dict[str, str] @@ -107,9 +105,10 @@ async def clear_cache( Clear the cache. Clear indices and data streams from the shared cache for partially mounted indices. - ``_ + ``_ - :param index: A comma-separated list of index names + :param index: A comma-separated list of data streams, indices, and aliases to + clear from the cache. It supports wildcards (`*`). :param allow_no_indices: Whether to ignore if a wildcard indices expression resolves into no concrete indices. (This includes `_all` string or when no indices have been specified) @@ -184,17 +183,22 @@ async def mount( ``_ :param repository: The name of the repository containing the snapshot of the - index to mount - :param snapshot: The name of the snapshot of the index to mount - :param index: - :param ignore_index_settings: - :param index_settings: - :param master_timeout: Explicit operation timeout for connection to master node - :param renamed_index: - :param storage: Selects the kind of local storage used to accelerate searches. - Experimental, and defaults to `full_copy` - :param wait_for_completion: Should this request wait until the operation has - completed before returning + index to mount. + :param snapshot: The name of the snapshot of the index to mount. + :param index: The name of the index contained in the snapshot whose data is to + be mounted. If no `renamed_index` is specified, this name will also be used + to create the new index. + :param ignore_index_settings: The names of settings that should be removed from + the index when it is mounted. + :param index_settings: The settings that should be added to the index when it + is mounted. + :param master_timeout: The period to wait for the master node. If the master + node is not available before the timeout expires, the request fails and returns + an error. To indicate that the request should never timeout, set it to `-1`. + :param renamed_index: The name of the index that will be created. + :param storage: The mount option for the searchable snapshot index. + :param wait_for_completion: If true, the request blocks until the operation is + complete. """ if repository in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'repository'") @@ -261,9 +265,10 @@ async def stats( """ Get searchable snapshot statistics. - ``_ + ``_ - :param index: A comma-separated list of index names + :param index: A comma-separated list of data streams and indices to retrieve + statistics for. :param level: Return stats aggregated at cluster, index or shard level """ __path_parts: t.Dict[str, str] diff --git a/elasticsearch/_async/client/security.py b/elasticsearch/_async/client/security.py index 1902de328..7d4478abe 100644 --- a/elasticsearch/_async/client/security.py +++ b/elasticsearch/_async/client/security.py @@ -45,14 +45,33 @@ async def activate_user_profile( ) -> ObjectApiResponse[t.Any]: """ Activate a user profile. Create or update a user profile on behalf of another - user. + user. NOTE: The user profile feature is designed only for use by Kibana and Elastic's + Observability, Enterprise Search, and Elastic Security solutions. Individual + users and external applications should not call this API directly. The calling + application must have either an `access_token` or a combination of `username` + and `password` for the user that the profile document is intended for. Elastic + reserves the right to change or remove this feature in future releases without + prior notice. This API creates or updates a profile document for end users with + information that is extracted from the user's authentication object including + `username`, `full_name,` `roles`, and the authentication realm. For example, + in the JWT `access_token` case, the profile user's `username` is extracted from + the JWT token claim pointed to by the `claims.principal` setting of the JWT realm + that authenticated the token. When updating a profile document, the API enables + the document if it was disabled. Any updates do not change existing content for + either the `labels` or `data` fields. ``_ - :param grant_type: - :param access_token: - :param password: - :param username: + :param grant_type: The type of grant. + :param access_token: The user's Elasticsearch access token or JWT. Both `access` + and `id` JWT token types are supported and they depend on the underlying + JWT realm configuration. If you specify the `access_token` grant type, this + parameter is required. It is not valid with other grant types. + :param password: The user's password. If you specify the `password` grant type, + this parameter is required. It is not valid with other grant types. + :param username: The username that identifies the user. If you specify the `password` + grant type, this parameter is required. It is not valid with other grant + types. """ if grant_type is None and body is None: raise ValueError("Empty value passed for parameter 'grant_type'") @@ -244,6 +263,94 @@ async def bulk_put_role( path_parts=__path_parts, ) + @_rewrite_parameters( + body_fields=("ids", "expiration", "metadata", "role_descriptors"), + ) + async def bulk_update_api_keys( + self, + *, + ids: t.Optional[t.Union[str, t.Sequence[str]]] = None, + error_trace: t.Optional[bool] = None, + expiration: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, + filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, + human: t.Optional[bool] = None, + metadata: t.Optional[t.Mapping[str, t.Any]] = None, + pretty: t.Optional[bool] = None, + role_descriptors: t.Optional[t.Mapping[str, t.Mapping[str, t.Any]]] = None, + body: t.Optional[t.Dict[str, t.Any]] = None, + ) -> ObjectApiResponse[t.Any]: + """ + Bulk update API keys. Update the attributes for multiple API keys. IMPORTANT: + It is not possible to use an API key as the authentication credential for this + API. To update API keys, the owner user's credentials are required. This API + is similar to the update API key API but enables you to apply the same update + to multiple API keys in one API call. This operation can greatly improve performance + over making individual updates. It is not possible to update expired or invalidated + API keys. This API supports updates to API key access scope, metadata and expiration. + The access scope of each 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 an 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. A successful request returns a JSON structure that + contains the IDs of all updated API keys, the IDs of API keys that already had + the requested changes and did not require an update, and error details for any + failed update. + + ``_ + + :param ids: The API key identifiers. + :param expiration: Expiration time for the API keys. By default, API keys never + expire. This property can be omitted to leave the value unchanged. + :param metadata: Arbitrary nested metadata to associate with the API keys. Within + the `metadata` object, top-level keys beginning with an underscore (`_`) + are reserved for system usage. Any information specified with this parameter + fully replaces metadata previously associated with the API key. + :param role_descriptors: The role descriptors to assign to the API keys. An 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, supply the `role_descriptors` parameter as 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. The structure of a role descriptor + is the same as the request for the create API keys API. + """ + if ids is None and body is None: + raise ValueError("Empty value passed for parameter 'ids'") + __path_parts: t.Dict[str, str] = {} + __path = "/_security/api_key/_bulk_update" + __query: t.Dict[str, t.Any] = {} + __body: t.Dict[str, t.Any] = body if body is not None else {} + if error_trace is not None: + __query["error_trace"] = error_trace + if filter_path is not None: + __query["filter_path"] = filter_path + if human is not None: + __query["human"] = human + if pretty is not None: + __query["pretty"] = pretty + if not __body: + if ids is not None: + __body["ids"] = ids + if expiration is not None: + __body["expiration"] = expiration + if metadata is not None: + __body["metadata"] = metadata + if role_descriptors is not None: + __body["role_descriptors"] = role_descriptors + __headers = {"accept": "application/json", "content-type": "application/json"} + return await self.perform_request( # type: ignore[return-value] + "POST", + __path, + params=__query, + headers=__headers, + body=__body, + endpoint_id="security.bulk_update_api_keys", + path_parts=__path_parts, + ) + @_rewrite_parameters( body_fields=("password", "password_hash"), ) @@ -773,6 +880,74 @@ async def create_service_token( path_parts=__path_parts, ) + @_rewrite_parameters( + body_fields=("x509_certificate_chain",), + ) + async def delegate_pki( + self, + *, + x509_certificate_chain: t.Optional[t.Sequence[str]] = None, + error_trace: t.Optional[bool] = None, + filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, + human: t.Optional[bool] = None, + pretty: t.Optional[bool] = None, + body: t.Optional[t.Dict[str, t.Any]] = None, + ) -> ObjectApiResponse[t.Any]: + """ + Delegate PKI authentication. This API implements the exchange of an X509Certificate + chain for an Elasticsearch access token. The certificate chain is validated, + according to RFC 5280, by sequentially considering the trust configuration of + every installed PKI realm that has `delegation.enabled` set to `true`. A successfully + trusted client certificate is also subject to the validation of the subject distinguished + name according to thw `username_pattern` of the respective realm. This API is + called by smart and trusted proxies, such as Kibana, which terminate the user's + TLS session but still want to authenticate the user by using a PKI realm—-​as + if the user connected directly to Elasticsearch. IMPORTANT: The association between + the subject public key in the target certificate and the corresponding private + key is not validated. This is part of the TLS authentication process and it is + delegated to the proxy that calls this API. The proxy is trusted to have performed + the TLS authentication and this API translates that authentication into an Elasticsearch + access token. + + ``_ + + :param x509_certificate_chain: The X509Certificate chain, which is represented + as an ordered string array. Each string in the array is a base64-encoded + (Section 4 of RFC4648 - not base64url-encoded) of the certificate's DER encoding. + The first element is the target certificate that contains the subject distinguished + name that is requesting access. This may be followed by additional certificates; + each subsequent certificate is used to certify the previous one. + """ + if x509_certificate_chain is None and body is None: + raise ValueError( + "Empty value passed for parameter 'x509_certificate_chain'" + ) + __path_parts: t.Dict[str, str] = {} + __path = "/_security/delegate_pki" + __query: t.Dict[str, t.Any] = {} + __body: t.Dict[str, t.Any] = body if body is not None else {} + if error_trace is not None: + __query["error_trace"] = error_trace + if filter_path is not None: + __query["filter_path"] = filter_path + if human is not None: + __query["human"] = human + if pretty is not None: + __query["pretty"] = pretty + if not __body: + if x509_certificate_chain is not None: + __body["x509_certificate_chain"] = x509_certificate_chain + __headers = {"accept": "application/json", "content-type": "application/json"} + return await self.perform_request( # type: ignore[return-value] + "POST", + __path, + params=__query, + headers=__headers, + body=__body, + endpoint_id="security.delegate_pki", + path_parts=__path_parts, + ) + @_rewrite_parameters() async def delete_privileges( self, @@ -1098,14 +1273,21 @@ async def disable_user_profile( ) -> ObjectApiResponse[t.Any]: """ Disable a user profile. Disable user profiles so that they are not visible in - user profile searches. + user profile searches. NOTE: The user profile feature is designed only for use + by Kibana and Elastic's Observability, Enterprise Search, and Elastic Security + solutions. Individual users and external applications should not call this API + directly. Elastic reserves the right to change or remove this feature in future + releases without prior notice. When you activate a user profile, its automatically + enabled and visible in user profile searches. You can use the disable user profile + API to disable a user profile so it’s not visible in these searches. To re-enable + a disabled user profile, use the enable user profile API . ``_ :param uid: Unique identifier for the user profile. :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', it waits for a refresh to + make this operation visible to search. If 'false', it does nothing with refreshes. """ if uid in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'uid'") @@ -1195,14 +1377,20 @@ async def enable_user_profile( ) -> ObjectApiResponse[t.Any]: """ Enable a user profile. Enable user profiles to make them visible in user profile - searches. + searches. NOTE: The user profile feature is designed only for use by Kibana and + Elastic's Observability, Enterprise Search, and Elastic Security solutions. Individual + users and external applications should not call this API directly. Elastic reserves + the right to change or remove this feature in future releases without prior notice. + When you activate a user profile, it's automatically enabled and visible in user + profile searches. If you later disable the user profile, you can use the enable + user profile API to make the profile visible in these searches again. ``_ - :param uid: Unique identifier for the user profile. + :param uid: A unique identifier for the user profile. :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', it waits for a refresh to + make this operation visible to search. If 'false', nothing is done with refreshes. """ if uid in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'uid'") @@ -1665,6 +1853,49 @@ async def get_service_credentials( path_parts=__path_parts, ) + @_rewrite_parameters() + async def get_settings( + self, + *, + error_trace: t.Optional[bool] = None, + filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, + human: t.Optional[bool] = None, + master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, + pretty: t.Optional[bool] = None, + ) -> ObjectApiResponse[t.Any]: + """ + Get security index settings. Get the user-configurable settings for the security + internal index (`.security` and associated indices). + + ``_ + + :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. + """ + __path_parts: t.Dict[str, str] = {} + __path = "/_security/settings" + __query: t.Dict[str, t.Any] = {} + if error_trace is not None: + __query["error_trace"] = error_trace + if filter_path is not None: + __query["filter_path"] = filter_path + if human is not None: + __query["human"] = human + if master_timeout is not None: + __query["master_timeout"] = master_timeout + if pretty is not None: + __query["pretty"] = pretty + __headers = {"accept": "application/json"} + return await self.perform_request( # type: ignore[return-value] + "GET", + __path, + params=__query, + headers=__headers, + endpoint_id="security.get_settings", + path_parts=__path_parts, + ) + @_rewrite_parameters( body_fields=( "grant_type", @@ -1858,15 +2089,19 @@ async def get_user_profile( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Get a user profile. Get a user's profile using the unique profile ID. + Get a user profile. Get a user's profile using the unique profile ID. NOTE: The + user profile feature is designed only for use by Kibana and Elastic's Observability, + Enterprise Search, and Elastic Security solutions. Individual users and external + applications should not call this API directly. Elastic reserves the right to + change or remove this feature in future releases without prior notice. ``_ :param uid: A unique identifier for the user profile. - :param data: List of filters for the `data` field of the profile document. To - return all content use `data=*`. To return a subset of content use `data=` - to retrieve content nested under the specified ``. By default returns - no `data` content. + :param data: A comma-separated list of filters for the `data` field of the profile + document. To return all content use `data=*`. To return a subset of content + use `data=` to retrieve content nested under the specified ``. + By default returns no `data` content. """ if uid in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'uid'") @@ -2138,11 +2373,15 @@ async def has_privileges_user_profile( ) -> ObjectApiResponse[t.Any]: """ Check user profile privileges. Determine whether the users associated with the - specified user profile IDs have all the requested privileges. + specified user profile IDs have all the requested privileges. NOTE: The user + profile feature is designed only for use by Kibana and Elastic's Observability, + Enterprise Search, and Elastic Security solutions. Individual users and external + applications should not call this API directly. Elastic reserves the right to + change or remove this feature in future releases without prior notice. ``_ - :param privileges: + :param privileges: An object containing all the privileges to be checked. :param uids: A list of profile IDs. The privileges are checked for associated users of the profiles. """ @@ -3313,13 +3552,25 @@ async def saml_authenticate( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Authenticate SAML. Submits a SAML response message to Elasticsearch for consumption. + Authenticate SAML. Submit a SAML response message to Elasticsearch for consumption. + NOTE: This API is intended for use by custom web applications other than Kibana. + If you are using Kibana, refer to the documentation for configuring SAML single-sign-on + on the Elastic Stack. The SAML message that is submitted can be: * A response + to a SAML authentication request that was previously created using the SAML prepare + authentication API. * An unsolicited SAML message in the case of an IdP-initiated + single sign-on (SSO) flow. In either case, the SAML message needs to be a base64 + encoded XML document with a root element of ``. After successful validation, + Elasticsearch responds with an Elasticsearch internal access token and refresh + token that can be subsequently used for authentication. This API endpoint essentially + exchanges SAML responses that indicate successful authentication in the IdP for + Elasticsearch access and refresh tokens, which can be used for authentication + against Elasticsearch. ``_ - :param content: The SAML response as it was sent by the user’s browser, usually + :param content: The SAML response as it was sent by the user's browser, usually a Base64 encoded XML document. - :param ids: A json array with all the valid SAML Request Ids that the caller + :param ids: A JSON array with all the valid SAML Request Ids that the caller of the API has for the current user. :param realm: The name of the realm that should authenticate the SAML response. Useful in cases where many SAML realms are defined. @@ -3376,10 +3627,19 @@ async def saml_complete_logout( ) -> ObjectApiResponse[t.Any]: """ Logout of SAML completely. Verifies the logout response sent from the SAML IdP. + NOTE: This API is intended for use by custom web applications other than Kibana. + If you are using Kibana, refer to the documentation for configuring SAML single-sign-on + on the Elastic Stack. The SAML IdP may send a logout response back to the SP + after handling the SP-initiated SAML Single Logout. This API verifies the response + by ensuring the content is relevant and validating its signature. An empty response + is returned if the verification process is successful. The response can be sent + by the IdP with either the HTTP-Redirect or the HTTP-Post binding. The caller + of this API must prepare the request accordingly so that this API can handle + either of them. ``_ - :param ids: A json array with all the valid SAML Request Ids that the caller + :param ids: A JSON array with all the valid SAML Request Ids that the caller of the API has for the current user. :param realm: The name of the SAML realm in Elasticsearch for which the configuration is used to verify the logout response. @@ -3441,25 +3701,33 @@ async def saml_invalidate( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Invalidate SAML. Submits a SAML LogoutRequest message to Elasticsearch for consumption. + Invalidate SAML. Submit a SAML LogoutRequest message to Elasticsearch for consumption. + NOTE: This API is intended for use by custom web applications other than Kibana. + If you are using Kibana, refer to the documentation for configuring SAML single-sign-on + on the Elastic Stack. The logout request comes from the SAML IdP during an IdP + initiated Single Logout. The custom web application can use this API to have + Elasticsearch process the `LogoutRequest`. After successful validation of the + request, Elasticsearch invalidates the access token and refresh token that corresponds + to that specific SAML principal and provides a URL that contains a SAML LogoutResponse + message. Thus the user can be redirected back to their IdP. ``_ :param query_string: The query part of the URL that the user was redirected to by the SAML IdP to initiate the Single Logout. This query should include - a single parameter named SAMLRequest that contains a SAML logout request + a single parameter named `SAMLRequest` that contains a SAML logout request that is deflated and Base64 encoded. If the SAML IdP has signed the logout - request, the URL should include two extra parameters named SigAlg and Signature + request, the URL should include two extra parameters named `SigAlg` and `Signature` that contain the algorithm used for the signature and the signature value - itself. In order for Elasticsearch to be able to verify the IdP’s signature, - the value of the query_string field must be an exact match to the string + itself. In order for Elasticsearch to be able to verify the IdP's signature, + the value of the `query_string` field must be an exact match to the string provided by the browser. The client application must not attempt to parse or process the string in any way. :param acs: The Assertion Consumer Service URL that matches the one of the SAML realm in Elasticsearch that should be used. You must specify either this - parameter or the realm parameter. + parameter or the `realm` parameter. :param realm: The name of the SAML realm in Elasticsearch the configuration. - You must specify either this parameter or the acs parameter. + You must specify either this parameter or the `acs` parameter. """ if query_string is None and body is None: raise ValueError("Empty value passed for parameter 'query_string'") @@ -3509,12 +3777,19 @@ async def saml_logout( ) -> ObjectApiResponse[t.Any]: """ Logout of SAML. Submits a request to invalidate an access token and refresh token. + NOTE: This API is intended for use by custom web applications other than Kibana. + If you are using Kibana, refer to the documentation for configuring SAML single-sign-on + on the Elastic Stack. This API invalidates the tokens that were generated for + a user by the SAML authenticate API. If the SAML realm in Elasticsearch is configured + accordingly and the SAML IdP supports this, the Elasticsearch response contains + a URL to redirect the user to the IdP that contains a SAML logout request (starting + an SP-initiated SAML Single Logout). ``_ :param token: The access token that was returned as a response to calling the SAML authenticate API. Alternatively, the most recent token that was received - after refreshing the original one by using a refresh_token. + after refreshing the original one by using a `refresh_token`. :param refresh_token: The refresh token that was returned as a response to calling the SAML authenticate API. Alternatively, the most recent refresh token that was received after refreshing the original access token. @@ -3565,19 +3840,31 @@ async def saml_prepare_authentication( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Prepare SAML authentication. Creates a SAML authentication request (``) - as a URL string, based on the configuration of the respective SAML realm in Elasticsearch. + Prepare SAML authentication. Create a SAML authentication request (``) + as a URL string based on the configuration of the respective SAML realm in Elasticsearch. + NOTE: This API is intended for use by custom web applications other than Kibana. + If you are using Kibana, refer to the documentation for configuring SAML single-sign-on + on the Elastic Stack. This API returns a URL pointing to the SAML Identity Provider. + You can use the URL to redirect the browser of the user in order to continue + the authentication process. The URL includes a single parameter named `SAMLRequest`, + which contains a SAML Authentication request that is deflated and Base64 encoded. + If the configuration dictates that SAML authentication requests should be signed, + the URL has two extra parameters named `SigAlg` and `Signature`. These parameters + contain the algorithm used for the signature and the signature value itself. + It also returns a random string that uniquely identifies this SAML Authentication + request. The caller of this API needs to store this identifier as it needs to + be used in a following step of the authentication process. ``_ :param acs: The Assertion Consumer Service URL that matches the one of the SAML realms in Elasticsearch. The realm is used to generate the authentication - request. You must specify either this parameter or the realm parameter. + request. You must specify either this parameter or the `realm` parameter. :param realm: The name of the SAML realm in Elasticsearch for which the configuration is used to generate the authentication request. You must specify either this - parameter or the acs parameter. + parameter or the `acs` parameter. :param relay_state: A string that will be included in the redirect URL that this - API returns as the RelayState query parameter. If the Authentication Request + API returns as the `RelayState` query parameter. If the Authentication Request is signed, this value is used as part of the signature computation. """ __path_parts: t.Dict[str, str] = {} @@ -3622,7 +3909,10 @@ async def saml_service_provider_metadata( ) -> ObjectApiResponse[t.Any]: """ Create SAML service provider metadata. Generate SAML metadata for a SAML 2.0 - Service Provider. + Service Provider. The SAML 2.0 specification provides a mechanism for Service + Providers to describe their capabilities and configuration using a metadata file. + This API generates Service Provider metadata based on the configuration of a + SAML realm in Elasticsearch. ``_ @@ -3669,21 +3959,27 @@ async def suggest_user_profiles( ) -> ObjectApiResponse[t.Any]: """ Suggest a user profile. Get suggestions for user profiles that match specified - search criteria. + search criteria. NOTE: The user profile feature is designed only for use by Kibana + and Elastic's Observability, Enterprise Search, and Elastic Security solutions. + Individual users and external applications should not call this API directly. + Elastic reserves the right to change or remove this feature in future releases + without prior notice. ``_ - :param data: List of filters for the `data` field of the profile document. To - return all content use `data=*`. To return a subset of content use `data=` - to retrieve content nested under the specified ``. By default returns - no `data` content. + :param data: A comma-separated list of filters for the `data` field of the profile + document. To return all content use `data=*`. To return a subset of content, + use `data=` to retrieve content nested under the specified ``. + By default, the API returns no `data` content. It is an error to specify + `data` as both the query parameter and the request body field. :param hint: Extra search criteria to improve relevance of the suggestion result. Profiles matching the spcified hint are ranked higher in the response. Profiles - not matching the hint don't exclude the profile from the response as long - as the profile matches the `name` field query. - :param name: Query string used to match name-related fields in user profile documents. - Name-related fields are the user's `username`, `full_name`, and `email`. - :param size: Number of profiles to return. + not matching the hint aren't excluded from the response as long as the profile + matches the `name` field query. + :param name: A query string used to match name-related fields in user profile + documents. Name-related fields are the user's `username`, `full_name`, and + `email`. + :param size: The number of profiles to return. """ __path_parts: t.Dict[str, str] = {} __path = "/_security/profile/_suggest" @@ -3825,7 +4121,18 @@ async def update_cross_cluster_api_key( ) -> ObjectApiResponse[t.Any]: """ Update a cross-cluster API key. Update the attributes of an existing cross-cluster - API key, which is used for API key based remote cluster access. + API key, which is used for API key based remote cluster access. To use this API, + you must have at least the `manage_security` cluster privilege. Users can only + update API keys that they created. 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. It's not possible + to update expired API keys, or API keys that have been invalidated by the invalidate + API key API. This API supports updates to an API key's access scope, metadata, + and expiration. The owner user's information, such as the `username` and `realm`, + is also updated automatically on every call. NOTE: This API cannot update REST + API keys, which should be updated by either the update API key or bulk update + API keys API. ``_ @@ -3834,8 +4141,8 @@ async def update_cross_cluster_api_key( of permissions for cross cluster search and cross cluster replication. At least one of them must be specified. When specified, the new access assignment fully replaces the previously assigned access. - :param expiration: Expiration time for the API key. By default, API keys never - expire. This property can be omitted to leave the value unchanged. + :param expiration: The expiration time for the API key. By default, API keys + never expire. This property can be omitted to leave the value 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. When specified, this information @@ -3875,6 +4182,81 @@ async def update_cross_cluster_api_key( path_parts=__path_parts, ) + @_rewrite_parameters( + body_fields=("security", "security_profile", "security_tokens"), + parameter_aliases={ + "security-profile": "security_profile", + "security-tokens": "security_tokens", + }, + ) + async def update_settings( + self, + *, + error_trace: t.Optional[bool] = None, + filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, + human: t.Optional[bool] = None, + master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, + pretty: t.Optional[bool] = None, + security: t.Optional[t.Mapping[str, t.Any]] = None, + security_profile: t.Optional[t.Mapping[str, t.Any]] = None, + security_tokens: t.Optional[t.Mapping[str, t.Any]] = 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 security index settings. Update the user-configurable settings for the + security internal index (`.security` and associated indices). Only a subset of + settings are allowed to be modified, for example `index.auto_expand_replicas` + and `index.number_of_replicas`. If a specific index is not in use on the system + and settings are provided for it, the request will be rejected. This API does + not yet support configuring the settings for indices before they are in use. + + ``_ + + :param master_timeout: The period to wait for a connection to the master node. + If no response is received before the timeout expires, the request fails + and returns an error. + :param security: Settings for the index used for most security configuration, + including native realm users and roles configured with the API. + :param security_profile: Settings for the index used to store profile information. + :param security_tokens: Settings for the index used to store tokens. + :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. + """ + __path_parts: t.Dict[str, str] = {} + __path = "/_security/settings" + __query: t.Dict[str, t.Any] = {} + __body: t.Dict[str, t.Any] = body if body is not None else {} + if error_trace is not None: + __query["error_trace"] = error_trace + if filter_path is not None: + __query["filter_path"] = filter_path + if human is not None: + __query["human"] = human + if master_timeout is not None: + __query["master_timeout"] = master_timeout + if pretty is not None: + __query["pretty"] = pretty + if timeout is not None: + __query["timeout"] = timeout + if not __body: + if security is not None: + __body["security"] = security + if security_profile is not None: + __body["security-profile"] = security_profile + if security_tokens is not None: + __body["security-tokens"] = security_tokens + __headers = {"accept": "application/json", "content-type": "application/json"} + return await self.perform_request( # type: ignore[return-value] + "PUT", + __path, + params=__query, + headers=__headers, + body=__body, + endpoint_id="security.update_settings", + path_parts=__path_parts, + ) + @_rewrite_parameters( body_fields=("data", "labels"), ) @@ -3897,22 +4279,37 @@ async def update_user_profile_data( ) -> ObjectApiResponse[t.Any]: """ Update user profile data. Update specific data for the user profile that is associated - with a unique ID. + with a unique ID. NOTE: The user profile feature is designed only for use by + Kibana and Elastic's Observability, Enterprise Search, and Elastic Security solutions. + Individual users and external applications should not call this API directly. + Elastic reserves the right to change or remove this feature in future releases + without prior notice. To use this API, you must have one of the following privileges: + * The `manage_user_profile` cluster privilege. * The `update_profile_data` global + privilege for the namespaces that are referenced in the request. This API updates + the `labels` and `data` fields of an existing user profile document with JSON + objects. New keys and their values are added to the profile document and conflicting + keys are replaced by data that's included in the request. For both labels and + data, content is namespaced by the top-level fields. The `update_profile_data` + global privilege grants privileges for updating only the allowed namespaces. ``_ :param uid: A unique identifier for the user profile. :param data: Non-searchable data that you want to associate with the user profile. - This field supports a nested data structure. + This field supports a nested data structure. Within the `data` object, top-level + keys cannot begin with an underscore (`_`) or contain a period (`.`). The + data object is not searchable, but can be retrieved with the get user profile + API. :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 labels: Searchable data that you want to associate with the user profile. - This field supports a nested data structure. + This field supports a nested data structure. Within the labels object, top-level + keys cannot begin with an underscore (`_`) or contain a period (`.`). :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', it waits for a refresh to + make this operation visible to search. If 'false', nothing is done with refreshes. """ if uid in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'uid'") diff --git a/elasticsearch/_async/client/shutdown.py b/elasticsearch/_async/client/shutdown.py index e4117bff8..98f4478fc 100644 --- a/elasticsearch/_async/client/shutdown.py +++ b/elasticsearch/_async/client/shutdown.py @@ -50,7 +50,7 @@ async def delete_node( and Elastic Cloud on Kubernetes. Direct use is not supported. If the operator privileges feature is enabled, you must be an operator to use this API. - ``_ + ``_ :param node_id: The node id of node to be removed from the shutdown state :param master_timeout: Period to wait for a connection to the master node. If @@ -98,9 +98,6 @@ async def get_node( t.Union[str, t.Literal["d", "h", "m", "micros", "ms", "nanos", "s"]] ] = None, pretty: t.Optional[bool] = None, - timeout: t.Optional[ - t.Union[str, t.Literal["d", "h", "m", "micros", "ms", "nanos", "s"]] - ] = None, ) -> ObjectApiResponse[t.Any]: """ Get the shutdown status. Get information about nodes that are ready to be shut @@ -111,14 +108,12 @@ async def get_node( the operator privileges feature is enabled, you must be an operator to use this API. - ``_ + ``_ :param node_id: Which node for which to retrieve the shutdown status :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. """ __path_parts: t.Dict[str, str] if node_id not in SKIP_IN_PATH: @@ -138,8 +133,6 @@ async def get_node( __query["master_timeout"] = master_timeout if pretty is not None: __query["pretty"] = pretty - if timeout is not None: - __query["timeout"] = timeout __headers = {"accept": "application/json"} return await self.perform_request( # type: ignore[return-value] "GET", @@ -178,19 +171,23 @@ async def put_node( """ Prepare a node to be shut down. NOTE: This feature is designed for indirect use by Elastic Cloud, Elastic Cloud Enterprise, and Elastic Cloud on Kubernetes. - Direct use is not supported. If the operator privileges feature is enabled, you - must be an operator to use this API. The API migrates ongoing tasks and index - shards to other nodes as needed to prepare a node to be restarted or shut down - and removed from the cluster. This ensures that Elasticsearch can be stopped - safely with minimal disruption to the cluster. You must specify the type of shutdown: - `restart`, `remove`, or `replace`. If a node is already being prepared for shutdown, - you can use this API to change the shutdown type. IMPORTANT: This API does NOT - terminate the Elasticsearch process. Monitor the node shutdown status to determine - when it is safe to stop Elasticsearch. + Direct use is not supported. If you specify a node that is offline, it will be + prepared for shut down when it rejoins the cluster. If the operator privileges + feature is enabled, you must be an operator to use this API. The API migrates + ongoing tasks and index shards to other nodes as needed to prepare a node to + be restarted or shut down and removed from the cluster. This ensures that Elasticsearch + can be stopped safely with minimal disruption to the cluster. You must specify + the type of shutdown: `restart`, `remove`, or `replace`. If a node is already + being prepared for shutdown, you can use this API to change the shutdown type. + IMPORTANT: This API does NOT terminate the Elasticsearch process. Monitor the + node shutdown status to determine when it is safe to stop Elasticsearch. - ``_ + ``_ - :param node_id: The node id of node to be shut down + :param node_id: The node identifier. This parameter is not validated against + the cluster's active nodes. This enables you to register a node for shut + down while it is offline. No error is thrown if you specify an invalid node + ID. :param reason: A human-readable reason that the node is being shut down. This field provides information for other cluster operators; it does not affect the shut down process. @@ -211,17 +208,17 @@ async def put_node( the index.unassigned.node_left.delayed_timeout setting. If you specify both a restart allocation delay and an index-level allocation delay, the longer of the two is used. - :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 master_timeout: The period to wait for a connection to the master node. + If no response is received before the timeout expires, the request fails + and returns an error. :param target_node_name: Only valid if type is replace. Specifies the name of the node that is replacing the node being shut down. Shards from the shut down node are only allowed to be allocated to the target node, and no other data will be allocated to the target node. During relocation of data certain allocation rules are ignored, such as disk watermarks or user attribute filtering rules. - :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 timeout: The period to wait for a response. If no response is received + before the timeout expires, the request fails and returns an error. """ if node_id in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'node_id'") diff --git a/elasticsearch/_async/client/slm.py b/elasticsearch/_async/client/slm.py index 6738eed0f..08ed4299f 100644 --- a/elasticsearch/_async/client/slm.py +++ b/elasticsearch/_async/client/slm.py @@ -33,7 +33,9 @@ async def delete_lifecycle( error_trace: t.Optional[bool] = None, filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, human: t.Optional[bool] = None, + 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, ) -> ObjectApiResponse[t.Any]: """ Delete a policy. Delete a snapshot lifecycle policy definition. This operation @@ -43,6 +45,11 @@ async def delete_lifecycle( ``_ :param policy_id: The id of the snapshot lifecycle policy to remove + :param master_timeout: The period to wait for a connection to the master node. + If no response is received before the timeout expires, the request fails + and returns an error. + :param timeout: The period to wait for a response. If no response is received + before the timeout expires, the request fails and returns an error. """ if policy_id in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'policy_id'") @@ -55,8 +62,12 @@ async def delete_lifecycle( __query["filter_path"] = filter_path if human is not None: __query["human"] = human + if master_timeout is not None: + __query["master_timeout"] = master_timeout if pretty is not None: __query["pretty"] = pretty + if timeout is not None: + __query["timeout"] = timeout __headers = {"accept": "application/json"} return await self.perform_request( # type: ignore[return-value] "DELETE", @@ -75,7 +86,9 @@ async def execute_lifecycle( error_trace: t.Optional[bool] = None, filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, human: t.Optional[bool] = None, + 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, ) -> ObjectApiResponse[t.Any]: """ Run a policy. Immediately create a snapshot according to the snapshot lifecycle @@ -86,6 +99,11 @@ async def execute_lifecycle( ``_ :param policy_id: The id of the snapshot lifecycle policy to be executed + :param master_timeout: The period to wait for a connection to the master node. + If no response is received before the timeout expires, the request fails + and returns an error. + :param timeout: The period to wait for a response. If no response is received + before the timeout expires, the request fails and returns an error. """ if policy_id in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'policy_id'") @@ -98,8 +116,12 @@ async def execute_lifecycle( __query["filter_path"] = filter_path if human is not None: __query["human"] = human + if master_timeout is not None: + __query["master_timeout"] = master_timeout if pretty is not None: __query["pretty"] = pretty + if timeout is not None: + __query["timeout"] = timeout __headers = {"accept": "application/json"} return await self.perform_request( # type: ignore[return-value] "PUT", @@ -117,7 +139,9 @@ async def execute_retention( error_trace: t.Optional[bool] = None, filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, human: t.Optional[bool] = None, + 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, ) -> ObjectApiResponse[t.Any]: """ Run a retention policy. Manually apply the retention policy to force immediate @@ -125,6 +149,12 @@ async def execute_retention( retention rules. The retention policy is normally applied according to its schedule. ``_ + + :param master_timeout: The period to wait for a connection to the master node. + If no response is received before the timeout expires, the request fails + and returns an error. + :param timeout: The period to wait for a response. If no response is received + before the timeout expires, the request fails and returns an error. """ __path_parts: t.Dict[str, str] = {} __path = "/_slm/_execute_retention" @@ -135,8 +165,12 @@ async def execute_retention( __query["filter_path"] = filter_path if human is not None: __query["human"] = human + if master_timeout is not None: + __query["master_timeout"] = master_timeout if pretty is not None: __query["pretty"] = pretty + if timeout is not None: + __query["timeout"] = timeout __headers = {"accept": "application/json"} return await self.perform_request( # type: ignore[return-value] "POST", @@ -155,7 +189,9 @@ async def get_lifecycle( error_trace: t.Optional[bool] = None, filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, human: t.Optional[bool] = None, + 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, ) -> ObjectApiResponse[t.Any]: """ Get policy information. Get snapshot lifecycle policy definitions and information @@ -164,6 +200,11 @@ async def get_lifecycle( ``_ :param policy_id: Comma-separated list of snapshot lifecycle policies to retrieve + :param master_timeout: The period to wait for a connection to the master node. + If no response is received before the timeout expires, the request fails + and returns an error. + :param timeout: The period to wait for a response. If no response is received + before the timeout expires, the request fails and returns an error. """ __path_parts: t.Dict[str, str] if policy_id not in SKIP_IN_PATH: @@ -179,8 +220,12 @@ async def get_lifecycle( __query["filter_path"] = filter_path if human is not None: __query["human"] = human + if master_timeout is not None: + __query["master_timeout"] = master_timeout if pretty is not None: __query["pretty"] = pretty + if timeout is not None: + __query["timeout"] = timeout __headers = {"accept": "application/json"} return await self.perform_request( # type: ignore[return-value] "GET", @@ -198,13 +243,21 @@ async def get_stats( error_trace: t.Optional[bool] = None, filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, human: t.Optional[bool] = None, + 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, ) -> ObjectApiResponse[t.Any]: """ Get snapshot lifecycle management statistics. Get global and policy-level statistics about actions taken by snapshot lifecycle management. ``_ + + :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. """ __path_parts: t.Dict[str, str] = {} __path = "/_slm/stats" @@ -215,8 +268,12 @@ async def get_stats( __query["filter_path"] = filter_path if human is not None: __query["human"] = human + if master_timeout is not None: + __query["master_timeout"] = master_timeout if pretty is not None: __query["pretty"] = pretty + if timeout is not None: + __query["timeout"] = timeout __headers = {"accept": "application/json"} return await self.perform_request( # type: ignore[return-value] "GET", @@ -234,12 +291,22 @@ async def get_status( error_trace: t.Optional[bool] = None, filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, human: t.Optional[bool] = None, + 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, ) -> ObjectApiResponse[t.Any]: """ Get the snapshot lifecycle management status. ``_ + + :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. To indicate that the request should never timeout, + set it to `-1`. + :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. To indicate + that the request should never timeout, set it to `-1`. """ __path_parts: t.Dict[str, str] = {} __path = "/_slm/status" @@ -250,8 +317,12 @@ async def get_status( __query["filter_path"] = filter_path if human is not None: __query["human"] = human + if master_timeout is not None: + __query["master_timeout"] = master_timeout if pretty is not None: __query["pretty"] = pretty + if timeout is not None: + __query["timeout"] = timeout __headers = {"accept": "application/json"} return await self.perform_request( # type: ignore[return-value] "GET", @@ -292,9 +363,10 @@ async def put_lifecycle( :param policy_id: The identifier for the snapshot lifecycle policy you want to create or update. :param config: Configuration for each snapshot created by the policy. - :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 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. To indicate that the request should never timeout, + set it to `-1`. :param name: Name automatically assigned to each snapshot created by the policy. Date math is supported. To prevent conflicting snapshot names, a UUID is automatically appended to each snapshot name. @@ -305,8 +377,9 @@ async def put_lifecycle( by the policy. :param schedule: Periodic or absolute schedule at which the policy creates snapshots. SLM applies schedule changes immediately. - :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 timeout: The period to wait for a response. If no response is received + before the timeout expires, the request fails and returns an error. To indicate + that the request should never timeout, set it to `-1`. """ if policy_id in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'policy_id'") @@ -359,7 +432,9 @@ async def start( error_trace: t.Optional[bool] = None, filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, human: t.Optional[bool] = None, + 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, ) -> ObjectApiResponse[t.Any]: """ Start snapshot lifecycle management. Snapshot lifecycle management (SLM) starts @@ -367,6 +442,14 @@ async def start( if it has been stopped using the stop SLM API. ``_ + + :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. To indicate that the request should never timeout, + set it to `-1`. + :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. To indicate + that the request should never timeout, set it to `-1`. """ __path_parts: t.Dict[str, str] = {} __path = "/_slm/start" @@ -377,8 +460,12 @@ async def start( __query["filter_path"] = filter_path if human is not None: __query["human"] = human + if master_timeout is not None: + __query["master_timeout"] = master_timeout if pretty is not None: __query["pretty"] = pretty + if timeout is not None: + __query["timeout"] = timeout __headers = {"accept": "application/json"} return await self.perform_request( # type: ignore[return-value] "POST", @@ -396,7 +483,9 @@ async def stop( error_trace: t.Optional[bool] = None, filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, human: t.Optional[bool] = None, + 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, ) -> ObjectApiResponse[t.Any]: """ Stop snapshot lifecycle management. Stop all snapshot lifecycle management (SLM) @@ -410,6 +499,14 @@ async def stop( status API to see if SLM is running. ``_ + + :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. To indicate that the request should never timeout, + set it to `-1`. + :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. To indicate + that the request should never timeout, set it to `-1`. """ __path_parts: t.Dict[str, str] = {} __path = "/_slm/stop" @@ -420,8 +517,12 @@ async def stop( __query["filter_path"] = filter_path if human is not None: __query["human"] = human + if master_timeout is not None: + __query["master_timeout"] = master_timeout if pretty is not None: __query["pretty"] = pretty + if timeout is not None: + __query["timeout"] = timeout __headers = {"accept": "application/json"} return await self.perform_request( # type: ignore[return-value] "POST", diff --git a/elasticsearch/_async/client/snapshot.py b/elasticsearch/_async/client/snapshot.py index cbaf16a8b..5c9b5ad3b 100644 --- a/elasticsearch/_async/client/snapshot.py +++ b/elasticsearch/_async/client/snapshot.py @@ -49,9 +49,16 @@ async def cleanup_repository( ``_ - :param name: Snapshot repository to clean up. - :param master_timeout: Period to wait for a connection to the master node. - :param timeout: Period to wait for a response. + :param name: The name of the snapshot repository to clean up. + :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 indicate that the request should never timeout, + set it to `-1` + :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. To indicate + that the request should never timeout, set it to `-1`. """ if name in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'name'") @@ -102,14 +109,19 @@ async def clone( Clone a snapshot. Clone part of all of a snapshot into another snapshot in the same repository. - ``_ + ``_ - :param repository: A repository name - :param snapshot: The name of the snapshot to clone from - :param target_snapshot: The name of the cloned snapshot to create - :param indices: - :param master_timeout: Explicit operation timeout for connection to master node - :param timeout: + :param repository: The name of the snapshot repository that both source and target + snapshot belong to. + :param snapshot: The source snapshot name. + :param target_snapshot: The target snapshot name. + :param indices: A comma-separated list of indices to include in the snapshot. + Multi-target syntax is supported. + :param master_timeout: The period to wait for the master node. If the master + node is not available before the timeout expires, the request fails and returns + an error. To indicate that the request should never timeout, set it to `-1`. + :param timeout: The period of time to wait for a response. If no response is + received before the timeout expires, the request fails and returns an error. """ if repository in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'repository'") @@ -155,6 +167,7 @@ async def clone( @_rewrite_parameters( body_fields=( + "expand_wildcards", "feature_states", "ignore_unavailable", "include_global_state", @@ -169,6 +182,14 @@ async def create( repository: str, snapshot: str, error_trace: t.Optional[bool] = None, + expand_wildcards: t.Optional[ + t.Union[ + t.Sequence[ + t.Union[str, t.Literal["all", "closed", "hidden", "none", "open"]] + ], + t.Union[str, t.Literal["all", "closed", "hidden", "none", "open"]], + ] + ] = None, feature_states: t.Optional[t.Sequence[str]] = None, filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, human: t.Optional[bool] = None, @@ -185,15 +206,22 @@ async def create( """ Create a snapshot. Take a snapshot of a cluster or of data streams and indices. - ``_ + ``_ - :param repository: Repository for the snapshot. - :param snapshot: Name of the snapshot. Must be unique in the repository. - :param feature_states: Feature states to include in the snapshot. Each feature + :param repository: The name of the repository for the snapshot. + :param snapshot: The name of the snapshot. It supportes date math. It must be + unique in the repository. + :param expand_wildcards: Determines how wildcard patterns in the `indices` parameter + match data streams and indices. It supports comma-separated values such as + `open,hidden`. + :param feature_states: The feature states to include in the snapshot. Each feature state includes one or more system indices containing related data. You can view a list of eligible features using the get features API. If `include_global_state` is `true`, all current feature states are included by default. If `include_global_state` - is `false`, no feature states are included by default. + is `false`, no feature states are included by default. Note that specifying + an empty array will result in the default behavior. To exclude all feature + states, regardless of the `include_global_state` value, specify an array + with only the value `none` (`["none"]`). :param ignore_unavailable: If `true`, the request ignores data streams and indices in `indices` that are missing or closed. If `false`, the request returns an error for any data stream or index that is missing or closed. @@ -202,18 +230,24 @@ async def create( composable index templates, legacy index templates, ingest pipelines, and ILM policies. It also includes data stored in system indices, such as Watches and task records (configurable via `feature_states`). - :param indices: Data streams and indices to include in the snapshot. Supports - multi-target syntax. Includes all data streams and indices by default. - :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 metadata: Optional metadata for the snapshot. May have any contents. Must - be less than 1024 bytes. This map is not automatically generated by Elasticsearch. - :param partial: If `true`, allows restoring a partial snapshot of indices with - unavailable shards. Only shards that were successfully included in the snapshot - will be restored. All missing shards will be recreated as empty. If `false`, - the entire restore operation will fail if one or more indices included in - the snapshot do not have all primary shards available. + :param indices: A comma-separated list of data streams and indices to include + in the snapshot. It supports a multi-target syntax. The default is an empty + array (`[]`), which includes all regular data streams and regular indices. + To exclude all data streams and indices, use `-*`. You can't use this parameter + to include or exclude system indices or system data streams from a snapshot. + Use `feature_states` instead. + :param master_timeout: The period to wait for a connection to the master node. + If no response is received before the timeout expires, the request fails + and returns an error. + :param metadata: Arbitrary metadata to the snapshot, such as a record of who + took the snapshot, why it was taken, or any other useful data. It can have + any contents but it must be less than 1024 bytes. This information is not + automatically generated by Elasticsearch. + :param partial: If `true`, it enables you to restore a partial snapshot of indices + with unavailable shards. Only shards that were successfully included in the + snapshot will be restored. All missing shards will be recreated as empty. + If `false`, the entire restore operation will fail if one or more indices + included in the snapshot do not have all primary shards available. :param wait_for_completion: If `true`, the request returns a response when the snapshot is complete. If `false`, the request returns a response when the snapshot initializes. @@ -242,6 +276,8 @@ async def create( if wait_for_completion is not None: __query["wait_for_completion"] = wait_for_completion if not __body: + if expand_wildcards is not None: + __body["expand_wildcards"] = expand_wildcards if feature_states is not None: __body["feature_states"] = feature_states if ignore_unavailable is not None: @@ -292,14 +328,26 @@ async def create_repository( clusters. To register a snapshot repository, the cluster's global metadata must be writeable. Ensure there are no cluster blocks (for example, `cluster.blocks.read_only` and `clsuter.blocks.read_only_allow_delete` settings) that prevent write access. + Several options for this API can be specified using a query parameter or a request + body parameter. If both parameters are specified, only the query parameter is + used. - ``_ + ``_ - :param name: A repository name + :param name: The name of the snapshot repository to register or update. :param repository: - :param master_timeout: Explicit operation timeout for connection to master node - :param timeout: Explicit operation timeout - :param verify: Whether to verify the repository after creation + :param master_timeout: The period to wait for the master node. If the master + node is not available before the timeout expires, the request fails and returns + an error. To indicate that the request should never timeout, set it to `-1`. + :param 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. To indicate + that the request should never timeout, set it to `-1`. + :param verify: If `true`, the request verifies the repository is functional on + all master and data nodes in the cluster. If `false`, this verification is + skipped. You can also perform this verification with the verify snapshot + repository API. """ if name in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'name'") @@ -353,11 +401,14 @@ async def delete( """ Delete snapshots. - ``_ + ``_ - :param repository: A repository name - :param snapshot: A comma-separated list of snapshot names - :param master_timeout: Explicit operation timeout for connection to master node + :param repository: The name of the repository to delete a snapshot from. + :param snapshot: A comma-separated list of snapshot names to delete. It also + accepts wildcards (`*`). + :param master_timeout: The period to wait for the master node. If the master + node is not available before the timeout expires, the request fails and returns + an error. To indicate that the request should never timeout, set it to `-1`. """ if repository in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'repository'") @@ -406,12 +457,18 @@ async def delete_repository( removes only the reference to the location where the repository is storing the snapshots. The snapshots themselves are left untouched and in place. - ``_ + ``_ - :param name: Name of the snapshot repository to unregister. Wildcard (`*`) patterns - are supported. - :param master_timeout: Explicit operation timeout for connection to master node - :param timeout: Explicit operation timeout + :param name: The ame of the snapshot repositories to unregister. Wildcard (`*`) + patterns are supported. + :param master_timeout: The period to wait for the master node. If the master + node is not available before the timeout expires, the request fails and returns + an error. To indicate that the request should never timeout, set it to `-1`. + :param 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. To indicate + that the request should never timeout, set it to `-1`. """ if name in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'name'") @@ -478,50 +535,65 @@ async def get( verbose: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Get snapshot information. - - ``_ - - :param repository: Comma-separated list of snapshot repository names used to - limit the request. Wildcard (*) expressions are supported. - :param snapshot: Comma-separated list of snapshot names to retrieve. Also accepts - wildcards (*). - To get information about all snapshots in a registered repository, - use a wildcard (*) or _all. - To get information about any snapshots that - are currently running, use _current. - :param after: Offset identifier to start pagination from as returned by the next - field in the response body. - :param from_sort_value: Value of the current sort column at which to start retrieval. - Can either be a string snapshot- or repository name when sorting by snapshot - or repository name, a millisecond time value or a number when sorting by - index- or shard count. - :param ignore_unavailable: If false, the request returns an error for any snapshots + Get snapshot information. NOTE: The `after` parameter and `next` field enable + you to iterate through snapshots with some consistency guarantees regarding concurrent + creation or deletion of snapshots. It is guaranteed that any snapshot that exists + at the beginning of the iteration and is not concurrently deleted will be seen + during the iteration. Snapshots concurrently created may be seen during an iteration. + + ``_ + + :param repository: A comma-separated list of snapshot repository names used to + limit the request. Wildcard (`*`) expressions are supported. + :param snapshot: A comma-separated list of snapshot names to retrieve Wildcards + (`*`) are supported. * To get information about all snapshots in a registered + repository, use a wildcard (`*`) or `_all`. * To get information about any + snapshots that are currently running, use `_current`. + :param after: An offset identifier to start pagination from as returned by the + next field in the response body. + :param from_sort_value: The value of the current sort column at which to start + retrieval. It can be a string `snapshot-` or a repository name when sorting + by snapshot or repository name. It can be a millisecond time value or a number + when sorting by `index-` or shard count. + :param ignore_unavailable: If `false`, the request returns an error for any snapshots that are unavailable. - :param include_repository: If true, returns the repository name in each snapshot. - :param index_details: If true, returns additional information about each index - in the snapshot comprising the number of shards in the index, the total size - of the index in bytes, and the maximum number of segments per shard in the - index. Defaults to false, meaning that this information is omitted. - :param index_names: If true, returns the name of each index in each snapshot. - :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 include_repository: If `true`, the response includes the repository name + in each snapshot. + :param index_details: If `true`, the response includes additional information + about each index in the snapshot comprising the number of shards in the index, + the total size of the index in bytes, and the maximum number of segments + per shard in the index. The default is `false`, meaning that this information + is omitted. + :param index_names: If `true`, the response includes the name of each index in + each snapshot. + :param master_timeout: The period to wait for a connection to the master node. + If no response is received before the timeout expires, the request fails + and returns an error. :param offset: Numeric offset to start pagination from based on the snapshots matching this request. Using a non-zero value for this parameter is mutually exclusive with using the after parameter. Defaults to 0. - :param order: Sort order. Valid values are asc for ascending and desc for descending - order. Defaults to asc, meaning ascending order. - :param size: Maximum number of snapshots to return. Defaults to 0 which means - return all that match the request without limit. - :param slm_policy_filter: Filter snapshots by a comma-separated list of SLM policy - names that snapshots belong to. Also accepts wildcards (*) and combinations - of wildcards followed by exclude patterns starting with -. To include snapshots - not created by an SLM policy you can use the special pattern _none that will - match all snapshots without an SLM policy. - :param sort: Allows setting a sort order for the result. Defaults to start_time, - i.e. sorting by snapshot start time stamp. - :param verbose: If true, returns additional information about each snapshot such - as the version of Elasticsearch which took the snapshot, the start and end - times of the snapshot, and the number of shards snapshotted. + :param order: The sort order. Valid values are `asc` for ascending and `desc` + for descending order. The default behavior is ascending order. + :param size: The maximum number of snapshots to return. The default is 0, which + means to return all that match the request without limit. + :param slm_policy_filter: Filter snapshots by a comma-separated list of snapshot + lifecycle management (SLM) policy names that snapshots belong to. You can + use wildcards (`*`) and combinations of wildcards followed by exclude patterns + starting with `-`. For example, the pattern `*,-policy-a-\\*` will return + all snapshots except for those that were created by an SLM policy with a + name starting with `policy-a-`. Note that the wildcard pattern `*` matches + all snapshots created by an SLM policy but not those snapshots that were + not created by an SLM policy. To include snapshots that were not created + by an SLM policy, you can use the special pattern `_none` that will match + all snapshots without an SLM policy. + :param sort: The sort order for the result. The default behavior is sorting by + snapshot start time stamp. + :param verbose: If `true`, returns additional information about each snapshot + such as the version of Elasticsearch which took the snapshot, the start and + end times of the snapshot, and the number of shards snapshotted. NOTE: The + parameters `size`, `order`, `after`, `from_sort_value`, `offset`, `slm_policy_filter`, + and `sort` are not supported when you set `verbose=false` and the sort order + for requests with `verbose=false` is undefined. """ if repository in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'repository'") @@ -592,12 +664,18 @@ async def get_repository( """ Get snapshot repository information. - ``_ + ``_ - :param name: A comma-separated list of repository names - :param local: Return local information, do not retrieve the state from master - node (default: false) - :param master_timeout: Explicit operation timeout for connection to master node + :param name: A comma-separated list of snapshot repository names used to limit + the request. Wildcard (`*`) expressions are supported including combining + wildcards with exclude patterns starting with `-`. To get information about + all snapshot repositories registered in the cluster, omit this parameter + or use `*` or `_all`. + :param local: If `true`, the request gets information from the local node only. + If `false`, the request gets information from the master node. + :param master_timeout: The period to wait for the master node. If the master + node is not available before the timeout expires, the request fails and returns + an error. To indicate that the request should never timeout, set it to `-1`. """ __path_parts: t.Dict[str, str] if name not in SKIP_IN_PATH: @@ -629,6 +707,225 @@ async def get_repository( path_parts=__path_parts, ) + @_rewrite_parameters() + async def repository_analyze( + self, + *, + name: str, + blob_count: t.Optional[int] = None, + concurrency: t.Optional[int] = None, + detailed: t.Optional[bool] = None, + early_read_node_count: t.Optional[int] = None, + error_trace: t.Optional[bool] = None, + filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, + human: t.Optional[bool] = None, + max_blob_size: t.Optional[t.Union[int, str]] = None, + max_total_data_size: t.Optional[t.Union[int, str]] = None, + pretty: t.Optional[bool] = None, + rare_action_probability: t.Optional[float] = None, + rarely_abort_writes: t.Optional[bool] = None, + read_node_count: t.Optional[int] = None, + register_operation_count: t.Optional[int] = None, + seed: t.Optional[int] = None, + timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, + ) -> ObjectApiResponse[t.Any]: + """ + Analyze a snapshot repository. Analyze the performance characteristics and any + incorrect behaviour found in a repository. The response exposes implementation + details of the analysis which may change from version to version. The response + body format is therefore not considered stable and may be different in newer + versions. There are a large number of third-party storage systems available, + not all of which are suitable for use as a snapshot repository by Elasticsearch. + Some storage systems behave incorrectly, or perform poorly, especially when accessed + concurrently by multiple clients as the nodes of an Elasticsearch cluster do. + This API performs a collection of read and write operations on your repository + which are designed to detect incorrect behaviour and to measure the performance + characteristics of your storage system. The default values for the parameters + are deliberately low to reduce the impact of running an analysis inadvertently + and to provide a sensible starting point for your investigations. Run your first + analysis with the default parameter values to check for simple problems. If successful, + run a sequence of increasingly large analyses until you encounter a failure or + you reach a `blob_count` of at least `2000`, a `max_blob_size` of at least `2gb`, + a `max_total_data_size` of at least `1tb`, and a `register_operation_count` of + at least `100`. Always specify a generous timeout, possibly `1h` or longer, to + allow time for each analysis to run to completion. Perform the analyses using + a multi-node cluster of a similar size to your production cluster so that it + can detect any problems that only arise when the repository is accessed by many + nodes at once. If the analysis fails, Elasticsearch detected that your repository + behaved unexpectedly. This usually means you are using a third-party storage + system with an incorrect or incompatible implementation of the API it claims + to support. If so, this storage system is not suitable for use as a snapshot + repository. You will need to work with the supplier of your storage system to + address the incompatibilities that Elasticsearch detects. If the analysis is + successful, the API returns details of the testing process, optionally including + how long each operation took. You can use this information to determine the performance + of your storage system. If any operation fails or returns an incorrect result, + the API returns an error. If the API returns an error, it may not have removed + all the data it wrote to the repository. The error will indicate the location + of any leftover data and this path is also recorded in the Elasticsearch logs. + You should verify that this location has been cleaned up correctly. If there + is still leftover data at the specified location, you should manually remove + it. If the connection from your client to Elasticsearch is closed while the client + is waiting for the result of the analysis, the test is cancelled. Some clients + are configured to close their connection if no response is received within a + certain timeout. An analysis takes a long time to complete so you might need + to relax any such client-side timeouts. On cancellation the analysis attempts + to clean up the data it was writing, but it may not be able to remove it all. + The path to the leftover data is recorded in the Elasticsearch logs. You should + verify that this location has been cleaned up correctly. If there is still leftover + data at the specified location, you should manually remove it. If the analysis + is successful then it detected no incorrect behaviour, but this does not mean + that correct behaviour is guaranteed. The analysis attempts to detect common + bugs but it does not offer 100% coverage. Additionally, it does not test the + following: * Your repository must perform durable writes. Once a blob has been + written it must remain in place until it is deleted, even after a power loss + or similar disaster. * Your repository must not suffer from silent data corruption. + Once a blob has been written, its contents must remain unchanged until it is + deliberately modified or deleted. * Your repository must behave correctly even + if connectivity from the cluster is disrupted. Reads and writes may fail in this + case, but they must not return incorrect results. IMPORTANT: An analysis writes + a substantial amount of data to your repository and then reads it back again. + This consumes bandwidth on the network between the cluster and the repository, + and storage space and I/O bandwidth on the repository itself. You must ensure + this load does not affect other users of these systems. Analyses respect the + repository settings `max_snapshot_bytes_per_sec` and `max_restore_bytes_per_sec` + if available and the cluster setting `indices.recovery.max_bytes_per_sec` which + you can use to limit the bandwidth they consume. NOTE: This API is intended for + exploratory use by humans. You should expect the request parameters and the response + format to vary in future versions. NOTE: Different versions of Elasticsearch + may perform different checks for repository compatibility, with newer versions + typically being stricter than older ones. A storage system that passes repository + analysis with one version of Elasticsearch may fail with a different version. + This indicates it behaves incorrectly in ways that the former version did not + detect. You must work with the supplier of your storage system to address the + incompatibilities detected by the repository analysis API in any version of Elasticsearch. + NOTE: This API may not work correctly in a mixed-version cluster. *Implementation + details* NOTE: This section of documentation describes how the repository analysis + API works in this version of Elasticsearch, but you should expect the implementation + to vary between versions. The request parameters and response format depend on + details of the implementation so may also be different in newer versions. The + analysis comprises a number of blob-level tasks, as set by the `blob_count` parameter + and a number of compare-and-exchange operations on linearizable registers, as + set by the `register_operation_count` parameter. These tasks are distributed + over the data and master-eligible nodes in the cluster for execution. For most + blob-level tasks, the executing node first writes a blob to the repository and + then instructs some of the other nodes in the cluster to attempt to read the + data it just wrote. The size of the blob is chosen randomly, according to the + `max_blob_size` and `max_total_data_size` parameters. If any of these reads fails + then the repository does not implement the necessary read-after-write semantics + that Elasticsearch requires. For some blob-level tasks, the executing node will + instruct some of its peers to attempt to read the data before the writing process + completes. These reads are permitted to fail, but must not return partial data. + If any read returns partial data then the repository does not implement the necessary + atomicity semantics that Elasticsearch requires. For some blob-level tasks, the + executing node will overwrite the blob while its peers are reading it. In this + case the data read may come from either the original or the overwritten blob, + but the read operation must not return partial data or a mix of data from the + two blobs. If any of these reads returns partial data or a mix of the two blobs + then the repository does not implement the necessary atomicity semantics that + Elasticsearch requires for overwrites. The executing node will use a variety + of different methods to write the blob. For instance, where applicable, it will + use both single-part and multi-part uploads. Similarly, the reading nodes will + use a variety of different methods to read the data back again. For instance + they may read the entire blob from start to end or may read only a subset of + the data. For some blob-level tasks, the executing node will cancel the write + before it is complete. In this case, it still instructs some of the other nodes + in the cluster to attempt to read the blob but all of these reads must fail to + find the blob. Linearizable registers are special blobs that Elasticsearch manipulates + using an atomic compare-and-exchange operation. This operation ensures correct + and strongly-consistent behavior even when the blob is accessed by multiple nodes + at the same time. The detailed implementation of the compare-and-exchange operation + on linearizable registers varies by repository type. Repository analysis verifies + that that uncontended compare-and-exchange operations on a linearizable register + blob always succeed. Repository analysis also verifies that contended operations + either succeed or report the contention but do not return incorrect results. + If an operation fails due to contention, Elasticsearch retries the operation + until it succeeds. Most of the compare-and-exchange operations performed by repository + analysis atomically increment a counter which is represented as an 8-byte blob. + Some operations also verify the behavior on small blobs with sizes other than + 8 bytes. + + ``_ + + :param name: The name of the repository. + :param blob_count: The total number of blobs to write to the repository during + the test. For realistic experiments, you should set it to at least `2000`. + :param concurrency: The number of operations to run concurrently during the test. + :param detailed: Indicates whether to return detailed results, including timing + information for every operation performed during the analysis. If false, + it returns only a summary of the analysis. + :param early_read_node_count: The number of nodes on which to perform an early + read operation while writing each blob. Early read operations are only rarely + performed. + :param max_blob_size: The maximum size of a blob to be written during the test. + For realistic experiments, you should set it to at least `2gb`. + :param max_total_data_size: An upper limit on the total size of all the blobs + written during the test. For realistic experiments, you should set it to + at least `1tb`. + :param rare_action_probability: The probability of performing a rare action such + as an early read, an overwrite, or an aborted write on each blob. + :param rarely_abort_writes: Indicates whether to rarely cancel writes before + they complete. + :param read_node_count: The number of nodes on which to read a blob after writing. + :param register_operation_count: The minimum number of linearizable register + operations to perform in total. For realistic experiments, you should set + it to at least `100`. + :param seed: The seed for the pseudo-random number generator used to generate + the list of operations performed during the test. To repeat the same set + of operations in multiple experiments, use the same seed in each experiment. + Note that the operations are performed concurrently so might not always happen + in the same order on each run. + :param timeout: The period of time to wait for the test to complete. If no response + is received before the timeout expires, the test is cancelled and returns + an error. + """ + if name in SKIP_IN_PATH: + raise ValueError("Empty value passed for parameter 'name'") + __path_parts: t.Dict[str, str] = {"repository": _quote(name)} + __path = f'/_snapshot/{__path_parts["repository"]}/_analyze' + __query: t.Dict[str, t.Any] = {} + if blob_count is not None: + __query["blob_count"] = blob_count + if concurrency is not None: + __query["concurrency"] = concurrency + if detailed is not None: + __query["detailed"] = detailed + if early_read_node_count is not None: + __query["early_read_node_count"] = early_read_node_count + if error_trace is not None: + __query["error_trace"] = error_trace + if filter_path is not None: + __query["filter_path"] = filter_path + if human is not None: + __query["human"] = human + if max_blob_size is not None: + __query["max_blob_size"] = max_blob_size + if max_total_data_size is not None: + __query["max_total_data_size"] = max_total_data_size + if pretty is not None: + __query["pretty"] = pretty + if rare_action_probability is not None: + __query["rare_action_probability"] = rare_action_probability + if rarely_abort_writes is not None: + __query["rarely_abort_writes"] = rarely_abort_writes + if read_node_count is not None: + __query["read_node_count"] = read_node_count + if register_operation_count is not None: + __query["register_operation_count"] = register_operation_count + if seed is not None: + __query["seed"] = seed + if timeout is not None: + __query["timeout"] = timeout + __headers = {"accept": "application/json"} + return await self.perform_request( # type: ignore[return-value] + "POST", + __path, + params=__query, + headers=__headers, + endpoint_id="snapshot.repository_analyze", + path_parts=__path_parts, + ) + @_rewrite_parameters() @_stability_warning(Stability.EXPERIMENTAL) async def repository_verify_integrity( @@ -682,21 +979,43 @@ async def repository_verify_integrity( prevented it from detecting. NOTE: This API is intended for exploratory use by humans. You should expect the request parameters and the response format to vary in future versions. NOTE: This API may not work correctly in a mixed-version - cluster. - - ``_ - - :param name: A repository name - :param blob_thread_pool_concurrency: Number of threads to use for reading blob - contents - :param index_snapshot_verification_concurrency: Number of snapshots to verify - concurrently within each index - :param index_verification_concurrency: Number of indices to verify concurrently - :param max_bytes_per_sec: Rate limit for individual blob verification - :param max_failed_shard_snapshots: Maximum permitted number of failed shard snapshots - :param meta_thread_pool_concurrency: Number of threads to use for reading metadata - :param snapshot_verification_concurrency: Number of snapshots to verify concurrently - :param verify_blob_contents: Whether to verify the contents of individual blobs + cluster. The default values for the parameters of this API are designed to limit + the impact of the integrity verification on other activities in your cluster. + For instance, by default it will only use at most half of the `snapshot_meta` + threads to verify the integrity of each snapshot, allowing other snapshot operations + to use the other half of this thread pool. If you modify these parameters to + speed up the verification process, you risk disrupting other snapshot-related + operations in your cluster. For large repositories, consider setting up a separate + single-node Elasticsearch cluster just for running the integrity verification + API. The response exposes implementation details of the analysis which may change + from version to version. The response body format is therefore not considered + stable and may be different in newer versions. + + ``_ + + :param name: The name of the snapshot repository. + :param blob_thread_pool_concurrency: If `verify_blob_contents` is `true`, this + parameter specifies how many blobs to verify at once. + :param index_snapshot_verification_concurrency: The maximum number of index snapshots + to verify concurrently within each index verification. + :param index_verification_concurrency: The number of indices to verify concurrently. + The default behavior is to use the entire `snapshot_meta` thread pool. + :param max_bytes_per_sec: If `verify_blob_contents` is `true`, this parameter + specifies the maximum amount of data that Elasticsearch will read from the + repository every second. + :param max_failed_shard_snapshots: The number of shard snapshot failures to track + during integrity verification, in order to avoid excessive resource usage. + If your repository contains more than this number of shard snapshot failures, + the verification will fail. + :param meta_thread_pool_concurrency: The maximum number of snapshot metadata + operations to run concurrently. The default behavior is to use at most half + of the `snapshot_meta` thread pool at once. + :param snapshot_verification_concurrency: The number of snapshots to verify concurrently. + The default behavior is to use at most half of the `snapshot_meta` thread + pool at once. + :param verify_blob_contents: Indicates whether to verify the checksum of every + data blob in the repository. If this feature is enabled, Elasticsearch will + read the entire repository contents, which may be extremely slow and expensive. """ if name in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'name'") @@ -794,23 +1113,66 @@ async def restore( or Workplace Search, you must restore the Enterprise Search encryption key before you restore the snapshot. - ``_ - - :param repository: A repository name - :param snapshot: A snapshot name - :param feature_states: - :param ignore_index_settings: - :param ignore_unavailable: - :param include_aliases: - :param include_global_state: - :param index_settings: - :param indices: - :param master_timeout: Explicit operation timeout for connection to master node - :param partial: - :param rename_pattern: - :param rename_replacement: - :param wait_for_completion: Should this request wait until the operation has - completed before returning + ``_ + + :param repository: The name of the repository to restore a snapshot from. + :param snapshot: The name of the snapshot to restore. + :param feature_states: The feature states to restore. If `include_global_state` + is `true`, the request restores all feature states in the snapshot by default. + If `include_global_state` is `false`, the request restores no feature states + by default. Note that specifying an empty array will result in the default + behavior. To restore no feature states, regardless of the `include_global_state` + value, specify an array containing only the value `none` (`["none"]`). + :param ignore_index_settings: The index settings to not restore from the snapshot. + You can't use this option to ignore `index.number_of_shards`. For data streams, + this option applies only to restored backing indices. New backing indices + are configured using the data stream's matching index template. + :param ignore_unavailable: If `true`, the request ignores any index or data stream + in indices that's missing from the snapshot. If `false`, the request returns + an error for any missing index or data stream. + :param include_aliases: If `true`, the request restores aliases for any restored + data streams and indices. If `false`, the request doesn’t restore aliases. + :param include_global_state: If `true`, restore the cluster state. The cluster + state includes: * Persistent cluster settings * Index templates * Legacy + index templates * Ingest pipelines * Index lifecycle management (ILM) policies + * Stored scripts * For snapshots taken after 7.12.0, feature states If `include_global_state` + is `true`, the restore operation merges the legacy index templates in your + cluster with the templates contained in the snapshot, replacing any existing + ones whose name matches one in the snapshot. It completely removes all persistent + settings, non-legacy index templates, ingest pipelines, and ILM lifecycle + policies that exist in your cluster and replaces them with the corresponding + items from the snapshot. Use the `feature_states` parameter to configure + how feature states are restored. If `include_global_state` is `true` and + a snapshot was created without a global state then the restore request will + fail. + :param index_settings: Index settings to add or change in restored indices, including + backing indices. You can't use this option to change `index.number_of_shards`. + For data streams, this option applies only to restored backing indices. New + backing indices are configured using the data stream's matching index template. + :param indices: A comma-separated list of indices and data streams to restore. + It supports a multi-target syntax. The default behavior is all regular indices + and regular data streams in the snapshot. You can't use this parameter to + restore system indices or system data streams. Use `feature_states` instead. + :param master_timeout: The period to wait for the master node. If the master + node is not available before the timeout expires, the request fails and returns + an error. To indicate that the request should never timeout, set it to `-1`. + :param partial: If `false`, the entire restore operation will fail if one or + more indices included in the snapshot do not have all primary shards available. + If true, it allows restoring a partial snapshot of indices with unavailable + shards. Only shards that were successfully included in the snapshot will + be restored. All missing shards will be recreated as empty. + :param rename_pattern: A rename pattern to apply to restored data streams and + indices. Data streams and indices matching the rename pattern will be renamed + according to `rename_replacement`. The rename pattern is applied as defined + by the regular expression that supports referencing the original text, according + to the `appendReplacement` logic. + :param rename_replacement: The rename replacement string that is used with the + `rename_pattern`. + :param wait_for_completion: If `true`, the request returns a response when the + restore operation completes. The operation is complete when it finishes all + attempts to recover primary shards for restored indices. This applies even + if one or more of the recovery attempts fail. If `false`, the request returns + a response when the restore operation initializes. """ if repository in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'repository'") @@ -889,22 +1251,31 @@ async def status( each shard participating in the snapshot. Note that this API should be used only to obtain detailed shard-level information for ongoing snapshots. If this detail is not needed or you want to obtain information about one or more existing snapshots, - use the get snapshot API. WARNING: Using the API to return the status of any - snapshots other than currently running snapshots can be expensive. The API requires - a read from the repository for each shard in each snapshot. For example, if you - have 100 snapshots with 1,000 shards each, an API request that includes all snapshots - will require 100,000 reads (100 snapshots x 1,000 shards). Depending on the latency - of your storage, such requests can take an extremely long time to return results. - These requests can also tax machine resources and, when using cloud storage, - incur high processing costs. - - ``_ - - :param repository: A repository name - :param snapshot: A comma-separated list of snapshot names - :param ignore_unavailable: Whether to ignore unavailable snapshots, defaults - to false which means a SnapshotMissingException is thrown - :param master_timeout: Explicit operation timeout for connection to master node + use the get snapshot API. If you omit the `` request path parameter, + the request retrieves information only for currently running snapshots. This + usage is preferred. If needed, you can specify `` and `` + to retrieve information for specific snapshots, even if they're not currently + running. WARNING: Using the API to return the status of any snapshots other than + currently running snapshots can be expensive. The API requires a read from the + repository for each shard in each snapshot. For example, if you have 100 snapshots + with 1,000 shards each, an API request that includes all snapshots will require + 100,000 reads (100 snapshots x 1,000 shards). Depending on the latency of your + storage, such requests can take an extremely long time to return results. These + requests can also tax machine resources and, when using cloud storage, incur + high processing costs. + + ``_ + + :param repository: The snapshot repository name used to limit the request. It + supports wildcards (`*`) if `` isn't specified. + :param snapshot: A comma-separated list of snapshots to retrieve status for. + The default is currently running snapshots. Wildcards (`*`) are not supported. + :param ignore_unavailable: If `false`, the request returns an error for any snapshots + that are unavailable. If `true`, the request ignores snapshots that are unavailable, + such as those that are corrupted or temporarily cannot be returned. + :param master_timeout: The period to wait for the master node. If the master + node is not available before the timeout expires, the request fails and returns + an error. To indicate that the request should never timeout, set it to `-1`. """ __path_parts: t.Dict[str, str] if repository not in SKIP_IN_PATH and snapshot not in SKIP_IN_PATH: @@ -958,11 +1329,17 @@ async def verify_repository( Verify a snapshot repository. Check for common misconfigurations in a snapshot repository. - ``_ + ``_ - :param name: A repository name - :param master_timeout: Explicit operation timeout for connection to master node - :param timeout: Explicit operation timeout + :param name: The name of the snapshot repository to verify. + :param master_timeout: The period to wait for the master node. If the master + node is not available before the timeout expires, the request fails and returns + an error. To indicate that the request should never timeout, set it to `-1`. + :param 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. To indicate + that the request should never timeout, set it to `-1`. """ if name in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'name'") diff --git a/elasticsearch/_async/client/sql.py b/elasticsearch/_async/client/sql.py index c041681e9..239df900b 100644 --- a/elasticsearch/_async/client/sql.py +++ b/elasticsearch/_async/client/sql.py @@ -85,11 +85,14 @@ async def delete_async( ) -> 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. + 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: Identifier for the search. + :param id: The identifier for the search. """ if id in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'id'") @@ -132,20 +135,23 @@ async def get_async( ) -> 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. + 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: Identifier for the search. - :param delimiter: Separator for CSV results. The API only supports this parameter - for CSV responses. - :param format: Format for the response. You must specify a format using this - parameter or the Accept HTTP header. If you specify both, the API uses this - parameter. - :param keep_alive: Retention period for the search and its results. Defaults + :param id: The identifier for the search. + :param delimiter: The separator for CSV results. The API supports this parameter + only for CSV responses. + :param format: The format for the response. You must specify a format using this + parameter or the `Accept` HTTP header. If you specify both, the API uses + this parameter. + :param keep_alive: The retention period for the search and its results. It defaults to the `keep_alive` period for the original SQL search. - :param wait_for_completion_timeout: Period to wait for complete results. Defaults - to no timeout, meaning the request waits for complete search results. + :param wait_for_completion_timeout: The period to wait for complete results. + It defaults to no timeout, meaning the request waits for complete search + results. """ if id in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'id'") @@ -194,7 +200,7 @@ async def get_async_status( ``_ - :param id: Identifier for the search. + :param id: The identifier for the search. """ if id in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'id'") @@ -221,6 +227,7 @@ async def get_async_status( @_rewrite_parameters( body_fields=( + "allow_partial_search_results", "catalog", "columnar", "cursor", @@ -243,6 +250,7 @@ async def get_async_status( async def query( self, *, + allow_partial_search_results: t.Optional[bool] = None, catalog: t.Optional[str] = None, columnar: t.Optional[bool] = None, cursor: t.Optional[str] = None, @@ -277,36 +285,45 @@ async def query( ``_ - :param catalog: Default catalog (cluster) for queries. If unspecified, the queries - execute on the data in the local cluster only. - :param columnar: If true, the results in a columnar fashion: one row represents - all the values of a certain column from the current page of results. - :param cursor: Cursor used to retrieve a set of paginated results. If you specify - a cursor, the API only uses the `columnar` and `time_zone` request body parameters. - It ignores other request body parameters. - :param fetch_size: The maximum number of rows (or entries) to return in one response - :param field_multi_value_leniency: Throw an exception when encountering multiple - values for a field (default) or be lenient and return the first value from - the list (without any guarantees of what that will be - typically the first - in natural ascending order). - :param filter: Elasticsearch query DSL for additional filtering. - :param format: Format for the response. - :param index_using_frozen: If true, the search can run on frozen indices. Defaults - to false. - :param keep_alive: Retention period for an async or saved synchronous search. - :param keep_on_completion: If true, Elasticsearch stores synchronous searches - if you also specify the wait_for_completion_timeout parameter. If false, - Elasticsearch only stores async searches that don’t finish before the wait_for_completion_timeout. - :param page_timeout: The timeout before a pagination request fails. - :param params: Values for parameters in the query. - :param query: SQL query to run. + :param allow_partial_search_results: If `true`, the response has partial results + when there are shard request timeouts or shard failures. If `false`, the + API returns an error with no partial results. + :param catalog: The default catalog (cluster) for queries. If unspecified, the + queries execute on the data in the local cluster only. + :param columnar: If `true`, the results are in a columnar fashion: one row represents + all the values of a certain column from the current page of results. The + API supports this parameter only for CBOR, JSON, SMILE, and YAML responses. + :param cursor: The cursor used to retrieve a set of paginated results. If you + specify a cursor, the API only uses the `columnar` and `time_zone` request + body parameters. It ignores other request body parameters. + :param fetch_size: The maximum number of rows (or entries) to return in one response. + :param field_multi_value_leniency: If `false`, the API returns an exception when + encountering multiple values for a field. If `true`, the API is lenient and + returns the first value from the array with no guarantee of consistent results. + :param filter: The Elasticsearch query DSL for additional filtering. + :param format: The format for the response. You can also specify a format using + the `Accept` HTTP header. If you specify both this parameter and the `Accept` + HTTP header, this parameter takes precedence. + :param index_using_frozen: If `true`, the search can run on frozen indices. + :param keep_alive: The retention period for an async or saved synchronous search. + :param keep_on_completion: If `true`, Elasticsearch stores synchronous searches + if you also specify the `wait_for_completion_timeout` parameter. If `false`, + Elasticsearch only stores async searches that don't finish before the `wait_for_completion_timeout`. + :param page_timeout: The minimum retention period for the scroll cursor. After + this time period, a pagination request might fail because the scroll cursor + is no longer available. Subsequent scroll requests prolong the lifetime of + the scroll cursor by the duration of `page_timeout` in the scroll request. + :param params: The values for parameters in the query. + :param query: The SQL query to run. :param request_timeout: The timeout before the request fails. - :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 time_zone: ISO-8601 time zone ID for the search. - :param wait_for_completion_timeout: Period to wait for complete results. Defaults - to no timeout, meaning the request waits for complete search results. If - the search doesn’t finish within this period, the search becomes async. + :param runtime_mappings: One or more runtime fields for the search request. These + fields take precedence over mapped fields with the same name. + :param time_zone: The ISO-8601 time zone ID for the search. + :param wait_for_completion_timeout: The period to wait for complete results. + It defaults to no timeout, meaning the request waits for complete search + results. If the search doesn't finish within this period, the search becomes + async. To save a synchronous search, you must specify this parameter and + the `keep_on_completion` parameter. """ __path_parts: t.Dict[str, str] = {} __path = "/_sql" @@ -323,6 +340,8 @@ async def query( if pretty is not None: __query["pretty"] = pretty if not __body: + if allow_partial_search_results is not None: + __body["allow_partial_search_results"] = allow_partial_search_results if catalog is not None: __body["catalog"] = catalog if columnar is not None: @@ -384,14 +403,15 @@ async def translate( ) -> ObjectApiResponse[t.Any]: """ Translate SQL into Elasticsearch queries. Translate an SQL search into a search - API request containing Query DSL. + API request containing Query DSL. It accepts the same request body parameters + as the SQL search API, excluding `cursor`. ``_ - :param query: SQL query to run. + :param query: The SQL query to run. :param fetch_size: The maximum number of rows (or entries) to return in one response. - :param filter: Elasticsearch query DSL for additional filtering. - :param time_zone: ISO-8601 time zone ID for the search. + :param filter: The Elasticsearch query DSL for additional filtering. + :param time_zone: The ISO-8601 time zone ID for the search. """ if query is None and body is None: raise ValueError("Empty value passed for parameter 'query'") diff --git a/elasticsearch/_async/client/synonyms.py b/elasticsearch/_async/client/synonyms.py index ee6e65713..9cb6d9a6e 100644 --- a/elasticsearch/_async/client/synonyms.py +++ b/elasticsearch/_async/client/synonyms.py @@ -36,11 +36,25 @@ async def delete_synonym( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Delete a synonym set. + Delete a synonym set. You can only delete a synonyms set that is not in use by + any index analyzer. Synonyms sets can be used in synonym graph token filters + and synonym token filters. These synonym filters can be used as part of search + analyzers. Analyzers need to be loaded when an index is restored (such as when + a node starts, or the index becomes open). Even if the analyzer is not used on + any field mapping, it still needs to be loaded on the index recovery phase. If + any analyzers cannot be loaded, the index becomes unavailable and the cluster + status becomes red or yellow as index shards are not available. To prevent that, + synonyms sets that are used in analyzers can't be deleted. A delete request in + this case will return a 400 response code. To remove a synonyms set, you must + first remove all indices that contain analyzers using it. You can migrate an + index by creating a new index that does not contain the token filter with the + synonyms set, and use the reindex API in order to copy over the index data. Once + finished, you can delete the index. When the synonyms set is not used in analyzers, + you will be able to delete it. ``_ - :param id: The id of the synonyms set to be deleted + :param id: The synonyms set identifier to delete. """ if id in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'id'") @@ -81,8 +95,8 @@ async def delete_synonym_rule( ``_ - :param set_id: The id of the synonym set to be updated - :param rule_id: The id of the synonym rule to be deleted + :param set_id: The ID of the synonym set to update. + :param rule_id: The ID of the synonym rule to delete. """ if set_id in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'set_id'") @@ -131,9 +145,9 @@ async def get_synonym( ``_ - :param id: "The id of the synonyms set to be retrieved - :param from_: Starting offset for query rules to be retrieved - :param size: specifies a max number of query rules to retrieve + :param id: The synonyms set identifier to retrieve. + :param from_: The starting offset for query rules to retrieve. + :param size: The max number of query rules to retrieve. """ if id in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'id'") @@ -178,8 +192,8 @@ async def get_synonym_rule( ``_ - :param set_id: The id of the synonym set to retrieve the synonym rule from - :param rule_id: The id of the synonym rule to retrieve + :param set_id: The ID of the synonym set to retrieve the synonym rule from. + :param rule_id: The ID of the synonym rule to retrieve. """ if set_id in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'set_id'") @@ -225,10 +239,10 @@ async def get_synonyms_sets( """ Get all synonym sets. Get a summary of all defined synonym sets. - ``_ + ``_ - :param from_: Starting offset - :param size: specifies a max number of results to get + :param from_: The starting offset for synonyms sets to retrieve. + :param size: The maximum number of synonyms sets to retrieve. """ __path_parts: t.Dict[str, str] = {} __path = "/_synonyms" @@ -274,12 +288,15 @@ async def put_synonym( """ Create or update a synonym set. Synonyms sets are limited to a maximum of 10,000 synonym rules per set. If you need to manage more synonym rules, you can create - multiple synonym sets. + multiple synonym sets. When an existing synonyms set is updated, the search analyzers + that use the synonyms set are reloaded automatically for all indices. This is + equivalent to invoking the reload search analyzers API for all indices that use + the synonyms set. ``_ - :param id: The id of the synonyms set to be created or updated - :param synonyms_set: The synonym set information to update + :param id: The ID of the synonyms set to be created or updated. + :param synonyms_set: The synonym rules definitions for the synonyms set. """ if id in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'id'") @@ -328,13 +345,16 @@ async def put_synonym_rule( ) -> ObjectApiResponse[t.Any]: """ Create or update a synonym rule. Create or update a synonym rule in a synonym - set. + set. If any of the synonym rules included is invalid, the API returns an error. + When you update a synonym rule, all analyzers using the synonyms set will be + reloaded automatically to reflect the new rule. ``_ - :param set_id: The id of the synonym set to be updated with the synonym rule - :param rule_id: The id of the synonym rule to be updated or created - :param synonyms: + :param set_id: The ID of the synonym set. + :param rule_id: The ID of the synonym rule to be updated or created. + :param synonyms: The synonym rule information definition, which must be in Solr + format. """ if set_id in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'set_id'") diff --git a/elasticsearch/_async/client/tasks.py b/elasticsearch/_async/client/tasks.py index 27fd7e4c4..7e8dd9166 100644 --- a/elasticsearch/_async/client/tasks.py +++ b/elasticsearch/_async/client/tasks.py @@ -47,27 +47,30 @@ async def cancel( wait_for_completion: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Cancel a task. A task may continue to run for some time after it has been cancelled - because it may not be able to safely stop its current activity straight away. - It is also possible that Elasticsearch must complete its work on other tasks - before it can process the cancellation. The get task information API will continue - to list these cancelled tasks until they complete. The cancelled flag in the - response indicates that the cancellation command has been processed and the task - will stop as soon as possible. To troubleshoot why a cancelled task does not - complete promptly, use the get task information API with the `?detailed` parameter - to identify the other tasks the system is running. You can also use the node - hot threads API to obtain detailed information about the work the system is doing + Cancel a task. WARNING: The task management API is new and should still be considered + a beta feature. The API may change in ways that are not backwards compatible. + A task may continue to run for some time after it has been cancelled because + it may not be able to safely stop its current activity straight away. It is also + possible that Elasticsearch must complete its work on other tasks before it can + process the cancellation. The get task information API will continue to list + these cancelled tasks until they complete. The cancelled flag in the response + indicates that the cancellation command has been processed and the task will + stop as soon as possible. To troubleshoot why a cancelled task does not complete + promptly, use the get task information API with the `?detailed` parameter to + identify the other tasks the system is running. You can also use the node hot + threads API to obtain detailed information about the work the system is doing instead of completing the cancelled task. ``_ - :param task_id: ID of the task. - :param actions: Comma-separated list or wildcard expression of actions used to - limit the request. - :param nodes: Comma-separated list of node IDs or names used to limit the request. - :param parent_task_id: Parent task ID used to limit the tasks. - :param wait_for_completion: Should the request block until the cancellation of - the task and its descendant tasks is completed. Defaults to false + :param task_id: The task identifier. + :param actions: A comma-separated list or wildcard expression of actions that + is used to limit the request. + :param nodes: A comma-separated list of node IDs or names that is used to limit + the request. + :param parent_task_id: A parent task ID that is used to limit the tasks. + :param wait_for_completion: If true, the request blocks until all found tasks + are complete. """ __path_parts: t.Dict[str, str] if task_id not in SKIP_IN_PATH: @@ -118,12 +121,16 @@ async def get( ) -> ObjectApiResponse[t.Any]: """ 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. """ @@ -167,7 +174,6 @@ async def list( t.Union[str, t.Literal["nodes", "none", "parents"]] ] = None, human: t.Optional[bool] = None, - master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, nodes: t.Optional[t.Union[str, t.Sequence[str]]] = None, parent_task_id: t.Optional[str] = None, pretty: t.Optional[bool] = None, @@ -176,25 +182,45 @@ async def list( ) -> ObjectApiResponse[t.Any]: """ Get all tasks. Get information about the tasks currently running on one or more - nodes in the cluster. + nodes in the cluster. WARNING: The task management API is new and should still + be considered a beta feature. The API may change in ways that are not backwards + compatible. **Identifying running tasks** The `X-Opaque-Id header`, when provided + on the HTTP request header, is going to be returned as a header in the response + as well as in the headers field for in the task information. This enables you + to track certain calls or associate certain tasks with the client that started + them. For example: ``` curl -i -H "X-Opaque-Id: 123456" "http://localhost:9200/_tasks?group_by=parents" + ``` The API returns the following result: ``` HTTP/1.1 200 OK X-Opaque-Id: 123456 + content-type: application/json; charset=UTF-8 content-length: 831 { "tasks" : + { "u5lcZHqcQhu-rUoFaqDphA:45" : { "node" : "u5lcZHqcQhu-rUoFaqDphA", "id" : 45, + "type" : "transport", "action" : "cluster:monitor/tasks/lists", "start_time_in_millis" + : 1513823752749, "running_time_in_nanos" : 293139, "cancellable" : false, "headers" + : { "X-Opaque-Id" : "123456" }, "children" : [ { "node" : "u5lcZHqcQhu-rUoFaqDphA", + "id" : 46, "type" : "direct", "action" : "cluster:monitor/tasks/lists[n]", "start_time_in_millis" + : 1513823752750, "running_time_in_nanos" : 92133, "cancellable" : false, "parent_task_id" + : "u5lcZHqcQhu-rUoFaqDphA:45", "headers" : { "X-Opaque-Id" : "123456" } } ] } + } } ``` In this example, `X-Opaque-Id: 123456` is the ID as a part of the response + header. The `X-Opaque-Id` in the task `headers` is the ID for the task that was + initiated by the REST request. The `X-Opaque-Id` in the children `headers` is + the child task of the task that was initiated by the REST request. ``_ - :param actions: Comma-separated list or wildcard expression of actions used to - limit the request. + :param actions: A comma-separated list or wildcard expression of actions used + to limit the request. For example, you can use `cluser:*` to retrieve all + cluster-related tasks. :param detailed: If `true`, the response includes detailed information about - shard recoveries. This information is useful to distinguish tasks from each + the running tasks. This information is useful to distinguish tasks from each other but is more costly to run. - :param group_by: Key used to group tasks in the response. - :param master_timeout: Period to wait for a connection to the master node. If - no response is received before the timeout expires, the request fails and - returns an error. - :param nodes: Comma-separated list of node IDs or names used to limit returned - information. - :param parent_task_id: Parent task ID used to limit returned information. To - return all tasks, omit this parameter or use a value of `-1`. - :param timeout: Period to wait for a response. If no response is received before - the timeout expires, the request fails and returns an error. + :param group_by: A key that is used to group tasks in the response. The task + lists can be grouped either by nodes or by parent tasks. + :param nodes: A comma-separated list of node IDs or names that is used to limit + the returned information. + :param parent_task_id: A parent task identifier that is used to limit returned + information. To return all tasks, omit this parameter or use a value of `-1`. + If the parent task is not found, the API does not return a 404 response code. + :param timeout: The period to wait for each node to respond. If a node does not + respond before its timeout expires, the response does not include its information. + However, timed out nodes are included in the `node_failures` property. :param wait_for_completion: If `true`, the request blocks until the operation is complete. """ @@ -213,8 +239,6 @@ async def list( __query["group_by"] = group_by if human is not None: __query["human"] = human - if master_timeout is not None: - __query["master_timeout"] = master_timeout if nodes is not None: __query["nodes"] = nodes if parent_task_id is not None: diff --git a/elasticsearch/_async/client/text_structure.py b/elasticsearch/_async/client/text_structure.py index a573d8238..50e338233 100644 --- a/elasticsearch/_async/client/text_structure.py +++ b/elasticsearch/_async/client/text_structure.py @@ -54,7 +54,21 @@ async def find_field_structure( ) -> ObjectApiResponse[t.Any]: """ Find the structure of a text field. Find the structure of a text field in an - Elasticsearch index. + Elasticsearch index. This API provides a starting point for extracting further + information from log messages already ingested into Elasticsearch. For example, + if you have ingested data into a very simple index that has just `@timestamp` + and message fields, you can use this API to see what common structure exists + in the message field. The response from the API contains: * Sample messages. + * Statistics that reveal the most common values for all fields detected within + the text and basic numeric statistics for numeric fields. * Information about + the structure of the text, which is useful when you write ingest configurations + to index it or similarly formatted text. * Appropriate mappings for an Elasticsearch + index, which you could use to ingest the text. All this information can be calculated + by the structure finder with no guidance. However, you can optionally override + some of the decisions about the text structure by specifying one or more query + parameters. If the structure finder produces unexpected results, specify the + `explain` query parameter and an explanation will appear in the response. It + helps determine why the returned structure was chosen. ``_ @@ -84,9 +98,9 @@ async def find_field_structure( `field1`, and `field2` are used in the `grok_pattern` output. The intention in that situation is that a user who knows the meanings will rename the fields before using them. - :param explain: If true, the response includes a field named `explanation`, which - is an array of strings that indicate how the structure finder produced its - result. + :param explain: If `true`, the response includes a field named `explanation`, + which is an array of strings that indicate how the structure finder produced + its result. :param format: The high level structure of the text. By default, the API chooses the format. In this default scenario, all rows must have the same number of fields for a delimited format to be detected. If the format is set to @@ -107,7 +121,7 @@ async def find_field_structure( :param should_trim_fields: If the format is `delimited`, you can specify whether values between delimiters should have whitespace trimmed from them. If this parameter is not specified and the delimiter is pipe (`|`), the default value - is true. Otherwise, the default value is false. + is true. Otherwise, the default value is `false`. :param timeout: The maximum amount of time that the structure analysis can take. If the analysis is still running when the timeout expires, it will be stopped. :param timestamp_field: The name of the field that contains the primary timestamp @@ -236,7 +250,10 @@ async def find_message_structure( Appropriate mappings for an Elasticsearch index, which you could use to ingest the text. All this information can be calculated by the structure finder with no guidance. However, you can optionally override some of the decisions about - the text structure by specifying one or more query parameters. + the text structure by specifying one or more query parameters. If the structure + finder produces unexpected results, specify the `explain` query parameter and + an explanation will appear in the response. It helps determine why the returned + structure was chosen. ``_ @@ -284,7 +301,7 @@ async def find_message_structure( :param should_trim_fields: If the format is `delimited`, you can specify whether values between delimiters should have whitespace trimmed from them. If this parameter is not specified and the delimiter is pipe (`|`), the default value - is true. Otherwise, the default value is false. + is true. Otherwise, the default value is `false`. :param timeout: The maximum amount of time that the structure analysis can take. If the analysis is still running when the timeout expires, it will be stopped. :param timestamp_field: The name of the field that contains the primary timestamp @@ -413,43 +430,51 @@ async def find_structure( ``_ :param text_files: - :param charset: The text’s character set. It must be a character set that is - supported by the JVM that Elasticsearch uses. For example, UTF-8, UTF-16LE, - windows-1252, or EUC-JP. If this parameter is not specified, the structure + :param charset: The text's character set. It must be a character set that is + supported by the JVM that Elasticsearch uses. For example, `UTF-8`, `UTF-16LE`, + `windows-1252`, or `EUC-JP`. If this parameter is not specified, the structure finder chooses an appropriate character set. - :param column_names: If you have set format to delimited, you can specify the + :param column_names: If you have set format to `delimited`, you can specify the column names in a comma-separated list. If this parameter is not specified, the structure finder uses the column names from the header row of the text. If the text does not have a header role, columns are named "column1", "column2", "column3", for example. - :param delimiter: If you have set format to delimited, you can specify the character - used to delimit the values in each row. Only a single character is supported; - the delimiter cannot have multiple characters. By default, the API considers - the following possibilities: comma, tab, semi-colon, and pipe (|). In this - default scenario, all rows must have the same number of fields for the delimited - format to be detected. If you specify a delimiter, up to 10% of the rows - can have a different number of columns than the first row. - :param ecs_compatibility: The mode of compatibility with ECS compliant Grok patterns - (disabled or v1, default: disabled). - :param explain: If this parameter is set to true, the response includes a field + :param delimiter: If you have set `format` to `delimited`, you can specify the + character used to delimit the values in each row. Only a single character + is supported; the delimiter cannot have multiple characters. By default, + the API considers the following possibilities: comma, tab, semi-colon, and + pipe (`|`). In this default scenario, all rows must have the same number + of fields for the delimited format to be detected. If you specify a delimiter, + up to 10% of the rows can have a different number of columns than the first + row. + :param ecs_compatibility: The mode of compatibility with ECS compliant Grok patterns. + Use this parameter to specify whether to use ECS Grok patterns instead of + legacy ones when the structure finder creates a Grok pattern. Valid values + are `disabled` and `v1`. This setting primarily has an impact when a whole + message Grok pattern such as `%{CATALINALOG}` matches the input. If the structure + finder identifies a common structure but has no idea of meaning then generic + field names such as `path`, `ipaddress`, `field1`, and `field2` are used + in the `grok_pattern` output, with the intention that a user who knows the + meanings rename these fields before using it. + :param explain: If this parameter is set to `true`, the response includes a field named explanation, which is an array of strings that indicate how the structure finder produced its result. If the structure finder produces unexpected results for some text, use this query parameter to help you determine why the returned structure was chosen. - :param format: The high level structure of the text. Valid values are ndjson, - xml, delimited, and semi_structured_text. By default, the API chooses the - format. In this default scenario, all rows must have the same number of fields - for a delimited format to be detected. If the format is set to delimited - and the delimiter is not set, however, the API tolerates up to 5% of rows - that have a different number of columns than the first row. - :param grok_pattern: If you have set format to semi_structured_text, you can - specify a Grok pattern that is used to extract fields from every message + :param format: The high level structure of the text. Valid values are `ndjson`, + `xml`, `delimited`, and `semi_structured_text`. By default, the API chooses + the format. In this default scenario, all rows must have the same number + of fields for a delimited format to be detected. If the format is set to + `delimited` and the delimiter is not set, however, the API tolerates up to + 5% of rows that have a different number of columns than the first row. + :param grok_pattern: If you have set `format` to `semi_structured_text`, you + can specify a Grok pattern that is used to extract fields from every message in the text. The name of the timestamp field in the Grok pattern must match - what is specified in the timestamp_field parameter. If that parameter is + what is specified in the `timestamp_field` parameter. If that parameter is not specified, the name of the timestamp field in the Grok pattern must match - "timestamp". If grok_pattern is not specified, the structure finder creates + "timestamp". If `grok_pattern` is not specified, the structure finder creates a Grok pattern. - :param has_header_row: If you have set format to delimited, you can use this + :param has_header_row: If you have set `format` to `delimited`, you can use this parameter to indicate whether the column names are in the first row of the text. If this parameter is not specified, the structure finder guesses based on the similarity of the first row of the text to other rows. @@ -459,26 +484,58 @@ async def find_structure( that this may lead to very long processing times if the way to group lines into messages is misdetected. :param lines_to_sample: The number of lines to include in the structural analysis, - starting from the beginning of the text. The minimum is 2; If the value of + starting from the beginning of the text. The minimum is 2. If the value of this parameter is greater than the number of lines in the text, the analysis proceeds (as long as there are at least two lines in the text) for all of - the lines. - :param quote: If you have set format to delimited, you can specify the character + the lines. NOTE: The number of lines and the variation of the lines affects + the speed of the analysis. For example, if you upload text where the first + 1000 lines are all variations on the same message, the analysis will find + more commonality than would be seen with a bigger sample. If possible, however, + it is more efficient to upload sample text with more variety in the first + 1000 lines than to request analysis of 100000 lines to achieve some variety. + :param quote: If you have set `format` to `delimited`, you can specify the character used to quote the values in each row if they contain newlines or the delimiter character. Only a single character is supported. If this parameter is not - specified, the default value is a double quote ("). If your delimited text + specified, the default value is a double quote (`"`). If your delimited text format does not use quoting, a workaround is to set this argument to a character that does not appear anywhere in the sample. - :param should_trim_fields: If you have set format to delimited, you can specify + :param should_trim_fields: If you have set `format` to `delimited`, you can specify whether values between delimiters should have whitespace trimmed from them. - If this parameter is not specified and the delimiter is pipe (|), the default - value is true. Otherwise, the default value is false. - :param timeout: Sets the maximum amount of time that the structure analysis can - take. If the analysis is still running when the timeout expires then it will - be stopped. - :param timestamp_field: Optional parameter to specify the timestamp field in - the file + If this parameter is not specified and the delimiter is pipe (`|`), the default + value is `true`. Otherwise, the default value is `false`. + :param timeout: The maximum amount of time that the structure analysis can take. + If the analysis is still running when the timeout expires then it will be + stopped. + :param timestamp_field: The name of the field that contains the primary timestamp + of each record in the text. In particular, if the text were ingested into + an index, this is the field that would be used to populate the `@timestamp` + field. If the `format` is `semi_structured_text`, this field must match the + name of the appropriate extraction in the `grok_pattern`. Therefore, for + semi-structured text, it is best not to specify this parameter unless `grok_pattern` + is also specified. For structured text, if you specify this parameter, the + field must exist within the text. If this parameter is not specified, the + structure finder makes a decision about which field (if any) is the primary + timestamp field. For structured text, it is not compulsory to have a timestamp + in the text. :param timestamp_format: The Java time format of the timestamp field in the text. + Only a subset of Java time format letter groups are supported: * `a` * `d` + * `dd` * `EEE` * `EEEE` * `H` * `HH` * `h` * `M` * `MM` * `MMM` * `MMMM` + * `mm` * `ss` * `XX` * `XXX` * `yy` * `yyyy` * `zzz` Additionally `S` letter + groups (fractional seconds) of length one to nine are supported providing + they occur after `ss` and separated from the `ss` by a `.`, `,` or `:`. Spacing + and punctuation is also permitted with the exception of `?`, newline and + carriage return, together with literal text enclosed in single quotes. For + example, `MM/dd HH.mm.ss,SSSSSS 'in' yyyy` is a valid override format. One + valuable use case for this parameter is when the format is semi-structured + text, there are multiple timestamp formats in the text, and you know which + format corresponds to the primary timestamp, but you do not want to specify + the full `grok_pattern`. Another is when the timestamp format is one that + the structure finder does not consider by default. If this parameter is not + specified, the structure finder chooses the best format from a built-in set. + If the special value `null` is specified the structure finder will not look + for a primary timestamp in the text. When the format is semi-structured text + this will result in the structure finder treating the text as single-line + messages. """ if text_files is None and body is None: raise ValueError( @@ -556,10 +613,12 @@ async def test_grok_pattern( ``_ - :param grok_pattern: Grok pattern to run on the text. - :param text: Lines of text to run the Grok pattern on. - :param ecs_compatibility: The mode of compatibility with ECS compliant Grok patterns - (disabled or v1, default: disabled). + :param grok_pattern: The Grok pattern to run on the text. + :param text: The lines of text to run the Grok pattern on. + :param ecs_compatibility: The mode of compatibility with ECS compliant Grok patterns. + Use this parameter to specify whether to use ECS Grok patterns instead of + legacy ones when the structure finder creates a Grok pattern. Valid values + are `disabled` and `v1`. """ if grok_pattern is None and body is None: raise ValueError("Empty value passed for parameter 'grok_pattern'") diff --git a/elasticsearch/_async/client/transform.py b/elasticsearch/_async/client/transform.py index 320b66b8c..b31edb079 100644 --- a/elasticsearch/_async/client/transform.py +++ b/elasticsearch/_async/client/transform.py @@ -489,6 +489,7 @@ async def reset_transform( force: t.Optional[bool] = None, human: t.Optional[bool] = None, pretty: t.Optional[bool] = None, + 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 @@ -503,6 +504,8 @@ async def reset_transform( :param force: If this value is `true`, the transform is reset regardless of its current state. If it's `false`, the transform must be stopped before it can be reset. + :param timeout: Period to wait for a response. If no response is received before + the timeout expires, the request fails and returns an error. """ if transform_id in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'transform_id'") @@ -519,6 +522,8 @@ async def reset_transform( __query["human"] = human if pretty is not None: __query["pretty"] = pretty + if timeout is not None: + __query["timeout"] = timeout __headers = {"accept": "application/json"} return await self.perform_request( # type: ignore[return-value] "POST", diff --git a/elasticsearch/_async/client/watcher.py b/elasticsearch/_async/client/watcher.py index f19212a90..8b9820062 100644 --- a/elasticsearch/_async/client/watcher.py +++ b/elasticsearch/_async/client/watcher.py @@ -42,11 +42,15 @@ async def ack_watch( in the `status.actions..ack.state` structure. IMPORTANT: If the specified watch is currently being executed, this API will return an error The reason for this behavior is to prevent overwriting the watch status from a watch execution. + Acknowledging an action throttles further executions of that action until its + `ack.state` is reset to `awaits_successful_execution`. This happens when the + condition of the watch is not met (the condition evaluates to false). ``_ - :param watch_id: Watch ID - :param action_id: A comma-separated list of the action ids to be acked + :param watch_id: The watch identifier. + :param action_id: A comma-separated list of the action identifiers to acknowledge. + If you omit this parameter, all of the actions of the watch are acknowledged. """ if watch_id in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'watch_id'") @@ -96,7 +100,7 @@ async def activate_watch( ``_ - :param watch_id: Watch ID + :param watch_id: The watch identifier. """ if watch_id in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'watch_id'") @@ -136,7 +140,7 @@ async def deactivate_watch( ``_ - :param watch_id: Watch ID + :param watch_id: The watch identifier. """ if watch_id in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'watch_id'") @@ -182,7 +186,7 @@ async def delete_watch( ``_ - :param id: Watch ID + :param id: The watch identifier. """ if id in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'id'") @@ -255,11 +259,17 @@ async def execute_watch( and control whether a watch record would be written to the watch history after it runs. You can use the run watch API to run watches that are not yet registered by specifying the watch definition inline. This serves as great tool for testing - and debugging your watches prior to adding them to Watcher. + and debugging your watches prior to adding them to Watcher. When Elasticsearch + security features are enabled on your cluster, watches are run with the privileges + of the user that stored the watches. If your user is allowed to read index `a`, + but not index `b`, then the exact same set of rules will apply during execution + of a watch. When using the run watch API, the authorization data of the user + that called the API will be used as a base, instead of the information who stored + the watch. ``_ - :param id: Identifier for the watch. + :param id: The watch identifier. :param action_modes: Determines how to handle the watch actions as part of the watch execution. :param alternative_input: When present, the watch uses this object as a payload @@ -270,12 +280,12 @@ async def execute_watch( :param record_execution: When set to `true`, the watch record representing the watch execution result is persisted to the `.watcher-history` index for the current time. In addition, the status of the watch is updated, possibly throttling - subsequent executions. This can also be specified as an HTTP parameter. + subsequent runs. This can also be specified as an HTTP parameter. :param simulated_actions: :param trigger_data: This structure is parsed as the data of the trigger event - that will be used during the watch execution + that will be used during the watch execution. :param watch: When present, this watch is used instead of the one specified in - the request. This watch is not persisted to the index and record_execution + the request. This watch is not persisted to the index and `record_execution` cannot be set. """ __path_parts: t.Dict[str, str] @@ -327,6 +337,50 @@ async def execute_watch( path_parts=__path_parts, ) + @_rewrite_parameters() + async def get_settings( + self, + *, + error_trace: t.Optional[bool] = None, + filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, + human: t.Optional[bool] = None, + master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, + pretty: t.Optional[bool] = None, + ) -> ObjectApiResponse[t.Any]: + """ + Get Watcher index settings. Get settings for the Watcher internal index (`.watches`). + Only a subset of settings are shown, for example `index.auto_expand_replicas` + and `index.number_of_replicas`. + + ``_ + + :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. + """ + __path_parts: t.Dict[str, str] = {} + __path = "/_watcher/settings" + __query: t.Dict[str, t.Any] = {} + if error_trace is not None: + __query["error_trace"] = error_trace + if filter_path is not None: + __query["filter_path"] = filter_path + if human is not None: + __query["human"] = human + if master_timeout is not None: + __query["master_timeout"] = master_timeout + if pretty is not None: + __query["pretty"] = pretty + __headers = {"accept": "application/json"} + return await self.perform_request( # type: ignore[return-value] + "GET", + __path, + params=__query, + headers=__headers, + endpoint_id="watcher.get_settings", + path_parts=__path_parts, + ) + @_rewrite_parameters() async def get_watch( self, @@ -342,7 +396,7 @@ async def get_watch( ``_ - :param id: Watch ID + :param id: The watch identifier. """ if id in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'id'") @@ -374,6 +428,7 @@ async def get_watch( "input", "metadata", "throttle_period", + "throttle_period_in_millis", "transform", "trigger", ), @@ -393,7 +448,8 @@ async def put_watch( input: t.Optional[t.Mapping[str, t.Any]] = None, metadata: t.Optional[t.Mapping[str, t.Any]] = None, pretty: t.Optional[bool] = None, - throttle_period: t.Optional[str] = None, + throttle_period: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, + throttle_period_in_millis: t.Optional[t.Any] = None, transform: t.Optional[t.Mapping[str, t.Any]] = None, trigger: t.Optional[t.Mapping[str, t.Any]] = None, version: t.Optional[int] = None, @@ -414,19 +470,28 @@ async def put_watch( ``_ - :param id: Watch ID - :param actions: - :param active: Specify whether the watch is in/active by default - :param condition: + :param id: The identifier for the watch. + :param actions: The list of actions that will be run if the condition matches. + :param active: The initial state of the watch. The default value is `true`, which + means the watch is active by default. + :param condition: The condition that defines if the actions should be run. :param if_primary_term: only update the watch if the last operation that has changed the watch has the specified primary term :param if_seq_no: only update the watch if the last operation that has changed the watch has the specified sequence number - :param input: - :param metadata: - :param throttle_period: - :param transform: - :param trigger: + :param input: The input that defines the input that loads the data for the watch. + :param metadata: Metadata JSON that will be copied into the history entries. + :param throttle_period: The minimum time between actions being run. The default + is 5 seconds. This default can be changed in the config file with the setting + `xpack.watcher.throttle.period.default_period`. If both this value and the + `throttle_period_in_millis` parameter are specified, Watcher uses the last + parameter included in the request. + :param throttle_period_in_millis: Minimum time in milliseconds between actions + being run. Defaults to 5000. If both this value and the throttle_period parameter + are specified, Watcher uses the last parameter included in the request. + :param transform: The transform that processes the watch payload to prepare it + for the watch actions. + :param trigger: The trigger that defines when the watch should run. :param version: Explicit version number for concurrency control """ if id in SKIP_IN_PATH: @@ -462,6 +527,8 @@ async def put_watch( __body["metadata"] = metadata if throttle_period is not None: __body["throttle_period"] = throttle_period + if throttle_period_in_millis is not None: + __body["throttle_period_in_millis"] = throttle_period_in_millis if transform is not None: __body["transform"] = transform if trigger is not None: @@ -508,16 +575,17 @@ async def query_watches( ) -> ObjectApiResponse[t.Any]: """ Query watches. Get all registered watches in a paginated manner and optionally - filter watches by a query. + filter watches by a query. Note that only the `_id` and `metadata.*` fields are + queryable or sortable. ``_ - :param from_: The offset from the first result to fetch. Needs to be non-negative. - :param query: Optional, query filter watches to be returned. - :param search_after: Optional search After to do pagination using last hit’s - sort values. - :param size: The number of hits to return. Needs to be non-negative. - :param sort: Optional sort definition. + :param from_: The offset from the first result to fetch. It must be non-negative. + :param query: A query that filters the watches to be returned. + :param search_after: Retrieve the next page of hits using a set of sort values + from the previous page. + :param size: The number of hits to return. It must be non-negative. + :param sort: One or more fields used to sort the search results. """ __path_parts: t.Dict[str, str] = {} __path = "/_watcher/_query/watches" @@ -575,12 +643,15 @@ async def start( error_trace: t.Optional[bool] = None, filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, human: t.Optional[bool] = None, + master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ Start the watch service. Start the Watcher service if it is not already running. ``_ + + :param master_timeout: Period to wait for a connection to the master node. """ __path_parts: t.Dict[str, str] = {} __path = "/_watcher/_start" @@ -591,6 +662,8 @@ async def start( __query["filter_path"] = filter_path if human is not None: __query["human"] = human + if master_timeout is not None: + __query["master_timeout"] = master_timeout if pretty is not None: __query["pretty"] = pretty __headers = {"accept": "application/json"} @@ -635,7 +708,8 @@ async def stats( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Get Watcher statistics. + Get Watcher statistics. This API always returns basic metrics. You retrieve more + metrics by using the metric parameter. ``_ @@ -678,12 +752,17 @@ async def stop( error_trace: t.Optional[bool] = None, filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, human: t.Optional[bool] = None, + master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ Stop the watch service. Stop the Watcher service if it is running. ``_ + + :param master_timeout: The period to wait for the master node. If the master + node is not available before the timeout expires, the request fails and returns + an error. To indicate that the request should never timeout, set it to `-1`. """ __path_parts: t.Dict[str, str] = {} __path = "/_watcher/_stop" @@ -694,6 +773,8 @@ async def stop( __query["filter_path"] = filter_path if human is not None: __query["human"] = human + if master_timeout is not None: + __query["master_timeout"] = master_timeout if pretty is not None: __query["pretty"] = pretty __headers = {"accept": "application/json"} @@ -705,3 +786,70 @@ async def stop( endpoint_id="watcher.stop", path_parts=__path_parts, ) + + @_rewrite_parameters( + body_fields=("index_auto_expand_replicas", "index_number_of_replicas"), + parameter_aliases={ + "index.auto_expand_replicas": "index_auto_expand_replicas", + "index.number_of_replicas": "index_number_of_replicas", + }, + ) + async def update_settings( + self, + *, + error_trace: t.Optional[bool] = None, + filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, + human: t.Optional[bool] = None, + index_auto_expand_replicas: t.Optional[str] = None, + index_number_of_replicas: t.Optional[int] = None, + 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 Watcher index settings. Update settings for the Watcher internal index + (`.watches`). Only a subset of settings can be modified. This includes `index.auto_expand_replicas` + and `index.number_of_replicas`. + + ``_ + + :param index_auto_expand_replicas: + :param index_number_of_replicas: + :param master_timeout: The period to wait for a connection to the master node. + If no response is received before the timeout expires, the request fails + and returns an error. + :param timeout: The period to wait for a response. If no response is received + before the timeout expires, the request fails and returns an error. + """ + __path_parts: t.Dict[str, str] = {} + __path = "/_watcher/settings" + __query: t.Dict[str, t.Any] = {} + __body: t.Dict[str, t.Any] = body if body is not None else {} + if error_trace is not None: + __query["error_trace"] = error_trace + if filter_path is not None: + __query["filter_path"] = filter_path + if human is not None: + __query["human"] = human + if master_timeout is not None: + __query["master_timeout"] = master_timeout + if pretty is not None: + __query["pretty"] = pretty + if timeout is not None: + __query["timeout"] = timeout + if not __body: + if index_auto_expand_replicas is not None: + __body["index.auto_expand_replicas"] = index_auto_expand_replicas + if index_number_of_replicas is not None: + __body["index.number_of_replicas"] = index_number_of_replicas + __headers = {"accept": "application/json", "content-type": "application/json"} + return await self.perform_request( # type: ignore[return-value] + "PUT", + __path, + params=__query, + headers=__headers, + body=__body, + endpoint_id="watcher.update_settings", + path_parts=__path_parts, + ) diff --git a/elasticsearch/_async/client/xpack.py b/elasticsearch/_async/client/xpack.py index 27cc16a64..82518a338 100644 --- a/elasticsearch/_async/client/xpack.py +++ b/elasticsearch/_async/client/xpack.py @@ -96,9 +96,10 @@ async def usage( ``_ - :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 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. To indicate that the request should never timeout, + set it to `-1`. """ __path_parts: t.Dict[str, str] = {} __path = "/_xpack/usage" diff --git a/elasticsearch/_sync/client/__init__.py b/elasticsearch/_sync/client/__init__.py index df79574d3..1273d3fcc 100644 --- a/elasticsearch/_sync/client/__init__.py +++ b/elasticsearch/_sync/client/__init__.py @@ -644,41 +644,125 @@ 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. + 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 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( @@ -758,7 +842,7 @@ def clear_scroll( ``_ - :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" @@ -882,46 +966,62 @@ 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. + Count search results. Get the number of documents matching a query. The query + can either be provided using a simple query string as a parameter or using the + Query DSL defined within the request body. The latter must be nested in a `query` + key, which is the same as the search API. 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. + :param query: Defines the search definition using the Query DSL. The query is + optional, and when not provided, it will use `match_all` to count all the + docs. + :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: @@ -2489,9 +2589,9 @@ def info( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Get cluster info. Returns basic information about the cluster. + Get cluster info. Get basic build, version, and cluster information. - ``_ + ``_ """ __path_parts: t.Dict[str, str] = {} __path = "/" @@ -4462,6 +4562,7 @@ def search_shards( human: t.Optional[bool] = None, ignore_unavailable: t.Optional[bool] = None, local: t.Optional[bool] = None, + master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, preference: t.Optional[str] = None, pretty: t.Optional[bool] = None, routing: t.Optional[str] = None, @@ -4489,6 +4590,7 @@ def search_shards( a missing or closed index. :param local: If `true`, the request retrieves information from the local node only. + :param master_timeout: Period to wait for a connection to the master node. :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. @@ -4515,6 +4617,8 @@ def search_shards( __query["ignore_unavailable"] = ignore_unavailable if local is not None: __query["local"] = local + if master_timeout is not None: + __query["master_timeout"] = master_timeout if preference is not None: __query["preference"] = preference if pretty is not None: diff --git a/elasticsearch/_sync/client/ccr.py b/elasticsearch/_sync/client/ccr.py index 489f88ac0..a274371ba 100644 --- a/elasticsearch/_sync/client/ccr.py +++ b/elasticsearch/_sync/client/ccr.py @@ -33,6 +33,7 @@ def delete_auto_follow_pattern( error_trace: t.Optional[bool] = None, filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, human: t.Optional[bool] = None, + master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ @@ -42,6 +43,7 @@ def delete_auto_follow_pattern( ``_ :param name: The name of the auto follow pattern. + :param master_timeout: Period to wait for a connection to the master node. """ if name in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'name'") @@ -54,6 +56,8 @@ def delete_auto_follow_pattern( __query["filter_path"] = filter_path if human is not None: __query["human"] = human + if master_timeout is not None: + __query["master_timeout"] = master_timeout if pretty is not None: __query["pretty"] = pretty __headers = {"accept": "application/json"} @@ -94,6 +98,7 @@ def follow( error_trace: t.Optional[bool] = None, filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, human: t.Optional[bool] = None, + master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, max_outstanding_read_requests: t.Optional[int] = None, max_outstanding_write_requests: t.Optional[int] = None, max_read_request_operation_count: t.Optional[int] = None, @@ -124,6 +129,7 @@ def follow( :param remote_cluster: The remote cluster containing the leader index. :param data_stream_name: If the leader index is part of a data stream, the name to which the local data stream for the followed index should be renamed. + :param master_timeout: Period to wait for a connection to the master node. :param max_outstanding_read_requests: The maximum number of outstanding reads requests from the remote cluster. :param max_outstanding_write_requests: The maximum number of outstanding write @@ -174,6 +180,8 @@ def follow( __query["filter_path"] = filter_path if human is not None: __query["human"] = human + if master_timeout is not None: + __query["master_timeout"] = master_timeout if pretty is not None: __query["pretty"] = pretty if wait_for_active_shards is not None: @@ -232,6 +240,7 @@ def follow_info( error_trace: t.Optional[bool] = None, filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, human: t.Optional[bool] = None, + master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ @@ -244,6 +253,7 @@ def follow_info( :param index: A comma-separated list of index patterns; use `_all` to perform the operation on all indices + :param master_timeout: Period to wait for a connection to the master node. """ if index in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'index'") @@ -256,6 +266,8 @@ def follow_info( __query["filter_path"] = filter_path if human is not None: __query["human"] = human + if master_timeout is not None: + __query["master_timeout"] = master_timeout if pretty is not None: __query["pretty"] = pretty __headers = {"accept": "application/json"} @@ -277,6 +289,7 @@ def follow_stats( filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, human: t.Optional[bool] = None, pretty: t.Optional[bool] = None, + timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, ) -> ObjectApiResponse[t.Any]: """ Get follower stats. Get cross-cluster replication follower stats. The API returns @@ -287,6 +300,8 @@ def follow_stats( :param index: A comma-separated list of index patterns; use `_all` to perform the operation on all indices + :param timeout: Period to wait for a response. If no response is received before + the timeout expires, the request fails and returns an error. """ if index in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'index'") @@ -301,6 +316,8 @@ def follow_stats( __query["human"] = human if pretty is not None: __query["pretty"] = pretty + if timeout is not None: + __query["timeout"] = timeout __headers = {"accept": "application/json"} return self.perform_request( # type: ignore[return-value] "GET", @@ -331,6 +348,7 @@ def forget_follower( human: t.Optional[bool] = None, leader_remote_cluster: t.Optional[str] = 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]: """ @@ -360,6 +378,8 @@ def forget_follower( :param follower_index: :param follower_index_uuid: :param leader_remote_cluster: + :param timeout: Period to wait for a response. If no response is received before + the timeout expires, the request fails and returns an error. """ if index in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'index'") @@ -375,6 +395,8 @@ def forget_follower( __query["human"] = human if pretty is not None: __query["pretty"] = pretty + if timeout is not None: + __query["timeout"] = timeout if not __body: if follower_cluster is not None: __body["follower_cluster"] = follower_cluster @@ -403,6 +425,7 @@ def get_auto_follow_pattern( error_trace: t.Optional[bool] = None, filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, human: t.Optional[bool] = None, + master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ @@ -412,6 +435,7 @@ def get_auto_follow_pattern( :param name: Specifies the auto-follow pattern collection that you want to retrieve. If you do not specify a name, the API returns information for all collections. + :param master_timeout: Period to wait for a connection to the master node. """ __path_parts: t.Dict[str, str] if name not in SKIP_IN_PATH: @@ -427,6 +451,8 @@ def get_auto_follow_pattern( __query["filter_path"] = filter_path if human is not None: __query["human"] = human + if master_timeout is not None: + __query["master_timeout"] = master_timeout if pretty is not None: __query["pretty"] = pretty __headers = {"accept": "application/json"} @@ -447,6 +473,7 @@ def pause_auto_follow_pattern( error_trace: t.Optional[bool] = None, filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, human: t.Optional[bool] = None, + master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ @@ -463,6 +490,7 @@ def pause_auto_follow_pattern( :param name: The name of the auto follow pattern that should pause discovering new indices to follow. + :param master_timeout: Period to wait for a connection to the master node. """ if name in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'name'") @@ -475,6 +503,8 @@ def pause_auto_follow_pattern( __query["filter_path"] = filter_path if human is not None: __query["human"] = human + if master_timeout is not None: + __query["master_timeout"] = master_timeout if pretty is not None: __query["pretty"] = pretty __headers = {"accept": "application/json"} @@ -495,6 +525,7 @@ def pause_follow( error_trace: t.Optional[bool] = None, filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, human: t.Optional[bool] = None, + master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ @@ -507,6 +538,7 @@ def pause_follow( :param index: The name of the follower index that should pause following its leader index. + :param master_timeout: Period to wait for a connection to the master node. """ if index in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'index'") @@ -519,6 +551,8 @@ def pause_follow( __query["filter_path"] = filter_path if human is not None: __query["human"] = human + if master_timeout is not None: + __query["master_timeout"] = master_timeout if pretty is not None: __query["pretty"] = pretty __headers = {"accept": "application/json"} @@ -561,6 +595,7 @@ def put_auto_follow_pattern( human: t.Optional[bool] = None, leader_index_exclusion_patterns: t.Optional[t.Sequence[str]] = None, leader_index_patterns: t.Optional[t.Sequence[str]] = None, + master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, max_outstanding_read_requests: t.Optional[int] = None, max_outstanding_write_requests: t.Optional[int] = None, max_read_request_operation_count: t.Optional[int] = None, @@ -600,6 +635,7 @@ def put_auto_follow_pattern( or more leader_index_exclusion_patterns won’t be followed. :param leader_index_patterns: An array of simple index patterns to match against indices in the remote cluster specified by the remote_cluster field. + :param master_timeout: Period to wait for a connection to the master node. :param max_outstanding_read_requests: The maximum number of outstanding reads requests from the remote cluster. :param max_outstanding_write_requests: The maximum number of outstanding reads @@ -644,6 +680,8 @@ def put_auto_follow_pattern( __query["filter_path"] = filter_path if human is not None: __query["human"] = human + if master_timeout is not None: + __query["master_timeout"] = master_timeout if pretty is not None: __query["pretty"] = pretty if not __body: @@ -704,6 +742,7 @@ def resume_auto_follow_pattern( error_trace: t.Optional[bool] = None, filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, human: t.Optional[bool] = None, + master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ @@ -717,6 +756,7 @@ def resume_auto_follow_pattern( :param name: The name of the auto follow pattern to resume discovering new indices to follow. + :param master_timeout: Period to wait for a connection to the master node. """ if name in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'name'") @@ -729,6 +769,8 @@ def resume_auto_follow_pattern( __query["filter_path"] = filter_path if human is not None: __query["human"] = human + if master_timeout is not None: + __query["master_timeout"] = master_timeout if pretty is not None: __query["pretty"] = pretty __headers = {"accept": "application/json"} @@ -762,6 +804,7 @@ def resume_follow( error_trace: t.Optional[bool] = None, filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, human: t.Optional[bool] = None, + master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, max_outstanding_read_requests: t.Optional[int] = None, max_outstanding_write_requests: t.Optional[int] = None, max_read_request_operation_count: t.Optional[int] = None, @@ -785,6 +828,7 @@ def resume_follow( ``_ :param index: The name of the follow index to resume following. + :param master_timeout: Period to wait for a connection to the master node. :param max_outstanding_read_requests: :param max_outstanding_write_requests: :param max_read_request_operation_count: @@ -808,6 +852,8 @@ def resume_follow( __query["filter_path"] = filter_path if human is not None: __query["human"] = human + if master_timeout is not None: + __query["master_timeout"] = master_timeout if pretty is not None: __query["pretty"] = pretty if not __body: @@ -859,13 +905,19 @@ def stats( error_trace: t.Optional[bool] = None, filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, human: t.Optional[bool] = None, + 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, ) -> ObjectApiResponse[t.Any]: """ Get cross-cluster replication stats. This API returns stats about auto-following and the same shard-level stats as the get follower stats API. ``_ + + :param master_timeout: Period to wait for a connection to the master node. + :param timeout: Period to wait for a response. If no response is received before + the timeout expires, the request fails and returns an error. """ __path_parts: t.Dict[str, str] = {} __path = "/_ccr/stats" @@ -876,8 +928,12 @@ def stats( __query["filter_path"] = filter_path if human is not None: __query["human"] = human + if master_timeout is not None: + __query["master_timeout"] = master_timeout if pretty is not None: __query["pretty"] = pretty + if timeout is not None: + __query["timeout"] = timeout __headers = {"accept": "application/json"} return self.perform_request( # type: ignore[return-value] "GET", @@ -896,6 +952,7 @@ def unfollow( error_trace: t.Optional[bool] = None, filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, human: t.Optional[bool] = None, + master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ @@ -911,6 +968,7 @@ def unfollow( :param index: The name of the follower index that should be turned into a regular index. + :param master_timeout: Period to wait for a connection to the master node. """ if index in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'index'") @@ -923,6 +981,8 @@ def unfollow( __query["filter_path"] = filter_path if human is not None: __query["human"] = human + if master_timeout is not None: + __query["master_timeout"] = master_timeout if pretty is not None: __query["pretty"] = pretty __headers = {"accept": "application/json"} diff --git a/elasticsearch/_sync/client/cluster.py b/elasticsearch/_sync/client/cluster.py index 01a82144d..5cdae146b 100644 --- a/elasticsearch/_sync/client/cluster.py +++ b/elasticsearch/_sync/client/cluster.py @@ -38,6 +38,7 @@ def allocation_explain( include_disk_info: t.Optional[bool] = None, include_yes_decisions: t.Optional[bool] = None, index: t.Optional[str] = None, + master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, pretty: t.Optional[bool] = None, primary: t.Optional[bool] = None, shard: t.Optional[int] = None, @@ -61,6 +62,7 @@ def allocation_explain( :param include_yes_decisions: If true, returns YES decisions in explanation. :param index: Specifies the name of the index that you would like an explanation for. + :param master_timeout: Period to wait for a connection to the master node. :param primary: If true, returns explanation for the primary shard for the given shard ID. :param shard: Specifies the ID of the shard that you would like an explanation @@ -80,6 +82,8 @@ def allocation_explain( __query["include_disk_info"] = include_disk_info if include_yes_decisions is not None: __query["include_yes_decisions"] = include_yes_decisions + if master_timeout is not None: + __query["master_timeout"] = master_timeout if pretty is not None: __query["pretty"] = pretty if not __body: @@ -119,9 +123,8 @@ def delete_component_template( timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, ) -> ObjectApiResponse[t.Any]: """ - Delete component templates. Deletes component templates. Component templates - are building blocks for constructing index templates that specify index mappings, - settings, and aliases. + Delete component templates. Component templates are building blocks for constructing + index templates that specify index mappings, settings, and aliases. ``_ @@ -167,6 +170,7 @@ def delete_voting_config_exclusions( error_trace: t.Optional[bool] = None, filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, human: t.Optional[bool] = None, + master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, pretty: t.Optional[bool] = None, wait_for_removal: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: @@ -176,6 +180,7 @@ def delete_voting_config_exclusions( ``_ + :param master_timeout: Period to wait for a connection to the master node. :param wait_for_removal: Specifies whether to wait for all excluded nodes to be removed from the cluster before clearing the voting configuration exclusions list. Defaults to true, meaning that all excluded nodes must be removed from @@ -192,6 +197,8 @@ def delete_voting_config_exclusions( __query["filter_path"] = filter_path if human is not None: __query["human"] = human + if master_timeout is not None: + __query["master_timeout"] = master_timeout if pretty is not None: __query["pretty"] = pretty if wait_for_removal is not None: @@ -275,7 +282,7 @@ def get_component_template( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Get component templates. Retrieves information about component templates. + Get component templates. Get information about component templates. ``_ @@ -625,6 +632,7 @@ def post_voting_config_exclusions( error_trace: t.Optional[bool] = None, filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, human: t.Optional[bool] = None, + master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, node_ids: t.Optional[t.Union[str, t.Sequence[str]]] = None, node_names: t.Optional[t.Union[str, t.Sequence[str]]] = None, pretty: t.Optional[bool] = None, @@ -661,6 +669,7 @@ def post_voting_config_exclusions( ``_ + :param master_timeout: Period to wait for a connection to the master node. :param node_ids: A comma-separated list of the persistent ids of the nodes to exclude from the voting configuration. If specified, you may not also specify node_names. @@ -680,6 +689,8 @@ def post_voting_config_exclusions( __query["filter_path"] = filter_path if human is not None: __query["human"] = human + if master_timeout is not None: + __query["master_timeout"] = master_timeout if node_ids is not None: __query["node_ids"] = node_ids if node_names is not None: @@ -719,20 +730,21 @@ def put_component_template( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Create or update a component template. Creates or updates 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. + 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. + 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. ``_ @@ -755,8 +767,8 @@ def put_component_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 meta: Optional user metadata about the component template. May have any - contents. This map is not automatically generated by Elasticsearch. This + :param meta: Optional user metadata about the component template. It may have + any contents. This map is not automatically generated by Elasticsearch. This information is stored in the cluster state, so keeping it short is preferable. To unset `_meta`, replace the template without specifying this information. :param version: Version number used to manage component templates externally. diff --git a/elasticsearch/_sync/client/connector.py b/elasticsearch/_sync/client/connector.py index 773438374..d25119d70 100644 --- a/elasticsearch/_sync/client/connector.py +++ b/elasticsearch/_sync/client/connector.py @@ -996,6 +996,106 @@ def sync_job_post( path_parts=__path_parts, ) + @_rewrite_parameters( + body_fields=( + "deleted_document_count", + "indexed_document_count", + "indexed_document_volume", + "last_seen", + "metadata", + "total_document_count", + ), + ) + @_stability_warning(Stability.EXPERIMENTAL) + def sync_job_update_stats( + self, + *, + connector_sync_job_id: str, + deleted_document_count: t.Optional[int] = None, + indexed_document_count: t.Optional[int] = None, + indexed_document_volume: t.Optional[int] = None, + error_trace: t.Optional[bool] = None, + filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, + human: t.Optional[bool] = None, + last_seen: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, + metadata: t.Optional[t.Mapping[str, t.Any]] = None, + pretty: t.Optional[bool] = None, + total_document_count: t.Optional[int] = None, + body: t.Optional[t.Dict[str, t.Any]] = None, + ) -> ObjectApiResponse[t.Any]: + """ + Set the connector sync job stats. Stats include: `deleted_document_count`, `indexed_document_count`, + `indexed_document_volume`, and `total_document_count`. You can also update `last_seen`. + This API is mainly used by the connector service for updating sync job information. + To sync data using self-managed connectors, you need to deploy the Elastic connector + service on your own infrastructure. This service runs automatically on Elastic + Cloud for Elastic managed connectors. + + ``_ + + :param connector_sync_job_id: The unique identifier of the connector sync job. + :param deleted_document_count: The number of documents the sync job deleted. + :param indexed_document_count: The number of documents the sync job indexed. + :param indexed_document_volume: The total size of the data (in MiB) the sync + job indexed. + :param last_seen: The timestamp to use in the `last_seen` property for the connector + sync job. + :param metadata: The connector-specific metadata. + :param total_document_count: The total number of documents in the target index + after the sync job finished. + """ + if connector_sync_job_id in SKIP_IN_PATH: + raise ValueError("Empty value passed for parameter 'connector_sync_job_id'") + if deleted_document_count is None and body is None: + raise ValueError( + "Empty value passed for parameter 'deleted_document_count'" + ) + if indexed_document_count is None and body is None: + raise ValueError( + "Empty value passed for parameter 'indexed_document_count'" + ) + if indexed_document_volume is None and body is None: + raise ValueError( + "Empty value passed for parameter 'indexed_document_volume'" + ) + __path_parts: t.Dict[str, str] = { + "connector_sync_job_id": _quote(connector_sync_job_id) + } + __path = f'/_connector/_sync_job/{__path_parts["connector_sync_job_id"]}/_stats' + __query: t.Dict[str, t.Any] = {} + __body: t.Dict[str, t.Any] = body if body is not None else {} + if error_trace is not None: + __query["error_trace"] = error_trace + if filter_path is not None: + __query["filter_path"] = filter_path + if human is not None: + __query["human"] = human + if pretty is not None: + __query["pretty"] = pretty + if not __body: + if deleted_document_count is not None: + __body["deleted_document_count"] = deleted_document_count + if indexed_document_count is not None: + __body["indexed_document_count"] = indexed_document_count + if indexed_document_volume is not None: + __body["indexed_document_volume"] = indexed_document_volume + if last_seen is not None: + __body["last_seen"] = last_seen + if metadata is not None: + __body["metadata"] = metadata + if total_document_count is not None: + __body["total_document_count"] = total_document_count + __headers = {"accept": "application/json", "content-type": "application/json"} + return self.perform_request( # type: ignore[return-value] + "PUT", + __path, + params=__query, + headers=__headers, + body=__body, + endpoint_id="connector.sync_job_update_stats", + path_parts=__path_parts, + ) + @_rewrite_parameters() @_stability_warning(Stability.EXPERIMENTAL) def update_active_filtering( diff --git a/elasticsearch/_sync/client/dangling_indices.py b/elasticsearch/_sync/client/dangling_indices.py index 6a4930c6d..4a7890c8f 100644 --- a/elasticsearch/_sync/client/dangling_indices.py +++ b/elasticsearch/_sync/client/dangling_indices.py @@ -44,7 +44,7 @@ def delete_dangling_index( For example, this can happen if you delete more than `cluster.indices.tombstones.size` indices while an Elasticsearch node is offline. - ``_ + ``_ :param index_uuid: The UUID of the index to delete. Use the get dangling indices API to find the UUID. @@ -103,7 +103,7 @@ def import_dangling_index( For example, this can happen if you delete more than `cluster.indices.tombstones.size` indices while an Elasticsearch node is offline. - ``_ + ``_ :param index_uuid: The UUID of the index to import. Use the get dangling indices API to locate the UUID. @@ -162,7 +162,7 @@ def list_dangling_indices( indices while an Elasticsearch node is offline. Use this API to list dangling indices, which you can then import or delete. - ``_ + ``_ """ __path_parts: t.Dict[str, str] = {} __path = "/_dangling" diff --git a/elasticsearch/_sync/client/enrich.py b/elasticsearch/_sync/client/enrich.py index 766134939..f54c7e034 100644 --- a/elasticsearch/_sync/client/enrich.py +++ b/elasticsearch/_sync/client/enrich.py @@ -33,6 +33,7 @@ def delete_policy( error_trace: t.Optional[bool] = None, filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, human: t.Optional[bool] = None, + master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ @@ -41,6 +42,7 @@ def delete_policy( ``_ :param name: Enrich policy to delete. + :param master_timeout: Period to wait for a connection to the master node. """ if name in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'name'") @@ -53,6 +55,8 @@ def delete_policy( __query["filter_path"] = filter_path if human is not None: __query["human"] = human + if master_timeout is not None: + __query["master_timeout"] = master_timeout if pretty is not None: __query["pretty"] = pretty __headers = {"accept": "application/json"} @@ -73,6 +77,7 @@ def execute_policy( error_trace: t.Optional[bool] = None, filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, human: t.Optional[bool] = None, + master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, pretty: t.Optional[bool] = None, wait_for_completion: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: @@ -82,6 +87,7 @@ def execute_policy( ``_ :param name: Enrich policy to execute. + :param master_timeout: Period to wait for a connection to the master node. :param wait_for_completion: If `true`, the request blocks other enrich policy execution requests until complete. """ @@ -96,6 +102,8 @@ def execute_policy( __query["filter_path"] = filter_path if human is not None: __query["human"] = human + if master_timeout is not None: + __query["master_timeout"] = master_timeout if pretty is not None: __query["pretty"] = pretty if wait_for_completion is not None: @@ -118,6 +126,7 @@ def get_policy( error_trace: t.Optional[bool] = None, filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, human: t.Optional[bool] = None, + master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ @@ -127,6 +136,7 @@ def get_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. + :param master_timeout: Period to wait for a connection to the master node. """ __path_parts: t.Dict[str, str] if name not in SKIP_IN_PATH: @@ -142,6 +152,8 @@ def get_policy( __query["filter_path"] = filter_path if human is not None: __query["human"] = human + if master_timeout is not None: + __query["master_timeout"] = master_timeout if pretty is not None: __query["pretty"] = pretty __headers = {"accept": "application/json"} @@ -165,6 +177,7 @@ def put_policy( filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, geo_match: t.Optional[t.Mapping[str, t.Any]] = None, human: t.Optional[bool] = None, + master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, match: t.Optional[t.Mapping[str, t.Any]] = None, pretty: t.Optional[bool] = None, range: t.Optional[t.Mapping[str, t.Any]] = None, @@ -178,6 +191,7 @@ def put_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` query. + :param master_timeout: Period to wait for a connection to the master node. :param match: Matches enrich data to incoming documents based on a `term` query. :param range: Matches a number, date, or IP address in incoming documents to a range in the enrich index based on a `term` query. @@ -194,6 +208,8 @@ def put_policy( __query["filter_path"] = filter_path if human is not None: __query["human"] = human + if master_timeout is not None: + __query["master_timeout"] = master_timeout if pretty is not None: __query["pretty"] = pretty if not __body: @@ -221,6 +237,7 @@ def stats( error_trace: t.Optional[bool] = None, filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, human: t.Optional[bool] = None, + master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ @@ -228,6 +245,8 @@ def stats( enrich policies that are currently executing. ``_ + + :param master_timeout: Period to wait for a connection to the master node. """ __path_parts: t.Dict[str, str] = {} __path = "/_enrich/_stats" @@ -238,6 +257,8 @@ def stats( __query["filter_path"] = filter_path if human is not None: __query["human"] = human + if master_timeout is not None: + __query["master_timeout"] = master_timeout if pretty is not None: __query["pretty"] = pretty __headers = {"accept": "application/json"} diff --git a/elasticsearch/_sync/client/esql.py b/elasticsearch/_sync/client/esql.py index 6670f262a..374a13761 100644 --- a/elasticsearch/_sync/client/esql.py +++ b/elasticsearch/_sync/client/esql.py @@ -20,11 +20,274 @@ from elastic_transport import ObjectApiResponse from ._base import NamespacedClient -from .utils import _rewrite_parameters +from .utils import SKIP_IN_PATH, _quote, _rewrite_parameters class EsqlClient(NamespacedClient): + @_rewrite_parameters( + body_fields=( + "query", + "columnar", + "filter", + "locale", + "params", + "profile", + "tables", + ), + ignore_deprecated_options={"params"}, + ) + def async_query( + self, + *, + query: t.Optional[str] = None, + columnar: t.Optional[bool] = None, + delimiter: t.Optional[str] = None, + drop_null_columns: t.Optional[bool] = None, + error_trace: t.Optional[bool] = None, + filter: t.Optional[t.Mapping[str, t.Any]] = None, + filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, + format: t.Optional[ + t.Union[ + str, + t.Literal[ + "arrow", "cbor", "csv", "json", "smile", "tsv", "txt", "yaml" + ], + ] + ] = None, + human: t.Optional[bool] = None, + keep_alive: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, + keep_on_completion: t.Optional[bool] = None, + locale: t.Optional[str] = None, + params: t.Optional[ + t.Sequence[t.Union[None, bool, float, int, str, t.Any]] + ] = None, + pretty: t.Optional[bool] = None, + profile: t.Optional[bool] = None, + tables: t.Optional[ + t.Mapping[str, t.Mapping[str, t.Mapping[str, t.Any]]] + ] = None, + wait_for_completion_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]: + """ + Run an async ES|QL query. Asynchronously run an ES|QL (Elasticsearch query language) + query, monitor its progress, and retrieve results when they become available. + The API accepts the same parameters and request body as the synchronous query + API, along with additional async related properties. + + ``_ + + :param query: The ES|QL query API accepts an ES|QL query string in the query + parameter, runs it, and returns the results. + :param columnar: By default, ES|QL returns results as rows. For example, FROM + returns each individual document as one row. For the JSON, YAML, CBOR and + smile formats, ES|QL can return the results in a columnar fashion where one + row represents all the values of a certain column in the results. + :param delimiter: The character to use between values within a CSV row. It is + valid only for the CSV format. + :param drop_null_columns: Indicates whether columns that are entirely `null` + will be removed from the `columns` and `values` portion of the results. If + `true`, the response will include an extra section under the name `all_columns` + which has the name of all the columns. + :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, for example `json` or `yaml`. + :param keep_alive: The period for which the query and its results are stored + in the cluster. The default period is five days. When this period expires, + the query and its results are deleted, even if the query is still ongoing. + If the `keep_on_completion` parameter is false, Elasticsearch only stores + async queries that do not complete within the period set by the `wait_for_completion_timeout` + parameter, regardless of this value. + :param keep_on_completion: Indicates whether the query and its results are stored + in the cluster. If false, the query and its results are stored in the cluster + only if the request does not complete during the period set by the `wait_for_completion_timeout` + parameter. + :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 (?) + in the query string for each of the parameters. + :param profile: If provided and `true` the response will include an extra `profile` + object with information on how the query was executed. This information is + for human debugging and its format can change at any time but it can give + some insight into the performance of each part of the query. + :param tables: Tables to use with the LOOKUP operation. The top level key is + the table name and the next level key is the column name. + :param wait_for_completion_timeout: The period to wait for the request to finish. + By default, the request waits for 1 second for the query results. If the + query completes during this period, results are returned Otherwise, a query + ID is returned that can later be used to retrieve the results. + """ + if query is None and body is None: + raise ValueError("Empty value passed for parameter 'query'") + __path_parts: t.Dict[str, str] = {} + __path = "/_query/async" + __query: t.Dict[str, t.Any] = {} + __body: t.Dict[str, t.Any] = body if body is not None else {} + if delimiter is not None: + __query["delimiter"] = delimiter + if drop_null_columns is not None: + __query["drop_null_columns"] = drop_null_columns + if error_trace is not None: + __query["error_trace"] = error_trace + if filter_path is not None: + __query["filter_path"] = filter_path + if format is not None: + __query["format"] = format + if human is not None: + __query["human"] = human + 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 pretty is not None: + __query["pretty"] = pretty + if wait_for_completion_timeout is not None: + __query["wait_for_completion_timeout"] = wait_for_completion_timeout + if not __body: + if query is not None: + __body["query"] = query + if columnar is not None: + __body["columnar"] = columnar + if filter is not None: + __body["filter"] = filter + if locale is not None: + __body["locale"] = locale + if params is not None: + __body["params"] = params + if profile is not None: + __body["profile"] = profile + if tables is not None: + __body["tables"] = tables + __headers = {"accept": "application/json", "content-type": "application/json"} + return self.perform_request( # type: ignore[return-value] + "POST", + __path, + params=__query, + headers=__headers, + body=__body, + endpoint_id="esql.async_query", + path_parts=__path_parts, + ) + + @_rewrite_parameters() + def async_query_delete( + self, + *, + id: str, + error_trace: t.Optional[bool] = None, + filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, + human: t.Optional[bool] = None, + pretty: t.Optional[bool] = None, + ) -> ObjectApiResponse[t.Any]: + """ + Delete an async ES|QL query. If the query is still running, it is cancelled. + Otherwise, the stored results are deleted. If the Elasticsearch security features + are enabled, only the following users can use this API to delete a query: * The + authenticated user that submitted the original query request * Users with the + `cancel_task` cluster privilege + + ``_ + + :param id: The unique identifier of the query. A query ID is provided in the + ES|QL async query API response for a query that does not complete in the + designated time. A query ID is also provided when the request was submitted + with the `keep_on_completion` parameter set to `true`. + """ + if id in SKIP_IN_PATH: + raise ValueError("Empty value passed for parameter 'id'") + __path_parts: t.Dict[str, str] = {"id": _quote(id)} + __path = f'/_query/async/{__path_parts["id"]}' + __query: t.Dict[str, t.Any] = {} + if error_trace is not None: + __query["error_trace"] = error_trace + if filter_path is not None: + __query["filter_path"] = filter_path + if human is not None: + __query["human"] = human + if pretty is not None: + __query["pretty"] = pretty + __headers = {"accept": "application/json"} + return self.perform_request( # type: ignore[return-value] + "DELETE", + __path, + params=__query, + headers=__headers, + endpoint_id="esql.async_query_delete", + path_parts=__path_parts, + ) + + @_rewrite_parameters() + def async_query_get( + self, + *, + id: str, + drop_null_columns: t.Optional[bool] = None, + error_trace: t.Optional[bool] = None, + filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, + human: t.Optional[bool] = None, + keep_alive: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, + pretty: t.Optional[bool] = None, + wait_for_completion_timeout: t.Optional[ + t.Union[str, t.Literal[-1], t.Literal[0]] + ] = None, + ) -> ObjectApiResponse[t.Any]: + """ + Get async ES|QL query results. Get the current status and available results or + stored results for an ES|QL asynchronous query. If the Elasticsearch security + features are enabled, only the user who first submitted the ES|QL query can retrieve + the results using this API. + + ``_ + + :param id: The unique identifier of the query. A query ID is provided in the + ES|QL async query API response for a query that does not complete in the + designated time. A query ID is also provided when the request was submitted + with the `keep_on_completion` parameter set to `true`. + :param drop_null_columns: Indicates whether columns that are entirely `null` + will be removed from the `columns` and `values` portion of the results. If + `true`, the response will include an extra section under the name `all_columns` + which has the name of all the columns. + :param keep_alive: The period for which the query and its results are stored + in the cluster. When this period expires, the query and its results are deleted, + even if the query is still ongoing. + :param wait_for_completion_timeout: The period to wait for the request to finish. + By default, the request waits for complete query results. If the request + completes during the period specified in this parameter, complete query results + are returned. Otherwise, the response returns an `is_running` value of `true` + and no results. + """ + if id in SKIP_IN_PATH: + raise ValueError("Empty value passed for parameter 'id'") + __path_parts: t.Dict[str, str] = {"id": _quote(id)} + __path = f'/_query/async/{__path_parts["id"]}' + __query: t.Dict[str, t.Any] = {} + if drop_null_columns is not None: + __query["drop_null_columns"] = drop_null_columns + if error_trace is not None: + __query["error_trace"] = error_trace + if filter_path is not None: + __query["filter_path"] = filter_path + if human is not None: + __query["human"] = human + if keep_alive is not None: + __query["keep_alive"] = keep_alive + if pretty is not None: + __query["pretty"] = pretty + if wait_for_completion_timeout is not None: + __query["wait_for_completion_timeout"] = wait_for_completion_timeout + __headers = {"accept": "application/json"} + return self.perform_request( # type: ignore[return-value] + "GET", + __path, + params=__query, + headers=__headers, + endpoint_id="esql.async_query_get", + path_parts=__path_parts, + ) + @_rewrite_parameters( body_fields=( "query", diff --git a/elasticsearch/_sync/client/features.py b/elasticsearch/_sync/client/features.py index d207b697a..33416d3ed 100644 --- a/elasticsearch/_sync/client/features.py +++ b/elasticsearch/_sync/client/features.py @@ -32,6 +32,7 @@ def get_features( error_trace: t.Optional[bool] = None, filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, human: t.Optional[bool] = None, + master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ @@ -48,6 +49,8 @@ def get_features( the plugin that defines that feature must be installed on the master node. ``_ + + :param master_timeout: Period to wait for a connection to the master node. """ __path_parts: t.Dict[str, str] = {} __path = "/_features" @@ -58,6 +61,8 @@ def get_features( __query["filter_path"] = filter_path if human is not None: __query["human"] = human + if master_timeout is not None: + __query["master_timeout"] = master_timeout if pretty is not None: __query["pretty"] = pretty __headers = {"accept": "application/json"} @@ -78,6 +83,7 @@ def reset_features( error_trace: t.Optional[bool] = None, filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, human: t.Optional[bool] = None, + master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ @@ -97,6 +103,8 @@ def reset_features( individual nodes. ``_ + + :param master_timeout: Period to wait for a connection to the master node. """ __path_parts: t.Dict[str, str] = {} __path = "/_features/_reset" @@ -107,6 +115,8 @@ def reset_features( __query["filter_path"] = filter_path if human is not None: __query["human"] = human + if master_timeout is not None: + __query["master_timeout"] = master_timeout if pretty is not None: __query["pretty"] = pretty __headers = {"accept": "application/json"} diff --git a/elasticsearch/_sync/client/ilm.py b/elasticsearch/_sync/client/ilm.py index 17f6f6e42..43cf6ec60 100644 --- a/elasticsearch/_sync/client/ilm.py +++ b/elasticsearch/_sync/client/ilm.py @@ -90,7 +90,6 @@ def explain_lifecycle( only_errors: t.Optional[bool] = None, only_managed: t.Optional[bool] = None, pretty: t.Optional[bool] = None, - timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, ) -> ObjectApiResponse[t.Any]: """ Explain the lifecycle state. Get the current lifecycle status for one or more @@ -112,8 +111,6 @@ def explain_lifecycle( while executing the policy, or attempting to use a policy that does not exist. :param only_managed: Filters the returned indices to only indices that are managed by ILM. - :param timeout: Period to wait for a response. If no response is received before - the timeout expires, the request fails and returns an error. """ if index in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'index'") @@ -134,8 +131,6 @@ def explain_lifecycle( __query["only_managed"] = only_managed if pretty is not None: __query["pretty"] = pretty - if timeout is not None: - __query["timeout"] = timeout __headers = {"accept": "application/json"} return self.perform_request( # type: ignore[return-value] "GET", @@ -341,8 +336,8 @@ def move_to_step( ``_ :param index: The name of the index whose lifecycle step is to change - :param current_step: - :param next_step: + :param current_step: The step that the index is expected to be in. + :param next_step: The step that you want to run. """ if index in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'index'") @@ -552,8 +547,11 @@ def start( ``_ - :param master_timeout: - :param timeout: + :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. """ __path_parts: t.Dict[str, str] = {} __path = "/_ilm/start" @@ -601,8 +599,11 @@ def stop( ``_ - :param master_timeout: - :param timeout: + :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. """ __path_parts: t.Dict[str, str] = {} __path = "/_ilm/stop" diff --git a/elasticsearch/_sync/client/indices.py b/elasticsearch/_sync/client/indices.py index 4a70f9d61..196eeb418 100644 --- a/elasticsearch/_sync/client/indices.py +++ b/elasticsearch/_sync/client/indices.py @@ -143,8 +143,12 @@ def analyze( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Get tokens from text analysis. The analyze API performs [analysis](https://www.elastic.co/guide/en/elasticsearch/reference/current/analysis.html) - on a text string and returns the resulting tokens. + 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. ``_ @@ -246,7 +250,10 @@ def clear_cache( ) -> ObjectApiResponse[t.Any]: """ Clear the cache. Clear the cache of one or more indices. For data streams, the - API clears the caches of the stream's backing indices. + API clears the caches of the stream's backing indices. By default, the clear + cache API clears all caches. To clear only specific caches, use the `fielddata`, + `query`, or `request` parameters. To clear the cache only of specific fields, + use the `fields` parameter. ``_ @@ -347,10 +354,28 @@ def clone( the new index, which is a much more time consuming process. * Finally, it recovers the target index as though it were a closed index which had just been re-opened. IMPORTANT: Indices can only be cloned if they meet the following requirements: + * The index must be marked as read-only and have a cluster health status of green. * The target index must not exist. * The source index must have the same number of primary shards as the target index. * The node handling the clone process must have sufficient free disk space to accommodate a second copy of the existing - index. + index. The current write index on a data stream cannot be cloned. In order to + clone the current write index, the data stream must first be rolled over so that + a new write index is created and then the previous write index can be cloned. + NOTE: Mappings cannot be specified in the `_clone` request. The mappings of the + source index will be used for the target index. **Monitor the cloning process** + The cloning process can be monitored with the cat recovery API or the cluster + health API can be used to wait until all primary shards have been allocated by + setting the `wait_for_status` parameter to `yellow`. The `_clone` API returns + as soon as the target index has been added to the cluster state, before any shards + have been allocated. At this point, all shards are in the state unassigned. If, + for any reason, the target index can't be allocated, its primary shard will remain + unassigned until it can be allocated on that node. Once the primary shard is + allocated, it moves to state initializing, and the clone process begins. When + the clone operation completes, the shard will become active. At that point, Elasticsearch + will try to allocate any replicas and may decide to relocate the primary shard + to another node. **Wait for active shards** Because the clone operation creates + a new index to clone the shards to, the wait for active shards setting on index + creation applies to the clone index action as well. ``_ @@ -536,7 +561,26 @@ def create( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Create an index. Creates a new index. + 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. ``_ @@ -732,7 +776,11 @@ def delete( timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, ) -> ObjectApiResponse[t.Any]: """ - Delete indices. Deletes one or more indices. + 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. ``_ @@ -804,7 +852,7 @@ def delete_alias( """ 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 (`*`). @@ -1034,7 +1082,7 @@ def delete_template( timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, ) -> ObjectApiResponse[t.Any]: """ - Deletes a legacy index template. + Delete a legacy index template. ``_ @@ -1100,7 +1148,13 @@ def disk_usage( Analyze the index disk usage. Analyze the disk usage of each field of an index or data stream. This API might not support indices created in previous Elasticsearch versions. The result of a small index can be inaccurate as some parts of an index - might not be analyzed by the API. + might not be analyzed by the API. NOTE: The total size of fields of the analyzed + shards of the index in the response is usually smaller than the index `store_size` + value because some small metadata files are ignored and some parts of data files + might not be scanned by the API. Since stored fields are stored together in a + compressed format, the sizes of stored fields are also estimates and can be inaccurate. + The stored size of the `_id` field is likely underestimated while the `_source` + field is overestimated. ``_ @@ -1249,8 +1303,7 @@ def exists( pretty: t.Optional[bool] = None, ) -> HeadApiResponse: """ - Check indices. Checks if one or more indices, index aliases, or data streams - exist. + Check indices. Check if one or more indices, index aliases, or data streams exist. ``_ @@ -1448,16 +1501,21 @@ def exists_template( pretty: t.Optional[bool] = None, ) -> HeadApiResponse: """ - Check existence of index templates. Returns information about whether a particular - index template exists. + Check existence of index templates. Get information about whether index templates + exist. Index templates define settings, mappings, and aliases that can be applied + automatically to new indices. IMPORTANT: This documentation is about legacy index + templates, which are deprecated and will be replaced by the composable templates + introduced in Elasticsearch 7.8. ``_ - :param name: The comma separated names of the index templates - :param flat_settings: Return settings in flat format (default: false) - :param local: Return local information, do not retrieve the state from master - node (default: false) - :param master_timeout: Explicit operation timeout for connection to master node + :param name: A comma-separated list of index template names used to limit the + request. Wildcard (`*`) expressions are supported. + :param flat_settings: Indicates whether to use a flat format for the response. + :param local: Indicates whether to get information from the local node only. + :param master_timeout: The period to wait for the master node. If the master + node is not available before the timeout expires, the request fails and returns + an error. To indicate that the request should never timeout, set it to `-1`. """ if name in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'name'") @@ -1560,9 +1618,7 @@ def field_usage_stats( filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, human: t.Optional[bool] = None, ignore_unavailable: t.Optional[bool] = None, - 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, wait_for_active_shards: t.Optional[ t.Union[int, t.Union[str, t.Literal["all", "index-setting"]]] ] = None, @@ -1571,7 +1627,10 @@ def field_usage_stats( Get field usage stats. Get field usage information for each shard and field of an index. Field usage statistics are automatically captured when queries are running on a cluster. A shard-level search request that accesses a given field, - even if multiple times during that request, is counted as a single use. + even if multiple times during that request, is counted as a single use. The response + body reports the per-shard usage count of the data structures that back the fields + in the index. A given request will increment each count by a maximum value of + 1, even if the request accesses the same field multiple times. ``_ @@ -1590,11 +1649,6 @@ def field_usage_stats( in the statistics. :param ignore_unavailable: If `true`, missing or closed indices are not included in the response. - :param master_timeout: Period to wait for a connection to the master node. If - no response is received before the timeout expires, the request fails and - returns an error. - :param timeout: 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_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`). @@ -1618,12 +1672,8 @@ def field_usage_stats( __query["human"] = human if ignore_unavailable is not None: __query["ignore_unavailable"] = ignore_unavailable - if master_timeout is not None: - __query["master_timeout"] = master_timeout if pretty is not None: __query["pretty"] = pretty - if timeout is not None: - __query["timeout"] = timeout if wait_for_active_shards is not None: __query["wait_for_active_shards"] = wait_for_active_shards __headers = {"accept": "application/json"} @@ -1771,7 +1821,35 @@ def forcemerge( merges. So the number of soft-deleted documents can then grow rapidly, resulting in higher disk usage and worse search performance. If you regularly force merge an index receiving writes, this can also make snapshots more expensive, since - the new documents can't be backed up incrementally. + the new documents can't be backed up incrementally. **Blocks during a force merge** + Calls to this API block until the merge is complete (unless request contains + `wait_for_completion=false`). If the client connection is lost before completion + then the force merge process will continue in the background. Any new requests + to force merge the same indices will also block until the ongoing force merge + is complete. **Running force merge 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 get the status of the task. However, you can not cancel + this task as the force merge task is not cancelable. Elasticsearch creates a + record of this task as a document at `_tasks/`. When you are done with + a task, you should delete the task document so Elasticsearch can reclaim the + space. **Force merging multiple indices** You can force merge multiple indices + with a single request by targeting: * One or more data streams that contain multiple + backing indices * Multiple indices * One or more aliases * All data streams and + indices in a cluster Each targeted shard is force-merged separately using the + force_merge threadpool. By default each node only has a single `force_merge` + thread which means that the shards on that node are force-merged one at a time. + If you expand the `force_merge` threadpool on a node then it will force merge + its shards in parallel Force merge makes the storage for the shard being merged + temporarily increase, as it may require free space up to triple its size in case + `max_num_segments parameter` is set to `1`, to rewrite all segments into a new + one. **Data streams and time-based indices** Force-merging is useful for managing + a data stream's older backing indices and other time-based indices, particularly + after a rollover. In these cases, each index only receives indexing traffic for + a certain period of time. Once an index receive no more writes, its shards can + be force-merged to a single segment. This can be a good idea because single-segment + shards can sometimes use simpler and more efficient data structures to perform + searches. For example: ``` POST /.ds-my-data-stream-2099.03.07-000001/_forcemerge?max_num_segments=1 + ``` ``_ @@ -1864,8 +1942,8 @@ def get( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Get index information. Returns information about one or more indices. For data - streams, the API returns information about the stream’s backing indices. + Get index information. Get information about one or more indices. For data streams, + the API returns information about the stream’s backing indices. ``_ @@ -1956,7 +2034,7 @@ def get_alias( """ 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, @@ -2082,6 +2160,42 @@ def get_data_lifecycle( path_parts=__path_parts, ) + @_rewrite_parameters() + def get_data_lifecycle_stats( + self, + *, + error_trace: t.Optional[bool] = None, + filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, + human: t.Optional[bool] = None, + pretty: t.Optional[bool] = None, + ) -> ObjectApiResponse[t.Any]: + """ + Get data stream lifecycle stats. Get statistics about the data streams that are + managed by a data stream lifecycle. + + ``_ + """ + __path_parts: t.Dict[str, str] = {} + __path = "/_lifecycle/stats" + __query: t.Dict[str, t.Any] = {} + if error_trace is not None: + __query["error_trace"] = error_trace + if filter_path is not None: + __query["filter_path"] = filter_path + if human is not None: + __query["human"] = human + if pretty is not None: + __query["pretty"] = pretty + __headers = {"accept": "application/json"} + return self.perform_request( # type: ignore[return-value] + "GET", + __path, + params=__query, + headers=__headers, + endpoint_id="indices.get_data_lifecycle_stats", + path_parts=__path_parts, + ) + @_rewrite_parameters() def get_data_stream( self, @@ -2181,11 +2295,13 @@ def get_field_mapping( """ Get mapping definitions. Retrieves mapping definitions for one or more fields. For data streams, the API retrieves field mappings for the stream’s backing indices. + This API is useful if you don't need a complete mapping or if an index mapping + contains a large number of fields. ``_ :param fields: Comma-separated list or wildcard expression of fields used to - limit returned information. + limit returned information. Supports wildcards (`*`). :param index: 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`. @@ -2257,7 +2373,7 @@ def get_index_template( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Get index templates. Returns information about one or more index templates. + Get index templates. Get information about one or more index templates. ``_ @@ -2330,8 +2446,8 @@ def get_mapping( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Get mapping definitions. Retrieves mapping definitions for one or more indices. - For data streams, the API retrieves mappings for the stream’s backing indices. + Get mapping definitions. For data streams, the API retrieves mappings for the + stream’s backing indices. ``_ @@ -2415,8 +2531,8 @@ def get_settings( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Get index settings. Returns setting information for one or more indices. For - data streams, returns setting information for the stream’s backing indices. + Get index settings. Get setting information for one or more indices. For data + streams, it returns setting information for the stream's backing indices. ``_ @@ -2503,7 +2619,9 @@ def get_template( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Get index templates. Retrieves information about one or more index templates. + Get index templates. Get information about one or more index templates. IMPORTANT: + This documentation is about legacy index templates, which are deprecated and + will be replaced by the composable templates introduced in Elasticsearch 7.8. ``_ @@ -2682,7 +2800,27 @@ def open( ] = None, ) -> ObjectApiResponse[t.Any]: """ - Opens a closed index. For data streams, the API opens any closed backing indices. + Open a closed index. For data streams, the API opens any closed backing indices. + A closed index is blocked for read/write operations and does not allow all operations + that opened indices allow. It is not possible to index documents or to search + for documents in a closed index. This allows closed indices to not have to maintain + internal data structures for indexing or searching documents, resulting in a + smaller overhead on the cluster. When opening or closing an index, the master + is responsible for restarting the index shards to reflect the new state of the + index. The shards will then go through the normal recovery process. The data + of opened or closed indices is automatically replicated by the cluster to ensure + that enough shard copies are safely kept around at all times. You can open and + close multiple indices. An error is thrown if the request explicitly refers to + a missing index. This behavior can be turned off by using the `ignore_unavailable=true` + parameter. By default, you must explicitly name the indices you are opening or + closing. To open or close indices with `_all`, `*`, or other wildcard expressions, + change the `action.destructive_requires_name` setting to `false`. This setting + can also be changed with the cluster update settings API. Closed indices consume + a significant amount of disk-space which can cause problems in managed environments. + Closing indices can be turned off with the cluster settings API by setting `cluster.indices.close.enable` + to `false`. Because opening or closing an index allocates its shards, the `wait_for_active_shards` + setting on index creation applies to the `_open` and `_close` index actions as + well. ``_ @@ -3025,7 +3163,33 @@ def put_index_template( ) -> ObjectApiResponse[t.Any]: """ Create or update an index template. Index templates define settings, mappings, - and aliases that can be applied automatically to new indices. + 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. ``_ @@ -3055,8 +3219,11 @@ def put_index_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 meta: Optional user metadata about the index template. May have any contents. - This map is not automatically generated by Elasticsearch. + :param meta: Optional user metadata about the index template. It may have any + contents. It is not automatically generated or used by Elasticsearch. This + user-defined object is stored in the cluster state, so keeping it short is + preferable To unset the metadata, replace the template without specifying + it. :param priority: Priority to determine index template precedence when a new data stream or index is created. The index template with the highest priority is chosen. If no priority is specified the template is treated as though @@ -3065,7 +3232,9 @@ def put_index_template( :param template: Template to be applied. It may optionally include an `aliases`, `mappings`, or `settings` configuration. :param version: Version number used to manage index templates externally. This - number is not automatically generated by Elasticsearch. + number is not automatically generated by Elasticsearch. External systems + can use these version numbers to simplify template management. To unset a + version, replace the template without specifying one. """ if name in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'name'") @@ -3184,9 +3353,27 @@ def put_mapping( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Update field mappings. Adds new fields to an existing data stream or index. You - can also use this API to change the search settings of existing fields. For data - streams, these changes are applied to all backing indices by default. + 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. ``_ @@ -3317,6 +3504,19 @@ def put_settings( """ 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. ``_ @@ -3430,7 +3630,14 @@ def put_template( according to their order. Index templates are only applied during index creation. Changes to index templates do not affect existing indices. Settings and mappings specified in create index API requests override any settings or mappings specified - in an index template. + in an index template. 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. **Indices matching multiple templates** Multiple index templates + can potentially match an index, in this case, both the settings and mappings + are merged into the final configuration of the index. The order of the merging + can be controlled using the order parameter, with lower order being applied first, + and higher orders overriding them. NOTE: Multiple matching templates with the + same order value will result in a non-deterministic merging order. ``_ @@ -3451,7 +3658,8 @@ def put_template( with lower values. :param settings: Configuration options for the index. :param version: Version number used to manage index templates externally. This - number is not automatically generated by Elasticsearch. + number is not automatically generated by Elasticsearch. To unset a version, + replace the template without specifying one. """ if name in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'name'") @@ -3512,23 +3720,25 @@ def recovery( """ Get index recovery information. Get information about ongoing and completed shard recoveries for one or more indices. For data streams, the API returns information - for the stream's backing indices. Shard recovery is the process of initializing - a shard copy, such as restoring a primary shard from a snapshot or creating a - replica shard from a primary shard. When a shard recovery completes, the recovered - shard is available for search and indexing. Recovery automatically occurs during - the following processes: * When creating an index for the first time. * When - a node rejoins the cluster and starts up any missing primary shard copies using - the data that it holds in its data path. * Creation of new replica shard copies - from the primary. * Relocation of a shard copy to a different node in the same - cluster. * A snapshot restore operation. * A clone, shrink, or split operation. - You can determine the cause of a shard recovery using the recovery or cat recovery - APIs. The index recovery API reports information about completed recoveries only - for shard copies that currently exist in the cluster. It only reports the last - recovery for each shard copy and does not report historical information about - earlier recoveries, nor does it report information about the recoveries of shard - copies that no longer exist. This means that if a shard copy completes a recovery - and then Elasticsearch relocates it onto a different node then the information - about the original recovery will not be shown in the recovery API. + for the stream's backing indices. All recoveries, whether ongoing or complete, + are kept in the cluster state and may be reported on at any time. Shard recovery + is the process of initializing a shard copy, such as restoring a primary shard + from a snapshot or creating a replica shard from a primary shard. When a shard + recovery completes, the recovered shard is available for search and indexing. + Recovery automatically occurs during the following processes: * When creating + an index for the first time. * When a node rejoins the cluster and starts up + any missing primary shard copies using the data that it holds in its data path. + * Creation of new replica shard copies from the primary. * Relocation of a shard + copy to a different node in the same cluster. * A snapshot restore operation. + * A clone, shrink, or split operation. You can determine the cause of a shard + recovery using the recovery or cat recovery APIs. The index recovery API reports + information about completed recoveries only for shard copies that currently exist + in the cluster. It only reports the last recovery for each shard copy and does + not report historical information about earlier recoveries, nor does it report + information about the recoveries of shard copies that no longer exist. This means + that if a shard copy completes a recovery and then Elasticsearch relocates it + onto a different node then the information about the original recovery will not + be shown in the recovery API. ``_ @@ -3592,7 +3802,17 @@ def refresh( """ 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. + 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. ``_ @@ -3754,6 +3974,24 @@ def resolve_cluster( search is likely to have errors returned when you do the cross-cluster search (including any authorization errors if you do not have permission to query the index). * Cluster version information, including the Elasticsearch server version. + For example, `GET /_resolve/cluster/my-index-*,cluster*:my-index-*` returns information + about the local cluster and all remotely configured clusters that start with + the alias `cluster*`. Each cluster returns information about whether it has any + indices, aliases or data streams that match `my-index-*`. **Advantages of using + this endpoint before a cross-cluster search** You may want to exclude a cluster + or index from a search when: * A remote cluster is not currently connected and + is configured with `skip_unavailable=false`. Running a cross-cluster search under + those conditions will cause the entire search to fail. * A cluster has no matching + indices, aliases or data streams for the index expression (or your user does + not have permissions to search them). For example, suppose your index expression + is `logs*,remote1:logs*` and the remote1 cluster has no indices, aliases or data + streams that match `logs*`. In that case, that cluster will return no results + from that cluster if you include it in a cross-cluster search. * The index expression + (combined with any query parameters you specify) will likely cause an exception + to be thrown when you do the search. In these cases, the "error" field in the + `_resolve/cluster` response will be present. (This is also where security/permission + errors will be shown.) * A remote cluster is an older version that does not support + the feature you want to use in your search. ``_ @@ -3900,7 +4138,33 @@ def rollover( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Roll over to a new index. Creates a new index for a data stream or index alias. + 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`. ``_ @@ -4267,8 +4531,8 @@ def simulate_index_template( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Simulate an index. Returns the index configuration that would be applied to the - specified index from an existing index template. + Simulate an index. Get the index configuration that would be applied to the specified + index from an existing index template. ``_ @@ -4345,7 +4609,7 @@ def simulate_template( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Simulate an index template. Returns the index configuration that would be applied + Simulate an index template. Get the index configuration that would be applied by a particular index template. ``_ @@ -4479,25 +4743,29 @@ def split( """ Split an index. Split an index into a new index with more primary shards. * Before you can split an index: * The index must be read-only. * The cluster health status - must be green. The number of times the index can be split (and the number of - shards that each original shard can be split into) is determined by the `index.number_of_routing_shards` - setting. The number of routing shards specifies the hashing space that is used - internally to distribute documents across shards with consistent hashing. For - instance, a 5 shard index with `number_of_routing_shards` set to 30 (5 x 2 x - 3) could be split by a factor of 2 or 3. A split operation: * Creates a new target - index with the same definition as the source index, but with a larger number - of primary shards. * Hard-links segments from the source index into the target - index. If the file system doesn't support hard-linking, all segments are copied - into the new index, which is a much more time consuming process. * Hashes all - documents again, after low level files are created, to delete documents that - belong to a different shard. * Recovers the target index as though it were a - closed index which had just been re-opened. IMPORTANT: Indices can only be split - if they satisfy the following requirements: * The target index must not exist. - * The source index must have fewer primary shards than the target index. * The - number of primary shards in the target index must be a multiple of the number - of primary shards in the source index. * The node handling the split process - must have sufficient free disk space to accommodate a second copy of the existing - index. + must be green. You can do make an index read-only with the following request + using the add index block API: ``` PUT /my_source_index/_block/write ``` The + current write index on a data stream cannot be split. In order to split the current + write index, the data stream must first be rolled over so that a new write index + is created and then the previous write index can be split. The number of times + the index can be split (and the number of shards that each original shard can + be split into) is determined by the `index.number_of_routing_shards` setting. + The number of routing shards specifies the hashing space that is used internally + to distribute documents across shards with consistent hashing. For instance, + a 5 shard index with `number_of_routing_shards` set to 30 (5 x 2 x 3) could be + split by a factor of 2 or 3. A split operation: * Creates a new target index + with the same definition as the source index, but with a larger number of primary + shards. * Hard-links segments from the source index into the target index. If + the file system doesn't support hard-linking, all segments are copied into the + new index, which is a much more time consuming process. * Hashes all documents + again, after low level files are created, to delete documents that belong to + a different shard. * Recovers the target index as though it were a closed index + which had just been re-opened. IMPORTANT: Indices can only be split if they satisfy + the following requirements: * The target index must not exist. * The source index + must have fewer primary shards than the target index. * The number of primary + shards in the target index must be a multiple of the number of primary shards + in the source index. * The node handling the split process must have sufficient + free disk space to accommodate a second copy of the existing index. ``_ diff --git a/elasticsearch/_sync/client/inference.py b/elasticsearch/_sync/client/inference.py index 39e861733..04ceceac6 100644 --- a/elasticsearch/_sync/client/inference.py +++ b/elasticsearch/_sync/client/inference.py @@ -317,3 +317,82 @@ def put( endpoint_id="inference.put", path_parts=__path_parts, ) + + @_rewrite_parameters( + body_name="inference_config", + ) + def update( + self, + *, + inference_id: str, + inference_config: t.Optional[t.Mapping[str, t.Any]] = None, + body: t.Optional[t.Mapping[str, t.Any]] = None, + task_type: t.Optional[ + t.Union[ + str, + t.Literal["completion", "rerank", "sparse_embedding", "text_embedding"], + ] + ] = None, + error_trace: t.Optional[bool] = None, + filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, + human: t.Optional[bool] = None, + pretty: t.Optional[bool] = None, + ) -> ObjectApiResponse[t.Any]: + """ + Update an inference endpoint. Modify `task_settings`, secrets (within `service_settings`), + or `num_allocations` for an inference endpoint, depending on the specific endpoint + service and `task_type`. 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, 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 unique identifier of the inference endpoint. + :param inference_config: + :param task_type: The type of inference task that the model performs. + """ + if inference_id in SKIP_IN_PATH: + raise ValueError("Empty value passed for parameter 'inference_id'") + if inference_config is None and body is None: + raise ValueError( + "Empty value passed for parameters 'inference_config' and 'body', one of them should be set." + ) + elif inference_config is not None and body is not None: + raise ValueError("Cannot set both 'inference_config' and 'body'") + __path_parts: t.Dict[str, str] + if task_type not in SKIP_IN_PATH and inference_id not in SKIP_IN_PATH: + __path_parts = { + "task_type": _quote(task_type), + "inference_id": _quote(inference_id), + } + __path = f'/_inference/{__path_parts["task_type"]}/{__path_parts["inference_id"]}/_update' + elif inference_id not in SKIP_IN_PATH: + __path_parts = {"inference_id": _quote(inference_id)} + __path = f'/_inference/{__path_parts["inference_id"]}/_update' + else: + raise ValueError("Couldn't find a path for the given parameters") + __query: t.Dict[str, t.Any] = {} + if error_trace is not None: + __query["error_trace"] = error_trace + if filter_path is not None: + __query["filter_path"] = filter_path + if human is not None: + __query["human"] = human + if pretty is not None: + __query["pretty"] = pretty + __body = inference_config if inference_config is not None else body + __headers = {"accept": "application/json", "content-type": "application/json"} + return self.perform_request( # type: ignore[return-value] + "POST", + __path, + params=__query, + headers=__headers, + body=__body, + endpoint_id="inference.update", + path_parts=__path_parts, + ) diff --git a/elasticsearch/_sync/client/ingest.py b/elasticsearch/_sync/client/ingest.py index 9fcd4064a..8824266a6 100644 --- a/elasticsearch/_sync/client/ingest.py +++ b/elasticsearch/_sync/client/ingest.py @@ -226,7 +226,6 @@ def get_geoip_database( error_trace: t.Optional[bool] = None, filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, human: t.Optional[bool] = None, - master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ @@ -238,9 +237,6 @@ def get_geoip_database( :param id: Comma-separated list of database configuration IDs to retrieve. Wildcard (`*`) expressions are supported. To get all database configurations, omit this parameter or use `*`. - :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. """ __path_parts: t.Dict[str, str] if id not in SKIP_IN_PATH: @@ -256,8 +252,6 @@ def get_geoip_database( __query["filter_path"] = filter_path if human is not None: __query["human"] = human - if master_timeout is not None: - __query["master_timeout"] = master_timeout if pretty is not None: __query["pretty"] = pretty __headers = {"accept": "application/json"} diff --git a/elasticsearch/_sync/client/license.py b/elasticsearch/_sync/client/license.py index bcdee2f89..872d12409 100644 --- a/elasticsearch/_sync/client/license.py +++ b/elasticsearch/_sync/client/license.py @@ -32,7 +32,9 @@ def delete( error_trace: t.Optional[bool] = None, filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, human: t.Optional[bool] = None, + 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, ) -> ObjectApiResponse[t.Any]: """ Delete the license. When the license expires, your subscription level reverts @@ -40,6 +42,10 @@ def delete( can use this API. ``_ + + :param master_timeout: Period to wait for a connection to the master node. + :param timeout: Period to wait for a response. If no response is received before + the timeout expires, the request fails and returns an error. """ __path_parts: t.Dict[str, str] = {} __path = "/_license" @@ -50,8 +56,12 @@ def delete( __query["filter_path"] = filter_path if human is not None: __query["human"] = human + if master_timeout is not None: + __query["master_timeout"] = master_timeout if pretty is not None: __query["pretty"] = pretty + if timeout is not None: + __query["timeout"] = timeout __headers = {"accept": "application/json"} return self.perform_request( # type: ignore[return-value] "DELETE", @@ -196,7 +206,9 @@ def post( human: t.Optional[bool] = None, license: t.Optional[t.Mapping[str, t.Any]] = None, licenses: t.Optional[t.Sequence[t.Mapping[str, t.Any]]] = None, + 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]: """ @@ -215,6 +227,9 @@ def post( :param license: :param licenses: A sequence of one or more JSON documents containing the license information. + :param master_timeout: Period to wait for a connection to the master node. + :param timeout: Period to wait for a response. If no response is received before + the timeout expires, the request fails and returns an error. """ __path_parts: t.Dict[str, str] = {} __path = "/_license" @@ -228,8 +243,12 @@ def post( __query["filter_path"] = filter_path if human is not None: __query["human"] = human + if master_timeout is not None: + __query["master_timeout"] = master_timeout if pretty is not None: __query["pretty"] = pretty + if timeout is not None: + __query["timeout"] = timeout if not __body: if license is not None: __body["license"] = license @@ -258,7 +277,9 @@ def post_start_basic( error_trace: t.Optional[bool] = None, filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, human: t.Optional[bool] = None, + 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, ) -> ObjectApiResponse[t.Any]: """ Start a basic license. Start an indefinite basic license, which gives access @@ -273,6 +294,9 @@ def post_start_basic( :param acknowledge: whether the user has acknowledged acknowledge messages (default: false) + :param master_timeout: Period to wait for a connection to the master node. + :param timeout: Period to wait for a response. If no response is received before + the timeout expires, the request fails and returns an error. """ __path_parts: t.Dict[str, str] = {} __path = "/_license/start_basic" @@ -285,8 +309,12 @@ def post_start_basic( __query["filter_path"] = filter_path if human is not None: __query["human"] = human + if master_timeout is not None: + __query["master_timeout"] = master_timeout if pretty is not None: __query["pretty"] = pretty + if timeout is not None: + __query["timeout"] = timeout __headers = {"accept": "application/json"} return self.perform_request( # type: ignore[return-value] "POST", @@ -305,6 +333,7 @@ def post_start_trial( error_trace: t.Optional[bool] = None, filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, human: t.Optional[bool] = None, + master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, pretty: t.Optional[bool] = None, type_query_string: t.Optional[str] = None, ) -> ObjectApiResponse[t.Any]: @@ -320,6 +349,7 @@ def post_start_trial( :param acknowledge: whether the user has acknowledged acknowledge messages (default: false) + :param master_timeout: Period to wait for a connection to the master node. :param type_query_string: """ __path_parts: t.Dict[str, str] = {} @@ -333,6 +363,8 @@ def post_start_trial( __query["filter_path"] = filter_path if human is not None: __query["human"] = human + if master_timeout is not None: + __query["master_timeout"] = master_timeout if pretty is not None: __query["pretty"] = pretty if type_query_string is not None: diff --git a/elasticsearch/_sync/client/logstash.py b/elasticsearch/_sync/client/logstash.py index 0d5585db7..b006c348e 100644 --- a/elasticsearch/_sync/client/logstash.py +++ b/elasticsearch/_sync/client/logstash.py @@ -37,7 +37,8 @@ def delete_pipeline( ) -> ObjectApiResponse[t.Any]: """ Delete a Logstash pipeline. Delete a pipeline that is used for Logstash Central - Management. + Management. If the request succeeds, you receive an empty response with an appropriate + status code. ``_ diff --git a/elasticsearch/_sync/client/migration.py b/elasticsearch/_sync/client/migration.py index ef0dfa625..35d142606 100644 --- a/elasticsearch/_sync/client/migration.py +++ b/elasticsearch/_sync/client/migration.py @@ -39,7 +39,7 @@ def deprecations( Get deprecation information. Get information about different cluster, node, and index level settings that use deprecated features that will be removed or changed in the next major version. TIP: This APIs is designed for indirect use by the - Upgrade Assistant. We strongly recommend you use the Upgrade Assistant. + Upgrade Assistant. You are strongly recommended to use the Upgrade Assistant. ``_ @@ -86,9 +86,9 @@ def get_feature_upgrade_status( to how features store configuration information and data in system indices. Check which features need to be migrated and the status of any migrations that are in progress. TIP: This API is designed for indirect use by the Upgrade Assistant. - We strongly recommend you use the Upgrade Assistant. + You are strongly recommended to use the Upgrade Assistant. - ``_ + ``_ """ __path_parts: t.Dict[str, str] = {} __path = "/_migration/system_features" @@ -127,7 +127,7 @@ def post_feature_upgrade( unavailable during the migration process. TIP: The API is designed for indirect use by the Upgrade Assistant. We strongly recommend you use the Upgrade Assistant. - ``_ + ``_ """ __path_parts: t.Dict[str, str] = {} __path = "/_migration/system_features" diff --git a/elasticsearch/_sync/client/ml.py b/elasticsearch/_sync/client/ml.py index 86c717e78..65120b2fc 100644 --- a/elasticsearch/_sync/client/ml.py +++ b/elasticsearch/_sync/client/ml.py @@ -686,6 +686,7 @@ def delete_trained_model( force: t.Optional[bool] = None, human: t.Optional[bool] = None, pretty: t.Optional[bool] = None, + 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 @@ -696,6 +697,8 @@ def delete_trained_model( :param model_id: The unique identifier of the trained model. :param force: Forcefully deletes a trained model that is referenced by ingest pipelines or has a started deployment. + :param timeout: Period to wait for a response. If no response is received before + the timeout expires, the request fails and returns an error. """ if model_id in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'model_id'") @@ -712,6 +715,8 @@ def delete_trained_model( __query["human"] = human if pretty is not None: __query["pretty"] = pretty + if timeout is not None: + __query["timeout"] = timeout __headers = {"accept": "application/json"} return self.perform_request( # type: ignore[return-value] "DELETE", @@ -3205,7 +3210,11 @@ def put_data_frame_analytics( """ 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. + 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. ``_ @@ -3381,8 +3390,9 @@ def put_datafeed( 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. When Elasticsearch security features are enabled, your datafeed + (`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 @@ -3645,7 +3655,8 @@ def put_job( ) -> ObjectApiResponse[t.Any]: """ Create an anomaly detection job. If you include a `datafeed_config`, you must - have read index privileges on the source index. + 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}}`. ``_ @@ -5451,7 +5462,7 @@ def validate( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Validates an anomaly detection job. + Validate an anomaly detection job. ``_ diff --git a/elasticsearch/_sync/client/nodes.py b/elasticsearch/_sync/client/nodes.py index 0a6a4af65..46238d20f 100644 --- a/elasticsearch/_sync/client/nodes.py +++ b/elasticsearch/_sync/client/nodes.py @@ -50,9 +50,9 @@ def clear_repositories_metering_archive( ``_ :param node_id: Comma-separated list of node IDs or names used to limit returned - information. All the nodes selective options are explained [here](https://www.elastic.co/guide/en/elasticsearch/reference/current/cluster.html#cluster-nodes). - :param max_archive_version: Specifies the maximum [archive_version](https://www.elastic.co/guide/en/elasticsearch/reference/current/get-repositories-metering-api.html#get-repositories-metering-api-response-body) - to be cleared from the archive. + information. + :param max_archive_version: Specifies the maximum `archive_version` to be cleared + from the archive. """ if node_id in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'node_id'") @@ -138,7 +138,6 @@ def hot_threads( human: t.Optional[bool] = None, ignore_idle_threads: t.Optional[bool] = None, interval: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, - master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, pretty: t.Optional[bool] = None, snapshots: t.Optional[int] = None, sort: t.Optional[ @@ -161,9 +160,6 @@ def hot_threads( :param ignore_idle_threads: If true, known idle threads (e.g. waiting in a socket select, or to get a task from an empty queue) are filtered out. :param interval: The interval to do the second sampling of threads. - :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 snapshots: Number of samples of thread stacktrace. :param sort: The sort order for 'cpu' type (default: total) :param threads: Specifies the number of hot threads to provide information for. @@ -189,8 +185,6 @@ def hot_threads( __query["ignore_idle_threads"] = ignore_idle_threads if interval is not None: __query["interval"] = interval - if master_timeout is not None: - __query["master_timeout"] = master_timeout if pretty is not None: __query["pretty"] = pretty if snapshots is not None: @@ -223,7 +217,6 @@ def info( filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, flat_settings: t.Optional[bool] = None, human: t.Optional[bool] = None, - 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, ) -> ObjectApiResponse[t.Any]: @@ -238,9 +231,6 @@ def info( :param metric: Limits the information returned to the specific metrics. Supports a comma-separated list, such as http,ingest. :param flat_settings: If true, returns settings in flat format. - :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. """ @@ -266,8 +256,6 @@ def info( __query["flat_settings"] = flat_settings if human is not None: __query["human"] = human - if master_timeout is not None: - __query["master_timeout"] = master_timeout if pretty is not None: __query["pretty"] = pretty if timeout is not None: @@ -374,7 +362,6 @@ def stats( level: t.Optional[ t.Union[str, t.Literal["cluster", "indices", "shards"]] ] = None, - 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, types: t.Optional[t.Sequence[str]] = None, @@ -406,9 +393,6 @@ def stats( from segments that are not loaded into memory. :param level: Indicates whether statistics are aggregated at the cluster, index, or shard level. - :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 types: A comma-separated list of document types for the indexing index @@ -467,8 +451,6 @@ def stats( __query["include_unloaded_segments"] = include_unloaded_segments if level is not None: __query["level"] = level - if master_timeout is not None: - __query["master_timeout"] = master_timeout if pretty is not None: __query["pretty"] = pretty if timeout is not None: diff --git a/elasticsearch/_sync/client/query_rules.py b/elasticsearch/_sync/client/query_rules.py index 24d3b2826..c49f4b774 100644 --- a/elasticsearch/_sync/client/query_rules.py +++ b/elasticsearch/_sync/client/query_rules.py @@ -37,7 +37,9 @@ def delete_rule( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Delete a query rule. Delete a query rule within a query ruleset. + 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. ``_ @@ -85,7 +87,8 @@ def delete_ruleset( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Delete a query ruleset. + Delete a query ruleset. Remove a query ruleset and its associated data. This + is a destructive action that is not recoverable. ``_ @@ -221,8 +224,8 @@ def list_rulesets( ``_ - :param from_: Starting offset (default: 0) - :param size: specifies a max number of results to get + :param from_: The offset from the first result to fetch. + :param size: The maximum number of results to retrieve. """ __path_parts: t.Dict[str, str] = {} __path = "/_query_rules" @@ -271,16 +274,25 @@ def put_rule( ) -> 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. ``_ :param ruleset_id: The unique identifier of the query ruleset containing the - rule to be created or updated + rule to be created or updated. :param rule_id: The unique identifier of the query rule within the specified - ruleset to be created or updated - :param actions: - :param criteria: - :param type: + ruleset to be created or updated. + :param actions: The actions to take when the rule is matched. The format of this + action depends on the rule type. + :param criteria: The criteria that must be met for the rule to be applied. If + multiple criteria are specified for a rule, all criteria must be met for + the rule to be applied. + :param type: The type of rule. :param priority: """ if ruleset_id in SKIP_IN_PATH: @@ -345,12 +357,19 @@ def put_ruleset( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Create or update a query ruleset. + 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 + updated. :param rules: """ if ruleset_id in SKIP_IN_PATH: @@ -405,7 +424,9 @@ def test( :param ruleset_id: The unique identifier of the query ruleset to be created or updated - :param match_criteria: + :param match_criteria: The match criteria to apply to rules in the given query + ruleset. Match criteria should match the keys defined in the `criteria.metadata` + field of the rule. """ if ruleset_id in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'ruleset_id'") diff --git a/elasticsearch/_sync/client/rollup.py b/elasticsearch/_sync/client/rollup.py index 67c66e3bb..63c37f1a4 100644 --- a/elasticsearch/_sync/client/rollup.py +++ b/elasticsearch/_sync/client/rollup.py @@ -397,14 +397,37 @@ def rollup_search( rolled-up documents utilize a different document structure than the original data. It rewrites standard Query DSL into a format that matches the rollup documents then takes the response and rewrites it back to what a client would expect given - the original query. + the original query. The request body supports a subset of features from the regular + search API. The following functionality is not available: `size`: Because rollups + work on pre-aggregated data, no search hits can be returned and so size must + be set to zero or omitted entirely. `highlighter`, `suggestors`, `post_filter`, + `profile`, `explain`: These are similarly disallowed. **Searching both historical + rollup and non-rollup data** The rollup search API has the capability to search + across both "live" non-rollup data and the aggregated rollup data. This is done + by simply adding the live indices to the URI. For example: ``` GET sensor-1,sensor_rollup/_rollup_search + { "size": 0, "aggregations": { "max_temperature": { "max": { "field": "temperature" + } } } } ``` The rollup search endpoint does two things when the search runs: + * The original request is sent to the non-rollup index unaltered. * A rewritten + version of the original request is sent to the rollup index. When the two responses + are received, the endpoint rewrites the rollup response and merges the two together. + During the merging process, if there is any overlap in buckets between the two + responses, the buckets from the non-rollup index are used. ``_ - :param index: Enables searching rolled-up data using the standard Query DSL. + :param index: A comma-separated list of data streams and indices used to limit + the request. This parameter has the following rules: * At least one data + stream, index, or wildcard expression must be specified. This target can + include a rollup or non-rollup index. For data streams, the stream's backing + indices can only serve as non-rollup indices. Omitting the parameter or using + `_all` are not permitted. * Multiple non-rollup indices may be specified. + * Only one rollup index may be specified. If more than one are supplied, + an exception occurs. * Wildcard expressions (`*`) may be used. If they match + more than one rollup index, an exception occurs. However, you can use an + expression to match multiple non-rollup indices or data streams. :param aggregations: Specifies aggregations. :param aggs: Specifies aggregations. - :param query: Specifies a DSL query. + :param query: Specifies a DSL query that is subject to some limitations. :param rest_total_hits_as_int: Indicates whether hits.total should be rendered as an integer or an object in the rest search response :param size: Must be zero if set, as rollups work on pre-aggregated data. @@ -506,14 +529,23 @@ def stop_job( ) -> ObjectApiResponse[t.Any]: """ Stop rollup jobs. If you try to stop a job that does not exist, an exception - occurs. If you try to stop a job that is already stopped, nothing happens. + occurs. If you try to stop a job that is already stopped, nothing happens. Since + only a stopped job can be deleted, it can be useful to block the API until the + indexer has fully stopped. This is accomplished with the `wait_for_completion` + query parameter, and optionally a timeout. For example: ``` POST _rollup/job/sensor/_stop?wait_for_completion=true&timeout=10s + ``` The parameter blocks the API call from returning until either the job has + moved to STOPPED or the specified time has elapsed. If the specified time elapses + without the job moving to STOPPED, a timeout exception occurs. ``_ :param id: Identifier for the rollup job. :param timeout: If `wait_for_completion` is `true`, the API blocks for (at maximum) the specified duration while waiting for the job to stop. If more than `timeout` - time has passed, the API throws a timeout exception. + time has passed, the API throws a timeout exception. NOTE: Even if a timeout + occurs, the stop request is still processing and eventually moves the job + to STOPPED. The timeout simply means the API call itself timed out while + waiting for the status change. :param wait_for_completion: If set to `true`, causes the API to block until the indexer state completely stops. If set to `false`, the API returns immediately and the indexer is stopped asynchronously in the background. diff --git a/elasticsearch/_sync/client/searchable_snapshots.py b/elasticsearch/_sync/client/searchable_snapshots.py index e4ba75989..028eba9bc 100644 --- a/elasticsearch/_sync/client/searchable_snapshots.py +++ b/elasticsearch/_sync/client/searchable_snapshots.py @@ -47,11 +47,9 @@ def cache_stats( Get cache statistics. Get statistics about the shared cache for partially mounted indices. - ``_ + ``_ - :param node_id: A comma-separated list of node IDs or names to limit the returned - information; use `_local` to return information from the node you're connecting - to, leave empty to get information from all nodes + :param node_id: The names of the nodes in the cluster to target. :param master_timeout: """ __path_parts: t.Dict[str, str] @@ -107,9 +105,10 @@ def clear_cache( Clear the cache. Clear indices and data streams from the shared cache for partially mounted indices. - ``_ + ``_ - :param index: A comma-separated list of index names + :param index: A comma-separated list of data streams, indices, and aliases to + clear from the cache. It supports wildcards (`*`). :param allow_no_indices: Whether to ignore if a wildcard indices expression resolves into no concrete indices. (This includes `_all` string or when no indices have been specified) @@ -184,17 +183,22 @@ def mount( ``_ :param repository: The name of the repository containing the snapshot of the - index to mount - :param snapshot: The name of the snapshot of the index to mount - :param index: - :param ignore_index_settings: - :param index_settings: - :param master_timeout: Explicit operation timeout for connection to master node - :param renamed_index: - :param storage: Selects the kind of local storage used to accelerate searches. - Experimental, and defaults to `full_copy` - :param wait_for_completion: Should this request wait until the operation has - completed before returning + index to mount. + :param snapshot: The name of the snapshot of the index to mount. + :param index: The name of the index contained in the snapshot whose data is to + be mounted. If no `renamed_index` is specified, this name will also be used + to create the new index. + :param ignore_index_settings: The names of settings that should be removed from + the index when it is mounted. + :param index_settings: The settings that should be added to the index when it + is mounted. + :param master_timeout: The period to wait for the master node. If the master + node is not available before the timeout expires, the request fails and returns + an error. To indicate that the request should never timeout, set it to `-1`. + :param renamed_index: The name of the index that will be created. + :param storage: The mount option for the searchable snapshot index. + :param wait_for_completion: If true, the request blocks until the operation is + complete. """ if repository in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'repository'") @@ -261,9 +265,10 @@ def stats( """ Get searchable snapshot statistics. - ``_ + ``_ - :param index: A comma-separated list of index names + :param index: A comma-separated list of data streams and indices to retrieve + statistics for. :param level: Return stats aggregated at cluster, index or shard level """ __path_parts: t.Dict[str, str] diff --git a/elasticsearch/_sync/client/security.py b/elasticsearch/_sync/client/security.py index dc956eeea..17ee5dcbc 100644 --- a/elasticsearch/_sync/client/security.py +++ b/elasticsearch/_sync/client/security.py @@ -45,14 +45,33 @@ def activate_user_profile( ) -> ObjectApiResponse[t.Any]: """ Activate a user profile. Create or update a user profile on behalf of another - user. + user. NOTE: The user profile feature is designed only for use by Kibana and Elastic's + Observability, Enterprise Search, and Elastic Security solutions. Individual + users and external applications should not call this API directly. The calling + application must have either an `access_token` or a combination of `username` + and `password` for the user that the profile document is intended for. Elastic + reserves the right to change or remove this feature in future releases without + prior notice. This API creates or updates a profile document for end users with + information that is extracted from the user's authentication object including + `username`, `full_name,` `roles`, and the authentication realm. For example, + in the JWT `access_token` case, the profile user's `username` is extracted from + the JWT token claim pointed to by the `claims.principal` setting of the JWT realm + that authenticated the token. When updating a profile document, the API enables + the document if it was disabled. Any updates do not change existing content for + either the `labels` or `data` fields. ``_ - :param grant_type: - :param access_token: - :param password: - :param username: + :param grant_type: The type of grant. + :param access_token: The user's Elasticsearch access token or JWT. Both `access` + and `id` JWT token types are supported and they depend on the underlying + JWT realm configuration. If you specify the `access_token` grant type, this + parameter is required. It is not valid with other grant types. + :param password: The user's password. If you specify the `password` grant type, + this parameter is required. It is not valid with other grant types. + :param username: The username that identifies the user. If you specify the `password` + grant type, this parameter is required. It is not valid with other grant + types. """ if grant_type is None and body is None: raise ValueError("Empty value passed for parameter 'grant_type'") @@ -244,6 +263,94 @@ def bulk_put_role( path_parts=__path_parts, ) + @_rewrite_parameters( + body_fields=("ids", "expiration", "metadata", "role_descriptors"), + ) + def bulk_update_api_keys( + self, + *, + ids: t.Optional[t.Union[str, t.Sequence[str]]] = None, + error_trace: t.Optional[bool] = None, + expiration: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, + filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, + human: t.Optional[bool] = None, + metadata: t.Optional[t.Mapping[str, t.Any]] = None, + pretty: t.Optional[bool] = None, + role_descriptors: t.Optional[t.Mapping[str, t.Mapping[str, t.Any]]] = None, + body: t.Optional[t.Dict[str, t.Any]] = None, + ) -> ObjectApiResponse[t.Any]: + """ + Bulk update API keys. Update the attributes for multiple API keys. IMPORTANT: + It is not possible to use an API key as the authentication credential for this + API. To update API keys, the owner user's credentials are required. This API + is similar to the update API key API but enables you to apply the same update + to multiple API keys in one API call. This operation can greatly improve performance + over making individual updates. It is not possible to update expired or invalidated + API keys. This API supports updates to API key access scope, metadata and expiration. + The access scope of each 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 an 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. A successful request returns a JSON structure that + contains the IDs of all updated API keys, the IDs of API keys that already had + the requested changes and did not require an update, and error details for any + failed update. + + ``_ + + :param ids: The API key identifiers. + :param expiration: Expiration time for the API keys. By default, API keys never + expire. This property can be omitted to leave the value unchanged. + :param metadata: Arbitrary nested metadata to associate with the API keys. Within + the `metadata` object, top-level keys beginning with an underscore (`_`) + are reserved for system usage. Any information specified with this parameter + fully replaces metadata previously associated with the API key. + :param role_descriptors: The role descriptors to assign to the API keys. An 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, supply the `role_descriptors` parameter as 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. The structure of a role descriptor + is the same as the request for the create API keys API. + """ + if ids is None and body is None: + raise ValueError("Empty value passed for parameter 'ids'") + __path_parts: t.Dict[str, str] = {} + __path = "/_security/api_key/_bulk_update" + __query: t.Dict[str, t.Any] = {} + __body: t.Dict[str, t.Any] = body if body is not None else {} + if error_trace is not None: + __query["error_trace"] = error_trace + if filter_path is not None: + __query["filter_path"] = filter_path + if human is not None: + __query["human"] = human + if pretty is not None: + __query["pretty"] = pretty + if not __body: + if ids is not None: + __body["ids"] = ids + if expiration is not None: + __body["expiration"] = expiration + if metadata is not None: + __body["metadata"] = metadata + if role_descriptors is not None: + __body["role_descriptors"] = role_descriptors + __headers = {"accept": "application/json", "content-type": "application/json"} + return self.perform_request( # type: ignore[return-value] + "POST", + __path, + params=__query, + headers=__headers, + body=__body, + endpoint_id="security.bulk_update_api_keys", + path_parts=__path_parts, + ) + @_rewrite_parameters( body_fields=("password", "password_hash"), ) @@ -773,6 +880,74 @@ def create_service_token( path_parts=__path_parts, ) + @_rewrite_parameters( + body_fields=("x509_certificate_chain",), + ) + def delegate_pki( + self, + *, + x509_certificate_chain: t.Optional[t.Sequence[str]] = None, + error_trace: t.Optional[bool] = None, + filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, + human: t.Optional[bool] = None, + pretty: t.Optional[bool] = None, + body: t.Optional[t.Dict[str, t.Any]] = None, + ) -> ObjectApiResponse[t.Any]: + """ + Delegate PKI authentication. This API implements the exchange of an X509Certificate + chain for an Elasticsearch access token. The certificate chain is validated, + according to RFC 5280, by sequentially considering the trust configuration of + every installed PKI realm that has `delegation.enabled` set to `true`. A successfully + trusted client certificate is also subject to the validation of the subject distinguished + name according to thw `username_pattern` of the respective realm. This API is + called by smart and trusted proxies, such as Kibana, which terminate the user's + TLS session but still want to authenticate the user by using a PKI realm—-​as + if the user connected directly to Elasticsearch. IMPORTANT: The association between + the subject public key in the target certificate and the corresponding private + key is not validated. This is part of the TLS authentication process and it is + delegated to the proxy that calls this API. The proxy is trusted to have performed + the TLS authentication and this API translates that authentication into an Elasticsearch + access token. + + ``_ + + :param x509_certificate_chain: The X509Certificate chain, which is represented + as an ordered string array. Each string in the array is a base64-encoded + (Section 4 of RFC4648 - not base64url-encoded) of the certificate's DER encoding. + The first element is the target certificate that contains the subject distinguished + name that is requesting access. This may be followed by additional certificates; + each subsequent certificate is used to certify the previous one. + """ + if x509_certificate_chain is None and body is None: + raise ValueError( + "Empty value passed for parameter 'x509_certificate_chain'" + ) + __path_parts: t.Dict[str, str] = {} + __path = "/_security/delegate_pki" + __query: t.Dict[str, t.Any] = {} + __body: t.Dict[str, t.Any] = body if body is not None else {} + if error_trace is not None: + __query["error_trace"] = error_trace + if filter_path is not None: + __query["filter_path"] = filter_path + if human is not None: + __query["human"] = human + if pretty is not None: + __query["pretty"] = pretty + if not __body: + if x509_certificate_chain is not None: + __body["x509_certificate_chain"] = x509_certificate_chain + __headers = {"accept": "application/json", "content-type": "application/json"} + return self.perform_request( # type: ignore[return-value] + "POST", + __path, + params=__query, + headers=__headers, + body=__body, + endpoint_id="security.delegate_pki", + path_parts=__path_parts, + ) + @_rewrite_parameters() def delete_privileges( self, @@ -1098,14 +1273,21 @@ def disable_user_profile( ) -> ObjectApiResponse[t.Any]: """ Disable a user profile. Disable user profiles so that they are not visible in - user profile searches. + user profile searches. NOTE: The user profile feature is designed only for use + by Kibana and Elastic's Observability, Enterprise Search, and Elastic Security + solutions. Individual users and external applications should not call this API + directly. Elastic reserves the right to change or remove this feature in future + releases without prior notice. When you activate a user profile, its automatically + enabled and visible in user profile searches. You can use the disable user profile + API to disable a user profile so it’s not visible in these searches. To re-enable + a disabled user profile, use the enable user profile API . ``_ :param uid: Unique identifier for the user profile. :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', it waits for a refresh to + make this operation visible to search. If 'false', it does nothing with refreshes. """ if uid in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'uid'") @@ -1195,14 +1377,20 @@ def enable_user_profile( ) -> ObjectApiResponse[t.Any]: """ Enable a user profile. Enable user profiles to make them visible in user profile - searches. + searches. NOTE: The user profile feature is designed only for use by Kibana and + Elastic's Observability, Enterprise Search, and Elastic Security solutions. Individual + users and external applications should not call this API directly. Elastic reserves + the right to change or remove this feature in future releases without prior notice. + When you activate a user profile, it's automatically enabled and visible in user + profile searches. If you later disable the user profile, you can use the enable + user profile API to make the profile visible in these searches again. ``_ - :param uid: Unique identifier for the user profile. + :param uid: A unique identifier for the user profile. :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', it waits for a refresh to + make this operation visible to search. If 'false', nothing is done with refreshes. """ if uid in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'uid'") @@ -1665,6 +1853,49 @@ def get_service_credentials( path_parts=__path_parts, ) + @_rewrite_parameters() + def get_settings( + self, + *, + error_trace: t.Optional[bool] = None, + filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, + human: t.Optional[bool] = None, + master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, + pretty: t.Optional[bool] = None, + ) -> ObjectApiResponse[t.Any]: + """ + Get security index settings. Get the user-configurable settings for the security + internal index (`.security` and associated indices). + + ``_ + + :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. + """ + __path_parts: t.Dict[str, str] = {} + __path = "/_security/settings" + __query: t.Dict[str, t.Any] = {} + if error_trace is not None: + __query["error_trace"] = error_trace + if filter_path is not None: + __query["filter_path"] = filter_path + if human is not None: + __query["human"] = human + if master_timeout is not None: + __query["master_timeout"] = master_timeout + if pretty is not None: + __query["pretty"] = pretty + __headers = {"accept": "application/json"} + return self.perform_request( # type: ignore[return-value] + "GET", + __path, + params=__query, + headers=__headers, + endpoint_id="security.get_settings", + path_parts=__path_parts, + ) + @_rewrite_parameters( body_fields=( "grant_type", @@ -1858,15 +2089,19 @@ def get_user_profile( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Get a user profile. Get a user's profile using the unique profile ID. + Get a user profile. Get a user's profile using the unique profile ID. NOTE: The + user profile feature is designed only for use by Kibana and Elastic's Observability, + Enterprise Search, and Elastic Security solutions. Individual users and external + applications should not call this API directly. Elastic reserves the right to + change or remove this feature in future releases without prior notice. ``_ :param uid: A unique identifier for the user profile. - :param data: List of filters for the `data` field of the profile document. To - return all content use `data=*`. To return a subset of content use `data=` - to retrieve content nested under the specified ``. By default returns - no `data` content. + :param data: A comma-separated list of filters for the `data` field of the profile + document. To return all content use `data=*`. To return a subset of content + use `data=` to retrieve content nested under the specified ``. + By default returns no `data` content. """ if uid in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'uid'") @@ -2138,11 +2373,15 @@ def has_privileges_user_profile( ) -> ObjectApiResponse[t.Any]: """ Check user profile privileges. Determine whether the users associated with the - specified user profile IDs have all the requested privileges. + specified user profile IDs have all the requested privileges. NOTE: The user + profile feature is designed only for use by Kibana and Elastic's Observability, + Enterprise Search, and Elastic Security solutions. Individual users and external + applications should not call this API directly. Elastic reserves the right to + change or remove this feature in future releases without prior notice. ``_ - :param privileges: + :param privileges: An object containing all the privileges to be checked. :param uids: A list of profile IDs. The privileges are checked for associated users of the profiles. """ @@ -3313,13 +3552,25 @@ def saml_authenticate( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Authenticate SAML. Submits a SAML response message to Elasticsearch for consumption. + Authenticate SAML. Submit a SAML response message to Elasticsearch for consumption. + NOTE: This API is intended for use by custom web applications other than Kibana. + If you are using Kibana, refer to the documentation for configuring SAML single-sign-on + on the Elastic Stack. The SAML message that is submitted can be: * A response + to a SAML authentication request that was previously created using the SAML prepare + authentication API. * An unsolicited SAML message in the case of an IdP-initiated + single sign-on (SSO) flow. In either case, the SAML message needs to be a base64 + encoded XML document with a root element of ``. After successful validation, + Elasticsearch responds with an Elasticsearch internal access token and refresh + token that can be subsequently used for authentication. This API endpoint essentially + exchanges SAML responses that indicate successful authentication in the IdP for + Elasticsearch access and refresh tokens, which can be used for authentication + against Elasticsearch. ``_ - :param content: The SAML response as it was sent by the user’s browser, usually + :param content: The SAML response as it was sent by the user's browser, usually a Base64 encoded XML document. - :param ids: A json array with all the valid SAML Request Ids that the caller + :param ids: A JSON array with all the valid SAML Request Ids that the caller of the API has for the current user. :param realm: The name of the realm that should authenticate the SAML response. Useful in cases where many SAML realms are defined. @@ -3376,10 +3627,19 @@ def saml_complete_logout( ) -> ObjectApiResponse[t.Any]: """ Logout of SAML completely. Verifies the logout response sent from the SAML IdP. + NOTE: This API is intended for use by custom web applications other than Kibana. + If you are using Kibana, refer to the documentation for configuring SAML single-sign-on + on the Elastic Stack. The SAML IdP may send a logout response back to the SP + after handling the SP-initiated SAML Single Logout. This API verifies the response + by ensuring the content is relevant and validating its signature. An empty response + is returned if the verification process is successful. The response can be sent + by the IdP with either the HTTP-Redirect or the HTTP-Post binding. The caller + of this API must prepare the request accordingly so that this API can handle + either of them. ``_ - :param ids: A json array with all the valid SAML Request Ids that the caller + :param ids: A JSON array with all the valid SAML Request Ids that the caller of the API has for the current user. :param realm: The name of the SAML realm in Elasticsearch for which the configuration is used to verify the logout response. @@ -3441,25 +3701,33 @@ def saml_invalidate( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Invalidate SAML. Submits a SAML LogoutRequest message to Elasticsearch for consumption. + Invalidate SAML. Submit a SAML LogoutRequest message to Elasticsearch for consumption. + NOTE: This API is intended for use by custom web applications other than Kibana. + If you are using Kibana, refer to the documentation for configuring SAML single-sign-on + on the Elastic Stack. The logout request comes from the SAML IdP during an IdP + initiated Single Logout. The custom web application can use this API to have + Elasticsearch process the `LogoutRequest`. After successful validation of the + request, Elasticsearch invalidates the access token and refresh token that corresponds + to that specific SAML principal and provides a URL that contains a SAML LogoutResponse + message. Thus the user can be redirected back to their IdP. ``_ :param query_string: The query part of the URL that the user was redirected to by the SAML IdP to initiate the Single Logout. This query should include - a single parameter named SAMLRequest that contains a SAML logout request + a single parameter named `SAMLRequest` that contains a SAML logout request that is deflated and Base64 encoded. If the SAML IdP has signed the logout - request, the URL should include two extra parameters named SigAlg and Signature + request, the URL should include two extra parameters named `SigAlg` and `Signature` that contain the algorithm used for the signature and the signature value - itself. In order for Elasticsearch to be able to verify the IdP’s signature, - the value of the query_string field must be an exact match to the string + itself. In order for Elasticsearch to be able to verify the IdP's signature, + the value of the `query_string` field must be an exact match to the string provided by the browser. The client application must not attempt to parse or process the string in any way. :param acs: The Assertion Consumer Service URL that matches the one of the SAML realm in Elasticsearch that should be used. You must specify either this - parameter or the realm parameter. + parameter or the `realm` parameter. :param realm: The name of the SAML realm in Elasticsearch the configuration. - You must specify either this parameter or the acs parameter. + You must specify either this parameter or the `acs` parameter. """ if query_string is None and body is None: raise ValueError("Empty value passed for parameter 'query_string'") @@ -3509,12 +3777,19 @@ def saml_logout( ) -> ObjectApiResponse[t.Any]: """ Logout of SAML. Submits a request to invalidate an access token and refresh token. + NOTE: This API is intended for use by custom web applications other than Kibana. + If you are using Kibana, refer to the documentation for configuring SAML single-sign-on + on the Elastic Stack. This API invalidates the tokens that were generated for + a user by the SAML authenticate API. If the SAML realm in Elasticsearch is configured + accordingly and the SAML IdP supports this, the Elasticsearch response contains + a URL to redirect the user to the IdP that contains a SAML logout request (starting + an SP-initiated SAML Single Logout). ``_ :param token: The access token that was returned as a response to calling the SAML authenticate API. Alternatively, the most recent token that was received - after refreshing the original one by using a refresh_token. + after refreshing the original one by using a `refresh_token`. :param refresh_token: The refresh token that was returned as a response to calling the SAML authenticate API. Alternatively, the most recent refresh token that was received after refreshing the original access token. @@ -3565,19 +3840,31 @@ def saml_prepare_authentication( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Prepare SAML authentication. Creates a SAML authentication request (``) - as a URL string, based on the configuration of the respective SAML realm in Elasticsearch. + Prepare SAML authentication. Create a SAML authentication request (``) + as a URL string based on the configuration of the respective SAML realm in Elasticsearch. + NOTE: This API is intended for use by custom web applications other than Kibana. + If you are using Kibana, refer to the documentation for configuring SAML single-sign-on + on the Elastic Stack. This API returns a URL pointing to the SAML Identity Provider. + You can use the URL to redirect the browser of the user in order to continue + the authentication process. The URL includes a single parameter named `SAMLRequest`, + which contains a SAML Authentication request that is deflated and Base64 encoded. + If the configuration dictates that SAML authentication requests should be signed, + the URL has two extra parameters named `SigAlg` and `Signature`. These parameters + contain the algorithm used for the signature and the signature value itself. + It also returns a random string that uniquely identifies this SAML Authentication + request. The caller of this API needs to store this identifier as it needs to + be used in a following step of the authentication process. ``_ :param acs: The Assertion Consumer Service URL that matches the one of the SAML realms in Elasticsearch. The realm is used to generate the authentication - request. You must specify either this parameter or the realm parameter. + request. You must specify either this parameter or the `realm` parameter. :param realm: The name of the SAML realm in Elasticsearch for which the configuration is used to generate the authentication request. You must specify either this - parameter or the acs parameter. + parameter or the `acs` parameter. :param relay_state: A string that will be included in the redirect URL that this - API returns as the RelayState query parameter. If the Authentication Request + API returns as the `RelayState` query parameter. If the Authentication Request is signed, this value is used as part of the signature computation. """ __path_parts: t.Dict[str, str] = {} @@ -3622,7 +3909,10 @@ def saml_service_provider_metadata( ) -> ObjectApiResponse[t.Any]: """ Create SAML service provider metadata. Generate SAML metadata for a SAML 2.0 - Service Provider. + Service Provider. The SAML 2.0 specification provides a mechanism for Service + Providers to describe their capabilities and configuration using a metadata file. + This API generates Service Provider metadata based on the configuration of a + SAML realm in Elasticsearch. ``_ @@ -3669,21 +3959,27 @@ def suggest_user_profiles( ) -> ObjectApiResponse[t.Any]: """ Suggest a user profile. Get suggestions for user profiles that match specified - search criteria. + search criteria. NOTE: The user profile feature is designed only for use by Kibana + and Elastic's Observability, Enterprise Search, and Elastic Security solutions. + Individual users and external applications should not call this API directly. + Elastic reserves the right to change or remove this feature in future releases + without prior notice. ``_ - :param data: List of filters for the `data` field of the profile document. To - return all content use `data=*`. To return a subset of content use `data=` - to retrieve content nested under the specified ``. By default returns - no `data` content. + :param data: A comma-separated list of filters for the `data` field of the profile + document. To return all content use `data=*`. To return a subset of content, + use `data=` to retrieve content nested under the specified ``. + By default, the API returns no `data` content. It is an error to specify + `data` as both the query parameter and the request body field. :param hint: Extra search criteria to improve relevance of the suggestion result. Profiles matching the spcified hint are ranked higher in the response. Profiles - not matching the hint don't exclude the profile from the response as long - as the profile matches the `name` field query. - :param name: Query string used to match name-related fields in user profile documents. - Name-related fields are the user's `username`, `full_name`, and `email`. - :param size: Number of profiles to return. + not matching the hint aren't excluded from the response as long as the profile + matches the `name` field query. + :param name: A query string used to match name-related fields in user profile + documents. Name-related fields are the user's `username`, `full_name`, and + `email`. + :param size: The number of profiles to return. """ __path_parts: t.Dict[str, str] = {} __path = "/_security/profile/_suggest" @@ -3825,7 +4121,18 @@ def update_cross_cluster_api_key( ) -> ObjectApiResponse[t.Any]: """ Update a cross-cluster API key. Update the attributes of an existing cross-cluster - API key, which is used for API key based remote cluster access. + API key, which is used for API key based remote cluster access. To use this API, + you must have at least the `manage_security` cluster privilege. Users can only + update API keys that they created. 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. It's not possible + to update expired API keys, or API keys that have been invalidated by the invalidate + API key API. This API supports updates to an API key's access scope, metadata, + and expiration. The owner user's information, such as the `username` and `realm`, + is also updated automatically on every call. NOTE: This API cannot update REST + API keys, which should be updated by either the update API key or bulk update + API keys API. ``_ @@ -3834,8 +4141,8 @@ def update_cross_cluster_api_key( of permissions for cross cluster search and cross cluster replication. At least one of them must be specified. When specified, the new access assignment fully replaces the previously assigned access. - :param expiration: Expiration time for the API key. By default, API keys never - expire. This property can be omitted to leave the value unchanged. + :param expiration: The expiration time for the API key. By default, API keys + never expire. This property can be omitted to leave the value 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. When specified, this information @@ -3875,6 +4182,81 @@ def update_cross_cluster_api_key( path_parts=__path_parts, ) + @_rewrite_parameters( + body_fields=("security", "security_profile", "security_tokens"), + parameter_aliases={ + "security-profile": "security_profile", + "security-tokens": "security_tokens", + }, + ) + def update_settings( + self, + *, + error_trace: t.Optional[bool] = None, + filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, + human: t.Optional[bool] = None, + master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, + pretty: t.Optional[bool] = None, + security: t.Optional[t.Mapping[str, t.Any]] = None, + security_profile: t.Optional[t.Mapping[str, t.Any]] = None, + security_tokens: t.Optional[t.Mapping[str, t.Any]] = 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 security index settings. Update the user-configurable settings for the + security internal index (`.security` and associated indices). Only a subset of + settings are allowed to be modified, for example `index.auto_expand_replicas` + and `index.number_of_replicas`. If a specific index is not in use on the system + and settings are provided for it, the request will be rejected. This API does + not yet support configuring the settings for indices before they are in use. + + ``_ + + :param master_timeout: The period to wait for a connection to the master node. + If no response is received before the timeout expires, the request fails + and returns an error. + :param security: Settings for the index used for most security configuration, + including native realm users and roles configured with the API. + :param security_profile: Settings for the index used to store profile information. + :param security_tokens: Settings for the index used to store tokens. + :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. + """ + __path_parts: t.Dict[str, str] = {} + __path = "/_security/settings" + __query: t.Dict[str, t.Any] = {} + __body: t.Dict[str, t.Any] = body if body is not None else {} + if error_trace is not None: + __query["error_trace"] = error_trace + if filter_path is not None: + __query["filter_path"] = filter_path + if human is not None: + __query["human"] = human + if master_timeout is not None: + __query["master_timeout"] = master_timeout + if pretty is not None: + __query["pretty"] = pretty + if timeout is not None: + __query["timeout"] = timeout + if not __body: + if security is not None: + __body["security"] = security + if security_profile is not None: + __body["security-profile"] = security_profile + if security_tokens is not None: + __body["security-tokens"] = security_tokens + __headers = {"accept": "application/json", "content-type": "application/json"} + return self.perform_request( # type: ignore[return-value] + "PUT", + __path, + params=__query, + headers=__headers, + body=__body, + endpoint_id="security.update_settings", + path_parts=__path_parts, + ) + @_rewrite_parameters( body_fields=("data", "labels"), ) @@ -3897,22 +4279,37 @@ def update_user_profile_data( ) -> ObjectApiResponse[t.Any]: """ Update user profile data. Update specific data for the user profile that is associated - with a unique ID. + with a unique ID. NOTE: The user profile feature is designed only for use by + Kibana and Elastic's Observability, Enterprise Search, and Elastic Security solutions. + Individual users and external applications should not call this API directly. + Elastic reserves the right to change or remove this feature in future releases + without prior notice. To use this API, you must have one of the following privileges: + * The `manage_user_profile` cluster privilege. * The `update_profile_data` global + privilege for the namespaces that are referenced in the request. This API updates + the `labels` and `data` fields of an existing user profile document with JSON + objects. New keys and their values are added to the profile document and conflicting + keys are replaced by data that's included in the request. For both labels and + data, content is namespaced by the top-level fields. The `update_profile_data` + global privilege grants privileges for updating only the allowed namespaces. ``_ :param uid: A unique identifier for the user profile. :param data: Non-searchable data that you want to associate with the user profile. - This field supports a nested data structure. + This field supports a nested data structure. Within the `data` object, top-level + keys cannot begin with an underscore (`_`) or contain a period (`.`). The + data object is not searchable, but can be retrieved with the get user profile + API. :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 labels: Searchable data that you want to associate with the user profile. - This field supports a nested data structure. + This field supports a nested data structure. Within the labels object, top-level + keys cannot begin with an underscore (`_`) or contain a period (`.`). :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', it waits for a refresh to + make this operation visible to search. If 'false', nothing is done with refreshes. """ if uid in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'uid'") diff --git a/elasticsearch/_sync/client/shutdown.py b/elasticsearch/_sync/client/shutdown.py index bfa561089..b2a0222d2 100644 --- a/elasticsearch/_sync/client/shutdown.py +++ b/elasticsearch/_sync/client/shutdown.py @@ -50,7 +50,7 @@ def delete_node( and Elastic Cloud on Kubernetes. Direct use is not supported. If the operator privileges feature is enabled, you must be an operator to use this API. - ``_ + ``_ :param node_id: The node id of node to be removed from the shutdown state :param master_timeout: Period to wait for a connection to the master node. If @@ -98,9 +98,6 @@ def get_node( t.Union[str, t.Literal["d", "h", "m", "micros", "ms", "nanos", "s"]] ] = None, pretty: t.Optional[bool] = None, - timeout: t.Optional[ - t.Union[str, t.Literal["d", "h", "m", "micros", "ms", "nanos", "s"]] - ] = None, ) -> ObjectApiResponse[t.Any]: """ Get the shutdown status. Get information about nodes that are ready to be shut @@ -111,14 +108,12 @@ def get_node( the operator privileges feature is enabled, you must be an operator to use this API. - ``_ + ``_ :param node_id: Which node for which to retrieve the shutdown status :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. """ __path_parts: t.Dict[str, str] if node_id not in SKIP_IN_PATH: @@ -138,8 +133,6 @@ def get_node( __query["master_timeout"] = master_timeout if pretty is not None: __query["pretty"] = pretty - if timeout is not None: - __query["timeout"] = timeout __headers = {"accept": "application/json"} return self.perform_request( # type: ignore[return-value] "GET", @@ -178,19 +171,23 @@ def put_node( """ Prepare a node to be shut down. NOTE: This feature is designed for indirect use by Elastic Cloud, Elastic Cloud Enterprise, and Elastic Cloud on Kubernetes. - Direct use is not supported. If the operator privileges feature is enabled, you - must be an operator to use this API. The API migrates ongoing tasks and index - shards to other nodes as needed to prepare a node to be restarted or shut down - and removed from the cluster. This ensures that Elasticsearch can be stopped - safely with minimal disruption to the cluster. You must specify the type of shutdown: - `restart`, `remove`, or `replace`. If a node is already being prepared for shutdown, - you can use this API to change the shutdown type. IMPORTANT: This API does NOT - terminate the Elasticsearch process. Monitor the node shutdown status to determine - when it is safe to stop Elasticsearch. + Direct use is not supported. If you specify a node that is offline, it will be + prepared for shut down when it rejoins the cluster. If the operator privileges + feature is enabled, you must be an operator to use this API. The API migrates + ongoing tasks and index shards to other nodes as needed to prepare a node to + be restarted or shut down and removed from the cluster. This ensures that Elasticsearch + can be stopped safely with minimal disruption to the cluster. You must specify + the type of shutdown: `restart`, `remove`, or `replace`. If a node is already + being prepared for shutdown, you can use this API to change the shutdown type. + IMPORTANT: This API does NOT terminate the Elasticsearch process. Monitor the + node shutdown status to determine when it is safe to stop Elasticsearch. - ``_ + ``_ - :param node_id: The node id of node to be shut down + :param node_id: The node identifier. This parameter is not validated against + the cluster's active nodes. This enables you to register a node for shut + down while it is offline. No error is thrown if you specify an invalid node + ID. :param reason: A human-readable reason that the node is being shut down. This field provides information for other cluster operators; it does not affect the shut down process. @@ -211,17 +208,17 @@ def put_node( the index.unassigned.node_left.delayed_timeout setting. If you specify both a restart allocation delay and an index-level allocation delay, the longer of the two is used. - :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 master_timeout: The period to wait for a connection to the master node. + If no response is received before the timeout expires, the request fails + and returns an error. :param target_node_name: Only valid if type is replace. Specifies the name of the node that is replacing the node being shut down. Shards from the shut down node are only allowed to be allocated to the target node, and no other data will be allocated to the target node. During relocation of data certain allocation rules are ignored, such as disk watermarks or user attribute filtering rules. - :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 timeout: The period to wait for a response. If no response is received + before the timeout expires, the request fails and returns an error. """ if node_id in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'node_id'") diff --git a/elasticsearch/_sync/client/slm.py b/elasticsearch/_sync/client/slm.py index 16737080b..5acaf04eb 100644 --- a/elasticsearch/_sync/client/slm.py +++ b/elasticsearch/_sync/client/slm.py @@ -33,7 +33,9 @@ def delete_lifecycle( error_trace: t.Optional[bool] = None, filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, human: t.Optional[bool] = None, + 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, ) -> ObjectApiResponse[t.Any]: """ Delete a policy. Delete a snapshot lifecycle policy definition. This operation @@ -43,6 +45,11 @@ def delete_lifecycle( ``_ :param policy_id: The id of the snapshot lifecycle policy to remove + :param master_timeout: The period to wait for a connection to the master node. + If no response is received before the timeout expires, the request fails + and returns an error. + :param timeout: The period to wait for a response. If no response is received + before the timeout expires, the request fails and returns an error. """ if policy_id in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'policy_id'") @@ -55,8 +62,12 @@ def delete_lifecycle( __query["filter_path"] = filter_path if human is not None: __query["human"] = human + if master_timeout is not None: + __query["master_timeout"] = master_timeout if pretty is not None: __query["pretty"] = pretty + if timeout is not None: + __query["timeout"] = timeout __headers = {"accept": "application/json"} return self.perform_request( # type: ignore[return-value] "DELETE", @@ -75,7 +86,9 @@ def execute_lifecycle( error_trace: t.Optional[bool] = None, filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, human: t.Optional[bool] = None, + 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, ) -> ObjectApiResponse[t.Any]: """ Run a policy. Immediately create a snapshot according to the snapshot lifecycle @@ -86,6 +99,11 @@ def execute_lifecycle( ``_ :param policy_id: The id of the snapshot lifecycle policy to be executed + :param master_timeout: The period to wait for a connection to the master node. + If no response is received before the timeout expires, the request fails + and returns an error. + :param timeout: The period to wait for a response. If no response is received + before the timeout expires, the request fails and returns an error. """ if policy_id in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'policy_id'") @@ -98,8 +116,12 @@ def execute_lifecycle( __query["filter_path"] = filter_path if human is not None: __query["human"] = human + if master_timeout is not None: + __query["master_timeout"] = master_timeout if pretty is not None: __query["pretty"] = pretty + if timeout is not None: + __query["timeout"] = timeout __headers = {"accept": "application/json"} return self.perform_request( # type: ignore[return-value] "PUT", @@ -117,7 +139,9 @@ def execute_retention( error_trace: t.Optional[bool] = None, filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, human: t.Optional[bool] = None, + 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, ) -> ObjectApiResponse[t.Any]: """ Run a retention policy. Manually apply the retention policy to force immediate @@ -125,6 +149,12 @@ def execute_retention( retention rules. The retention policy is normally applied according to its schedule. ``_ + + :param master_timeout: The period to wait for a connection to the master node. + If no response is received before the timeout expires, the request fails + and returns an error. + :param timeout: The period to wait for a response. If no response is received + before the timeout expires, the request fails and returns an error. """ __path_parts: t.Dict[str, str] = {} __path = "/_slm/_execute_retention" @@ -135,8 +165,12 @@ def execute_retention( __query["filter_path"] = filter_path if human is not None: __query["human"] = human + if master_timeout is not None: + __query["master_timeout"] = master_timeout if pretty is not None: __query["pretty"] = pretty + if timeout is not None: + __query["timeout"] = timeout __headers = {"accept": "application/json"} return self.perform_request( # type: ignore[return-value] "POST", @@ -155,7 +189,9 @@ def get_lifecycle( error_trace: t.Optional[bool] = None, filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, human: t.Optional[bool] = None, + 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, ) -> ObjectApiResponse[t.Any]: """ Get policy information. Get snapshot lifecycle policy definitions and information @@ -164,6 +200,11 @@ def get_lifecycle( ``_ :param policy_id: Comma-separated list of snapshot lifecycle policies to retrieve + :param master_timeout: The period to wait for a connection to the master node. + If no response is received before the timeout expires, the request fails + and returns an error. + :param timeout: The period to wait for a response. If no response is received + before the timeout expires, the request fails and returns an error. """ __path_parts: t.Dict[str, str] if policy_id not in SKIP_IN_PATH: @@ -179,8 +220,12 @@ def get_lifecycle( __query["filter_path"] = filter_path if human is not None: __query["human"] = human + if master_timeout is not None: + __query["master_timeout"] = master_timeout if pretty is not None: __query["pretty"] = pretty + if timeout is not None: + __query["timeout"] = timeout __headers = {"accept": "application/json"} return self.perform_request( # type: ignore[return-value] "GET", @@ -198,13 +243,21 @@ def get_stats( error_trace: t.Optional[bool] = None, filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, human: t.Optional[bool] = None, + 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, ) -> ObjectApiResponse[t.Any]: """ Get snapshot lifecycle management statistics. Get global and policy-level statistics about actions taken by snapshot lifecycle management. ``_ + + :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. """ __path_parts: t.Dict[str, str] = {} __path = "/_slm/stats" @@ -215,8 +268,12 @@ def get_stats( __query["filter_path"] = filter_path if human is not None: __query["human"] = human + if master_timeout is not None: + __query["master_timeout"] = master_timeout if pretty is not None: __query["pretty"] = pretty + if timeout is not None: + __query["timeout"] = timeout __headers = {"accept": "application/json"} return self.perform_request( # type: ignore[return-value] "GET", @@ -234,12 +291,22 @@ def get_status( error_trace: t.Optional[bool] = None, filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, human: t.Optional[bool] = None, + 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, ) -> ObjectApiResponse[t.Any]: """ Get the snapshot lifecycle management status. ``_ + + :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. To indicate that the request should never timeout, + set it to `-1`. + :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. To indicate + that the request should never timeout, set it to `-1`. """ __path_parts: t.Dict[str, str] = {} __path = "/_slm/status" @@ -250,8 +317,12 @@ def get_status( __query["filter_path"] = filter_path if human is not None: __query["human"] = human + if master_timeout is not None: + __query["master_timeout"] = master_timeout if pretty is not None: __query["pretty"] = pretty + if timeout is not None: + __query["timeout"] = timeout __headers = {"accept": "application/json"} return self.perform_request( # type: ignore[return-value] "GET", @@ -292,9 +363,10 @@ def put_lifecycle( :param policy_id: The identifier for the snapshot lifecycle policy you want to create or update. :param config: Configuration for each snapshot created by the policy. - :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 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. To indicate that the request should never timeout, + set it to `-1`. :param name: Name automatically assigned to each snapshot created by the policy. Date math is supported. To prevent conflicting snapshot names, a UUID is automatically appended to each snapshot name. @@ -305,8 +377,9 @@ def put_lifecycle( by the policy. :param schedule: Periodic or absolute schedule at which the policy creates snapshots. SLM applies schedule changes immediately. - :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 timeout: The period to wait for a response. If no response is received + before the timeout expires, the request fails and returns an error. To indicate + that the request should never timeout, set it to `-1`. """ if policy_id in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'policy_id'") @@ -359,7 +432,9 @@ def start( error_trace: t.Optional[bool] = None, filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, human: t.Optional[bool] = None, + 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, ) -> ObjectApiResponse[t.Any]: """ Start snapshot lifecycle management. Snapshot lifecycle management (SLM) starts @@ -367,6 +442,14 @@ def start( if it has been stopped using the stop SLM API. ``_ + + :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. To indicate that the request should never timeout, + set it to `-1`. + :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. To indicate + that the request should never timeout, set it to `-1`. """ __path_parts: t.Dict[str, str] = {} __path = "/_slm/start" @@ -377,8 +460,12 @@ def start( __query["filter_path"] = filter_path if human is not None: __query["human"] = human + if master_timeout is not None: + __query["master_timeout"] = master_timeout if pretty is not None: __query["pretty"] = pretty + if timeout is not None: + __query["timeout"] = timeout __headers = {"accept": "application/json"} return self.perform_request( # type: ignore[return-value] "POST", @@ -396,7 +483,9 @@ def stop( error_trace: t.Optional[bool] = None, filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, human: t.Optional[bool] = None, + 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, ) -> ObjectApiResponse[t.Any]: """ Stop snapshot lifecycle management. Stop all snapshot lifecycle management (SLM) @@ -410,6 +499,14 @@ def stop( status API to see if SLM is running. ``_ + + :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. To indicate that the request should never timeout, + set it to `-1`. + :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. To indicate + that the request should never timeout, set it to `-1`. """ __path_parts: t.Dict[str, str] = {} __path = "/_slm/stop" @@ -420,8 +517,12 @@ def stop( __query["filter_path"] = filter_path if human is not None: __query["human"] = human + if master_timeout is not None: + __query["master_timeout"] = master_timeout if pretty is not None: __query["pretty"] = pretty + if timeout is not None: + __query["timeout"] = timeout __headers = {"accept": "application/json"} return self.perform_request( # type: ignore[return-value] "POST", diff --git a/elasticsearch/_sync/client/snapshot.py b/elasticsearch/_sync/client/snapshot.py index f9a92c078..ccc697611 100644 --- a/elasticsearch/_sync/client/snapshot.py +++ b/elasticsearch/_sync/client/snapshot.py @@ -49,9 +49,16 @@ def cleanup_repository( ``_ - :param name: Snapshot repository to clean up. - :param master_timeout: Period to wait for a connection to the master node. - :param timeout: Period to wait for a response. + :param name: The name of the snapshot repository to clean up. + :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 indicate that the request should never timeout, + set it to `-1` + :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. To indicate + that the request should never timeout, set it to `-1`. """ if name in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'name'") @@ -102,14 +109,19 @@ def clone( Clone a snapshot. Clone part of all of a snapshot into another snapshot in the same repository. - ``_ + ``_ - :param repository: A repository name - :param snapshot: The name of the snapshot to clone from - :param target_snapshot: The name of the cloned snapshot to create - :param indices: - :param master_timeout: Explicit operation timeout for connection to master node - :param timeout: + :param repository: The name of the snapshot repository that both source and target + snapshot belong to. + :param snapshot: The source snapshot name. + :param target_snapshot: The target snapshot name. + :param indices: A comma-separated list of indices to include in the snapshot. + Multi-target syntax is supported. + :param master_timeout: The period to wait for the master node. If the master + node is not available before the timeout expires, the request fails and returns + an error. To indicate that the request should never timeout, set it to `-1`. + :param timeout: The period of time to wait for a response. If no response is + received before the timeout expires, the request fails and returns an error. """ if repository in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'repository'") @@ -155,6 +167,7 @@ def clone( @_rewrite_parameters( body_fields=( + "expand_wildcards", "feature_states", "ignore_unavailable", "include_global_state", @@ -169,6 +182,14 @@ def create( repository: str, snapshot: str, error_trace: t.Optional[bool] = None, + expand_wildcards: t.Optional[ + t.Union[ + t.Sequence[ + t.Union[str, t.Literal["all", "closed", "hidden", "none", "open"]] + ], + t.Union[str, t.Literal["all", "closed", "hidden", "none", "open"]], + ] + ] = None, feature_states: t.Optional[t.Sequence[str]] = None, filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, human: t.Optional[bool] = None, @@ -185,15 +206,22 @@ def create( """ Create a snapshot. Take a snapshot of a cluster or of data streams and indices. - ``_ + ``_ - :param repository: Repository for the snapshot. - :param snapshot: Name of the snapshot. Must be unique in the repository. - :param feature_states: Feature states to include in the snapshot. Each feature + :param repository: The name of the repository for the snapshot. + :param snapshot: The name of the snapshot. It supportes date math. It must be + unique in the repository. + :param expand_wildcards: Determines how wildcard patterns in the `indices` parameter + match data streams and indices. It supports comma-separated values such as + `open,hidden`. + :param feature_states: The feature states to include in the snapshot. Each feature state includes one or more system indices containing related data. You can view a list of eligible features using the get features API. If `include_global_state` is `true`, all current feature states are included by default. If `include_global_state` - is `false`, no feature states are included by default. + is `false`, no feature states are included by default. Note that specifying + an empty array will result in the default behavior. To exclude all feature + states, regardless of the `include_global_state` value, specify an array + with only the value `none` (`["none"]`). :param ignore_unavailable: If `true`, the request ignores data streams and indices in `indices` that are missing or closed. If `false`, the request returns an error for any data stream or index that is missing or closed. @@ -202,18 +230,24 @@ def create( composable index templates, legacy index templates, ingest pipelines, and ILM policies. It also includes data stored in system indices, such as Watches and task records (configurable via `feature_states`). - :param indices: Data streams and indices to include in the snapshot. Supports - multi-target syntax. Includes all data streams and indices by default. - :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 metadata: Optional metadata for the snapshot. May have any contents. Must - be less than 1024 bytes. This map is not automatically generated by Elasticsearch. - :param partial: If `true`, allows restoring a partial snapshot of indices with - unavailable shards. Only shards that were successfully included in the snapshot - will be restored. All missing shards will be recreated as empty. If `false`, - the entire restore operation will fail if one or more indices included in - the snapshot do not have all primary shards available. + :param indices: A comma-separated list of data streams and indices to include + in the snapshot. It supports a multi-target syntax. The default is an empty + array (`[]`), which includes all regular data streams and regular indices. + To exclude all data streams and indices, use `-*`. You can't use this parameter + to include or exclude system indices or system data streams from a snapshot. + Use `feature_states` instead. + :param master_timeout: The period to wait for a connection to the master node. + If no response is received before the timeout expires, the request fails + and returns an error. + :param metadata: Arbitrary metadata to the snapshot, such as a record of who + took the snapshot, why it was taken, or any other useful data. It can have + any contents but it must be less than 1024 bytes. This information is not + automatically generated by Elasticsearch. + :param partial: If `true`, it enables you to restore a partial snapshot of indices + with unavailable shards. Only shards that were successfully included in the + snapshot will be restored. All missing shards will be recreated as empty. + If `false`, the entire restore operation will fail if one or more indices + included in the snapshot do not have all primary shards available. :param wait_for_completion: If `true`, the request returns a response when the snapshot is complete. If `false`, the request returns a response when the snapshot initializes. @@ -242,6 +276,8 @@ def create( if wait_for_completion is not None: __query["wait_for_completion"] = wait_for_completion if not __body: + if expand_wildcards is not None: + __body["expand_wildcards"] = expand_wildcards if feature_states is not None: __body["feature_states"] = feature_states if ignore_unavailable is not None: @@ -292,14 +328,26 @@ def create_repository( clusters. To register a snapshot repository, the cluster's global metadata must be writeable. Ensure there are no cluster blocks (for example, `cluster.blocks.read_only` and `clsuter.blocks.read_only_allow_delete` settings) that prevent write access. + Several options for this API can be specified using a query parameter or a request + body parameter. If both parameters are specified, only the query parameter is + used. - ``_ + ``_ - :param name: A repository name + :param name: The name of the snapshot repository to register or update. :param repository: - :param master_timeout: Explicit operation timeout for connection to master node - :param timeout: Explicit operation timeout - :param verify: Whether to verify the repository after creation + :param master_timeout: The period to wait for the master node. If the master + node is not available before the timeout expires, the request fails and returns + an error. To indicate that the request should never timeout, set it to `-1`. + :param 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. To indicate + that the request should never timeout, set it to `-1`. + :param verify: If `true`, the request verifies the repository is functional on + all master and data nodes in the cluster. If `false`, this verification is + skipped. You can also perform this verification with the verify snapshot + repository API. """ if name in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'name'") @@ -353,11 +401,14 @@ def delete( """ Delete snapshots. - ``_ + ``_ - :param repository: A repository name - :param snapshot: A comma-separated list of snapshot names - :param master_timeout: Explicit operation timeout for connection to master node + :param repository: The name of the repository to delete a snapshot from. + :param snapshot: A comma-separated list of snapshot names to delete. It also + accepts wildcards (`*`). + :param master_timeout: The period to wait for the master node. If the master + node is not available before the timeout expires, the request fails and returns + an error. To indicate that the request should never timeout, set it to `-1`. """ if repository in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'repository'") @@ -406,12 +457,18 @@ def delete_repository( removes only the reference to the location where the repository is storing the snapshots. The snapshots themselves are left untouched and in place. - ``_ + ``_ - :param name: Name of the snapshot repository to unregister. Wildcard (`*`) patterns - are supported. - :param master_timeout: Explicit operation timeout for connection to master node - :param timeout: Explicit operation timeout + :param name: The ame of the snapshot repositories to unregister. Wildcard (`*`) + patterns are supported. + :param master_timeout: The period to wait for the master node. If the master + node is not available before the timeout expires, the request fails and returns + an error. To indicate that the request should never timeout, set it to `-1`. + :param 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. To indicate + that the request should never timeout, set it to `-1`. """ if name in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'name'") @@ -478,50 +535,65 @@ def get( verbose: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Get snapshot information. - - ``_ - - :param repository: Comma-separated list of snapshot repository names used to - limit the request. Wildcard (*) expressions are supported. - :param snapshot: Comma-separated list of snapshot names to retrieve. Also accepts - wildcards (*). - To get information about all snapshots in a registered repository, - use a wildcard (*) or _all. - To get information about any snapshots that - are currently running, use _current. - :param after: Offset identifier to start pagination from as returned by the next - field in the response body. - :param from_sort_value: Value of the current sort column at which to start retrieval. - Can either be a string snapshot- or repository name when sorting by snapshot - or repository name, a millisecond time value or a number when sorting by - index- or shard count. - :param ignore_unavailable: If false, the request returns an error for any snapshots + Get snapshot information. NOTE: The `after` parameter and `next` field enable + you to iterate through snapshots with some consistency guarantees regarding concurrent + creation or deletion of snapshots. It is guaranteed that any snapshot that exists + at the beginning of the iteration and is not concurrently deleted will be seen + during the iteration. Snapshots concurrently created may be seen during an iteration. + + ``_ + + :param repository: A comma-separated list of snapshot repository names used to + limit the request. Wildcard (`*`) expressions are supported. + :param snapshot: A comma-separated list of snapshot names to retrieve Wildcards + (`*`) are supported. * To get information about all snapshots in a registered + repository, use a wildcard (`*`) or `_all`. * To get information about any + snapshots that are currently running, use `_current`. + :param after: An offset identifier to start pagination from as returned by the + next field in the response body. + :param from_sort_value: The value of the current sort column at which to start + retrieval. It can be a string `snapshot-` or a repository name when sorting + by snapshot or repository name. It can be a millisecond time value or a number + when sorting by `index-` or shard count. + :param ignore_unavailable: If `false`, the request returns an error for any snapshots that are unavailable. - :param include_repository: If true, returns the repository name in each snapshot. - :param index_details: If true, returns additional information about each index - in the snapshot comprising the number of shards in the index, the total size - of the index in bytes, and the maximum number of segments per shard in the - index. Defaults to false, meaning that this information is omitted. - :param index_names: If true, returns the name of each index in each snapshot. - :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 include_repository: If `true`, the response includes the repository name + in each snapshot. + :param index_details: If `true`, the response includes additional information + about each index in the snapshot comprising the number of shards in the index, + the total size of the index in bytes, and the maximum number of segments + per shard in the index. The default is `false`, meaning that this information + is omitted. + :param index_names: If `true`, the response includes the name of each index in + each snapshot. + :param master_timeout: The period to wait for a connection to the master node. + If no response is received before the timeout expires, the request fails + and returns an error. :param offset: Numeric offset to start pagination from based on the snapshots matching this request. Using a non-zero value for this parameter is mutually exclusive with using the after parameter. Defaults to 0. - :param order: Sort order. Valid values are asc for ascending and desc for descending - order. Defaults to asc, meaning ascending order. - :param size: Maximum number of snapshots to return. Defaults to 0 which means - return all that match the request without limit. - :param slm_policy_filter: Filter snapshots by a comma-separated list of SLM policy - names that snapshots belong to. Also accepts wildcards (*) and combinations - of wildcards followed by exclude patterns starting with -. To include snapshots - not created by an SLM policy you can use the special pattern _none that will - match all snapshots without an SLM policy. - :param sort: Allows setting a sort order for the result. Defaults to start_time, - i.e. sorting by snapshot start time stamp. - :param verbose: If true, returns additional information about each snapshot such - as the version of Elasticsearch which took the snapshot, the start and end - times of the snapshot, and the number of shards snapshotted. + :param order: The sort order. Valid values are `asc` for ascending and `desc` + for descending order. The default behavior is ascending order. + :param size: The maximum number of snapshots to return. The default is 0, which + means to return all that match the request without limit. + :param slm_policy_filter: Filter snapshots by a comma-separated list of snapshot + lifecycle management (SLM) policy names that snapshots belong to. You can + use wildcards (`*`) and combinations of wildcards followed by exclude patterns + starting with `-`. For example, the pattern `*,-policy-a-\\*` will return + all snapshots except for those that were created by an SLM policy with a + name starting with `policy-a-`. Note that the wildcard pattern `*` matches + all snapshots created by an SLM policy but not those snapshots that were + not created by an SLM policy. To include snapshots that were not created + by an SLM policy, you can use the special pattern `_none` that will match + all snapshots without an SLM policy. + :param sort: The sort order for the result. The default behavior is sorting by + snapshot start time stamp. + :param verbose: If `true`, returns additional information about each snapshot + such as the version of Elasticsearch which took the snapshot, the start and + end times of the snapshot, and the number of shards snapshotted. NOTE: The + parameters `size`, `order`, `after`, `from_sort_value`, `offset`, `slm_policy_filter`, + and `sort` are not supported when you set `verbose=false` and the sort order + for requests with `verbose=false` is undefined. """ if repository in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'repository'") @@ -592,12 +664,18 @@ def get_repository( """ Get snapshot repository information. - ``_ + ``_ - :param name: A comma-separated list of repository names - :param local: Return local information, do not retrieve the state from master - node (default: false) - :param master_timeout: Explicit operation timeout for connection to master node + :param name: A comma-separated list of snapshot repository names used to limit + the request. Wildcard (`*`) expressions are supported including combining + wildcards with exclude patterns starting with `-`. To get information about + all snapshot repositories registered in the cluster, omit this parameter + or use `*` or `_all`. + :param local: If `true`, the request gets information from the local node only. + If `false`, the request gets information from the master node. + :param master_timeout: The period to wait for the master node. If the master + node is not available before the timeout expires, the request fails and returns + an error. To indicate that the request should never timeout, set it to `-1`. """ __path_parts: t.Dict[str, str] if name not in SKIP_IN_PATH: @@ -629,6 +707,225 @@ def get_repository( path_parts=__path_parts, ) + @_rewrite_parameters() + def repository_analyze( + self, + *, + name: str, + blob_count: t.Optional[int] = None, + concurrency: t.Optional[int] = None, + detailed: t.Optional[bool] = None, + early_read_node_count: t.Optional[int] = None, + error_trace: t.Optional[bool] = None, + filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, + human: t.Optional[bool] = None, + max_blob_size: t.Optional[t.Union[int, str]] = None, + max_total_data_size: t.Optional[t.Union[int, str]] = None, + pretty: t.Optional[bool] = None, + rare_action_probability: t.Optional[float] = None, + rarely_abort_writes: t.Optional[bool] = None, + read_node_count: t.Optional[int] = None, + register_operation_count: t.Optional[int] = None, + seed: t.Optional[int] = None, + timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, + ) -> ObjectApiResponse[t.Any]: + """ + Analyze a snapshot repository. Analyze the performance characteristics and any + incorrect behaviour found in a repository. The response exposes implementation + details of the analysis which may change from version to version. The response + body format is therefore not considered stable and may be different in newer + versions. There are a large number of third-party storage systems available, + not all of which are suitable for use as a snapshot repository by Elasticsearch. + Some storage systems behave incorrectly, or perform poorly, especially when accessed + concurrently by multiple clients as the nodes of an Elasticsearch cluster do. + This API performs a collection of read and write operations on your repository + which are designed to detect incorrect behaviour and to measure the performance + characteristics of your storage system. The default values for the parameters + are deliberately low to reduce the impact of running an analysis inadvertently + and to provide a sensible starting point for your investigations. Run your first + analysis with the default parameter values to check for simple problems. If successful, + run a sequence of increasingly large analyses until you encounter a failure or + you reach a `blob_count` of at least `2000`, a `max_blob_size` of at least `2gb`, + a `max_total_data_size` of at least `1tb`, and a `register_operation_count` of + at least `100`. Always specify a generous timeout, possibly `1h` or longer, to + allow time for each analysis to run to completion. Perform the analyses using + a multi-node cluster of a similar size to your production cluster so that it + can detect any problems that only arise when the repository is accessed by many + nodes at once. If the analysis fails, Elasticsearch detected that your repository + behaved unexpectedly. This usually means you are using a third-party storage + system with an incorrect or incompatible implementation of the API it claims + to support. If so, this storage system is not suitable for use as a snapshot + repository. You will need to work with the supplier of your storage system to + address the incompatibilities that Elasticsearch detects. If the analysis is + successful, the API returns details of the testing process, optionally including + how long each operation took. You can use this information to determine the performance + of your storage system. If any operation fails or returns an incorrect result, + the API returns an error. If the API returns an error, it may not have removed + all the data it wrote to the repository. The error will indicate the location + of any leftover data and this path is also recorded in the Elasticsearch logs. + You should verify that this location has been cleaned up correctly. If there + is still leftover data at the specified location, you should manually remove + it. If the connection from your client to Elasticsearch is closed while the client + is waiting for the result of the analysis, the test is cancelled. Some clients + are configured to close their connection if no response is received within a + certain timeout. An analysis takes a long time to complete so you might need + to relax any such client-side timeouts. On cancellation the analysis attempts + to clean up the data it was writing, but it may not be able to remove it all. + The path to the leftover data is recorded in the Elasticsearch logs. You should + verify that this location has been cleaned up correctly. If there is still leftover + data at the specified location, you should manually remove it. If the analysis + is successful then it detected no incorrect behaviour, but this does not mean + that correct behaviour is guaranteed. The analysis attempts to detect common + bugs but it does not offer 100% coverage. Additionally, it does not test the + following: * Your repository must perform durable writes. Once a blob has been + written it must remain in place until it is deleted, even after a power loss + or similar disaster. * Your repository must not suffer from silent data corruption. + Once a blob has been written, its contents must remain unchanged until it is + deliberately modified or deleted. * Your repository must behave correctly even + if connectivity from the cluster is disrupted. Reads and writes may fail in this + case, but they must not return incorrect results. IMPORTANT: An analysis writes + a substantial amount of data to your repository and then reads it back again. + This consumes bandwidth on the network between the cluster and the repository, + and storage space and I/O bandwidth on the repository itself. You must ensure + this load does not affect other users of these systems. Analyses respect the + repository settings `max_snapshot_bytes_per_sec` and `max_restore_bytes_per_sec` + if available and the cluster setting `indices.recovery.max_bytes_per_sec` which + you can use to limit the bandwidth they consume. NOTE: This API is intended for + exploratory use by humans. You should expect the request parameters and the response + format to vary in future versions. NOTE: Different versions of Elasticsearch + may perform different checks for repository compatibility, with newer versions + typically being stricter than older ones. A storage system that passes repository + analysis with one version of Elasticsearch may fail with a different version. + This indicates it behaves incorrectly in ways that the former version did not + detect. You must work with the supplier of your storage system to address the + incompatibilities detected by the repository analysis API in any version of Elasticsearch. + NOTE: This API may not work correctly in a mixed-version cluster. *Implementation + details* NOTE: This section of documentation describes how the repository analysis + API works in this version of Elasticsearch, but you should expect the implementation + to vary between versions. The request parameters and response format depend on + details of the implementation so may also be different in newer versions. The + analysis comprises a number of blob-level tasks, as set by the `blob_count` parameter + and a number of compare-and-exchange operations on linearizable registers, as + set by the `register_operation_count` parameter. These tasks are distributed + over the data and master-eligible nodes in the cluster for execution. For most + blob-level tasks, the executing node first writes a blob to the repository and + then instructs some of the other nodes in the cluster to attempt to read the + data it just wrote. The size of the blob is chosen randomly, according to the + `max_blob_size` and `max_total_data_size` parameters. If any of these reads fails + then the repository does not implement the necessary read-after-write semantics + that Elasticsearch requires. For some blob-level tasks, the executing node will + instruct some of its peers to attempt to read the data before the writing process + completes. These reads are permitted to fail, but must not return partial data. + If any read returns partial data then the repository does not implement the necessary + atomicity semantics that Elasticsearch requires. For some blob-level tasks, the + executing node will overwrite the blob while its peers are reading it. In this + case the data read may come from either the original or the overwritten blob, + but the read operation must not return partial data or a mix of data from the + two blobs. If any of these reads returns partial data or a mix of the two blobs + then the repository does not implement the necessary atomicity semantics that + Elasticsearch requires for overwrites. The executing node will use a variety + of different methods to write the blob. For instance, where applicable, it will + use both single-part and multi-part uploads. Similarly, the reading nodes will + use a variety of different methods to read the data back again. For instance + they may read the entire blob from start to end or may read only a subset of + the data. For some blob-level tasks, the executing node will cancel the write + before it is complete. In this case, it still instructs some of the other nodes + in the cluster to attempt to read the blob but all of these reads must fail to + find the blob. Linearizable registers are special blobs that Elasticsearch manipulates + using an atomic compare-and-exchange operation. This operation ensures correct + and strongly-consistent behavior even when the blob is accessed by multiple nodes + at the same time. The detailed implementation of the compare-and-exchange operation + on linearizable registers varies by repository type. Repository analysis verifies + that that uncontended compare-and-exchange operations on a linearizable register + blob always succeed. Repository analysis also verifies that contended operations + either succeed or report the contention but do not return incorrect results. + If an operation fails due to contention, Elasticsearch retries the operation + until it succeeds. Most of the compare-and-exchange operations performed by repository + analysis atomically increment a counter which is represented as an 8-byte blob. + Some operations also verify the behavior on small blobs with sizes other than + 8 bytes. + + ``_ + + :param name: The name of the repository. + :param blob_count: The total number of blobs to write to the repository during + the test. For realistic experiments, you should set it to at least `2000`. + :param concurrency: The number of operations to run concurrently during the test. + :param detailed: Indicates whether to return detailed results, including timing + information for every operation performed during the analysis. If false, + it returns only a summary of the analysis. + :param early_read_node_count: The number of nodes on which to perform an early + read operation while writing each blob. Early read operations are only rarely + performed. + :param max_blob_size: The maximum size of a blob to be written during the test. + For realistic experiments, you should set it to at least `2gb`. + :param max_total_data_size: An upper limit on the total size of all the blobs + written during the test. For realistic experiments, you should set it to + at least `1tb`. + :param rare_action_probability: The probability of performing a rare action such + as an early read, an overwrite, or an aborted write on each blob. + :param rarely_abort_writes: Indicates whether to rarely cancel writes before + they complete. + :param read_node_count: The number of nodes on which to read a blob after writing. + :param register_operation_count: The minimum number of linearizable register + operations to perform in total. For realistic experiments, you should set + it to at least `100`. + :param seed: The seed for the pseudo-random number generator used to generate + the list of operations performed during the test. To repeat the same set + of operations in multiple experiments, use the same seed in each experiment. + Note that the operations are performed concurrently so might not always happen + in the same order on each run. + :param timeout: The period of time to wait for the test to complete. If no response + is received before the timeout expires, the test is cancelled and returns + an error. + """ + if name in SKIP_IN_PATH: + raise ValueError("Empty value passed for parameter 'name'") + __path_parts: t.Dict[str, str] = {"repository": _quote(name)} + __path = f'/_snapshot/{__path_parts["repository"]}/_analyze' + __query: t.Dict[str, t.Any] = {} + if blob_count is not None: + __query["blob_count"] = blob_count + if concurrency is not None: + __query["concurrency"] = concurrency + if detailed is not None: + __query["detailed"] = detailed + if early_read_node_count is not None: + __query["early_read_node_count"] = early_read_node_count + if error_trace is not None: + __query["error_trace"] = error_trace + if filter_path is not None: + __query["filter_path"] = filter_path + if human is not None: + __query["human"] = human + if max_blob_size is not None: + __query["max_blob_size"] = max_blob_size + if max_total_data_size is not None: + __query["max_total_data_size"] = max_total_data_size + if pretty is not None: + __query["pretty"] = pretty + if rare_action_probability is not None: + __query["rare_action_probability"] = rare_action_probability + if rarely_abort_writes is not None: + __query["rarely_abort_writes"] = rarely_abort_writes + if read_node_count is not None: + __query["read_node_count"] = read_node_count + if register_operation_count is not None: + __query["register_operation_count"] = register_operation_count + if seed is not None: + __query["seed"] = seed + if timeout is not None: + __query["timeout"] = timeout + __headers = {"accept": "application/json"} + return self.perform_request( # type: ignore[return-value] + "POST", + __path, + params=__query, + headers=__headers, + endpoint_id="snapshot.repository_analyze", + path_parts=__path_parts, + ) + @_rewrite_parameters() @_stability_warning(Stability.EXPERIMENTAL) def repository_verify_integrity( @@ -682,21 +979,43 @@ def repository_verify_integrity( prevented it from detecting. NOTE: This API is intended for exploratory use by humans. You should expect the request parameters and the response format to vary in future versions. NOTE: This API may not work correctly in a mixed-version - cluster. - - ``_ - - :param name: A repository name - :param blob_thread_pool_concurrency: Number of threads to use for reading blob - contents - :param index_snapshot_verification_concurrency: Number of snapshots to verify - concurrently within each index - :param index_verification_concurrency: Number of indices to verify concurrently - :param max_bytes_per_sec: Rate limit for individual blob verification - :param max_failed_shard_snapshots: Maximum permitted number of failed shard snapshots - :param meta_thread_pool_concurrency: Number of threads to use for reading metadata - :param snapshot_verification_concurrency: Number of snapshots to verify concurrently - :param verify_blob_contents: Whether to verify the contents of individual blobs + cluster. The default values for the parameters of this API are designed to limit + the impact of the integrity verification on other activities in your cluster. + For instance, by default it will only use at most half of the `snapshot_meta` + threads to verify the integrity of each snapshot, allowing other snapshot operations + to use the other half of this thread pool. If you modify these parameters to + speed up the verification process, you risk disrupting other snapshot-related + operations in your cluster. For large repositories, consider setting up a separate + single-node Elasticsearch cluster just for running the integrity verification + API. The response exposes implementation details of the analysis which may change + from version to version. The response body format is therefore not considered + stable and may be different in newer versions. + + ``_ + + :param name: The name of the snapshot repository. + :param blob_thread_pool_concurrency: If `verify_blob_contents` is `true`, this + parameter specifies how many blobs to verify at once. + :param index_snapshot_verification_concurrency: The maximum number of index snapshots + to verify concurrently within each index verification. + :param index_verification_concurrency: The number of indices to verify concurrently. + The default behavior is to use the entire `snapshot_meta` thread pool. + :param max_bytes_per_sec: If `verify_blob_contents` is `true`, this parameter + specifies the maximum amount of data that Elasticsearch will read from the + repository every second. + :param max_failed_shard_snapshots: The number of shard snapshot failures to track + during integrity verification, in order to avoid excessive resource usage. + If your repository contains more than this number of shard snapshot failures, + the verification will fail. + :param meta_thread_pool_concurrency: The maximum number of snapshot metadata + operations to run concurrently. The default behavior is to use at most half + of the `snapshot_meta` thread pool at once. + :param snapshot_verification_concurrency: The number of snapshots to verify concurrently. + The default behavior is to use at most half of the `snapshot_meta` thread + pool at once. + :param verify_blob_contents: Indicates whether to verify the checksum of every + data blob in the repository. If this feature is enabled, Elasticsearch will + read the entire repository contents, which may be extremely slow and expensive. """ if name in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'name'") @@ -794,23 +1113,66 @@ def restore( or Workplace Search, you must restore the Enterprise Search encryption key before you restore the snapshot. - ``_ - - :param repository: A repository name - :param snapshot: A snapshot name - :param feature_states: - :param ignore_index_settings: - :param ignore_unavailable: - :param include_aliases: - :param include_global_state: - :param index_settings: - :param indices: - :param master_timeout: Explicit operation timeout for connection to master node - :param partial: - :param rename_pattern: - :param rename_replacement: - :param wait_for_completion: Should this request wait until the operation has - completed before returning + ``_ + + :param repository: The name of the repository to restore a snapshot from. + :param snapshot: The name of the snapshot to restore. + :param feature_states: The feature states to restore. If `include_global_state` + is `true`, the request restores all feature states in the snapshot by default. + If `include_global_state` is `false`, the request restores no feature states + by default. Note that specifying an empty array will result in the default + behavior. To restore no feature states, regardless of the `include_global_state` + value, specify an array containing only the value `none` (`["none"]`). + :param ignore_index_settings: The index settings to not restore from the snapshot. + You can't use this option to ignore `index.number_of_shards`. For data streams, + this option applies only to restored backing indices. New backing indices + are configured using the data stream's matching index template. + :param ignore_unavailable: If `true`, the request ignores any index or data stream + in indices that's missing from the snapshot. If `false`, the request returns + an error for any missing index or data stream. + :param include_aliases: If `true`, the request restores aliases for any restored + data streams and indices. If `false`, the request doesn’t restore aliases. + :param include_global_state: If `true`, restore the cluster state. The cluster + state includes: * Persistent cluster settings * Index templates * Legacy + index templates * Ingest pipelines * Index lifecycle management (ILM) policies + * Stored scripts * For snapshots taken after 7.12.0, feature states If `include_global_state` + is `true`, the restore operation merges the legacy index templates in your + cluster with the templates contained in the snapshot, replacing any existing + ones whose name matches one in the snapshot. It completely removes all persistent + settings, non-legacy index templates, ingest pipelines, and ILM lifecycle + policies that exist in your cluster and replaces them with the corresponding + items from the snapshot. Use the `feature_states` parameter to configure + how feature states are restored. If `include_global_state` is `true` and + a snapshot was created without a global state then the restore request will + fail. + :param index_settings: Index settings to add or change in restored indices, including + backing indices. You can't use this option to change `index.number_of_shards`. + For data streams, this option applies only to restored backing indices. New + backing indices are configured using the data stream's matching index template. + :param indices: A comma-separated list of indices and data streams to restore. + It supports a multi-target syntax. The default behavior is all regular indices + and regular data streams in the snapshot. You can't use this parameter to + restore system indices or system data streams. Use `feature_states` instead. + :param master_timeout: The period to wait for the master node. If the master + node is not available before the timeout expires, the request fails and returns + an error. To indicate that the request should never timeout, set it to `-1`. + :param partial: If `false`, the entire restore operation will fail if one or + more indices included in the snapshot do not have all primary shards available. + If true, it allows restoring a partial snapshot of indices with unavailable + shards. Only shards that were successfully included in the snapshot will + be restored. All missing shards will be recreated as empty. + :param rename_pattern: A rename pattern to apply to restored data streams and + indices. Data streams and indices matching the rename pattern will be renamed + according to `rename_replacement`. The rename pattern is applied as defined + by the regular expression that supports referencing the original text, according + to the `appendReplacement` logic. + :param rename_replacement: The rename replacement string that is used with the + `rename_pattern`. + :param wait_for_completion: If `true`, the request returns a response when the + restore operation completes. The operation is complete when it finishes all + attempts to recover primary shards for restored indices. This applies even + if one or more of the recovery attempts fail. If `false`, the request returns + a response when the restore operation initializes. """ if repository in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'repository'") @@ -889,22 +1251,31 @@ def status( each shard participating in the snapshot. Note that this API should be used only to obtain detailed shard-level information for ongoing snapshots. If this detail is not needed or you want to obtain information about one or more existing snapshots, - use the get snapshot API. WARNING: Using the API to return the status of any - snapshots other than currently running snapshots can be expensive. The API requires - a read from the repository for each shard in each snapshot. For example, if you - have 100 snapshots with 1,000 shards each, an API request that includes all snapshots - will require 100,000 reads (100 snapshots x 1,000 shards). Depending on the latency - of your storage, such requests can take an extremely long time to return results. - These requests can also tax machine resources and, when using cloud storage, - incur high processing costs. - - ``_ - - :param repository: A repository name - :param snapshot: A comma-separated list of snapshot names - :param ignore_unavailable: Whether to ignore unavailable snapshots, defaults - to false which means a SnapshotMissingException is thrown - :param master_timeout: Explicit operation timeout for connection to master node + use the get snapshot API. If you omit the `` request path parameter, + the request retrieves information only for currently running snapshots. This + usage is preferred. If needed, you can specify `` and `` + to retrieve information for specific snapshots, even if they're not currently + running. WARNING: Using the API to return the status of any snapshots other than + currently running snapshots can be expensive. The API requires a read from the + repository for each shard in each snapshot. For example, if you have 100 snapshots + with 1,000 shards each, an API request that includes all snapshots will require + 100,000 reads (100 snapshots x 1,000 shards). Depending on the latency of your + storage, such requests can take an extremely long time to return results. These + requests can also tax machine resources and, when using cloud storage, incur + high processing costs. + + ``_ + + :param repository: The snapshot repository name used to limit the request. It + supports wildcards (`*`) if `` isn't specified. + :param snapshot: A comma-separated list of snapshots to retrieve status for. + The default is currently running snapshots. Wildcards (`*`) are not supported. + :param ignore_unavailable: If `false`, the request returns an error for any snapshots + that are unavailable. If `true`, the request ignores snapshots that are unavailable, + such as those that are corrupted or temporarily cannot be returned. + :param master_timeout: The period to wait for the master node. If the master + node is not available before the timeout expires, the request fails and returns + an error. To indicate that the request should never timeout, set it to `-1`. """ __path_parts: t.Dict[str, str] if repository not in SKIP_IN_PATH and snapshot not in SKIP_IN_PATH: @@ -958,11 +1329,17 @@ def verify_repository( Verify a snapshot repository. Check for common misconfigurations in a snapshot repository. - ``_ + ``_ - :param name: A repository name - :param master_timeout: Explicit operation timeout for connection to master node - :param timeout: Explicit operation timeout + :param name: The name of the snapshot repository to verify. + :param master_timeout: The period to wait for the master node. If the master + node is not available before the timeout expires, the request fails and returns + an error. To indicate that the request should never timeout, set it to `-1`. + :param 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. To indicate + that the request should never timeout, set it to `-1`. """ if name in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'name'") diff --git a/elasticsearch/_sync/client/sql.py b/elasticsearch/_sync/client/sql.py index bf190210a..9ab4f94cf 100644 --- a/elasticsearch/_sync/client/sql.py +++ b/elasticsearch/_sync/client/sql.py @@ -85,11 +85,14 @@ def delete_async( ) -> 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. + 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: Identifier for the search. + :param id: The identifier for the search. """ if id in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'id'") @@ -132,20 +135,23 @@ def get_async( ) -> 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. + 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: Identifier for the search. - :param delimiter: Separator for CSV results. The API only supports this parameter - for CSV responses. - :param format: Format for the response. You must specify a format using this - parameter or the Accept HTTP header. If you specify both, the API uses this - parameter. - :param keep_alive: Retention period for the search and its results. Defaults + :param id: The identifier for the search. + :param delimiter: The separator for CSV results. The API supports this parameter + only for CSV responses. + :param format: The format for the response. You must specify a format using this + parameter or the `Accept` HTTP header. If you specify both, the API uses + this parameter. + :param keep_alive: The retention period for the search and its results. It defaults to the `keep_alive` period for the original SQL search. - :param wait_for_completion_timeout: Period to wait for complete results. Defaults - to no timeout, meaning the request waits for complete search results. + :param wait_for_completion_timeout: The period to wait for complete results. + It defaults to no timeout, meaning the request waits for complete search + results. """ if id in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'id'") @@ -194,7 +200,7 @@ def get_async_status( ``_ - :param id: Identifier for the search. + :param id: The identifier for the search. """ if id in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'id'") @@ -221,6 +227,7 @@ def get_async_status( @_rewrite_parameters( body_fields=( + "allow_partial_search_results", "catalog", "columnar", "cursor", @@ -243,6 +250,7 @@ def get_async_status( def query( self, *, + allow_partial_search_results: t.Optional[bool] = None, catalog: t.Optional[str] = None, columnar: t.Optional[bool] = None, cursor: t.Optional[str] = None, @@ -277,36 +285,45 @@ def query( ``_ - :param catalog: Default catalog (cluster) for queries. If unspecified, the queries - execute on the data in the local cluster only. - :param columnar: If true, the results in a columnar fashion: one row represents - all the values of a certain column from the current page of results. - :param cursor: Cursor used to retrieve a set of paginated results. If you specify - a cursor, the API only uses the `columnar` and `time_zone` request body parameters. - It ignores other request body parameters. - :param fetch_size: The maximum number of rows (or entries) to return in one response - :param field_multi_value_leniency: Throw an exception when encountering multiple - values for a field (default) or be lenient and return the first value from - the list (without any guarantees of what that will be - typically the first - in natural ascending order). - :param filter: Elasticsearch query DSL for additional filtering. - :param format: Format for the response. - :param index_using_frozen: If true, the search can run on frozen indices. Defaults - to false. - :param keep_alive: Retention period for an async or saved synchronous search. - :param keep_on_completion: If true, Elasticsearch stores synchronous searches - if you also specify the wait_for_completion_timeout parameter. If false, - Elasticsearch only stores async searches that don’t finish before the wait_for_completion_timeout. - :param page_timeout: The timeout before a pagination request fails. - :param params: Values for parameters in the query. - :param query: SQL query to run. + :param allow_partial_search_results: If `true`, the response has partial results + when there are shard request timeouts or shard failures. If `false`, the + API returns an error with no partial results. + :param catalog: The default catalog (cluster) for queries. If unspecified, the + queries execute on the data in the local cluster only. + :param columnar: If `true`, the results are in a columnar fashion: one row represents + all the values of a certain column from the current page of results. The + API supports this parameter only for CBOR, JSON, SMILE, and YAML responses. + :param cursor: The cursor used to retrieve a set of paginated results. If you + specify a cursor, the API only uses the `columnar` and `time_zone` request + body parameters. It ignores other request body parameters. + :param fetch_size: The maximum number of rows (or entries) to return in one response. + :param field_multi_value_leniency: If `false`, the API returns an exception when + encountering multiple values for a field. If `true`, the API is lenient and + returns the first value from the array with no guarantee of consistent results. + :param filter: The Elasticsearch query DSL for additional filtering. + :param format: The format for the response. You can also specify a format using + the `Accept` HTTP header. If you specify both this parameter and the `Accept` + HTTP header, this parameter takes precedence. + :param index_using_frozen: If `true`, the search can run on frozen indices. + :param keep_alive: The retention period for an async or saved synchronous search. + :param keep_on_completion: If `true`, Elasticsearch stores synchronous searches + if you also specify the `wait_for_completion_timeout` parameter. If `false`, + Elasticsearch only stores async searches that don't finish before the `wait_for_completion_timeout`. + :param page_timeout: The minimum retention period for the scroll cursor. After + this time period, a pagination request might fail because the scroll cursor + is no longer available. Subsequent scroll requests prolong the lifetime of + the scroll cursor by the duration of `page_timeout` in the scroll request. + :param params: The values for parameters in the query. + :param query: The SQL query to run. :param request_timeout: The timeout before the request fails. - :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 time_zone: ISO-8601 time zone ID for the search. - :param wait_for_completion_timeout: Period to wait for complete results. Defaults - to no timeout, meaning the request waits for complete search results. If - the search doesn’t finish within this period, the search becomes async. + :param runtime_mappings: One or more runtime fields for the search request. These + fields take precedence over mapped fields with the same name. + :param time_zone: The ISO-8601 time zone ID for the search. + :param wait_for_completion_timeout: The period to wait for complete results. + It defaults to no timeout, meaning the request waits for complete search + results. If the search doesn't finish within this period, the search becomes + async. To save a synchronous search, you must specify this parameter and + the `keep_on_completion` parameter. """ __path_parts: t.Dict[str, str] = {} __path = "/_sql" @@ -323,6 +340,8 @@ def query( if pretty is not None: __query["pretty"] = pretty if not __body: + if allow_partial_search_results is not None: + __body["allow_partial_search_results"] = allow_partial_search_results if catalog is not None: __body["catalog"] = catalog if columnar is not None: @@ -384,14 +403,15 @@ def translate( ) -> ObjectApiResponse[t.Any]: """ Translate SQL into Elasticsearch queries. Translate an SQL search into a search - API request containing Query DSL. + API request containing Query DSL. It accepts the same request body parameters + as the SQL search API, excluding `cursor`. ``_ - :param query: SQL query to run. + :param query: The SQL query to run. :param fetch_size: The maximum number of rows (or entries) to return in one response. - :param filter: Elasticsearch query DSL for additional filtering. - :param time_zone: ISO-8601 time zone ID for the search. + :param filter: The Elasticsearch query DSL for additional filtering. + :param time_zone: The ISO-8601 time zone ID for the search. """ if query is None and body is None: raise ValueError("Empty value passed for parameter 'query'") diff --git a/elasticsearch/_sync/client/synonyms.py b/elasticsearch/_sync/client/synonyms.py index 453a85a7d..a13c3bab3 100644 --- a/elasticsearch/_sync/client/synonyms.py +++ b/elasticsearch/_sync/client/synonyms.py @@ -36,11 +36,25 @@ def delete_synonym( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Delete a synonym set. + Delete a synonym set. You can only delete a synonyms set that is not in use by + any index analyzer. Synonyms sets can be used in synonym graph token filters + and synonym token filters. These synonym filters can be used as part of search + analyzers. Analyzers need to be loaded when an index is restored (such as when + a node starts, or the index becomes open). Even if the analyzer is not used on + any field mapping, it still needs to be loaded on the index recovery phase. If + any analyzers cannot be loaded, the index becomes unavailable and the cluster + status becomes red or yellow as index shards are not available. To prevent that, + synonyms sets that are used in analyzers can't be deleted. A delete request in + this case will return a 400 response code. To remove a synonyms set, you must + first remove all indices that contain analyzers using it. You can migrate an + index by creating a new index that does not contain the token filter with the + synonyms set, and use the reindex API in order to copy over the index data. Once + finished, you can delete the index. When the synonyms set is not used in analyzers, + you will be able to delete it. ``_ - :param id: The id of the synonyms set to be deleted + :param id: The synonyms set identifier to delete. """ if id in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'id'") @@ -81,8 +95,8 @@ def delete_synonym_rule( ``_ - :param set_id: The id of the synonym set to be updated - :param rule_id: The id of the synonym rule to be deleted + :param set_id: The ID of the synonym set to update. + :param rule_id: The ID of the synonym rule to delete. """ if set_id in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'set_id'") @@ -131,9 +145,9 @@ def get_synonym( ``_ - :param id: "The id of the synonyms set to be retrieved - :param from_: Starting offset for query rules to be retrieved - :param size: specifies a max number of query rules to retrieve + :param id: The synonyms set identifier to retrieve. + :param from_: The starting offset for query rules to retrieve. + :param size: The max number of query rules to retrieve. """ if id in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'id'") @@ -178,8 +192,8 @@ def get_synonym_rule( ``_ - :param set_id: The id of the synonym set to retrieve the synonym rule from - :param rule_id: The id of the synonym rule to retrieve + :param set_id: The ID of the synonym set to retrieve the synonym rule from. + :param rule_id: The ID of the synonym rule to retrieve. """ if set_id in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'set_id'") @@ -225,10 +239,10 @@ def get_synonyms_sets( """ Get all synonym sets. Get a summary of all defined synonym sets. - ``_ + ``_ - :param from_: Starting offset - :param size: specifies a max number of results to get + :param from_: The starting offset for synonyms sets to retrieve. + :param size: The maximum number of synonyms sets to retrieve. """ __path_parts: t.Dict[str, str] = {} __path = "/_synonyms" @@ -274,12 +288,15 @@ def put_synonym( """ Create or update a synonym set. Synonyms sets are limited to a maximum of 10,000 synonym rules per set. If you need to manage more synonym rules, you can create - multiple synonym sets. + multiple synonym sets. When an existing synonyms set is updated, the search analyzers + that use the synonyms set are reloaded automatically for all indices. This is + equivalent to invoking the reload search analyzers API for all indices that use + the synonyms set. ``_ - :param id: The id of the synonyms set to be created or updated - :param synonyms_set: The synonym set information to update + :param id: The ID of the synonyms set to be created or updated. + :param synonyms_set: The synonym rules definitions for the synonyms set. """ if id in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'id'") @@ -328,13 +345,16 @@ def put_synonym_rule( ) -> ObjectApiResponse[t.Any]: """ Create or update a synonym rule. Create or update a synonym rule in a synonym - set. + set. If any of the synonym rules included is invalid, the API returns an error. + When you update a synonym rule, all analyzers using the synonyms set will be + reloaded automatically to reflect the new rule. ``_ - :param set_id: The id of the synonym set to be updated with the synonym rule - :param rule_id: The id of the synonym rule to be updated or created - :param synonyms: + :param set_id: The ID of the synonym set. + :param rule_id: The ID of the synonym rule to be updated or created. + :param synonyms: The synonym rule information definition, which must be in Solr + format. """ if set_id in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'set_id'") diff --git a/elasticsearch/_sync/client/tasks.py b/elasticsearch/_sync/client/tasks.py index 24886bc75..ea94ce71c 100644 --- a/elasticsearch/_sync/client/tasks.py +++ b/elasticsearch/_sync/client/tasks.py @@ -47,27 +47,30 @@ def cancel( wait_for_completion: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Cancel a task. A task may continue to run for some time after it has been cancelled - because it may not be able to safely stop its current activity straight away. - It is also possible that Elasticsearch must complete its work on other tasks - before it can process the cancellation. The get task information API will continue - to list these cancelled tasks until they complete. The cancelled flag in the - response indicates that the cancellation command has been processed and the task - will stop as soon as possible. To troubleshoot why a cancelled task does not - complete promptly, use the get task information API with the `?detailed` parameter - to identify the other tasks the system is running. You can also use the node - hot threads API to obtain detailed information about the work the system is doing + Cancel a task. WARNING: The task management API is new and should still be considered + a beta feature. The API may change in ways that are not backwards compatible. + A task may continue to run for some time after it has been cancelled because + it may not be able to safely stop its current activity straight away. It is also + possible that Elasticsearch must complete its work on other tasks before it can + process the cancellation. The get task information API will continue to list + these cancelled tasks until they complete. The cancelled flag in the response + indicates that the cancellation command has been processed and the task will + stop as soon as possible. To troubleshoot why a cancelled task does not complete + promptly, use the get task information API with the `?detailed` parameter to + identify the other tasks the system is running. You can also use the node hot + threads API to obtain detailed information about the work the system is doing instead of completing the cancelled task. ``_ - :param task_id: ID of the task. - :param actions: Comma-separated list or wildcard expression of actions used to - limit the request. - :param nodes: Comma-separated list of node IDs or names used to limit the request. - :param parent_task_id: Parent task ID used to limit the tasks. - :param wait_for_completion: Should the request block until the cancellation of - the task and its descendant tasks is completed. Defaults to false + :param task_id: The task identifier. + :param actions: A comma-separated list or wildcard expression of actions that + is used to limit the request. + :param nodes: A comma-separated list of node IDs or names that is used to limit + the request. + :param parent_task_id: A parent task ID that is used to limit the tasks. + :param wait_for_completion: If true, the request blocks until all found tasks + are complete. """ __path_parts: t.Dict[str, str] if task_id not in SKIP_IN_PATH: @@ -118,12 +121,16 @@ def get( ) -> ObjectApiResponse[t.Any]: """ 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. """ @@ -167,7 +174,6 @@ def list( t.Union[str, t.Literal["nodes", "none", "parents"]] ] = None, human: t.Optional[bool] = None, - master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, nodes: t.Optional[t.Union[str, t.Sequence[str]]] = None, parent_task_id: t.Optional[str] = None, pretty: t.Optional[bool] = None, @@ -176,25 +182,45 @@ def list( ) -> ObjectApiResponse[t.Any]: """ Get all tasks. Get information about the tasks currently running on one or more - nodes in the cluster. + nodes in the cluster. WARNING: The task management API is new and should still + be considered a beta feature. The API may change in ways that are not backwards + compatible. **Identifying running tasks** The `X-Opaque-Id header`, when provided + on the HTTP request header, is going to be returned as a header in the response + as well as in the headers field for in the task information. This enables you + to track certain calls or associate certain tasks with the client that started + them. For example: ``` curl -i -H "X-Opaque-Id: 123456" "http://localhost:9200/_tasks?group_by=parents" + ``` The API returns the following result: ``` HTTP/1.1 200 OK X-Opaque-Id: 123456 + content-type: application/json; charset=UTF-8 content-length: 831 { "tasks" : + { "u5lcZHqcQhu-rUoFaqDphA:45" : { "node" : "u5lcZHqcQhu-rUoFaqDphA", "id" : 45, + "type" : "transport", "action" : "cluster:monitor/tasks/lists", "start_time_in_millis" + : 1513823752749, "running_time_in_nanos" : 293139, "cancellable" : false, "headers" + : { "X-Opaque-Id" : "123456" }, "children" : [ { "node" : "u5lcZHqcQhu-rUoFaqDphA", + "id" : 46, "type" : "direct", "action" : "cluster:monitor/tasks/lists[n]", "start_time_in_millis" + : 1513823752750, "running_time_in_nanos" : 92133, "cancellable" : false, "parent_task_id" + : "u5lcZHqcQhu-rUoFaqDphA:45", "headers" : { "X-Opaque-Id" : "123456" } } ] } + } } ``` In this example, `X-Opaque-Id: 123456` is the ID as a part of the response + header. The `X-Opaque-Id` in the task `headers` is the ID for the task that was + initiated by the REST request. The `X-Opaque-Id` in the children `headers` is + the child task of the task that was initiated by the REST request. ``_ - :param actions: Comma-separated list or wildcard expression of actions used to - limit the request. + :param actions: A comma-separated list or wildcard expression of actions used + to limit the request. For example, you can use `cluser:*` to retrieve all + cluster-related tasks. :param detailed: If `true`, the response includes detailed information about - shard recoveries. This information is useful to distinguish tasks from each + the running tasks. This information is useful to distinguish tasks from each other but is more costly to run. - :param group_by: Key used to group tasks in the response. - :param master_timeout: Period to wait for a connection to the master node. If - no response is received before the timeout expires, the request fails and - returns an error. - :param nodes: Comma-separated list of node IDs or names used to limit returned - information. - :param parent_task_id: Parent task ID used to limit returned information. To - return all tasks, omit this parameter or use a value of `-1`. - :param timeout: Period to wait for a response. If no response is received before - the timeout expires, the request fails and returns an error. + :param group_by: A key that is used to group tasks in the response. The task + lists can be grouped either by nodes or by parent tasks. + :param nodes: A comma-separated list of node IDs or names that is used to limit + the returned information. + :param parent_task_id: A parent task identifier that is used to limit returned + information. To return all tasks, omit this parameter or use a value of `-1`. + If the parent task is not found, the API does not return a 404 response code. + :param timeout: The period to wait for each node to respond. If a node does not + respond before its timeout expires, the response does not include its information. + However, timed out nodes are included in the `node_failures` property. :param wait_for_completion: If `true`, the request blocks until the operation is complete. """ @@ -213,8 +239,6 @@ def list( __query["group_by"] = group_by if human is not None: __query["human"] = human - if master_timeout is not None: - __query["master_timeout"] = master_timeout if nodes is not None: __query["nodes"] = nodes if parent_task_id is not None: diff --git a/elasticsearch/_sync/client/text_structure.py b/elasticsearch/_sync/client/text_structure.py index 01ec7c5f8..7fb4f995a 100644 --- a/elasticsearch/_sync/client/text_structure.py +++ b/elasticsearch/_sync/client/text_structure.py @@ -54,7 +54,21 @@ def find_field_structure( ) -> ObjectApiResponse[t.Any]: """ Find the structure of a text field. Find the structure of a text field in an - Elasticsearch index. + Elasticsearch index. This API provides a starting point for extracting further + information from log messages already ingested into Elasticsearch. For example, + if you have ingested data into a very simple index that has just `@timestamp` + and message fields, you can use this API to see what common structure exists + in the message field. The response from the API contains: * Sample messages. + * Statistics that reveal the most common values for all fields detected within + the text and basic numeric statistics for numeric fields. * Information about + the structure of the text, which is useful when you write ingest configurations + to index it or similarly formatted text. * Appropriate mappings for an Elasticsearch + index, which you could use to ingest the text. All this information can be calculated + by the structure finder with no guidance. However, you can optionally override + some of the decisions about the text structure by specifying one or more query + parameters. If the structure finder produces unexpected results, specify the + `explain` query parameter and an explanation will appear in the response. It + helps determine why the returned structure was chosen. ``_ @@ -84,9 +98,9 @@ def find_field_structure( `field1`, and `field2` are used in the `grok_pattern` output. The intention in that situation is that a user who knows the meanings will rename the fields before using them. - :param explain: If true, the response includes a field named `explanation`, which - is an array of strings that indicate how the structure finder produced its - result. + :param explain: If `true`, the response includes a field named `explanation`, + which is an array of strings that indicate how the structure finder produced + its result. :param format: The high level structure of the text. By default, the API chooses the format. In this default scenario, all rows must have the same number of fields for a delimited format to be detected. If the format is set to @@ -107,7 +121,7 @@ def find_field_structure( :param should_trim_fields: If the format is `delimited`, you can specify whether values between delimiters should have whitespace trimmed from them. If this parameter is not specified and the delimiter is pipe (`|`), the default value - is true. Otherwise, the default value is false. + is true. Otherwise, the default value is `false`. :param timeout: The maximum amount of time that the structure analysis can take. If the analysis is still running when the timeout expires, it will be stopped. :param timestamp_field: The name of the field that contains the primary timestamp @@ -236,7 +250,10 @@ def find_message_structure( Appropriate mappings for an Elasticsearch index, which you could use to ingest the text. All this information can be calculated by the structure finder with no guidance. However, you can optionally override some of the decisions about - the text structure by specifying one or more query parameters. + the text structure by specifying one or more query parameters. If the structure + finder produces unexpected results, specify the `explain` query parameter and + an explanation will appear in the response. It helps determine why the returned + structure was chosen. ``_ @@ -284,7 +301,7 @@ def find_message_structure( :param should_trim_fields: If the format is `delimited`, you can specify whether values between delimiters should have whitespace trimmed from them. If this parameter is not specified and the delimiter is pipe (`|`), the default value - is true. Otherwise, the default value is false. + is true. Otherwise, the default value is `false`. :param timeout: The maximum amount of time that the structure analysis can take. If the analysis is still running when the timeout expires, it will be stopped. :param timestamp_field: The name of the field that contains the primary timestamp @@ -413,43 +430,51 @@ def find_structure( ``_ :param text_files: - :param charset: The text’s character set. It must be a character set that is - supported by the JVM that Elasticsearch uses. For example, UTF-8, UTF-16LE, - windows-1252, or EUC-JP. If this parameter is not specified, the structure + :param charset: The text's character set. It must be a character set that is + supported by the JVM that Elasticsearch uses. For example, `UTF-8`, `UTF-16LE`, + `windows-1252`, or `EUC-JP`. If this parameter is not specified, the structure finder chooses an appropriate character set. - :param column_names: If you have set format to delimited, you can specify the + :param column_names: If you have set format to `delimited`, you can specify the column names in a comma-separated list. If this parameter is not specified, the structure finder uses the column names from the header row of the text. If the text does not have a header role, columns are named "column1", "column2", "column3", for example. - :param delimiter: If you have set format to delimited, you can specify the character - used to delimit the values in each row. Only a single character is supported; - the delimiter cannot have multiple characters. By default, the API considers - the following possibilities: comma, tab, semi-colon, and pipe (|). In this - default scenario, all rows must have the same number of fields for the delimited - format to be detected. If you specify a delimiter, up to 10% of the rows - can have a different number of columns than the first row. - :param ecs_compatibility: The mode of compatibility with ECS compliant Grok patterns - (disabled or v1, default: disabled). - :param explain: If this parameter is set to true, the response includes a field + :param delimiter: If you have set `format` to `delimited`, you can specify the + character used to delimit the values in each row. Only a single character + is supported; the delimiter cannot have multiple characters. By default, + the API considers the following possibilities: comma, tab, semi-colon, and + pipe (`|`). In this default scenario, all rows must have the same number + of fields for the delimited format to be detected. If you specify a delimiter, + up to 10% of the rows can have a different number of columns than the first + row. + :param ecs_compatibility: The mode of compatibility with ECS compliant Grok patterns. + Use this parameter to specify whether to use ECS Grok patterns instead of + legacy ones when the structure finder creates a Grok pattern. Valid values + are `disabled` and `v1`. This setting primarily has an impact when a whole + message Grok pattern such as `%{CATALINALOG}` matches the input. If the structure + finder identifies a common structure but has no idea of meaning then generic + field names such as `path`, `ipaddress`, `field1`, and `field2` are used + in the `grok_pattern` output, with the intention that a user who knows the + meanings rename these fields before using it. + :param explain: If this parameter is set to `true`, the response includes a field named explanation, which is an array of strings that indicate how the structure finder produced its result. If the structure finder produces unexpected results for some text, use this query parameter to help you determine why the returned structure was chosen. - :param format: The high level structure of the text. Valid values are ndjson, - xml, delimited, and semi_structured_text. By default, the API chooses the - format. In this default scenario, all rows must have the same number of fields - for a delimited format to be detected. If the format is set to delimited - and the delimiter is not set, however, the API tolerates up to 5% of rows - that have a different number of columns than the first row. - :param grok_pattern: If you have set format to semi_structured_text, you can - specify a Grok pattern that is used to extract fields from every message + :param format: The high level structure of the text. Valid values are `ndjson`, + `xml`, `delimited`, and `semi_structured_text`. By default, the API chooses + the format. In this default scenario, all rows must have the same number + of fields for a delimited format to be detected. If the format is set to + `delimited` and the delimiter is not set, however, the API tolerates up to + 5% of rows that have a different number of columns than the first row. + :param grok_pattern: If you have set `format` to `semi_structured_text`, you + can specify a Grok pattern that is used to extract fields from every message in the text. The name of the timestamp field in the Grok pattern must match - what is specified in the timestamp_field parameter. If that parameter is + what is specified in the `timestamp_field` parameter. If that parameter is not specified, the name of the timestamp field in the Grok pattern must match - "timestamp". If grok_pattern is not specified, the structure finder creates + "timestamp". If `grok_pattern` is not specified, the structure finder creates a Grok pattern. - :param has_header_row: If you have set format to delimited, you can use this + :param has_header_row: If you have set `format` to `delimited`, you can use this parameter to indicate whether the column names are in the first row of the text. If this parameter is not specified, the structure finder guesses based on the similarity of the first row of the text to other rows. @@ -459,26 +484,58 @@ def find_structure( that this may lead to very long processing times if the way to group lines into messages is misdetected. :param lines_to_sample: The number of lines to include in the structural analysis, - starting from the beginning of the text. The minimum is 2; If the value of + starting from the beginning of the text. The minimum is 2. If the value of this parameter is greater than the number of lines in the text, the analysis proceeds (as long as there are at least two lines in the text) for all of - the lines. - :param quote: If you have set format to delimited, you can specify the character + the lines. NOTE: The number of lines and the variation of the lines affects + the speed of the analysis. For example, if you upload text where the first + 1000 lines are all variations on the same message, the analysis will find + more commonality than would be seen with a bigger sample. If possible, however, + it is more efficient to upload sample text with more variety in the first + 1000 lines than to request analysis of 100000 lines to achieve some variety. + :param quote: If you have set `format` to `delimited`, you can specify the character used to quote the values in each row if they contain newlines or the delimiter character. Only a single character is supported. If this parameter is not - specified, the default value is a double quote ("). If your delimited text + specified, the default value is a double quote (`"`). If your delimited text format does not use quoting, a workaround is to set this argument to a character that does not appear anywhere in the sample. - :param should_trim_fields: If you have set format to delimited, you can specify + :param should_trim_fields: If you have set `format` to `delimited`, you can specify whether values between delimiters should have whitespace trimmed from them. - If this parameter is not specified and the delimiter is pipe (|), the default - value is true. Otherwise, the default value is false. - :param timeout: Sets the maximum amount of time that the structure analysis can - take. If the analysis is still running when the timeout expires then it will - be stopped. - :param timestamp_field: Optional parameter to specify the timestamp field in - the file + If this parameter is not specified and the delimiter is pipe (`|`), the default + value is `true`. Otherwise, the default value is `false`. + :param timeout: The maximum amount of time that the structure analysis can take. + If the analysis is still running when the timeout expires then it will be + stopped. + :param timestamp_field: The name of the field that contains the primary timestamp + of each record in the text. In particular, if the text were ingested into + an index, this is the field that would be used to populate the `@timestamp` + field. If the `format` is `semi_structured_text`, this field must match the + name of the appropriate extraction in the `grok_pattern`. Therefore, for + semi-structured text, it is best not to specify this parameter unless `grok_pattern` + is also specified. For structured text, if you specify this parameter, the + field must exist within the text. If this parameter is not specified, the + structure finder makes a decision about which field (if any) is the primary + timestamp field. For structured text, it is not compulsory to have a timestamp + in the text. :param timestamp_format: The Java time format of the timestamp field in the text. + Only a subset of Java time format letter groups are supported: * `a` * `d` + * `dd` * `EEE` * `EEEE` * `H` * `HH` * `h` * `M` * `MM` * `MMM` * `MMMM` + * `mm` * `ss` * `XX` * `XXX` * `yy` * `yyyy` * `zzz` Additionally `S` letter + groups (fractional seconds) of length one to nine are supported providing + they occur after `ss` and separated from the `ss` by a `.`, `,` or `:`. Spacing + and punctuation is also permitted with the exception of `?`, newline and + carriage return, together with literal text enclosed in single quotes. For + example, `MM/dd HH.mm.ss,SSSSSS 'in' yyyy` is a valid override format. One + valuable use case for this parameter is when the format is semi-structured + text, there are multiple timestamp formats in the text, and you know which + format corresponds to the primary timestamp, but you do not want to specify + the full `grok_pattern`. Another is when the timestamp format is one that + the structure finder does not consider by default. If this parameter is not + specified, the structure finder chooses the best format from a built-in set. + If the special value `null` is specified the structure finder will not look + for a primary timestamp in the text. When the format is semi-structured text + this will result in the structure finder treating the text as single-line + messages. """ if text_files is None and body is None: raise ValueError( @@ -556,10 +613,12 @@ def test_grok_pattern( ``_ - :param grok_pattern: Grok pattern to run on the text. - :param text: Lines of text to run the Grok pattern on. - :param ecs_compatibility: The mode of compatibility with ECS compliant Grok patterns - (disabled or v1, default: disabled). + :param grok_pattern: The Grok pattern to run on the text. + :param text: The lines of text to run the Grok pattern on. + :param ecs_compatibility: The mode of compatibility with ECS compliant Grok patterns. + Use this parameter to specify whether to use ECS Grok patterns instead of + legacy ones when the structure finder creates a Grok pattern. Valid values + are `disabled` and `v1`. """ if grok_pattern is None and body is None: raise ValueError("Empty value passed for parameter 'grok_pattern'") diff --git a/elasticsearch/_sync/client/transform.py b/elasticsearch/_sync/client/transform.py index b10144783..7b422cf71 100644 --- a/elasticsearch/_sync/client/transform.py +++ b/elasticsearch/_sync/client/transform.py @@ -489,6 +489,7 @@ def reset_transform( force: t.Optional[bool] = None, human: t.Optional[bool] = None, pretty: t.Optional[bool] = None, + 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 @@ -503,6 +504,8 @@ def reset_transform( :param force: If this value is `true`, the transform is reset regardless of its current state. If it's `false`, the transform must be stopped before it can be reset. + :param timeout: Period to wait for a response. If no response is received before + the timeout expires, the request fails and returns an error. """ if transform_id in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'transform_id'") @@ -519,6 +522,8 @@ def reset_transform( __query["human"] = human if pretty is not None: __query["pretty"] = pretty + if timeout is not None: + __query["timeout"] = timeout __headers = {"accept": "application/json"} return self.perform_request( # type: ignore[return-value] "POST", diff --git a/elasticsearch/_sync/client/watcher.py b/elasticsearch/_sync/client/watcher.py index 9378588a8..47a00d805 100644 --- a/elasticsearch/_sync/client/watcher.py +++ b/elasticsearch/_sync/client/watcher.py @@ -42,11 +42,15 @@ def ack_watch( in the `status.actions..ack.state` structure. IMPORTANT: If the specified watch is currently being executed, this API will return an error The reason for this behavior is to prevent overwriting the watch status from a watch execution. + Acknowledging an action throttles further executions of that action until its + `ack.state` is reset to `awaits_successful_execution`. This happens when the + condition of the watch is not met (the condition evaluates to false). ``_ - :param watch_id: Watch ID - :param action_id: A comma-separated list of the action ids to be acked + :param watch_id: The watch identifier. + :param action_id: A comma-separated list of the action identifiers to acknowledge. + If you omit this parameter, all of the actions of the watch are acknowledged. """ if watch_id in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'watch_id'") @@ -96,7 +100,7 @@ def activate_watch( ``_ - :param watch_id: Watch ID + :param watch_id: The watch identifier. """ if watch_id in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'watch_id'") @@ -136,7 +140,7 @@ def deactivate_watch( ``_ - :param watch_id: Watch ID + :param watch_id: The watch identifier. """ if watch_id in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'watch_id'") @@ -182,7 +186,7 @@ def delete_watch( ``_ - :param id: Watch ID + :param id: The watch identifier. """ if id in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'id'") @@ -255,11 +259,17 @@ def execute_watch( and control whether a watch record would be written to the watch history after it runs. You can use the run watch API to run watches that are not yet registered by specifying the watch definition inline. This serves as great tool for testing - and debugging your watches prior to adding them to Watcher. + and debugging your watches prior to adding them to Watcher. When Elasticsearch + security features are enabled on your cluster, watches are run with the privileges + of the user that stored the watches. If your user is allowed to read index `a`, + but not index `b`, then the exact same set of rules will apply during execution + of a watch. When using the run watch API, the authorization data of the user + that called the API will be used as a base, instead of the information who stored + the watch. ``_ - :param id: Identifier for the watch. + :param id: The watch identifier. :param action_modes: Determines how to handle the watch actions as part of the watch execution. :param alternative_input: When present, the watch uses this object as a payload @@ -270,12 +280,12 @@ def execute_watch( :param record_execution: When set to `true`, the watch record representing the watch execution result is persisted to the `.watcher-history` index for the current time. In addition, the status of the watch is updated, possibly throttling - subsequent executions. This can also be specified as an HTTP parameter. + subsequent runs. This can also be specified as an HTTP parameter. :param simulated_actions: :param trigger_data: This structure is parsed as the data of the trigger event - that will be used during the watch execution + that will be used during the watch execution. :param watch: When present, this watch is used instead of the one specified in - the request. This watch is not persisted to the index and record_execution + the request. This watch is not persisted to the index and `record_execution` cannot be set. """ __path_parts: t.Dict[str, str] @@ -327,6 +337,50 @@ def execute_watch( path_parts=__path_parts, ) + @_rewrite_parameters() + def get_settings( + self, + *, + error_trace: t.Optional[bool] = None, + filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, + human: t.Optional[bool] = None, + master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, + pretty: t.Optional[bool] = None, + ) -> ObjectApiResponse[t.Any]: + """ + Get Watcher index settings. Get settings for the Watcher internal index (`.watches`). + Only a subset of settings are shown, for example `index.auto_expand_replicas` + and `index.number_of_replicas`. + + ``_ + + :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. + """ + __path_parts: t.Dict[str, str] = {} + __path = "/_watcher/settings" + __query: t.Dict[str, t.Any] = {} + if error_trace is not None: + __query["error_trace"] = error_trace + if filter_path is not None: + __query["filter_path"] = filter_path + if human is not None: + __query["human"] = human + if master_timeout is not None: + __query["master_timeout"] = master_timeout + if pretty is not None: + __query["pretty"] = pretty + __headers = {"accept": "application/json"} + return self.perform_request( # type: ignore[return-value] + "GET", + __path, + params=__query, + headers=__headers, + endpoint_id="watcher.get_settings", + path_parts=__path_parts, + ) + @_rewrite_parameters() def get_watch( self, @@ -342,7 +396,7 @@ def get_watch( ``_ - :param id: Watch ID + :param id: The watch identifier. """ if id in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'id'") @@ -374,6 +428,7 @@ def get_watch( "input", "metadata", "throttle_period", + "throttle_period_in_millis", "transform", "trigger", ), @@ -393,7 +448,8 @@ def put_watch( input: t.Optional[t.Mapping[str, t.Any]] = None, metadata: t.Optional[t.Mapping[str, t.Any]] = None, pretty: t.Optional[bool] = None, - throttle_period: t.Optional[str] = None, + throttle_period: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, + throttle_period_in_millis: t.Optional[t.Any] = None, transform: t.Optional[t.Mapping[str, t.Any]] = None, trigger: t.Optional[t.Mapping[str, t.Any]] = None, version: t.Optional[int] = None, @@ -414,19 +470,28 @@ def put_watch( ``_ - :param id: Watch ID - :param actions: - :param active: Specify whether the watch is in/active by default - :param condition: + :param id: The identifier for the watch. + :param actions: The list of actions that will be run if the condition matches. + :param active: The initial state of the watch. The default value is `true`, which + means the watch is active by default. + :param condition: The condition that defines if the actions should be run. :param if_primary_term: only update the watch if the last operation that has changed the watch has the specified primary term :param if_seq_no: only update the watch if the last operation that has changed the watch has the specified sequence number - :param input: - :param metadata: - :param throttle_period: - :param transform: - :param trigger: + :param input: The input that defines the input that loads the data for the watch. + :param metadata: Metadata JSON that will be copied into the history entries. + :param throttle_period: The minimum time between actions being run. The default + is 5 seconds. This default can be changed in the config file with the setting + `xpack.watcher.throttle.period.default_period`. If both this value and the + `throttle_period_in_millis` parameter are specified, Watcher uses the last + parameter included in the request. + :param throttle_period_in_millis: Minimum time in milliseconds between actions + being run. Defaults to 5000. If both this value and the throttle_period parameter + are specified, Watcher uses the last parameter included in the request. + :param transform: The transform that processes the watch payload to prepare it + for the watch actions. + :param trigger: The trigger that defines when the watch should run. :param version: Explicit version number for concurrency control """ if id in SKIP_IN_PATH: @@ -462,6 +527,8 @@ def put_watch( __body["metadata"] = metadata if throttle_period is not None: __body["throttle_period"] = throttle_period + if throttle_period_in_millis is not None: + __body["throttle_period_in_millis"] = throttle_period_in_millis if transform is not None: __body["transform"] = transform if trigger is not None: @@ -508,16 +575,17 @@ def query_watches( ) -> ObjectApiResponse[t.Any]: """ Query watches. Get all registered watches in a paginated manner and optionally - filter watches by a query. + filter watches by a query. Note that only the `_id` and `metadata.*` fields are + queryable or sortable. ``_ - :param from_: The offset from the first result to fetch. Needs to be non-negative. - :param query: Optional, query filter watches to be returned. - :param search_after: Optional search After to do pagination using last hit’s - sort values. - :param size: The number of hits to return. Needs to be non-negative. - :param sort: Optional sort definition. + :param from_: The offset from the first result to fetch. It must be non-negative. + :param query: A query that filters the watches to be returned. + :param search_after: Retrieve the next page of hits using a set of sort values + from the previous page. + :param size: The number of hits to return. It must be non-negative. + :param sort: One or more fields used to sort the search results. """ __path_parts: t.Dict[str, str] = {} __path = "/_watcher/_query/watches" @@ -575,12 +643,15 @@ def start( error_trace: t.Optional[bool] = None, filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, human: t.Optional[bool] = None, + master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ Start the watch service. Start the Watcher service if it is not already running. ``_ + + :param master_timeout: Period to wait for a connection to the master node. """ __path_parts: t.Dict[str, str] = {} __path = "/_watcher/_start" @@ -591,6 +662,8 @@ def start( __query["filter_path"] = filter_path if human is not None: __query["human"] = human + if master_timeout is not None: + __query["master_timeout"] = master_timeout if pretty is not None: __query["pretty"] = pretty __headers = {"accept": "application/json"} @@ -635,7 +708,8 @@ def stats( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Get Watcher statistics. + Get Watcher statistics. This API always returns basic metrics. You retrieve more + metrics by using the metric parameter. ``_ @@ -678,12 +752,17 @@ def stop( error_trace: t.Optional[bool] = None, filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, human: t.Optional[bool] = None, + master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ Stop the watch service. Stop the Watcher service if it is running. ``_ + + :param master_timeout: The period to wait for the master node. If the master + node is not available before the timeout expires, the request fails and returns + an error. To indicate that the request should never timeout, set it to `-1`. """ __path_parts: t.Dict[str, str] = {} __path = "/_watcher/_stop" @@ -694,6 +773,8 @@ def stop( __query["filter_path"] = filter_path if human is not None: __query["human"] = human + if master_timeout is not None: + __query["master_timeout"] = master_timeout if pretty is not None: __query["pretty"] = pretty __headers = {"accept": "application/json"} @@ -705,3 +786,70 @@ def stop( endpoint_id="watcher.stop", path_parts=__path_parts, ) + + @_rewrite_parameters( + body_fields=("index_auto_expand_replicas", "index_number_of_replicas"), + parameter_aliases={ + "index.auto_expand_replicas": "index_auto_expand_replicas", + "index.number_of_replicas": "index_number_of_replicas", + }, + ) + def update_settings( + self, + *, + error_trace: t.Optional[bool] = None, + filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, + human: t.Optional[bool] = None, + index_auto_expand_replicas: t.Optional[str] = None, + index_number_of_replicas: t.Optional[int] = None, + 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 Watcher index settings. Update settings for the Watcher internal index + (`.watches`). Only a subset of settings can be modified. This includes `index.auto_expand_replicas` + and `index.number_of_replicas`. + + ``_ + + :param index_auto_expand_replicas: + :param index_number_of_replicas: + :param master_timeout: The period to wait for a connection to the master node. + If no response is received before the timeout expires, the request fails + and returns an error. + :param timeout: The period to wait for a response. If no response is received + before the timeout expires, the request fails and returns an error. + """ + __path_parts: t.Dict[str, str] = {} + __path = "/_watcher/settings" + __query: t.Dict[str, t.Any] = {} + __body: t.Dict[str, t.Any] = body if body is not None else {} + if error_trace is not None: + __query["error_trace"] = error_trace + if filter_path is not None: + __query["filter_path"] = filter_path + if human is not None: + __query["human"] = human + if master_timeout is not None: + __query["master_timeout"] = master_timeout + if pretty is not None: + __query["pretty"] = pretty + if timeout is not None: + __query["timeout"] = timeout + if not __body: + if index_auto_expand_replicas is not None: + __body["index.auto_expand_replicas"] = index_auto_expand_replicas + if index_number_of_replicas is not None: + __body["index.number_of_replicas"] = index_number_of_replicas + __headers = {"accept": "application/json", "content-type": "application/json"} + return self.perform_request( # type: ignore[return-value] + "PUT", + __path, + params=__query, + headers=__headers, + body=__body, + endpoint_id="watcher.update_settings", + path_parts=__path_parts, + ) diff --git a/elasticsearch/_sync/client/xpack.py b/elasticsearch/_sync/client/xpack.py index 6c5073b14..0e5857580 100644 --- a/elasticsearch/_sync/client/xpack.py +++ b/elasticsearch/_sync/client/xpack.py @@ -96,9 +96,10 @@ def usage( ``_ - :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 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. To indicate that the request should never timeout, + set it to `-1`. """ __path_parts: t.Dict[str, str] = {} __path = "/_xpack/usage"