diff --git a/elasticsearch/_async/client/__init__.py b/elasticsearch/_async/client/__init__.py index caf9c5d44..4947a69ab 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 = "/" diff --git a/elasticsearch/_async/client/cluster.py b/elasticsearch/_async/client/cluster.py index 36cb92624..9e0dcb7ca 100644 --- a/elasticsearch/_async/client/cluster.py +++ b/elasticsearch/_async/client/cluster.py @@ -119,9 +119,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. ``_ @@ -275,7 +274,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. ``_ @@ -719,20 +718,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 +755,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 bb6262c93..e83cbaa53 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 50d67d11c..4f0fe7c82 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/ilm.py b/elasticsearch/_async/client/ilm.py index 643db3aa9..cd2a438ad 100644 --- a/elasticsearch/_async/client/ilm.py +++ b/elasticsearch/_async/client/ilm.py @@ -341,8 +341,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 +552,8 @@ async def start( ``_ - :param master_timeout: - :param timeout: + :param master_timeout: Explicit operation timeout for connection to master node + :param timeout: Explicit operation timeout """ __path_parts: t.Dict[str, str] = {} __path = "/_ilm/start" @@ -601,8 +601,8 @@ async def stop( ``_ - :param master_timeout: - :param timeout: + :param master_timeout: Explicit operation timeout for connection to master node + :param timeout: Explicit operation timeout """ __path_parts: t.Dict[str, str] = {} __path = "/_ilm/stop" diff --git a/elasticsearch/_async/client/indices.py b/elasticsearch/_async/client/indices.py index 84b8009bb..4237ff983 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. ``_ @@ -1447,16 +1500,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'") @@ -1570,7 +1628,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. ``_ @@ -1770,7 +1831,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 + ``` ``_ @@ -1863,8 +1952,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. ``_ @@ -1955,7 +2044,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, @@ -2080,6 +2169,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, @@ -2179,11 +2304,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`. @@ -2255,7 +2382,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. ``_ @@ -2328,8 +2455,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. ``_ @@ -2413,8 +2540,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. ``_ @@ -2501,7 +2628,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. ``_ @@ -2680,7 +2809,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. ``_ @@ -3033,7 +3182,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. ``_ @@ -3063,8 +3238,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 @@ -3073,7 +3251,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'") @@ -3192,9 +3372,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. ``_ @@ -3325,6 +3523,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. ``_ @@ -3438,7 +3649,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. ``_ @@ -3459,7 +3677,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'") @@ -3520,23 +3739,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. ``_ @@ -3600,7 +3821,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. ``_ @@ -3762,6 +3993,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. ``_ @@ -3908,7 +4157,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`. ``_ @@ -4279,8 +4554,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. ``_ @@ -4357,7 +4632,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. ``_ @@ -4491,25 +4766,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 501a541ce..0b124e281 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 a0972a254..d2ec37976 100644 --- a/elasticsearch/_async/client/ingest.py +++ b/elasticsearch/_async/client/ingest.py @@ -90,16 +90,18 @@ async def delete_ip_location_database( timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, ) -> ObjectApiResponse[t.Any]: """ - Deletes an IP location database configuration. + Delete IP geolocation database configurations. ``_ - :param id: A comma-separated list of IP location database configurations to delete - :param master_timeout: Period to wait for a connection to the master node. If - no response is received before the timeout expires, the request fails and - returns an error. - :param timeout: Period to wait for a response. If no response is received before - the timeout expires, the request fails and returns an error. + :param id: A comma-separated list of IP location database configurations. + :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. A value of `-1` indicates that the request should never + time out. + :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. A value + of `-1` indicates that the request should never time out. """ if id in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'id'") @@ -280,16 +282,17 @@ async def get_ip_location_database( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Returns information about one or more IP location database configurations. + Get IP geolocation database configurations. ``_ :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. + :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. A value of `-1` indicates that the request should never + time out. """ __path_parts: t.Dict[str, str] if id not in SKIP_IN_PATH: @@ -430,8 +433,8 @@ async def put_geoip_database( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Create or update GeoIP database configurations. Create or update IP geolocation - database configurations. + Create or update a GeoIP database configuration. Refer to the create or update + IP geolocation database configuration API. ``_ @@ -503,17 +506,21 @@ async def put_ip_location_database( timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, ) -> ObjectApiResponse[t.Any]: """ - Returns information about one or more IP location database configurations. + Create or update an IP geolocation database configuration. ``_ - :param id: ID of the database configuration to create or update. + :param id: The database configuration identifier. :param configuration: - :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 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. A value of `-1` indicates that the request should never + time out. + :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 indicates that it was not completely acknowledged. A value of + `-1` indicates that the request should never time out. """ if id in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'id'") diff --git a/elasticsearch/_async/client/logstash.py b/elasticsearch/_async/client/logstash.py index 046b0e037..308588e32 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 cacf1e9e1..4bf4cead0 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 7f7308aeb..b8e73ae50 100644 --- a/elasticsearch/_async/client/ml.py +++ b/elasticsearch/_async/client/ml.py @@ -2702,7 +2702,7 @@ async def info( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Return ML defaults and limits. Returns defaults and limits used by machine learning. + Get machine learning information. Get defaults and limits used by machine learning. This endpoint is designed to be used by a user interface that needs to fully understand machine learning configurations where some options are not specified, meaning that the defaults should be used. This endpoint may be used to find out @@ -3205,7 +3205,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. ``_ @@ -3382,7 +3386,8 @@ async def put_datafeed( 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 + 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 +3650,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 +5457,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. ``_ @@ -5521,7 +5527,7 @@ async def validate_detector( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Validates an anomaly detection detector. + Validate an anomaly detection job. ``_ diff --git a/elasticsearch/_async/client/nodes.py b/elasticsearch/_async/client/nodes.py index 6e9006333..99c0d62f7 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'") diff --git a/elasticsearch/_async/client/query_rules.py b/elasticsearch/_async/client/query_rules.py index 7b0d2de0b..3380840c5 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 9774cd0ed..fcf4dda78 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/search_application.py b/elasticsearch/_async/client/search_application.py index bd3928713..72e1ca23e 100644 --- a/elasticsearch/_async/client/search_application.py +++ b/elasticsearch/_async/client/search_application.py @@ -251,6 +251,71 @@ async def list( path_parts=__path_parts, ) + @_rewrite_parameters( + body_name="payload", + ) + @_stability_warning(Stability.EXPERIMENTAL) + async def post_behavioral_analytics_event( + self, + *, + collection_name: str, + event_type: t.Union[str, t.Literal["page_view", "search", "search_click"]], + payload: t.Optional[t.Any] = None, + body: t.Optional[t.Any] = None, + debug: t.Optional[bool] = None, + error_trace: t.Optional[bool] = None, + filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, + human: t.Optional[bool] = None, + pretty: t.Optional[bool] = None, + ) -> ObjectApiResponse[t.Any]: + """ + Create a behavioral analytics collection event. + + ``_ + + :param collection_name: The name of the behavioral analytics collection. + :param event_type: The analytics event type. + :param payload: + :param debug: Whether the response type has to include more details + """ + if collection_name in SKIP_IN_PATH: + raise ValueError("Empty value passed for parameter 'collection_name'") + if event_type in SKIP_IN_PATH: + raise ValueError("Empty value passed for parameter 'event_type'") + if payload is None and body is None: + raise ValueError( + "Empty value passed for parameters 'payload' and 'body', one of them should be set." + ) + elif payload is not None and body is not None: + raise ValueError("Cannot set both 'payload' and 'body'") + __path_parts: t.Dict[str, str] = { + "collection_name": _quote(collection_name), + "event_type": _quote(event_type), + } + __path = f'/_application/analytics/{__path_parts["collection_name"]}/event/{__path_parts["event_type"]}' + __query: t.Dict[str, t.Any] = {} + if debug is not None: + __query["debug"] = debug + if error_trace is not None: + __query["error_trace"] = error_trace + if filter_path is not None: + __query["filter_path"] = filter_path + if human is not None: + __query["human"] = human + if pretty is not None: + __query["pretty"] = pretty + __body = payload if payload is not None else body + __headers = {"accept": "application/json", "content-type": "application/json"} + return await self.perform_request( # type: ignore[return-value] + "POST", + __path, + params=__query, + headers=__headers, + body=__body, + endpoint_id="search_application.post_behavioral_analytics_event", + path_parts=__path_parts, + ) + @_rewrite_parameters( body_name="search_application", ) diff --git a/elasticsearch/_async/client/searchable_snapshots.py b/elasticsearch/_async/client/searchable_snapshots.py index 029fba754..ac3975751 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 8242ff57e..57fafd1b2 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'") @@ -1667,6 +1855,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", @@ -1860,15 +2091,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'") @@ -2140,11 +2375,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. """ @@ -2326,6 +2565,230 @@ async def invalidate_token( path_parts=__path_parts, ) + @_rewrite_parameters( + body_fields=("nonce", "redirect_uri", "state", "realm"), + ) + async def oidc_authenticate( + self, + *, + nonce: t.Optional[str] = None, + redirect_uri: t.Optional[str] = None, + state: t.Optional[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, + realm: t.Optional[str] = None, + body: t.Optional[t.Dict[str, t.Any]] = None, + ) -> ObjectApiResponse[t.Any]: + """ + Authenticate OpenID Connect. Exchange an OpenID Connect authentication response + message for an Elasticsearch internal access token and refresh token that can + be subsequently used for authentication. Elasticsearch exposes all the necessary + OpenID Connect related functionality with the OpenID Connect APIs. These APIs + are used internally by Kibana in order to provide OpenID Connect based authentication, + but can also be used by other, custom web applications or other clients. + + ``_ + + :param nonce: Associate a client session with an ID token and mitigate replay + attacks. This value needs to be the same as the one that was provided to + the `/_security/oidc/prepare` API or the one that was generated by Elasticsearch + and included in the response to that call. + :param redirect_uri: The URL to which the OpenID Connect Provider redirected + the User Agent in response to an authentication request after a successful + authentication. This URL must be provided as-is (URL encoded), taken from + the body of the response or as the value of a location header in the response + from the OpenID Connect Provider. + :param state: Maintain state between the authentication request and the response. + This value needs to be the same as the one that was provided to the `/_security/oidc/prepare` + API or the one that was generated by Elasticsearch and included in the response + to that call. + :param realm: The name of the OpenID Connect realm. This property is useful in + cases where multiple realms are defined. + """ + if nonce is None and body is None: + raise ValueError("Empty value passed for parameter 'nonce'") + if redirect_uri is None and body is None: + raise ValueError("Empty value passed for parameter 'redirect_uri'") + if state is None and body is None: + raise ValueError("Empty value passed for parameter 'state'") + __path_parts: t.Dict[str, str] = {} + __path = "/_security/oidc/authenticate" + __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 nonce is not None: + __body["nonce"] = nonce + if redirect_uri is not None: + __body["redirect_uri"] = redirect_uri + if state is not None: + __body["state"] = state + if realm is not None: + __body["realm"] = realm + __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.oidc_authenticate", + path_parts=__path_parts, + ) + + @_rewrite_parameters( + body_fields=("access_token", "refresh_token"), + ) + async def oidc_logout( + self, + *, + access_token: t.Optional[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, + refresh_token: t.Optional[str] = None, + body: t.Optional[t.Dict[str, t.Any]] = None, + ) -> ObjectApiResponse[t.Any]: + """ + Logout of OpenID Connect. Invalidate an access token and a refresh token that + were generated as a response to the `/_security/oidc/authenticate` API. If the + OpenID Connect authentication realm in Elasticsearch is accordingly configured, + the response to this call will contain a URI pointing to the end session endpoint + of the OpenID Connect Provider in order to perform single logout. Elasticsearch + exposes all the necessary OpenID Connect related functionality with the OpenID + Connect APIs. These APIs are used internally by Kibana in order to provide OpenID + Connect based authentication, but can also be used by other, custom web applications + or other clients. + + ``_ + + :param access_token: The access token to be invalidated. + :param refresh_token: The refresh token to be invalidated. + """ + if access_token is None and body is None: + raise ValueError("Empty value passed for parameter 'access_token'") + __path_parts: t.Dict[str, str] = {} + __path = "/_security/oidc/logout" + __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 access_token is not None: + __body["access_token"] = access_token + if refresh_token is not None: + __body["refresh_token"] = refresh_token + __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.oidc_logout", + path_parts=__path_parts, + ) + + @_rewrite_parameters( + body_fields=("iss", "login_hint", "nonce", "realm", "state"), + ) + async def oidc_prepare_authentication( + self, + *, + error_trace: t.Optional[bool] = None, + filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, + human: t.Optional[bool] = None, + iss: t.Optional[str] = None, + login_hint: t.Optional[str] = None, + nonce: t.Optional[str] = None, + pretty: t.Optional[bool] = None, + realm: t.Optional[str] = None, + state: t.Optional[str] = None, + body: t.Optional[t.Dict[str, t.Any]] = None, + ) -> ObjectApiResponse[t.Any]: + """ + Prepare OpenID connect authentication. Create an oAuth 2.0 authentication request + as a URL string based on the configuration of the OpenID Connect authentication + realm in Elasticsearch. The response of this API is a URL pointing to the Authorization + Endpoint of the configured OpenID Connect Provider, which can be used to redirect + the browser of the user in order to continue the authentication process. Elasticsearch + exposes all the necessary OpenID Connect related functionality with the OpenID + Connect APIs. These APIs are used internally by Kibana in order to provide OpenID + Connect based authentication, but can also be used by other, custom web applications + or other clients. + + ``_ + + :param iss: In the case of a third party initiated single sign on, this is the + issuer identifier for the OP that the RP is to send the authentication request + to. It cannot be specified when *realm* is specified. One of *realm* or *iss* + is required. + :param login_hint: In the case of a third party initiated single sign on, it + is a string value that is included in the authentication request as the *login_hint* + parameter. This parameter is not valid when *realm* is specified. + :param nonce: The value used to associate a client session with an ID token and + to mitigate replay attacks. If the caller of the API does not provide a value, + Elasticsearch will generate one with sufficient entropy and return it in + the response. + :param realm: The name of the OpenID Connect realm in Elasticsearch the configuration + of which should be used in order to generate the authentication request. + It cannot be specified when *iss* is specified. One of *realm* or *iss* is + required. + :param state: The value used to maintain state between the authentication request + and the response, typically used as a Cross-Site Request Forgery mitigation. + If the caller of the API does not provide a value, Elasticsearch will generate + one with sufficient entropy and return it in the response. + """ + __path_parts: t.Dict[str, str] = {} + __path = "/_security/oidc/prepare" + __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 iss is not None: + __body["iss"] = iss + if login_hint is not None: + __body["login_hint"] = login_hint + if nonce is not None: + __body["nonce"] = nonce + if realm is not None: + __body["realm"] = realm + if state is not None: + __body["state"] = state + __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.oidc_prepare_authentication", + path_parts=__path_parts, + ) + @_rewrite_parameters( body_name="privileges", ) @@ -3088,13 +3551,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. @@ -3151,10 +3626,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. @@ -3216,25 +3700,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'") @@ -3284,12 +3776,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. @@ -3340,19 +3839,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] = {} @@ -3397,7 +3908,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. ``_ @@ -3444,21 +3958,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" @@ -3600,7 +4120,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. ``_ @@ -3609,8 +4140,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 @@ -3650,6 +4181,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"), ) @@ -3672,22 +4278,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..d62605917 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 @@ -111,7 +111,7 @@ 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 @@ -178,19 +178,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 +215,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/simulate.py b/elasticsearch/_async/client/simulate.py index c4beb9dda..6c40ff3c7 100644 --- a/elasticsearch/_async/client/simulate.py +++ b/elasticsearch/_async/client/simulate.py @@ -87,7 +87,7 @@ async def ingest( This can be used to replace existing pipeline definitions or to create new ones. The pipeline substitutions are used only within this request. - ``_ + ``_ :param docs: Sample documents to test in the pipeline. :param index: The index to simulate ingesting into. This value can be overridden diff --git a/elasticsearch/_async/client/slm.py b/elasticsearch/_async/client/slm.py index 1164a6006..1870a9de5 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 adf46e3b4..d644eabcf 100644 --- a/elasticsearch/_async/client/snapshot.py +++ b/elasticsearch/_async/client/snapshot.py @@ -102,7 +102,7 @@ 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 @@ -185,7 +185,7 @@ 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. @@ -353,7 +353,7 @@ async def delete( """ Delete snapshots. - ``_ + ``_ :param repository: A repository name :param snapshot: A comma-separated list of snapshot names @@ -406,7 +406,7 @@ 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. @@ -480,7 +480,7 @@ async def get( """ Get snapshot information. - ``_ + ``_ :param repository: Comma-separated list of snapshot repository names used to limit the request. Wildcard (*) expressions are supported. @@ -592,7 +592,7 @@ 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 @@ -629,6 +629,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( @@ -684,7 +903,7 @@ async def repository_verify_integrity( 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 @@ -794,7 +1013,7 @@ 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 @@ -898,7 +1117,7 @@ async def status( 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 @@ -958,7 +1177,7 @@ 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 diff --git a/elasticsearch/_async/client/sql.py b/elasticsearch/_async/client/sql.py index a18926827..2a93a5837 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 3ebdd183a..e6fe303fc 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 b65a15997..fa589affb 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. """ @@ -176,25 +183,48 @@ 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 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 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. """ diff --git a/elasticsearch/_async/client/text_structure.py b/elasticsearch/_async/client/text_structure.py index a0d126037..f06f0940a 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/watcher.py b/elasticsearch/_async/client/watcher.py index be0da66f6..26be17552 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" @@ -635,7 +703,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 +747,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 +768,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 +781,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 f449b4cc4..090aca019 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 fbd71769d..347643eb3 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 = "/" diff --git a/elasticsearch/_sync/client/cluster.py b/elasticsearch/_sync/client/cluster.py index d52b243bc..9989e889e 100644 --- a/elasticsearch/_sync/client/cluster.py +++ b/elasticsearch/_sync/client/cluster.py @@ -119,9 +119,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. ``_ @@ -275,7 +274,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. ``_ @@ -719,20 +718,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 +755,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 6a1ee9752..7b334ab01 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 a41daf50c..9e0ab3870 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/ilm.py b/elasticsearch/_sync/client/ilm.py index 2c846c6d4..28e41c891 100644 --- a/elasticsearch/_sync/client/ilm.py +++ b/elasticsearch/_sync/client/ilm.py @@ -341,8 +341,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 +552,8 @@ def start( ``_ - :param master_timeout: - :param timeout: + :param master_timeout: Explicit operation timeout for connection to master node + :param timeout: Explicit operation timeout """ __path_parts: t.Dict[str, str] = {} __path = "/_ilm/start" @@ -601,8 +601,8 @@ def stop( ``_ - :param master_timeout: - :param timeout: + :param master_timeout: Explicit operation timeout for connection to master node + :param timeout: Explicit operation timeout """ __path_parts: t.Dict[str, str] = {} __path = "/_ilm/stop" diff --git a/elasticsearch/_sync/client/indices.py b/elasticsearch/_sync/client/indices.py index 30c8644d0..c379acc2c 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. ``_ @@ -1447,16 +1500,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'") @@ -1570,7 +1628,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. ``_ @@ -1770,7 +1831,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 + ``` ``_ @@ -1863,8 +1952,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. ``_ @@ -1955,7 +2044,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, @@ -2080,6 +2169,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, @@ -2179,11 +2304,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`. @@ -2255,7 +2382,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. ``_ @@ -2328,8 +2455,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. ``_ @@ -2413,8 +2540,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. ``_ @@ -2501,7 +2628,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. ``_ @@ -2680,7 +2809,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. ``_ @@ -3033,7 +3182,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. ``_ @@ -3063,8 +3238,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 @@ -3073,7 +3251,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'") @@ -3192,9 +3372,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. ``_ @@ -3325,6 +3523,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. ``_ @@ -3438,7 +3649,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. ``_ @@ -3459,7 +3677,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'") @@ -3520,23 +3739,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. ``_ @@ -3600,7 +3821,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. ``_ @@ -3762,6 +3993,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. ``_ @@ -3908,7 +4157,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`. ``_ @@ -4279,8 +4554,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. ``_ @@ -4357,7 +4632,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. ``_ @@ -4491,25 +4766,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 2cb5707f1..553789086 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 ae785811d..f47ad1c84 100644 --- a/elasticsearch/_sync/client/ingest.py +++ b/elasticsearch/_sync/client/ingest.py @@ -90,16 +90,18 @@ def delete_ip_location_database( timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, ) -> ObjectApiResponse[t.Any]: """ - Deletes an IP location database configuration. + Delete IP geolocation database configurations. ``_ - :param id: A comma-separated list of IP location database configurations to delete - :param master_timeout: Period to wait for a connection to the master node. If - no response is received before the timeout expires, the request fails and - returns an error. - :param timeout: Period to wait for a response. If no response is received before - the timeout expires, the request fails and returns an error. + :param id: A comma-separated list of IP location database configurations. + :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. A value of `-1` indicates that the request should never + time out. + :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. A value + of `-1` indicates that the request should never time out. """ if id in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'id'") @@ -280,16 +282,17 @@ def get_ip_location_database( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Returns information about one or more IP location database configurations. + Get IP geolocation database configurations. ``_ :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. + :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. A value of `-1` indicates that the request should never + time out. """ __path_parts: t.Dict[str, str] if id not in SKIP_IN_PATH: @@ -430,8 +433,8 @@ def put_geoip_database( body: t.Optional[t.Dict[str, t.Any]] = None, ) -> ObjectApiResponse[t.Any]: """ - Create or update GeoIP database configurations. Create or update IP geolocation - database configurations. + Create or update a GeoIP database configuration. Refer to the create or update + IP geolocation database configuration API. ``_ @@ -503,17 +506,21 @@ def put_ip_location_database( timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None, ) -> ObjectApiResponse[t.Any]: """ - Returns information about one or more IP location database configurations. + Create or update an IP geolocation database configuration. ``_ - :param id: ID of the database configuration to create or update. + :param id: The database configuration identifier. :param configuration: - :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 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. A value of `-1` indicates that the request should never + time out. + :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 indicates that it was not completely acknowledged. A value of + `-1` indicates that the request should never time out. """ if id in SKIP_IN_PATH: raise ValueError("Empty value passed for parameter 'id'") diff --git a/elasticsearch/_sync/client/logstash.py b/elasticsearch/_sync/client/logstash.py index 6e0878941..7bd02551f 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 74cffaaa9..a1d3160c5 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 addf8e994..b80edd0c6 100644 --- a/elasticsearch/_sync/client/ml.py +++ b/elasticsearch/_sync/client/ml.py @@ -2702,7 +2702,7 @@ def info( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Return ML defaults and limits. Returns defaults and limits used by machine learning. + Get machine learning information. Get defaults and limits used by machine learning. This endpoint is designed to be used by a user interface that needs to fully understand machine learning configurations where some options are not specified, meaning that the defaults should be used. This endpoint may be used to find out @@ -3205,7 +3205,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. ``_ @@ -3382,7 +3386,8 @@ def put_datafeed( 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 + 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 +3650,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 +5457,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. ``_ @@ -5521,7 +5527,7 @@ def validate_detector( pretty: t.Optional[bool] = None, ) -> ObjectApiResponse[t.Any]: """ - Validates an anomaly detection detector. + Validate an anomaly detection job. ``_ diff --git a/elasticsearch/_sync/client/nodes.py b/elasticsearch/_sync/client/nodes.py index 61f2d54c3..e3c467ade 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'") diff --git a/elasticsearch/_sync/client/query_rules.py b/elasticsearch/_sync/client/query_rules.py index 0fa60244c..147642436 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 fa4d54c0c..3baa6c10c 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/search_application.py b/elasticsearch/_sync/client/search_application.py index 97b36b582..64858faae 100644 --- a/elasticsearch/_sync/client/search_application.py +++ b/elasticsearch/_sync/client/search_application.py @@ -251,6 +251,71 @@ def list( path_parts=__path_parts, ) + @_rewrite_parameters( + body_name="payload", + ) + @_stability_warning(Stability.EXPERIMENTAL) + def post_behavioral_analytics_event( + self, + *, + collection_name: str, + event_type: t.Union[str, t.Literal["page_view", "search", "search_click"]], + payload: t.Optional[t.Any] = None, + body: t.Optional[t.Any] = None, + debug: t.Optional[bool] = None, + error_trace: t.Optional[bool] = None, + filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, + human: t.Optional[bool] = None, + pretty: t.Optional[bool] = None, + ) -> ObjectApiResponse[t.Any]: + """ + Create a behavioral analytics collection event. + + ``_ + + :param collection_name: The name of the behavioral analytics collection. + :param event_type: The analytics event type. + :param payload: + :param debug: Whether the response type has to include more details + """ + if collection_name in SKIP_IN_PATH: + raise ValueError("Empty value passed for parameter 'collection_name'") + if event_type in SKIP_IN_PATH: + raise ValueError("Empty value passed for parameter 'event_type'") + if payload is None and body is None: + raise ValueError( + "Empty value passed for parameters 'payload' and 'body', one of them should be set." + ) + elif payload is not None and body is not None: + raise ValueError("Cannot set both 'payload' and 'body'") + __path_parts: t.Dict[str, str] = { + "collection_name": _quote(collection_name), + "event_type": _quote(event_type), + } + __path = f'/_application/analytics/{__path_parts["collection_name"]}/event/{__path_parts["event_type"]}' + __query: t.Dict[str, t.Any] = {} + if debug is not None: + __query["debug"] = debug + if error_trace is not None: + __query["error_trace"] = error_trace + if filter_path is not None: + __query["filter_path"] = filter_path + if human is not None: + __query["human"] = human + if pretty is not None: + __query["pretty"] = pretty + __body = payload if payload is not None else body + __headers = {"accept": "application/json", "content-type": "application/json"} + return self.perform_request( # type: ignore[return-value] + "POST", + __path, + params=__query, + headers=__headers, + body=__body, + endpoint_id="search_application.post_behavioral_analytics_event", + path_parts=__path_parts, + ) + @_rewrite_parameters( body_name="search_application", ) diff --git a/elasticsearch/_sync/client/searchable_snapshots.py b/elasticsearch/_sync/client/searchable_snapshots.py index 7793f48a1..63c1d4fda 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 c8f986ab2..d69e0d2d6 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'") @@ -1667,6 +1855,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", @@ -1860,15 +2091,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'") @@ -2140,11 +2375,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. """ @@ -2326,6 +2565,230 @@ def invalidate_token( path_parts=__path_parts, ) + @_rewrite_parameters( + body_fields=("nonce", "redirect_uri", "state", "realm"), + ) + def oidc_authenticate( + self, + *, + nonce: t.Optional[str] = None, + redirect_uri: t.Optional[str] = None, + state: t.Optional[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, + realm: t.Optional[str] = None, + body: t.Optional[t.Dict[str, t.Any]] = None, + ) -> ObjectApiResponse[t.Any]: + """ + Authenticate OpenID Connect. Exchange an OpenID Connect authentication response + message for an Elasticsearch internal access token and refresh token that can + be subsequently used for authentication. Elasticsearch exposes all the necessary + OpenID Connect related functionality with the OpenID Connect APIs. These APIs + are used internally by Kibana in order to provide OpenID Connect based authentication, + but can also be used by other, custom web applications or other clients. + + ``_ + + :param nonce: Associate a client session with an ID token and mitigate replay + attacks. This value needs to be the same as the one that was provided to + the `/_security/oidc/prepare` API or the one that was generated by Elasticsearch + and included in the response to that call. + :param redirect_uri: The URL to which the OpenID Connect Provider redirected + the User Agent in response to an authentication request after a successful + authentication. This URL must be provided as-is (URL encoded), taken from + the body of the response or as the value of a location header in the response + from the OpenID Connect Provider. + :param state: Maintain state between the authentication request and the response. + This value needs to be the same as the one that was provided to the `/_security/oidc/prepare` + API or the one that was generated by Elasticsearch and included in the response + to that call. + :param realm: The name of the OpenID Connect realm. This property is useful in + cases where multiple realms are defined. + """ + if nonce is None and body is None: + raise ValueError("Empty value passed for parameter 'nonce'") + if redirect_uri is None and body is None: + raise ValueError("Empty value passed for parameter 'redirect_uri'") + if state is None and body is None: + raise ValueError("Empty value passed for parameter 'state'") + __path_parts: t.Dict[str, str] = {} + __path = "/_security/oidc/authenticate" + __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 nonce is not None: + __body["nonce"] = nonce + if redirect_uri is not None: + __body["redirect_uri"] = redirect_uri + if state is not None: + __body["state"] = state + if realm is not None: + __body["realm"] = realm + __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.oidc_authenticate", + path_parts=__path_parts, + ) + + @_rewrite_parameters( + body_fields=("access_token", "refresh_token"), + ) + def oidc_logout( + self, + *, + access_token: t.Optional[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, + refresh_token: t.Optional[str] = None, + body: t.Optional[t.Dict[str, t.Any]] = None, + ) -> ObjectApiResponse[t.Any]: + """ + Logout of OpenID Connect. Invalidate an access token and a refresh token that + were generated as a response to the `/_security/oidc/authenticate` API. If the + OpenID Connect authentication realm in Elasticsearch is accordingly configured, + the response to this call will contain a URI pointing to the end session endpoint + of the OpenID Connect Provider in order to perform single logout. Elasticsearch + exposes all the necessary OpenID Connect related functionality with the OpenID + Connect APIs. These APIs are used internally by Kibana in order to provide OpenID + Connect based authentication, but can also be used by other, custom web applications + or other clients. + + ``_ + + :param access_token: The access token to be invalidated. + :param refresh_token: The refresh token to be invalidated. + """ + if access_token is None and body is None: + raise ValueError("Empty value passed for parameter 'access_token'") + __path_parts: t.Dict[str, str] = {} + __path = "/_security/oidc/logout" + __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 access_token is not None: + __body["access_token"] = access_token + if refresh_token is not None: + __body["refresh_token"] = refresh_token + __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.oidc_logout", + path_parts=__path_parts, + ) + + @_rewrite_parameters( + body_fields=("iss", "login_hint", "nonce", "realm", "state"), + ) + def oidc_prepare_authentication( + self, + *, + error_trace: t.Optional[bool] = None, + filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None, + human: t.Optional[bool] = None, + iss: t.Optional[str] = None, + login_hint: t.Optional[str] = None, + nonce: t.Optional[str] = None, + pretty: t.Optional[bool] = None, + realm: t.Optional[str] = None, + state: t.Optional[str] = None, + body: t.Optional[t.Dict[str, t.Any]] = None, + ) -> ObjectApiResponse[t.Any]: + """ + Prepare OpenID connect authentication. Create an oAuth 2.0 authentication request + as a URL string based on the configuration of the OpenID Connect authentication + realm in Elasticsearch. The response of this API is a URL pointing to the Authorization + Endpoint of the configured OpenID Connect Provider, which can be used to redirect + the browser of the user in order to continue the authentication process. Elasticsearch + exposes all the necessary OpenID Connect related functionality with the OpenID + Connect APIs. These APIs are used internally by Kibana in order to provide OpenID + Connect based authentication, but can also be used by other, custom web applications + or other clients. + + ``_ + + :param iss: In the case of a third party initiated single sign on, this is the + issuer identifier for the OP that the RP is to send the authentication request + to. It cannot be specified when *realm* is specified. One of *realm* or *iss* + is required. + :param login_hint: In the case of a third party initiated single sign on, it + is a string value that is included in the authentication request as the *login_hint* + parameter. This parameter is not valid when *realm* is specified. + :param nonce: The value used to associate a client session with an ID token and + to mitigate replay attacks. If the caller of the API does not provide a value, + Elasticsearch will generate one with sufficient entropy and return it in + the response. + :param realm: The name of the OpenID Connect realm in Elasticsearch the configuration + of which should be used in order to generate the authentication request. + It cannot be specified when *iss* is specified. One of *realm* or *iss* is + required. + :param state: The value used to maintain state between the authentication request + and the response, typically used as a Cross-Site Request Forgery mitigation. + If the caller of the API does not provide a value, Elasticsearch will generate + one with sufficient entropy and return it in the response. + """ + __path_parts: t.Dict[str, str] = {} + __path = "/_security/oidc/prepare" + __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 iss is not None: + __body["iss"] = iss + if login_hint is not None: + __body["login_hint"] = login_hint + if nonce is not None: + __body["nonce"] = nonce + if realm is not None: + __body["realm"] = realm + if state is not None: + __body["state"] = state + __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.oidc_prepare_authentication", + path_parts=__path_parts, + ) + @_rewrite_parameters( body_name="privileges", ) @@ -3088,13 +3551,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. @@ -3151,10 +3626,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. @@ -3216,25 +3700,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'") @@ -3284,12 +3776,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. @@ -3340,19 +3839,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] = {} @@ -3397,7 +3908,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. ``_ @@ -3444,21 +3958,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" @@ -3600,7 +4120,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. ``_ @@ -3609,8 +4140,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 @@ -3650,6 +4181,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"), ) @@ -3672,22 +4278,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..be6c38d55 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 @@ -111,7 +111,7 @@ 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 @@ -178,19 +178,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 +215,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/simulate.py b/elasticsearch/_sync/client/simulate.py index ac1f7cc90..0139e229f 100644 --- a/elasticsearch/_sync/client/simulate.py +++ b/elasticsearch/_sync/client/simulate.py @@ -87,7 +87,7 @@ def ingest( This can be used to replace existing pipeline definitions or to create new ones. The pipeline substitutions are used only within this request. - ``_ + ``_ :param docs: Sample documents to test in the pipeline. :param index: The index to simulate ingesting into. This value can be overridden diff --git a/elasticsearch/_sync/client/slm.py b/elasticsearch/_sync/client/slm.py index 92bc47fe9..ff7c59c8d 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 b628ad6a8..ed74387ba 100644 --- a/elasticsearch/_sync/client/snapshot.py +++ b/elasticsearch/_sync/client/snapshot.py @@ -102,7 +102,7 @@ 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 @@ -185,7 +185,7 @@ 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. @@ -353,7 +353,7 @@ def delete( """ Delete snapshots. - ``_ + ``_ :param repository: A repository name :param snapshot: A comma-separated list of snapshot names @@ -406,7 +406,7 @@ 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. @@ -480,7 +480,7 @@ def get( """ Get snapshot information. - ``_ + ``_ :param repository: Comma-separated list of snapshot repository names used to limit the request. Wildcard (*) expressions are supported. @@ -592,7 +592,7 @@ 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 @@ -629,6 +629,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( @@ -684,7 +903,7 @@ def repository_verify_integrity( 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 @@ -794,7 +1013,7 @@ 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 @@ -898,7 +1117,7 @@ def status( 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 @@ -958,7 +1177,7 @@ 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 diff --git a/elasticsearch/_sync/client/sql.py b/elasticsearch/_sync/client/sql.py index c82e66662..d56edbd03 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 3679e223f..92639b50c 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 22fd53d80..6eb303050 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. """ @@ -176,25 +183,48 @@ 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 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 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. """ diff --git a/elasticsearch/_sync/client/text_structure.py b/elasticsearch/_sync/client/text_structure.py index 32b536a0b..2acc56893 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/watcher.py b/elasticsearch/_sync/client/watcher.py index 89fb4b9b0..a3f5e3933 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" @@ -635,7 +703,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 +747,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 +768,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 +781,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 4d0ea7bda..a2f26ab91 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"