From 6063bac72977ca0f6b20a09f366894a781b7a647 Mon Sep 17 00:00:00 2001 From: Elastic Machine Date: Mon, 1 Sep 2025 06:03:36 +0000 Subject: [PATCH] Auto-generated API code --- docs/reference.asciidoc | 283 +++++++++++++++++++++++++++--------- src/api/api/indices.ts | 2 +- src/api/api/snapshot.ts | 12 +- src/api/types.ts | 57 +++++--- src/api/typesWithBodyKey.ts | 57 +++++--- 5 files changed, 292 insertions(+), 119 deletions(-) diff --git a/docs/reference.asciidoc b/docs/reference.asciidoc index 9f759f79a..5ed0d93cb 100644 --- a/docs/reference.asciidoc +++ b/docs/reference.asciidoc @@ -7629,7 +7629,7 @@ For example, a request targeting `foo*,bar*` returns an error if an index starts [discrete] ==== rollover Roll over to a new index. -TIP: It is recommended to use the index lifecycle rollover action to automate rollovers. +TIP: We recommend using the index lifecycle rollover action to automate rollovers. However, Serverless does not support Index Lifecycle Management (ILM), so don't use this approach in the Serverless context. The rollover API creates a new index for a data stream or index alias. The API behavior depends on the rollover target. @@ -14706,9 +14706,13 @@ client.snapshot.cleanupRepository({ repository }) ==== Arguments * *Request (object):* -** *`repository` (string)*: Snapshot repository to clean up. -** *`master_timeout` (Optional, string | -1 | 0)*: Period to wait for a connection to the master node. -** *`timeout` (Optional, string | -1 | 0)*: Period to wait for a response. +** *`repository` (string)*: The name of the snapshot repository to clean up. +** *`master_timeout` (Optional, string | -1 | 0)*: The period to wait for a connection to the master node. +If the master node is not available before the timeout expires, the request fails and returns an error. +To indicate that the request should never timeout, set it to `-1` +** *`timeout` (Optional, string | -1 | 0)*: The period to wait for a response from all relevant nodes in the cluster after updating the cluster metadata. +If no response is received before the timeout expires, the cluster metadata update still applies but the response will indicate that it was not completely acknowledged. +To indicate that the request should never timeout, set it to `-1`. [discrete] ==== clone @@ -14725,11 +14729,14 @@ client.snapshot.clone({ repository, snapshot, target_snapshot, indices }) ==== Arguments * *Request (object):* -** *`repository` (string)*: A repository name -** *`snapshot` (string)*: The name of the snapshot to clone from -** *`target_snapshot` (string)*: The name of the cloned snapshot to create -** *`indices` (string)* -** *`master_timeout` (Optional, string | -1 | 0)*: Explicit operation timeout for connection to master node +** *`repository` (string)*: The name of the snapshot repository that both source and target snapshot belong to. +** *`snapshot` (string)*: The source snapshot name. +** *`target_snapshot` (string)*: The target snapshot name. +** *`indices` (string)*: A list of indices to include in the snapshot. +Multi-target syntax is supported. +** *`master_timeout` (Optional, string | -1 | 0)*: 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`. [discrete] ==== create @@ -14746,16 +14753,45 @@ client.snapshot.create({ repository, snapshot }) ==== Arguments * *Request (object):* -** *`repository` (string)*: Repository for the snapshot. -** *`snapshot` (string)*: Name of the snapshot. Must be unique in the repository. -** *`ignore_unavailable` (Optional, boolean)*: If `true`, the request ignores data streams and indices in `indices` that are missing or closed. If `false`, the request returns an error for any data stream or index that is missing or closed. -** *`include_global_state` (Optional, boolean)*: If `true`, the current cluster state is included in the snapshot. The cluster state includes persistent cluster settings, composable index templates, legacy index templates, ingest pipelines, and ILM policies. It also includes data stored in system indices, such as Watches and task records (configurable via `feature_states`). -** *`indices` (Optional, string | string[])*: Data streams and indices to include in the snapshot. Supports multi-target syntax. Includes all data streams and indices by default. -** *`feature_states` (Optional, string[])*: Feature states to include in the snapshot. Each feature state includes one or more system indices containing related data. You can view a list of eligible features using the get features API. If `include_global_state` is `true`, all current feature states are included by default. If `include_global_state` is `false`, no feature states are included by default. -** *`metadata` (Optional, Record)*: Optional metadata for the snapshot. May have any contents. Must be less than 1024 bytes. This map is not automatically generated by Elasticsearch. -** *`partial` (Optional, boolean)*: If `true`, allows restoring a partial snapshot of indices with unavailable shards. Only shards that were successfully included in the snapshot will be restored. All missing shards will be recreated as empty. If `false`, the entire restore operation will fail if one or more indices included in the snapshot do not have all primary shards available. -** *`master_timeout` (Optional, string | -1 | 0)*: 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. -** *`wait_for_completion` (Optional, boolean)*: If `true`, the request returns a response when the snapshot is complete. If `false`, the request returns a response when the snapshot initializes. +** *`repository` (string)*: The name of the repository for the snapshot. +** *`snapshot` (string)*: The name of the snapshot. +It supportes date math. +It must be unique in the repository. +** *`expand_wildcards` (Optional, Enum("all" | "open" | "closed" | "hidden" | "none") | Enum("all" | "open" | "closed" | "hidden" | "none")[])*: Determines how wildcard patterns in the `indices` parameter match data streams and indices. +It supports a list of values such as `open,hidden`. +** *`feature_states` (Optional, string[])*: The feature states to include in the snapshot. +Each feature state includes one or more system indices containing related data. +You can view a list of eligible features using the get features API. + +If `include_global_state` is `true`, all current feature states are included by default. +If `include_global_state` is `false`, no feature states are included by default. + +Note that specifying an empty array will result in the default behavior. +To exclude all feature states, regardless of the `include_global_state` value, specify an array with only the value `none` (`["none"]`). +** *`ignore_unavailable` (Optional, boolean)*: If `true`, the request ignores data streams and indices in `indices` that are missing or closed. +If `false`, the request returns an error for any data stream or index that is missing or closed. +** *`include_global_state` (Optional, boolean)*: If `true`, the current cluster state is included in the snapshot. +The cluster state includes persistent cluster settings, composable index templates, legacy index templates, ingest pipelines, and ILM policies. +It also includes data stored in system indices, such as Watches and task records (configurable via `feature_states`). +** *`indices` (Optional, string | string[])*: A list of data streams and indices to include in the snapshot. +It supports a multi-target syntax. +The default is an empty array (`[]`), which includes all regular data streams and regular indices. +To exclude all data streams and indices, use `-*`. + +You can't use this parameter to include or exclude system indices or system data streams from a snapshot. +Use `feature_states` instead. +** *`metadata` (Optional, Record)*: Arbitrary metadata to the snapshot, such as a record of who took the snapshot, why it was taken, or any other useful data. +It can have any contents but it must be less than 1024 bytes. +This information is not automatically generated by Elasticsearch. +** *`partial` (Optional, boolean)*: If `true`, it enables you to restore a partial snapshot of indices with unavailable shards. +Only shards that were successfully included in the snapshot will be restored. +All missing shards will be recreated as empty. + +If `false`, the entire restore operation will fail if one or more indices included in the snapshot do not have all primary shards available. +** *`master_timeout` (Optional, string | -1 | 0)*: 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. +** *`wait_for_completion` (Optional, boolean)*: If `true`, the request returns a response when the snapshot is complete. +If `false`, the request returns a response when the snapshot initializes. [discrete] ==== create_repository @@ -14764,7 +14800,10 @@ IMPORTANT: If you are migrating searchable snapshots, the repository name must b To register a snapshot repository, the cluster's global metadata must be writeable. Ensure there are no cluster blocks (for example, `cluster.blocks.read_only` and `clsuter.blocks.read_only_allow_delete` settings) that prevent write access. -{ref}/modules-snapshots.html[Endpoint documentation] +Several options for this API can be specified using a query parameter or a request body parameter. +If both parameters are specified, only the query parameter is used. + +{ref}/put-snapshot-repo-api.html[Endpoint documentation] [source,ts] ---- client.snapshot.createRepository({ repository }) @@ -14774,10 +14813,16 @@ client.snapshot.createRepository({ repository }) ==== Arguments * *Request (object):* -** *`repository` (string)*: A repository name -** *`master_timeout` (Optional, string | -1 | 0)*: Explicit operation timeout for connection to master node -** *`timeout` (Optional, string | -1 | 0)*: Explicit operation timeout -** *`verify` (Optional, boolean)*: Whether to verify the repository after creation +** *`repository` (string)*: The name of the snapshot repository to register or update. +** *`master_timeout` (Optional, string | -1 | 0)*: 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`. +** *`timeout` (Optional, string | -1 | 0)*: The period to wait for a response from all relevant nodes in the cluster after updating the cluster metadata. +If no response is received before the timeout expires, the cluster metadata update still applies but the response will indicate that it was not completely acknowledged. +To indicate that the request should never timeout, set it to `-1`. +** *`verify` (Optional, boolean)*: If `true`, the request verifies the repository is functional on all master and data nodes in the cluster. +If `false`, this verification is skipped. +You can also perform this verification with the verify snapshot repository API. [discrete] ==== delete @@ -14793,9 +14838,12 @@ client.snapshot.delete({ repository, snapshot }) ==== Arguments * *Request (object):* -** *`repository` (string)*: A repository name -** *`snapshot` (string)*: A list of snapshot names -** *`master_timeout` (Optional, string | -1 | 0)*: Explicit operation timeout for connection to master node +** *`repository` (string)*: The name of the repository to delete a snapshot from. +** *`snapshot` (string)*: A list of snapshot names to delete. +It also accepts wildcards (`*`). +** *`master_timeout` (Optional, string | -1 | 0)*: 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`. ** *`wait_for_completion` (Optional, boolean)*: If `true`, the request returns a response when the matching snapshots are all deleted. If `false`, the request returns a response as soon as the deletes are scheduled. @@ -14815,14 +14863,23 @@ client.snapshot.deleteRepository({ repository }) ==== Arguments * *Request (object):* -** *`repository` (string | string[])*: Name of the snapshot repository to unregister. Wildcard (`*`) patterns are supported. -** *`master_timeout` (Optional, string | -1 | 0)*: Explicit operation timeout for connection to master node -** *`timeout` (Optional, string | -1 | 0)*: Explicit operation timeout +** *`repository` (string | string[])*: The ame of the snapshot repositories to unregister. +Wildcard (`*`) patterns are supported. +** *`master_timeout` (Optional, string | -1 | 0)*: 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`. +** *`timeout` (Optional, string | -1 | 0)*: The period to wait for a response from all relevant nodes in the cluster after updating the cluster metadata. +If no response is received before the timeout expires, the cluster metadata update still applies but the response will indicate that it was not completely acknowledged. +To indicate that the request should never timeout, set it to `-1`. [discrete] ==== get Get snapshot information. +NOTE: The `after` parameter and `next` field enable you to iterate through snapshots with some consistency guarantees regarding concurrent creation or deletion of snapshots. +It is guaranteed that any snapshot that exists at the beginning of the iteration and is not concurrently deleted will be seen during the iteration. +Snapshots concurrently created may be seen during an iteration. + {ref}/get-snapshot-api.html[Endpoint documentation] [source,ts] ---- @@ -14833,23 +14890,41 @@ client.snapshot.get({ repository, snapshot }) ==== Arguments * *Request (object):* -** *`repository` (string)*: List of snapshot repository names used to limit the request. Wildcard (*) expressions are supported. -** *`snapshot` (string | string[])*: List of snapshot names to retrieve. Also accepts wildcards (*). -- To get information about all snapshots in a registered repository, use a wildcard (*) or _all. -- To get information about any snapshots that are currently running, use _current. -** *`ignore_unavailable` (Optional, boolean)*: If false, the request returns an error for any snapshots that are unavailable. -** *`master_timeout` (Optional, string | -1 | 0)*: 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. -** *`verbose` (Optional, boolean)*: If true, returns additional information about each snapshot such as the version of Elasticsearch which took the snapshot, the start and end times of the snapshot, and the number of shards snapshotted. -** *`index_details` (Optional, boolean)*: If true, returns additional information about each index in the snapshot comprising the number of shards in the index, the total size of the index in bytes, and the maximum number of segments per shard in the index. Defaults to false, meaning that this information is omitted. -** *`index_names` (Optional, boolean)*: If true, returns the name of each index in each snapshot. -** *`include_repository` (Optional, boolean)*: If true, returns the repository name in each snapshot. -** *`sort` (Optional, Enum("start_time" | "duration" | "name" | "index_count" | "repository" | "shard_count" | "failed_shard_count"))*: Allows setting a sort order for the result. Defaults to start_time, i.e. sorting by snapshot start time stamp. -** *`size` (Optional, number)*: Maximum number of snapshots to return. Defaults to 0 which means return all that match the request without limit. -** *`order` (Optional, Enum("asc" | "desc"))*: Sort order. Valid values are asc for ascending and desc for descending order. Defaults to asc, meaning ascending order. -** *`after` (Optional, string)*: Offset identifier to start pagination from as returned by the next field in the response body. +** *`repository` (string)*: A list of snapshot repository names used to limit the request. +Wildcard (`*`) expressions are supported. +** *`snapshot` (string | string[])*: A list of snapshot names to retrieve +Wildcards (`*`) are supported. + +* To get information about all snapshots in a registered repository, use a wildcard (`*`) or `_all`. +* To get information about any snapshots that are currently running, use `_current`. +** *`after` (Optional, string)*: An offset identifier to start pagination from as returned by the next field in the response body. +** *`from_sort_value` (Optional, string)*: The value of the current sort column at which to start retrieval. +It can be a string `snapshot-` or a repository name when sorting by snapshot or repository name. +It can be a millisecond time value or a number when sorting by `index-` or shard count. +** *`ignore_unavailable` (Optional, boolean)*: If `false`, the request returns an error for any snapshots that are unavailable. +** *`index_details` (Optional, boolean)*: If `true`, the response includes additional information about each index in the snapshot comprising the number of shards in the index, the total size of the index in bytes, and the maximum number of segments per shard in the index. +The default is `false`, meaning that this information is omitted. +** *`index_names` (Optional, boolean)*: If `true`, the response includes the name of each index in each snapshot. +** *`include_repository` (Optional, boolean)*: If `true`, the response includes the repository name in each snapshot. +** *`master_timeout` (Optional, string | -1 | 0)*: 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. +** *`order` (Optional, Enum("asc" | "desc"))*: The sort order. +Valid values are `asc` for ascending and `desc` for descending order. +The default behavior is ascending order. ** *`offset` (Optional, number)*: Numeric offset to start pagination from based on the snapshots matching this request. Using a non-zero value for this parameter is mutually exclusive with using the after parameter. Defaults to 0. -** *`from_sort_value` (Optional, string)*: Value of the current sort column at which to start retrieval. Can either be a string snapshot- or repository name when sorting by snapshot or repository name, a millisecond time value or a number when sorting by index- or shard count. -** *`slm_policy_filter` (Optional, string)*: Filter snapshots by a list of SLM policy names that snapshots belong to. Also accepts wildcards (*) and combinations of wildcards followed by exclude patterns starting with -. To include snapshots not created by an SLM policy you can use the special pattern _none that will match all snapshots without an SLM policy. +** *`size` (Optional, number)*: The maximum number of snapshots to return. +The default is 0, which means to return all that match the request without limit. +** *`slm_policy_filter` (Optional, string)*: Filter snapshots by a list of snapshot lifecycle management (SLM) policy names that snapshots belong to. + +You can use wildcards (`*`) and combinations of wildcards followed by exclude patterns starting with `-`. +For example, the pattern `*,-policy-a-\*` will return all snapshots except for those that were created by an SLM policy with a name starting with `policy-a-`. +Note that the wildcard pattern `*` matches all snapshots created by an SLM policy but not those snapshots that were not created by an SLM policy. +To include snapshots that were not created by an SLM policy, you can use the special pattern `_none` that will match all snapshots without an SLM policy. +** *`sort` (Optional, Enum("start_time" | "duration" | "name" | "index_count" | "repository" | "shard_count" | "failed_shard_count"))*: The sort order for the result. +The default behavior is sorting by snapshot start time stamp. +** *`verbose` (Optional, boolean)*: If `true`, returns additional information about each snapshot such as the version of Elasticsearch which took the snapshot, the start and end times of the snapshot, and the number of shards snapshotted. + +NOTE: The parameters `size`, `order`, `after`, `from_sort_value`, `offset`, `slm_policy_filter`, and `sort` are not supported when you set `verbose=false` and the sort order for requests with `verbose=false` is undefined. [discrete] ==== get_repository @@ -14865,9 +14940,15 @@ client.snapshot.getRepository({ ... }) ==== Arguments * *Request (object):* -** *`repository` (Optional, string | string[])*: A list of repository names -** *`local` (Optional, boolean)*: Return local information, do not retrieve the state from master node (default: false) -** *`master_timeout` (Optional, string | -1 | 0)*: Explicit operation timeout for connection to master node +** *`repository` (Optional, string | string[])*: A list of snapshot repository names used to limit the request. +Wildcard (`*`) expressions are supported including combining wildcards with exclude patterns starting with `-`. + +To get information about all snapshot repositories registered in the cluster, omit this parameter or use `*` or `_all`. +** *`local` (Optional, boolean)*: If `true`, the request gets information from the local node only. +If `false`, the request gets information from the master node. +** *`master_timeout` (Optional, string | -1 | 0)*: 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`. [discrete] ==== repository_analyze @@ -15029,28 +15110,80 @@ client.snapshot.restore({ repository, snapshot }) ==== Arguments * *Request (object):* -** *`repository` (string)*: A repository name -** *`snapshot` (string)*: A snapshot name -** *`feature_states` (Optional, string[])* -** *`ignore_index_settings` (Optional, string[])* -** *`ignore_unavailable` (Optional, boolean)* -** *`include_aliases` (Optional, boolean)* -** *`include_global_state` (Optional, boolean)* -** *`index_settings` (Optional, { index, mode, routing_path, soft_deletes, sort, number_of_shards, number_of_replicas, number_of_routing_shards, check_on_startup, codec, routing_partition_size, load_fixed_bitset_filters_eagerly, hidden, auto_expand_replicas, merge, search, refresh_interval, max_result_window, max_inner_result_window, max_rescore_window, max_docvalue_fields_search, max_script_fields, max_ngram_diff, max_shingle_diff, blocks, max_refresh_listeners, analyze, highlight, max_terms_count, max_regex_length, routing, gc_deletes, default_pipeline, final_pipeline, lifecycle, provided_name, creation_date, creation_date_string, uuid, version, verified_before_close, format, max_slices_per_scroll, translog, query_string, priority, top_metrics_max_size, analysis, settings, time_series, queries, similarity, mapping, indexing.slowlog, indexing_pressure, store })* -** *`indices` (Optional, string | string[])* -** *`partial` (Optional, boolean)* -** *`rename_pattern` (Optional, string)* -** *`rename_replacement` (Optional, string)* -** *`master_timeout` (Optional, string | -1 | 0)*: Explicit operation timeout for connection to master node -** *`wait_for_completion` (Optional, boolean)*: Should this request wait until the operation has completed before returning +** *`repository` (string)*: The name of the repository to restore a snapshot from. +** *`snapshot` (string)*: The name of the snapshot to restore. +** *`feature_states` (Optional, string[])*: The feature states to restore. +If `include_global_state` is `true`, the request restores all feature states in the snapshot by default. +If `include_global_state` is `false`, the request restores no feature states by default. +Note that specifying an empty array will result in the default behavior. +To restore no feature states, regardless of the `include_global_state` value, specify an array containing only the value `none` (`["none"]`). +** *`ignore_index_settings` (Optional, string[])*: The index settings to not restore from the snapshot. +You can't use this option to ignore `index.number_of_shards`. + +For data streams, this option applies only to restored backing indices. +New backing indices are configured using the data stream's matching index template. +** *`ignore_unavailable` (Optional, boolean)*: If `true`, the request ignores any index or data stream in indices that's missing from the snapshot. +If `false`, the request returns an error for any missing index or data stream. +** *`include_aliases` (Optional, boolean)*: If `true`, the request restores aliases for any restored data streams and indices. +If `false`, the request doesn’t restore aliases. +** *`include_global_state` (Optional, boolean)*: If `true`, restore the cluster state. The cluster state includes: + +* Persistent cluster settings +* Index templates +* Legacy index templates +* Ingest pipelines +* Index lifecycle management (ILM) policies +* Stored scripts +* For snapshots taken after 7.12.0, feature states + +If `include_global_state` is `true`, the restore operation merges the legacy index templates in your cluster with the templates contained in the snapshot, replacing any existing ones whose name matches one in the snapshot. +It completely removes all persistent settings, non-legacy index templates, ingest pipelines, and ILM lifecycle policies that exist in your cluster and replaces them with the corresponding items from the snapshot. + +Use the `feature_states` parameter to configure how feature states are restored. + +If `include_global_state` is `true` and a snapshot was created without a global state then the restore request will fail. +** *`index_settings` (Optional, { index, mode, routing_path, soft_deletes, sort, number_of_shards, number_of_replicas, number_of_routing_shards, check_on_startup, codec, routing_partition_size, load_fixed_bitset_filters_eagerly, hidden, auto_expand_replicas, merge, search, refresh_interval, max_result_window, max_inner_result_window, max_rescore_window, max_docvalue_fields_search, max_script_fields, max_ngram_diff, max_shingle_diff, blocks, max_refresh_listeners, analyze, highlight, max_terms_count, max_regex_length, routing, gc_deletes, default_pipeline, final_pipeline, lifecycle, provided_name, creation_date, creation_date_string, uuid, version, verified_before_close, format, max_slices_per_scroll, translog, query_string, priority, top_metrics_max_size, analysis, settings, time_series, queries, similarity, mapping, indexing.slowlog, indexing_pressure, store })*: Index settings to add or change in restored indices, including backing indices. +You can't use this option to change `index.number_of_shards`. + +For data streams, this option applies only to restored backing indices. +New backing indices are configured using the data stream's matching index template. +** *`indices` (Optional, string | string[])*: A list of indices and data streams to restore. +It supports a multi-target syntax. +The default behavior is all regular indices and regular data streams in the snapshot. + +You can't use this parameter to restore system indices or system data streams. +Use `feature_states` instead. +** *`partial` (Optional, boolean)*: If `false`, the entire restore operation will fail if one or more indices included in the snapshot do not have all primary shards available. + +If true, it allows restoring a partial snapshot of indices with unavailable shards. +Only shards that were successfully included in the snapshot will be restored. +All missing shards will be recreated as empty. +** *`rename_pattern` (Optional, string)*: A rename pattern to apply to restored data streams and indices. +Data streams and indices matching the rename pattern will be renamed according to `rename_replacement`. + +The rename pattern is applied as defined by the regular expression that supports referencing the original text, according to the `appendReplacement` logic. +** *`rename_replacement` (Optional, string)*: The rename replacement string that is used with the `rename_pattern`. +** *`master_timeout` (Optional, string | -1 | 0)*: 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`. +** *`wait_for_completion` (Optional, boolean)*: If `true`, the request returns a response when the restore operation completes. +The operation is complete when it finishes all attempts to recover primary shards for restored indices. +This applies even if one or more of the recovery attempts fail. + +If `false`, the request returns a response when the restore operation initializes. [discrete] ==== status Get the snapshot status. Get a detailed description of the current state for each shard participating in the snapshot. + Note that this API should be used only to obtain detailed shard-level information for ongoing snapshots. If this detail is not needed or you want to obtain information about one or more existing snapshots, use the get snapshot API. +If you omit the `` request path parameter, the request retrieves information only for currently running snapshots. +This usage is preferred. +If needed, you can specify `` and `` to retrieve information for specific snapshots, even if they're not currently running. + WARNING: Using the API to return the status of any snapshots other than currently running snapshots can be expensive. The API requires a read from the repository for each shard in each snapshot. For example, if you have 100 snapshots with 1,000 shards each, an API request that includes all snapshots will require 100,000 reads (100 snapshots x 1,000 shards). @@ -15068,10 +15201,16 @@ client.snapshot.status({ ... }) ==== Arguments * *Request (object):* -** *`repository` (Optional, string)*: A repository name -** *`snapshot` (Optional, string | string[])*: A list of snapshot names -** *`ignore_unavailable` (Optional, boolean)*: Whether to ignore unavailable snapshots, defaults to false which means a SnapshotMissingException is thrown -** *`master_timeout` (Optional, string | -1 | 0)*: Explicit operation timeout for connection to master node +** *`repository` (Optional, string)*: The snapshot repository name used to limit the request. +It supports wildcards (`*`) if `` isn't specified. +** *`snapshot` (Optional, string | string[])*: A list of snapshots to retrieve status for. +The default is currently running snapshots. +Wildcards (`*`) are not supported. +** *`ignore_unavailable` (Optional, boolean)*: If `false`, the request returns an error for any snapshots that are unavailable. +If `true`, the request ignores snapshots that are unavailable, such as those that are corrupted or temporarily cannot be returned. +** *`master_timeout` (Optional, string | -1 | 0)*: 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`. [discrete] ==== verify_repository @@ -15088,9 +15227,13 @@ client.snapshot.verifyRepository({ repository }) ==== Arguments * *Request (object):* -** *`repository` (string)*: A repository name -** *`master_timeout` (Optional, string | -1 | 0)*: Explicit operation timeout for connection to master node -** *`timeout` (Optional, string | -1 | 0)*: Explicit operation timeout +** *`repository` (string)*: The name of the snapshot repository to verify. +** *`master_timeout` (Optional, string | -1 | 0)*: 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`. +** *`timeout` (Optional, string | -1 | 0)*: The period to wait for a response from all relevant nodes in the cluster after updating the cluster metadata. +If no response is received before the timeout expires, the cluster metadata update still applies but the response will indicate that it was not completely acknowledged. +To indicate that the request should never timeout, set it to `-1`. [discrete] === sql diff --git a/src/api/api/indices.ts b/src/api/api/indices.ts index b5dff052d..923070498 100644 --- a/src/api/api/indices.ts +++ b/src/api/api/indices.ts @@ -2190,7 +2190,7 @@ export default class Indices { } /** - * 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`. + * Roll over to a new index. TIP: We recommend using the index lifecycle rollover action to automate rollovers. However, Serverless does not support Index Lifecycle Management (ILM), so don't use this approach in the Serverless context. 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`. * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.19/indices-rollover-index.html | Elasticsearch API documentation} */ async rollover (this: That, params: T.IndicesRolloverRequest | TB.IndicesRolloverRequest, options?: TransportRequestOptionsWithOutMeta): Promise diff --git a/src/api/api/snapshot.ts b/src/api/api/snapshot.ts index 39d060ae1..4f8d70ff9 100644 --- a/src/api/api/snapshot.ts +++ b/src/api/api/snapshot.ts @@ -131,7 +131,7 @@ export default class Snapshot { async create (this: That, params: T.SnapshotCreateRequest | TB.SnapshotCreateRequest, options?: TransportRequestOptions): Promise async create (this: That, params: T.SnapshotCreateRequest | TB.SnapshotCreateRequest, options?: TransportRequestOptions): Promise { const acceptedPath: string[] = ['repository', 'snapshot'] - const acceptedBody: string[] = ['ignore_unavailable', 'include_global_state', 'indices', 'feature_states', 'metadata', 'partial'] + const acceptedBody: string[] = ['expand_wildcards', 'feature_states', 'ignore_unavailable', 'include_global_state', 'indices', 'metadata', 'partial'] const querystring: Record = {} // @ts-expect-error const userBody: any = params?.body @@ -168,8 +168,8 @@ export default class Snapshot { } /** - * Create or update a snapshot repository. IMPORTANT: If you are migrating searchable snapshots, the repository name must be identical in the source and destination clusters. To register a snapshot repository, the cluster's global metadata must be writeable. Ensure there are no cluster blocks (for example, `cluster.blocks.read_only` and `clsuter.blocks.read_only_allow_delete` settings) that prevent write access. - * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.19/modules-snapshots.html | Elasticsearch API documentation} + * Create or update a snapshot repository. IMPORTANT: If you are migrating searchable snapshots, the repository name must be identical in the source and destination clusters. To register a snapshot repository, the cluster's global metadata must be writeable. Ensure there are no cluster blocks (for example, `cluster.blocks.read_only` and `clsuter.blocks.read_only_allow_delete` settings) that prevent write access. Several options for this API can be specified using a query parameter or a request body parameter. If both parameters are specified, only the query parameter is used. + * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.19/put-snapshot-repo-api.html | Elasticsearch API documentation} */ async createRepository (this: That, params: T.SnapshotCreateRepositoryRequest | TB.SnapshotCreateRepositoryRequest, options?: TransportRequestOptionsWithOutMeta): Promise async createRepository (this: That, params: T.SnapshotCreateRepositoryRequest | TB.SnapshotCreateRepositoryRequest, options?: TransportRequestOptionsWithMeta): Promise> @@ -270,7 +270,7 @@ export default class Snapshot { } /** - * Get snapshot information. + * Get snapshot information. NOTE: The `after` parameter and `next` field enable you to iterate through snapshots with some consistency guarantees regarding concurrent creation or deletion of snapshots. It is guaranteed that any snapshot that exists at the beginning of the iteration and is not concurrently deleted will be seen during the iteration. Snapshots concurrently created may be seen during an iteration. * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.19/get-snapshot-api.html | Elasticsearch API documentation} */ async get (this: That, params: T.SnapshotGetRequest | TB.SnapshotGetRequest, options?: TransportRequestOptionsWithOutMeta): Promise @@ -375,7 +375,7 @@ export default class Snapshot { } /** - * Verify the repository integrity. Verify the integrity of the contents of a snapshot repository. This API enables you to perform a comprehensive check of the contents of a repository, looking for any anomalies in its data or metadata which might prevent you from restoring snapshots from the repository or which might cause future snapshot create or delete operations to fail. If you suspect the integrity of the contents of one of your snapshot repositories, cease all write activity to this repository immediately, set its `read_only` option to `true`, and use this API to verify its integrity. Until you do so: * It may not be possible to restore some snapshots from this repository. * Searchable snapshots may report errors when searched or may have unassigned shards. * Taking snapshots into this repository may fail or may appear to succeed but have created a snapshot which cannot be restored. * Deleting snapshots from this repository may fail or may appear to succeed but leave the underlying data on disk. * Continuing to write to the repository while it is in an invalid state may causing additional damage to its contents. If the API finds any problems with the integrity of the contents of your repository, Elasticsearch will not be able to repair the damage. The only way to bring the repository back into a fully working state after its contents have been damaged is by restoring its contents from a repository backup which was taken before the damage occurred. You must also identify what caused the damage and take action to prevent it from happening again. If you cannot restore a repository backup, register a new repository and use this for all future snapshot operations. In some cases it may be possible to recover some of the contents of a damaged repository, either by restoring as many of its snapshots as needed and taking new snapshots of the restored data, or by using the reindex API to copy data from any searchable snapshots mounted from the damaged repository. Avoid all operations which write to the repository while the verify repository integrity API is running. If something changes the repository contents while an integrity verification is running then Elasticsearch may incorrectly report having detected some anomalies in its contents due to the concurrent writes. It may also incorrectly fail to report some anomalies that the concurrent writes prevented it from detecting. NOTE: This API is intended for exploratory use by humans. You should expect the request parameters and the response format to vary in future versions. NOTE: This API may not work correctly in a mixed-version cluster. + * Verify the repository integrity. Verify the integrity of the contents of a snapshot repository. This API enables you to perform a comprehensive check of the contents of a repository, looking for any anomalies in its data or metadata which might prevent you from restoring snapshots from the repository or which might cause future snapshot create or delete operations to fail. If you suspect the integrity of the contents of one of your snapshot repositories, cease all write activity to this repository immediately, set its `read_only` option to `true`, and use this API to verify its integrity. Until you do so: * It may not be possible to restore some snapshots from this repository. * Searchable snapshots may report errors when searched or may have unassigned shards. * Taking snapshots into this repository may fail or may appear to succeed but have created a snapshot which cannot be restored. * Deleting snapshots from this repository may fail or may appear to succeed but leave the underlying data on disk. * Continuing to write to the repository while it is in an invalid state may causing additional damage to its contents. If the API finds any problems with the integrity of the contents of your repository, Elasticsearch will not be able to repair the damage. The only way to bring the repository back into a fully working state after its contents have been damaged is by restoring its contents from a repository backup which was taken before the damage occurred. You must also identify what caused the damage and take action to prevent it from happening again. If you cannot restore a repository backup, register a new repository and use this for all future snapshot operations. In some cases it may be possible to recover some of the contents of a damaged repository, either by restoring as many of its snapshots as needed and taking new snapshots of the restored data, or by using the reindex API to copy data from any searchable snapshots mounted from the damaged repository. Avoid all operations which write to the repository while the verify repository integrity API is running. If something changes the repository contents while an integrity verification is running then Elasticsearch may incorrectly report having detected some anomalies in its contents due to the concurrent writes. It may also incorrectly fail to report some anomalies that the concurrent writes prevented it from detecting. NOTE: This API is intended for exploratory use by humans. You should expect the request parameters and the response format to vary in future versions. NOTE: This API may not work correctly in a mixed-version cluster. The default values for the parameters of this API are designed to limit the impact of the integrity verification on other activities in your cluster. For instance, by default it will only use at most half of the `snapshot_meta` threads to verify the integrity of each snapshot, allowing other snapshot operations to use the other half of this thread pool. If you modify these parameters to speed up the verification process, you risk disrupting other snapshot-related operations in your cluster. For large repositories, consider setting up a separate single-node Elasticsearch cluster just for running the integrity verification API. The response exposes implementation details of the analysis which may change from version to version. The response body format is therefore not considered stable and may be different in newer versions. * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.19/verify-repo-integrity-api.html | Elasticsearch API documentation} */ async repositoryVerifyIntegrity (this: That, params: T.SnapshotRepositoryVerifyIntegrityRequest | TB.SnapshotRepositoryVerifyIntegrityRequest, options?: TransportRequestOptionsWithOutMeta): Promise @@ -452,7 +452,7 @@ export default class Snapshot { } /** - * Get the snapshot status. Get a detailed description of the current state for each shard participating in the snapshot. Note that this API should be used only to obtain detailed shard-level information for ongoing snapshots. If this detail is not needed or you want to obtain information about one or more existing snapshots, use the get snapshot API. WARNING: Using the API to return the status of any snapshots other than currently running snapshots can be expensive. The API requires a read from the repository for each shard in each snapshot. For example, if you have 100 snapshots with 1,000 shards each, an API request that includes all snapshots will require 100,000 reads (100 snapshots x 1,000 shards). Depending on the latency of your storage, such requests can take an extremely long time to return results. These requests can also tax machine resources and, when using cloud storage, incur high processing costs. + * Get the snapshot status. Get a detailed description of the current state for each shard participating in the snapshot. Note that this API should be used only to obtain detailed shard-level information for ongoing snapshots. If this detail is not needed or you want to obtain information about one or more existing snapshots, use the get snapshot API. If you omit the `` request path parameter, the request retrieves information only for currently running snapshots. This usage is preferred. If needed, you can specify `` and `` to retrieve information for specific snapshots, even if they're not currently running. WARNING: Using the API to return the status of any snapshots other than currently running snapshots can be expensive. The API requires a read from the repository for each shard in each snapshot. For example, if you have 100 snapshots with 1,000 shards each, an API request that includes all snapshots will require 100,000 reads (100 snapshots x 1,000 shards). Depending on the latency of your storage, such requests can take an extremely long time to return results. These requests can also tax machine resources and, when using cloud storage, incur high processing costs. * @see {@link https://www.elastic.co/guide/en/elasticsearch/reference/8.19/get-snapshot-status-api.html | Elasticsearch API documentation} */ async status (this: That, params?: T.SnapshotStatusRequest | TB.SnapshotStatusRequest, options?: TransportRequestOptionsWithOutMeta): Promise diff --git a/src/api/types.ts b/src/api/types.ts index 973f7c079..df971ede0 100644 --- a/src/api/types.ts +++ b/src/api/types.ts @@ -2825,10 +2825,14 @@ export type Service = string export interface ShardFailure { index?: IndexName + _index?: IndexName node?: string + _node?: string reason: ErrorCause - shard: integer + shard?: integer + _shard?: integer status?: string + primary?: boolean } export interface ShardStatistics { @@ -20594,11 +20598,13 @@ export interface SnapshotAzureRepository extends SnapshotRepositoryBase { } export interface SnapshotAzureRepositorySettings extends SnapshotRepositorySettingsBase { + base_path?: string client?: string container?: string - base_path?: string - readonly?: boolean + delete_objects_max_size?: integer location_mode?: string + max_concurrent_batch_deletes?: integer + readonly?: boolean } export interface SnapshotFileCountSnapshotStats { @@ -20613,10 +20619,10 @@ export interface SnapshotGcsRepository extends SnapshotRepositoryBase { export interface SnapshotGcsRepositorySettings extends SnapshotRepositorySettingsBase { bucket: string - client?: string + application_name?: string base_path?: string + client?: string readonly?: boolean - application_name?: string } export interface SnapshotIndexDetails { @@ -20663,13 +20669,20 @@ export interface SnapshotS3Repository extends SnapshotRepositoryBase { export interface SnapshotS3RepositorySettings extends SnapshotRepositorySettingsBase { bucket: string - client?: string base_path?: string - readonly?: boolean - server_side_encryption?: boolean buffer_size?: ByteSize canned_acl?: string + client?: string + delete_objects_max_size?: integer + get_register_retry_delay?: Duration + max_multipart_parts?: integer + max_multipart_upload_cleanup_size?: integer + readonly?: boolean + server_side_encryption?: boolean storage_class?: string + 'throttled_delete_retry.delay_increment'?: Duration + 'throttled_delete_retry.maximum_delay'?: Duration + 'throttled_delete_retry.maximum_number_of_retries'?: integer } export interface SnapshotShardsStats { @@ -20814,10 +20827,11 @@ export interface SnapshotCreateRequest extends RequestBase { snapshot: Name master_timeout?: Duration wait_for_completion?: boolean + expand_wildcards?: ExpandWildcards + feature_states?: string[] ignore_unavailable?: boolean include_global_state?: boolean indices?: Indices - feature_states?: string[] metadata?: Metadata partial?: boolean } @@ -20857,26 +20871,27 @@ export type SnapshotDeleteRepositoryResponse = AcknowledgedResponseBase export interface SnapshotGetRequest extends RequestBase { repository: Name snapshot: Names + after?: string + from_sort_value?: string ignore_unavailable?: boolean - master_timeout?: Duration - verbose?: boolean index_details?: boolean index_names?: boolean include_repository?: boolean - sort?: SnapshotSnapshotSort - size?: integer + master_timeout?: Duration order?: SortOrder - after?: string offset?: integer - from_sort_value?: string + size?: integer slm_policy_filter?: Name + sort?: SnapshotSnapshotSort + verbose?: boolean } export interface SnapshotGetResponse { + remaining: integer + total: integer + next?: string responses?: SnapshotGetSnapshotResponseItem[] snapshots?: SnapshotSnapshotInfo[] - total: integer - remaining: integer } export interface SnapshotGetSnapshotResponseItem { @@ -21002,14 +21017,14 @@ export interface SnapshotRepositoryAnalyzeWriteSummaryInfo { export interface SnapshotRepositoryVerifyIntegrityRequest extends RequestBase { name: Names - meta_thread_pool_concurrency?: integer blob_thread_pool_concurrency?: integer - snapshot_verification_concurrency?: integer - index_verification_concurrency?: integer index_snapshot_verification_concurrency?: integer + index_verification_concurrency?: integer + max_bytes_per_sec?: string max_failed_shard_snapshots?: integer + meta_thread_pool_concurrency?: integer + snapshot_verification_concurrency?: integer verify_blob_contents?: boolean - max_bytes_per_sec?: string } export type SnapshotRepositoryVerifyIntegrityResponse = any diff --git a/src/api/typesWithBodyKey.ts b/src/api/typesWithBodyKey.ts index c7b0856ea..637a1a368 100644 --- a/src/api/typesWithBodyKey.ts +++ b/src/api/typesWithBodyKey.ts @@ -2902,10 +2902,14 @@ export type Service = string export interface ShardFailure { index?: IndexName + _index?: IndexName node?: string + _node?: string reason: ErrorCause - shard: integer + shard?: integer + _shard?: integer status?: string + primary?: boolean } export interface ShardStatistics { @@ -21185,11 +21189,13 @@ export interface SnapshotAzureRepository extends SnapshotRepositoryBase { } export interface SnapshotAzureRepositorySettings extends SnapshotRepositorySettingsBase { + base_path?: string client?: string container?: string - base_path?: string - readonly?: boolean + delete_objects_max_size?: integer location_mode?: string + max_concurrent_batch_deletes?: integer + readonly?: boolean } export interface SnapshotFileCountSnapshotStats { @@ -21204,10 +21210,10 @@ export interface SnapshotGcsRepository extends SnapshotRepositoryBase { export interface SnapshotGcsRepositorySettings extends SnapshotRepositorySettingsBase { bucket: string - client?: string + application_name?: string base_path?: string + client?: string readonly?: boolean - application_name?: string } export interface SnapshotIndexDetails { @@ -21254,13 +21260,20 @@ export interface SnapshotS3Repository extends SnapshotRepositoryBase { export interface SnapshotS3RepositorySettings extends SnapshotRepositorySettingsBase { bucket: string - client?: string base_path?: string - readonly?: boolean - server_side_encryption?: boolean buffer_size?: ByteSize canned_acl?: string + client?: string + delete_objects_max_size?: integer + get_register_retry_delay?: Duration + max_multipart_parts?: integer + max_multipart_upload_cleanup_size?: integer + readonly?: boolean + server_side_encryption?: boolean storage_class?: string + 'throttled_delete_retry.delay_increment'?: Duration + 'throttled_delete_retry.maximum_delay'?: Duration + 'throttled_delete_retry.maximum_number_of_retries'?: integer } export interface SnapshotShardsStats { @@ -21410,10 +21423,11 @@ export interface SnapshotCreateRequest extends RequestBase { wait_for_completion?: boolean /** @deprecated The use of the 'body' key has been deprecated, move the nested keys to the top level object. */ body?: { + expand_wildcards?: ExpandWildcards + feature_states?: string[] ignore_unavailable?: boolean include_global_state?: boolean indices?: Indices - feature_states?: string[] metadata?: Metadata partial?: boolean } @@ -21455,26 +21469,27 @@ export type SnapshotDeleteRepositoryResponse = AcknowledgedResponseBase export interface SnapshotGetRequest extends RequestBase { repository: Name snapshot: Names + after?: string + from_sort_value?: string ignore_unavailable?: boolean - master_timeout?: Duration - verbose?: boolean index_details?: boolean index_names?: boolean include_repository?: boolean - sort?: SnapshotSnapshotSort - size?: integer + master_timeout?: Duration order?: SortOrder - after?: string offset?: integer - from_sort_value?: string + size?: integer slm_policy_filter?: Name + sort?: SnapshotSnapshotSort + verbose?: boolean } export interface SnapshotGetResponse { + remaining: integer + total: integer + next?: string responses?: SnapshotGetSnapshotResponseItem[] snapshots?: SnapshotSnapshotInfo[] - total: integer - remaining: integer } export interface SnapshotGetSnapshotResponseItem { @@ -21600,14 +21615,14 @@ export interface SnapshotRepositoryAnalyzeWriteSummaryInfo { export interface SnapshotRepositoryVerifyIntegrityRequest extends RequestBase { name: Names - meta_thread_pool_concurrency?: integer blob_thread_pool_concurrency?: integer - snapshot_verification_concurrency?: integer - index_verification_concurrency?: integer index_snapshot_verification_concurrency?: integer + index_verification_concurrency?: integer + max_bytes_per_sec?: string max_failed_shard_snapshots?: integer + meta_thread_pool_concurrency?: integer + snapshot_verification_concurrency?: integer verify_blob_contents?: boolean - max_bytes_per_sec?: string } export type SnapshotRepositoryVerifyIntegrityResponse = any