From eec8e22d391ee28ebe41e4dff9be7b4f68cba384 Mon Sep 17 00:00:00 2001 From: Elastic Machine Date: Tue, 14 Jan 2025 07:35:51 +0000 Subject: [PATCH] Auto-generated API code --- elasticsearch/_async/client/__init__.py | 4 +- elasticsearch/_async/client/cluster.py | 38 +- elasticsearch/_async/client/connector.py | 100 ++++ .../_async/client/dangling_indices.py | 6 +- elasticsearch/_async/client/ilm.py | 12 +- elasticsearch/_async/client/indices.py | 441 +++++++++++++--- elasticsearch/_async/client/ingest.py | 47 +- elasticsearch/_async/client/logstash.py | 3 +- elasticsearch/_async/client/migration.py | 8 +- elasticsearch/_async/client/ml.py | 18 +- elasticsearch/_async/client/nodes.py | 6 +- elasticsearch/_async/client/query_rules.py | 45 +- elasticsearch/_async/client/rollup.py | 42 +- .../_async/client/search_application.py | 65 +++ .../_async/client/searchable_snapshots.py | 43 +- elasticsearch/_async/client/security.py | 498 ++++++++++++++++++ elasticsearch/_async/client/shutdown.py | 40 +- elasticsearch/_async/client/simulate.py | 2 +- elasticsearch/_async/client/slm.py | 111 +++- elasticsearch/_async/client/snapshot.py | 20 +- elasticsearch/_async/client/sql.py | 112 ++-- elasticsearch/_async/client/synonyms.py | 58 +- elasticsearch/_async/client/text_structure.py | 155 ++++-- elasticsearch/_async/client/watcher.py | 201 ++++++- elasticsearch/_async/client/xpack.py | 7 +- elasticsearch/_sync/client/__init__.py | 4 +- elasticsearch/_sync/client/cluster.py | 38 +- elasticsearch/_sync/client/connector.py | 100 ++++ .../_sync/client/dangling_indices.py | 6 +- elasticsearch/_sync/client/ilm.py | 12 +- elasticsearch/_sync/client/indices.py | 441 +++++++++++++--- elasticsearch/_sync/client/ingest.py | 47 +- elasticsearch/_sync/client/logstash.py | 3 +- elasticsearch/_sync/client/migration.py | 8 +- elasticsearch/_sync/client/ml.py | 18 +- elasticsearch/_sync/client/nodes.py | 6 +- elasticsearch/_sync/client/query_rules.py | 45 +- elasticsearch/_sync/client/rollup.py | 42 +- .../_sync/client/search_application.py | 65 +++ .../_sync/client/searchable_snapshots.py | 43 +- elasticsearch/_sync/client/security.py | 498 ++++++++++++++++++ elasticsearch/_sync/client/shutdown.py | 40 +- elasticsearch/_sync/client/simulate.py | 2 +- elasticsearch/_sync/client/slm.py | 111 +++- elasticsearch/_sync/client/snapshot.py | 20 +- elasticsearch/_sync/client/sql.py | 112 ++-- elasticsearch/_sync/client/synonyms.py | 58 +- elasticsearch/_sync/client/text_structure.py | 155 ++++-- elasticsearch/_sync/client/watcher.py | 201 ++++++- elasticsearch/_sync/client/xpack.py | 7 +- 50 files changed, 3442 insertions(+), 722 deletions(-) diff --git a/elasticsearch/_async/client/__init__.py b/elasticsearch/_async/client/__init__.py index caf9c5d44..75476f710 100644 --- a/elasticsearch/_async/client/__init__.py +++ b/elasticsearch/_async/client/__init__.py @@ -2491,9 +2491,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..58831420c 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,8 +2044,6 @@ 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, omit this parameter or use `*` or `_all`. @@ -2080,6 +2167,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 +2302,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 +2380,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 +2453,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 +2538,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 +2626,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 +2807,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 +3180,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 +3236,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 +3249,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 +3370,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 +3521,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 +3647,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 +3675,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 +3737,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 +3819,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 +3991,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 +4155,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 +4552,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 +4630,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 +4764,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/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..ee9347ef8 100644 --- a/elasticsearch/_async/client/security.py +++ b/elasticsearch/_async/client/security.py @@ -244,6 +244,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 +861,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, @@ -1667,6 +1823,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", @@ -2326,6 +2525,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", ) @@ -3650,6 +4073,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"), ) 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..9274746f4 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 @@ -684,7 +684,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 +794,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 +898,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 +958,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/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..cd391eebc 100644 --- a/elasticsearch/_sync/client/__init__.py +++ b/elasticsearch/_sync/client/__init__.py @@ -2489,9 +2489,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..d530fc8f3 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,8 +2044,6 @@ 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, omit this parameter or use `*` or `_all`. @@ -2080,6 +2167,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 +2302,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 +2380,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 +2453,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 +2538,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 +2626,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 +2807,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 +3180,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 +3236,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 +3249,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 +3370,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 +3521,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 +3647,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 +3675,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 +3737,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 +3819,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 +3991,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 +4155,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 +4552,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 +4630,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 +4764,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/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..53d1b79a9 100644 --- a/elasticsearch/_sync/client/security.py +++ b/elasticsearch/_sync/client/security.py @@ -244,6 +244,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 +861,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, @@ -1667,6 +1823,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", @@ -2326,6 +2525,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", ) @@ -3650,6 +4073,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"), ) 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..f717776e9 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 @@ -684,7 +684,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 +794,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 +898,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 +958,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/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"