diff --git a/output/openapi/elasticsearch-openapi.json b/output/openapi/elasticsearch-openapi.json index d2b0aa8198..cf7870f39b 100644 --- a/output/openapi/elasticsearch-openapi.json +++ b/output/openapi/elasticsearch-openapi.json @@ -33303,7 +33303,7 @@ { "in": "path", "name": "repository", - "description": "Snapshot repository to clean up.", + "description": "The name of the snapshot repository to clean up.", "required": true, "deprecated": false, "schema": { @@ -33314,7 +33314,7 @@ { "in": "query", "name": "master_timeout", - "description": "Period to wait for a connection to the master node.", + "description": "The period to wait for a connection to the master node.\nIf the master node is not available before the timeout expires, the request fails and returns an error.\nTo indicate that the request should never timeout, set it to `-1`", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Duration" @@ -33324,7 +33324,7 @@ { "in": "query", "name": "timeout", - "description": "Period to wait for a response.", + "description": "The period to wait for a response from all relevant nodes in the cluster after updating the cluster metadata.\nIf 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.\nTo indicate that the request should never timeout, set it to `-1`.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Duration" @@ -33367,7 +33367,7 @@ { "in": "path", "name": "repository", - "description": "A repository name", + "description": "The name of the snapshot repository that both source and target snapshot belong to.", "required": true, "deprecated": false, "schema": { @@ -33378,7 +33378,7 @@ { "in": "path", "name": "snapshot", - "description": "The name of the snapshot to clone from", + "description": "The source snapshot name.", "required": true, "deprecated": false, "schema": { @@ -33389,7 +33389,7 @@ { "in": "path", "name": "target_snapshot", - "description": "The name of the cloned snapshot to create", + "description": "The target snapshot name.", "required": true, "deprecated": false, "schema": { @@ -33400,7 +33400,17 @@ { "in": "query", "name": "master_timeout", - "description": "Explicit operation timeout for connection to master node", + "description": "The period to wait for the master node.\nIf the master node is not available before the timeout expires, the request fails and returns an error.\nTo indicate that the request should never timeout, set it to `-1`.", + "deprecated": false, + "schema": { + "$ref": "#/components/schemas/_types:Duration" + }, + "style": "form" + }, + { + "in": "query", + "name": "timeout", + "description": "The period of time to wait for a response.\nIf no response is received before the timeout expires, the request fails and returns an error.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Duration" @@ -33415,6 +33425,7 @@ "type": "object", "properties": { "indices": { + "description": "A comma-separated list of indices to include in the snapshot.\nMulti-target syntax is supported.", "type": "string" } }, @@ -33447,12 +33458,13 @@ "snapshot" ], "summary": "Get snapshot information", + "description": "NOTE: The `after` parameter and `next` field enable you to iterate through snapshots with some consistency guarantees regarding concurrent creation or deletion of snapshots.\nIt is guaranteed that any snapshot that exists at the beginning of the iteration and is not concurrently deleted will be seen during the iteration.\nSnapshots concurrently created may be seen during an iteration.", "operationId": "snapshot-get", "parameters": [ { "in": "path", "name": "repository", - "description": "Comma-separated list of snapshot repository names used to limit the request. Wildcard (*) expressions are supported.", + "description": "A comma-separated list of snapshot repository names used to limit the request.\nWildcard (`*`) expressions are supported.", "required": true, "deprecated": false, "schema": { @@ -33463,7 +33475,7 @@ { "in": "path", "name": "snapshot", - "description": "Comma-separated list of snapshot names to retrieve. Also accepts wildcards (*).\n- To get information about all snapshots in a registered repository, use a wildcard (*) or _all.\n- To get information about any snapshots that are currently running, use _current.", + "description": "A comma-separated list of snapshot names to retrieve\nWildcards (`*`) are supported.\n\n* To get information about all snapshots in a registered repository, use a wildcard (`*`) or `_all`.\n* To get information about any snapshots that are currently running, use `_current`.", "required": true, "deprecated": false, "schema": { @@ -33473,28 +33485,28 @@ }, { "in": "query", - "name": "ignore_unavailable", - "description": "If false, the request returns an error for any snapshots that are unavailable.", + "name": "after", + "description": "An offset identifier to start pagination from as returned by the next field in the response body.", "deprecated": false, "schema": { - "type": "boolean" + "type": "string" }, "style": "form" }, { "in": "query", - "name": "master_timeout", - "description": "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.", + "name": "from_sort_value", + "description": "The value of the current sort column at which to start retrieval.\nIt can be a string `snapshot-` or a repository name when sorting by snapshot or repository name.\nIt can be a millisecond time value or a number when sorting by `index-` or shard count.", "deprecated": false, "schema": { - "$ref": "#/components/schemas/_types:Duration" + "type": "string" }, "style": "form" }, { "in": "query", - "name": "verbose", - "description": "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.", + "name": "ignore_unavailable", + "description": "If `false`, the request returns an error for any snapshots that are unavailable.", "deprecated": false, "schema": { "type": "boolean" @@ -33504,7 +33516,7 @@ { "in": "query", "name": "index_details", - "description": "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.", + "description": "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.\nThe default is `false`, meaning that this information is omitted.", "deprecated": false, "schema": { "type": "boolean" @@ -33514,7 +33526,7 @@ { "in": "query", "name": "index_names", - "description": "If true, returns the name of each index in each snapshot.", + "description": "If `true`, the response includes the name of each index in each snapshot.", "deprecated": false, "schema": { "type": "boolean" @@ -33524,7 +33536,7 @@ { "in": "query", "name": "include_repository", - "description": "If true, returns the repository name in each snapshot.", + "description": "If `true`, the response includes the repository name in each snapshot.", "deprecated": false, "schema": { "type": "boolean" @@ -33533,71 +33545,71 @@ }, { "in": "query", - "name": "sort", - "description": "Allows setting a sort order for the result. Defaults to start_time, i.e. sorting by snapshot start time stamp.", + "name": "master_timeout", + "description": "The period to wait for a connection to the master node.\nIf no response is received before the timeout expires, the request fails and returns an error.", "deprecated": false, "schema": { - "$ref": "#/components/schemas/snapshot._types:SnapshotSort" + "$ref": "#/components/schemas/_types:Duration" }, "style": "form" }, { "in": "query", - "name": "size", - "description": "Maximum number of snapshots to return. Defaults to 0 which means return all that match the request without limit.", + "name": "order", + "description": "The sort order.\nValid values are `asc` for ascending and `desc` for descending order.\nThe default behavior is ascending order.", "deprecated": false, "schema": { - "type": "number" + "$ref": "#/components/schemas/_types:SortOrder" }, "style": "form" }, { "in": "query", - "name": "order", - "description": "Sort order. Valid values are asc for ascending and desc for descending order. Defaults to asc, meaning ascending order.", + "name": "offset", + "description": "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.", "deprecated": false, "schema": { - "$ref": "#/components/schemas/_types:SortOrder" + "type": "number" }, "style": "form" }, { "in": "query", - "name": "after", - "description": "Offset identifier to start pagination from as returned by the next field in the response body.", + "name": "size", + "description": "The maximum number of snapshots to return.\nThe default is 0, which means to return all that match the request without limit.", "deprecated": false, "schema": { - "type": "string" + "type": "number" }, "style": "form" }, { "in": "query", - "name": "offset", - "description": "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.", + "name": "slm_policy_filter", + "description": "Filter snapshots by a comma-separated list of snapshot lifecycle management (SLM) policy names that snapshots belong to.\n\nYou can use wildcards (`*`) and combinations of wildcards followed by exclude patterns starting with `-`.\nFor 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-`.\nNote that the wildcard pattern `*` matches all snapshots created by an SLM policy but not those snapshots that were not created by an SLM policy.\nTo 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.", "deprecated": false, "schema": { - "type": "number" + "$ref": "#/components/schemas/_types:Name" }, "style": "form" }, { "in": "query", - "name": "from_sort_value", - "description": "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.", + "name": "sort", + "description": "The sort order for the result.\nThe default behavior is sorting by snapshot start time stamp.", "deprecated": false, "schema": { - "type": "string" + "$ref": "#/components/schemas/snapshot._types:SnapshotSort" }, "style": "form" }, { "in": "query", - "name": "slm_policy_filter", - "description": "Filter snapshots by a comma-separated list of SLM policy names that snapshots belong to. Also accepts wildcards (*) and combinations of wildcards followed by exclude patterns starting with -. To include snapshots not created by an SLM policy you can use the special pattern _none that will match all snapshots without an SLM policy.", + "name": "verbose", + "description": "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.\n\nNOTE: 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.", "deprecated": false, "schema": { - "$ref": "#/components/schemas/_types:Name" + "type": "boolean" }, "style": "form" } @@ -33610,6 +33622,18 @@ "schema": { "type": "object", "properties": { + "remaining": { + "description": "The number of remaining snapshots that were not returned due to size limits and that can be fetched by additional requests using the `next` field value.", + "type": "number" + }, + "total": { + "description": "The total number of snapshots that match the request when ignoring the size limit or `after` query parameter.", + "type": "number" + }, + "next": { + "description": "If the request contained a size limit and there might be more results, a `next` field will be added to the response.\nIt can be used as the `after` query parameter to fetch additional results.", + "type": "string" + }, "responses": { "type": "array", "items": { @@ -33621,19 +33645,11 @@ "items": { "$ref": "#/components/schemas/snapshot._types:SnapshotInfo" } - }, - "total": { - "description": "The total number of snapshots that match the request when ignoring size limit or after query parameter.", - "type": "number" - }, - "remaining": { - "description": "The number of remaining snapshots that were not returned due to size limits and that can be fetched by additional requests using the next field value.", - "type": "number" } }, "required": [ - "total", - "remaining" + "remaining", + "total" ] } } @@ -33720,7 +33736,7 @@ { "in": "path", "name": "repository", - "description": "A repository name", + "description": "The name of the repository to delete a snapshot from.", "required": true, "deprecated": false, "schema": { @@ -33731,7 +33747,7 @@ { "in": "path", "name": "snapshot", - "description": "A comma-separated list of snapshot names", + "description": "A comma-separated list of snapshot names to delete.\nIt also accepts wildcards (`*`).", "required": true, "deprecated": false, "schema": { @@ -33742,7 +33758,7 @@ { "in": "query", "name": "master_timeout", - "description": "Explicit operation timeout for connection to master node", + "description": "The period to wait for the master node.\nIf the master node is not available before the timeout expires, the request fails and returns an error.\nTo indicate that the request should never timeout, set it to `-1`.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Duration" @@ -33794,7 +33810,7 @@ "snapshot" ], "summary": "Create or update a snapshot repository", - "description": "IMPORTANT: If you are migrating searchable snapshots, the repository name must be identical in the source and destination clusters.\nTo register a snapshot repository, the cluster's global metadata must be writeable.\nEnsure there are no cluster blocks (for example, `cluster.blocks.read_only` and `clsuter.blocks.read_only_allow_delete` settings) that prevent write access.", + "description": "IMPORTANT: If you are migrating searchable snapshots, the repository name must be identical in the source and destination clusters.\nTo register a snapshot repository, the cluster's global metadata must be writeable.\nEnsure there are no cluster blocks (for example, `cluster.blocks.read_only` and `clsuter.blocks.read_only_allow_delete` settings) that prevent write access.\n\nSeveral options for this API can be specified using a query parameter or a request body parameter.\nIf both parameters are specified, only the query parameter is used.", "externalDocs": { "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/snapshots-register-repository.html" }, @@ -33828,7 +33844,7 @@ "snapshot" ], "summary": "Create or update a snapshot repository", - "description": "IMPORTANT: If you are migrating searchable snapshots, the repository name must be identical in the source and destination clusters.\nTo register a snapshot repository, the cluster's global metadata must be writeable.\nEnsure there are no cluster blocks (for example, `cluster.blocks.read_only` and `clsuter.blocks.read_only_allow_delete` settings) that prevent write access.", + "description": "IMPORTANT: If you are migrating searchable snapshots, the repository name must be identical in the source and destination clusters.\nTo register a snapshot repository, the cluster's global metadata must be writeable.\nEnsure there are no cluster blocks (for example, `cluster.blocks.read_only` and `clsuter.blocks.read_only_allow_delete` settings) that prevent write access.\n\nSeveral options for this API can be specified using a query parameter or a request body parameter.\nIf both parameters are specified, only the query parameter is used.", "externalDocs": { "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/snapshots-register-repository.html" }, @@ -33868,7 +33884,7 @@ { "in": "path", "name": "repository", - "description": "Name of the snapshot repository to unregister. Wildcard (`*`) patterns are supported.", + "description": "The ame of the snapshot repositories to unregister.\nWildcard (`*`) patterns are supported.", "required": true, "deprecated": false, "schema": { @@ -33879,7 +33895,7 @@ { "in": "query", "name": "master_timeout", - "description": "Explicit operation timeout for connection to master node", + "description": "The period to wait for the master node.\nIf the master node is not available before the timeout expires, the request fails and returns an error.\nTo indicate that the request should never timeout, set it to `-1`.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Duration" @@ -33889,7 +33905,7 @@ { "in": "query", "name": "timeout", - "description": "Explicit operation timeout", + "description": "The period to wait for a response from all relevant nodes in the cluster after updating the cluster metadata.\nIf 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.\nTo indicate that the request should never timeout, set it to `-1`.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Duration" @@ -33941,13 +33957,13 @@ "snapshot" ], "summary": "Verify the repository integrity", - "description": "Verify the integrity of the contents of a snapshot repository.\n\nThis 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.\n\nIf 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.\nUntil you do so:\n\n* It may not be possible to restore some snapshots from this repository.\n* Searchable snapshots may report errors when searched or may have unassigned shards.\n* Taking snapshots into this repository may fail or may appear to succeed but have created a snapshot which cannot be restored.\n* Deleting snapshots from this repository may fail or may appear to succeed but leave the underlying data on disk.\n* Continuing to write to the repository while it is in an invalid state may causing additional damage to its contents.\n\nIf the API finds any problems with the integrity of the contents of your repository, Elasticsearch will not be able to repair the damage.\nThe 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.\nYou must also identify what caused the damage and take action to prevent it from happening again.\n\nIf you cannot restore a repository backup, register a new repository and use this for all future snapshot operations.\nIn 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.\n\nAvoid all operations which write to the repository while the verify repository integrity API is running.\nIf 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.\nIt may also incorrectly fail to report some anomalies that the concurrent writes prevented it from detecting.\n\nNOTE: This API is intended for exploratory use by humans. You should expect the request parameters and the response format to vary in future versions.\n\nNOTE: This API may not work correctly in a mixed-version cluster.", + "description": "Verify the integrity of the contents of a snapshot repository.\n\nThis 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.\n\nIf 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.\nUntil you do so:\n\n* It may not be possible to restore some snapshots from this repository.\n* Searchable snapshots may report errors when searched or may have unassigned shards.\n* Taking snapshots into this repository may fail or may appear to succeed but have created a snapshot which cannot be restored.\n* Deleting snapshots from this repository may fail or may appear to succeed but leave the underlying data on disk.\n* Continuing to write to the repository while it is in an invalid state may causing additional damage to its contents.\n\nIf the API finds any problems with the integrity of the contents of your repository, Elasticsearch will not be able to repair the damage.\nThe 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.\nYou must also identify what caused the damage and take action to prevent it from happening again.\n\nIf you cannot restore a repository backup, register a new repository and use this for all future snapshot operations.\nIn 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.\n\nAvoid all operations which write to the repository while the verify repository integrity API is running.\nIf 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.\nIt may also incorrectly fail to report some anomalies that the concurrent writes prevented it from detecting.\n\nNOTE: This API is intended for exploratory use by humans. You should expect the request parameters and the response format to vary in future versions.\n\nNOTE: This API may not work correctly in a mixed-version cluster.\n\nThe default values for the parameters of this API are designed to limit the impact of the integrity verification on other activities in your cluster.\nFor 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.\nIf you modify these parameters to speed up the verification process, you risk disrupting other snapshot-related operations in your cluster.\nFor large repositories, consider setting up a separate single-node Elasticsearch cluster just for running the integrity verification API.\n\nThe response exposes implementation details of the analysis which may change from version to version.\nThe response body format is therefore not considered stable and may be different in newer versions.", "operationId": "snapshot-repository-verify-integrity", "parameters": [ { "in": "path", "name": "repository", - "description": "A repository name", + "description": "The name of the snapshot repository.", "required": true, "deprecated": false, "schema": { @@ -33957,8 +33973,8 @@ }, { "in": "query", - "name": "meta_thread_pool_concurrency", - "description": "Number of threads to use for reading metadata", + "name": "blob_thread_pool_concurrency", + "description": "If `verify_blob_contents` is `true`, this parameter specifies how many blobs to verify at once.", "deprecated": false, "schema": { "type": "number" @@ -33967,8 +33983,8 @@ }, { "in": "query", - "name": "blob_thread_pool_concurrency", - "description": "Number of threads to use for reading blob contents", + "name": "index_snapshot_verification_concurrency", + "description": "The maximum number of index snapshots to verify concurrently within each index verification.", "deprecated": false, "schema": { "type": "number" @@ -33977,8 +33993,8 @@ }, { "in": "query", - "name": "snapshot_verification_concurrency", - "description": "Number of snapshots to verify concurrently", + "name": "index_verification_concurrency", + "description": "The number of indices to verify concurrently.\nThe default behavior is to use the entire `snapshot_meta` thread pool.", "deprecated": false, "schema": { "type": "number" @@ -33987,18 +34003,18 @@ }, { "in": "query", - "name": "index_verification_concurrency", - "description": "Number of indices to verify concurrently", + "name": "max_bytes_per_sec", + "description": "If `verify_blob_contents` is `true`, this parameter specifies the maximum amount of data that Elasticsearch will read from the repository every second.", "deprecated": false, "schema": { - "type": "number" + "type": "string" }, "style": "form" }, { "in": "query", - "name": "index_snapshot_verification_concurrency", - "description": "Number of snapshots to verify concurrently within each index", + "name": "max_failed_shard_snapshots", + "description": "The number of shard snapshot failures to track during integrity verification, in order to avoid excessive resource usage.\nIf your repository contains more than this number of shard snapshot failures, the verification will fail.", "deprecated": false, "schema": { "type": "number" @@ -34007,8 +34023,8 @@ }, { "in": "query", - "name": "max_failed_shard_snapshots", - "description": "Maximum permitted number of failed shard snapshots", + "name": "meta_thread_pool_concurrency", + "description": "The maximum number of snapshot metadata operations to run concurrently.\nThe default behavior is to use at most half of the `snapshot_meta` thread pool at once.", "deprecated": false, "schema": { "type": "number" @@ -34017,21 +34033,21 @@ }, { "in": "query", - "name": "verify_blob_contents", - "description": "Whether to verify the contents of individual blobs", + "name": "snapshot_verification_concurrency", + "description": "The number of snapshots to verify concurrently.\nThe default behavior is to use at most half of the `snapshot_meta` thread pool at once.", "deprecated": false, "schema": { - "type": "boolean" + "type": "number" }, "style": "form" }, { "in": "query", - "name": "max_bytes_per_sec", - "description": "Rate limit for individual blob verification", + "name": "verify_blob_contents", + "description": "Indicates whether to verify the checksum of every data blob in the repository.\nIf this feature is enabled, Elasticsearch will read the entire repository contents, which may be extremely slow and expensive.", "deprecated": false, "schema": { - "type": "string" + "type": "boolean" }, "style": "form" } @@ -34066,7 +34082,7 @@ { "in": "path", "name": "repository", - "description": "A repository name", + "description": "The name of the repository to restore a snapshot from.", "required": true, "deprecated": false, "schema": { @@ -34077,7 +34093,7 @@ { "in": "path", "name": "snapshot", - "description": "A snapshot name", + "description": "The name of the snapshot to restore.", "required": true, "deprecated": false, "schema": { @@ -34088,7 +34104,7 @@ { "in": "query", "name": "master_timeout", - "description": "Explicit operation timeout for connection to master node", + "description": "The period to wait for the master node.\nIf the master node is not available before the timeout expires, the request fails and returns an error.\nTo indicate that the request should never timeout, set it to `-1`.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Duration" @@ -34098,7 +34114,7 @@ { "in": "query", "name": "wait_for_completion", - "description": "Should this request wait until the operation has completed before returning", + "description": "If `true`, the request returns a response when the restore operation completes.\nThe operation is complete when it finishes all attempts to recover primary shards for restored indices.\nThis applies even if one or more of the recovery attempts fail.\n\nIf `false`, the request returns a response when the restore operation initializes.", "deprecated": false, "schema": { "type": "boolean" @@ -34113,24 +34129,32 @@ "type": "object", "properties": { "feature_states": { + "externalDocs": { + "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/snapshot-restore.html#feature-state" + }, + "description": "The feature states to restore.\nIf `include_global_state` is `true`, the request restores all feature states in the snapshot by default.\nIf `include_global_state` is `false`, the request restores no feature states by default.\nNote that specifying an empty array will result in the default behavior.\nTo restore no feature states, regardless of the `include_global_state` value, specify an array containing only the value `none` (`[\"none\"]`).", "type": "array", "items": { "type": "string" } }, "ignore_index_settings": { + "description": "The index settings to not restore from the snapshot.\nYou can't use this option to ignore `index.number_of_shards`.\n\nFor data streams, this option applies only to restored backing indices.\nNew backing indices are configured using the data stream's matching index template.", "type": "array", "items": { "type": "string" } }, "ignore_unavailable": { + "description": "If `true`, the request ignores any index or data stream in indices that's missing from the snapshot.\nIf `false`, the request returns an error for any missing index or data stream.", "type": "boolean" }, "include_aliases": { + "description": "If `true`, the request restores aliases for any restored data streams and indices.\nIf `false`, the request doesn’t restore aliases.", "type": "boolean" }, "include_global_state": { + "description": "If `true`, restore the cluster state. The cluster state includes:\n\n* Persistent cluster settings\n* Index templates\n* Legacy index templates\n* Ingest pipelines\n* Index lifecycle management (ILM) policies\n* Stored scripts\n* For snapshots taken after 7.12.0, feature states\n\nIf `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.\nIt 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.\n\nUse the `feature_states` parameter to configure how feature states are restored.\n\nIf `include_global_state` is `true` and a snapshot was created without a global state then the restore request will fail.", "type": "boolean" }, "index_settings": { @@ -34140,12 +34164,18 @@ "$ref": "#/components/schemas/_types:Indices" }, "partial": { + "description": "If `false`, the entire restore operation will fail if one or more indices included in the snapshot do not have all primary shards available.\n\nIf true, it allows restoring a partial snapshot of indices with unavailable shards.\nOnly shards that were successfully included in the snapshot will be restored.\nAll missing shards will be recreated as empty.", "type": "boolean" }, "rename_pattern": { + "externalDocs": { + "url": "https://docs.oracle.com/javase/8/docs/api/java/util/regex/Matcher.html#appendReplacement-java.lang.StringBuffer-java.lang.String-" + }, + "description": "A rename pattern to apply to restored data streams and indices.\nData streams and indices matching the rename pattern will be renamed according to `rename_replacement`.\n\nThe rename pattern is applied as defined by the regular expression that supports referencing the original text, according to the `appendReplacement` logic.", "type": "string" }, "rename_replacement": { + "description": "The rename replacement string that is used with the `rename_pattern`.", "type": "string" } } @@ -34182,7 +34212,7 @@ "snapshot" ], "summary": "Get the snapshot status", - "description": "Get a detailed description of the current state for each shard participating in the snapshot.\nNote that this API should be used only to obtain detailed shard-level information for ongoing snapshots.\nIf this detail is not needed or you want to obtain information about one or more existing snapshots, use the get snapshot API.\n\nWARNING: Using the API to return the status of any snapshots other than currently running snapshots can be expensive.\nThe API requires a read from the repository for each shard in each snapshot.\nFor 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).\n\nDepending on the latency of your storage, such requests can take an extremely long time to return results.\nThese requests can also tax machine resources and, when using cloud storage, incur high processing costs.", + "description": "Get a detailed description of the current state for each shard participating in the snapshot.\n\nNote that this API should be used only to obtain detailed shard-level information for ongoing snapshots.\nIf this detail is not needed or you want to obtain information about one or more existing snapshots, use the get snapshot API.\n\nIf you omit the `` request path parameter, the request retrieves information only for currently running snapshots.\nThis usage is preferred.\nIf needed, you can specify `` and `` to retrieve information for specific snapshots, even if they're not currently running.\n\nWARNING: Using the API to return the status of any snapshots other than currently running snapshots can be expensive.\nThe API requires a read from the repository for each shard in each snapshot.\nFor 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).\n\nDepending on the latency of your storage, such requests can take an extremely long time to return results.\nThese requests can also tax machine resources and, when using cloud storage, incur high processing costs.", "operationId": "snapshot-status", "parameters": [ { @@ -34206,7 +34236,7 @@ "snapshot" ], "summary": "Get the snapshot status", - "description": "Get a detailed description of the current state for each shard participating in the snapshot.\nNote that this API should be used only to obtain detailed shard-level information for ongoing snapshots.\nIf this detail is not needed or you want to obtain information about one or more existing snapshots, use the get snapshot API.\n\nWARNING: Using the API to return the status of any snapshots other than currently running snapshots can be expensive.\nThe API requires a read from the repository for each shard in each snapshot.\nFor 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).\n\nDepending on the latency of your storage, such requests can take an extremely long time to return results.\nThese requests can also tax machine resources and, when using cloud storage, incur high processing costs.", + "description": "Get a detailed description of the current state for each shard participating in the snapshot.\n\nNote that this API should be used only to obtain detailed shard-level information for ongoing snapshots.\nIf this detail is not needed or you want to obtain information about one or more existing snapshots, use the get snapshot API.\n\nIf you omit the `` request path parameter, the request retrieves information only for currently running snapshots.\nThis usage is preferred.\nIf needed, you can specify `` and `` to retrieve information for specific snapshots, even if they're not currently running.\n\nWARNING: Using the API to return the status of any snapshots other than currently running snapshots can be expensive.\nThe API requires a read from the repository for each shard in each snapshot.\nFor 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).\n\nDepending on the latency of your storage, such requests can take an extremely long time to return results.\nThese requests can also tax machine resources and, when using cloud storage, incur high processing costs.", "operationId": "snapshot-status-1", "parameters": [ { @@ -34233,7 +34263,7 @@ "snapshot" ], "summary": "Get the snapshot status", - "description": "Get a detailed description of the current state for each shard participating in the snapshot.\nNote that this API should be used only to obtain detailed shard-level information for ongoing snapshots.\nIf this detail is not needed or you want to obtain information about one or more existing snapshots, use the get snapshot API.\n\nWARNING: Using the API to return the status of any snapshots other than currently running snapshots can be expensive.\nThe API requires a read from the repository for each shard in each snapshot.\nFor 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).\n\nDepending on the latency of your storage, such requests can take an extremely long time to return results.\nThese requests can also tax machine resources and, when using cloud storage, incur high processing costs.", + "description": "Get a detailed description of the current state for each shard participating in the snapshot.\n\nNote that this API should be used only to obtain detailed shard-level information for ongoing snapshots.\nIf this detail is not needed or you want to obtain information about one or more existing snapshots, use the get snapshot API.\n\nIf you omit the `` request path parameter, the request retrieves information only for currently running snapshots.\nThis usage is preferred.\nIf needed, you can specify `` and `` to retrieve information for specific snapshots, even if they're not currently running.\n\nWARNING: Using the API to return the status of any snapshots other than currently running snapshots can be expensive.\nThe API requires a read from the repository for each shard in each snapshot.\nFor 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).\n\nDepending on the latency of your storage, such requests can take an extremely long time to return results.\nThese requests can also tax machine resources and, when using cloud storage, incur high processing costs.", "operationId": "snapshot-status-2", "parameters": [ { @@ -34272,7 +34302,7 @@ { "in": "path", "name": "repository", - "description": "A repository name", + "description": "The name of the snapshot repository to verify.", "required": true, "deprecated": false, "schema": { @@ -34283,7 +34313,7 @@ { "in": "query", "name": "master_timeout", - "description": "Explicit operation timeout for connection to master node", + "description": "The period to wait for the master node.\nIf the master node is not available before the timeout expires, the request fails and returns an error.\nTo indicate that the request should never timeout, set it to `-1`.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Duration" @@ -34293,7 +34323,7 @@ { "in": "query", "name": "timeout", - "description": "Explicit operation timeout", + "description": "The period to wait for a response from all relevant nodes in the cluster after updating the cluster metadata.\nIf 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.\nTo indicate that the request should never timeout, set it to `-1`.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Duration" @@ -34310,6 +34340,7 @@ "type": "object", "properties": { "nodes": { + "description": "Information about the nodes connected to the snapshot repository.\nThe key is the ID of the node.", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/snapshot.verify_repository:CompactNodeInfo" @@ -87102,11 +87133,11 @@ "type": "object", "properties": { "deleted_blobs": { - "description": "Number of binary large objects (blobs) removed during cleanup.", + "description": "The number of binary large objects (blobs) removed from the snapshot repository during cleanup operations.\nA non-zero value indicates that unreferenced blobs were found and subsequently cleaned up.", "type": "number" }, "deleted_bytes": { - "description": "Number of bytes freed by cleanup operations.", + "description": "The number of bytes freed by cleanup operations.", "type": "number" } }, @@ -87304,6 +87335,10 @@ "type": "object", "properties": { "type": { + "externalDocs": { + "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/repository-azure.html" + }, + "description": "The Azure repository type.", "type": "string", "enum": [ "azure" @@ -87328,20 +87363,33 @@ { "type": "object", "properties": { + "base_path": { + "description": "The path to the repository data within the container.\nIt defaults to the root directory.\n\nNOTE: Don't set `base_path` when configuring a snapshot repository for Elastic Cloud Enterprise.\nElastic Cloud Enterprise automatically generates the `base_path` for each deployment so that multiple deployments can share the same bucket.", + "type": "string" + }, "client": { + "description": "The name of the Azure repository client to use.", "type": "string" }, "container": { + "description": "The Azure container.", "type": "string" }, - "base_path": { + "delete_objects_max_size": { + "description": "The maxmimum batch size, between 1 and 256, used for `BlobBatch` requests.\nDefaults to 256 which is the maximum number supported by the Azure blob batch API.", + "type": "number" + }, + "location_mode": { + "description": "Either `primary_only` or `secondary_only`.\nNote that if you set it to `secondary_only`, it will force `readonly` to `true`.", "type": "string" }, + "max_concurrent_batch_deletes": { + "description": "The maximum number of concurrent batch delete requests that will be submitted for any individual bulk delete with `BlobBatch`.\nNote that the effective number of concurrent deletes is further limited by the Azure client connection and event loop thread limits.\nDefaults to 10, minimum is 1, maximum is 100.", + "type": "number" + }, "readonly": { + "description": "If `true`, the repository is read-only.\nThe cluster can retrieve and restore snapshots from the repository but not write to the repository or create snapshots in it.\n\nOnly a cluster with write access can create snapshots in the repository.\nAll other clusters connected to the repository should have the `readonly` parameter set to `true`.\nIf `false`, the cluster can write to the repository and create snapshots in it.\n\nIMPORTANT: If you register the same snapshot repository with multiple clusters, only one cluster should have write access to the repository.\nHaving multiple clusters write to the repository at the same time risks corrupting the contents of the repository.", "type": "boolean" - }, - "location_mode": { - "type": "string" } } } @@ -87354,6 +87402,7 @@ "$ref": "#/components/schemas/_types:ByteSize" }, "compress": { + "description": "When set to `true`, metadata files are stored in compressed format.\nThis setting doesn't affect index files that are already compressed by default.", "type": "boolean" }, "max_restore_bytes_per_sec": { @@ -87381,6 +87430,10 @@ "type": "object", "properties": { "type": { + "externalDocs": { + "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/repository-gcs.html" + }, + "description": "The Google Cloud Storage repository type.", "type": "string", "enum": [ "gcs" @@ -87406,19 +87459,25 @@ "type": "object", "properties": { "bucket": { + "description": "The name of the bucket to be used for snapshots.", "type": "string" }, - "client": { + "application_name": { + "deprecated": true, + "description": "The name used by the client when it uses the Google Cloud Storage service.", "type": "string" }, "base_path": { + "description": "The path to the repository data within the bucket.\nIt defaults to the root of the bucket.\n\nNOTE: Don't set `base_path` when configuring a snapshot repository for Elastic Cloud Enterprise.\nElastic Cloud Enterprise automatically generates the `base_path` for each deployment so that multiple deployments can share the same bucket.", + "type": "string" + }, + "client": { + "description": "The name of the client to use to connect to Google Cloud Storage.", "type": "string" }, "readonly": { + "description": "If `true`, the repository is read-only.\nThe cluster can retrieve and restore snapshots from the repository but not write to the repository or create snapshots in it.\n\nOnly a cluster with write access can create snapshots in the repository.\nAll other clusters connected to the repository should have the `readonly` parameter set to `true`.\n\nIf `false`, the cluster can write to the repository and create snapshots in it.\n\nIMPORTANT: If you register the same snapshot repository with multiple clusters, only one cluster should have write access to the repository.\nHaving multiple clusters write to the repository at the same time risks corrupting the contents of the repository.", "type": "boolean" - }, - "application_name": { - "type": "string" } }, "required": [ @@ -87436,6 +87495,10 @@ "type": "object", "properties": { "type": { + "externalDocs": { + "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/repository-s3.html" + }, + "description": "The S3 repository type.", "type": "string", "enum": [ "s3" @@ -87461,28 +87524,75 @@ "type": "object", "properties": { "bucket": { + "externalDocs": { + "url": "https://docs.aws.amazon.com/AmazonS3/latest/userguide/BucketRestrictions.html#bucketnamingrules" + }, + "description": "The name of the S3 bucket to use for snapshots.\nThe bucket name must adhere to Amazon's S3 bucket naming rules.", "type": "string" }, - "client": { + "base_path": { + "description": "The path to the repository data within its bucket.\nIt defaults to an empty string, meaning that the repository is at the root of the bucket.\nThe value of this setting should not start or end with a forward slash (`/`).\n\nNOTE: Don't set base_path when configuring a snapshot repository for Elastic Cloud Enterprise.\nElastic Cloud Enterprise automatically generates the `base_path` for each deployment so that multiple deployments may share the same bucket.", "type": "string" }, - "base_path": { + "buffer_size": { + "$ref": "#/components/schemas/_types:ByteSize" + }, + "canned_acl": { + "externalDocs": { + "url": "https://docs.aws.amazon.com/AmazonS3/latest/userguide/acl-overview.html#canned-acl" + }, + "description": "The S3 repository supports all S3 canned ACLs: `private`, `public-read`, `public-read-write`, `authenticated-read`, `log-delivery-write`, `bucket-owner-read`, `bucket-owner-full-control`.\nYou could specify a canned ACL using the `canned_acl` setting.\nWhen the S3 repository creates buckets and objects, it adds the canned ACL into the buckets and objects.", + "type": "string" + }, + "client": { + "description": "The name of the S3 client to use to connect to S3.", "type": "string" }, + "delete_objects_max_size": { + "externalDocs": { + "url": "https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteObjects.html" + }, + "description": "The maxmimum batch size, between 1 and 1000, used for `DeleteObjects` requests.\nDefaults to 1000 which is the maximum number supported by the AWS DeleteObjects API.", + "type": "number" + }, + "get_register_retry_delay": { + "$ref": "#/components/schemas/_types:Duration" + }, + "max_multipart_parts": { + "description": "The maximum number of parts that Elasticsearch will write during a multipart upload of a single object.\nFiles which are larger than `buffer_size × max_multipart_parts` will be chunked into several smaller objects.\nElasticsearch may also split a file across multiple objects to satisfy other constraints such as the `chunk_size` limit.\nDefaults to `10000` which is the maximum number of parts in a multipart upload in AWS S3.", + "type": "number" + }, + "max_multipart_upload_cleanup_size": { + "externalDocs": { + "url": "https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListMultipartUploads.html" + }, + "description": "The maximum number of possibly-dangling multipart uploads to clean up in each batch of snapshot deletions.\nDefaults to 1000 which is the maximum number supported by the AWS ListMultipartUploads API.\nIf set to `0`, Elasticsearch will not attempt to clean up dangling multipart uploads.", + "type": "number" + }, "readonly": { + "description": "If true, the repository is read-only.\nThe cluster can retrieve and restore snapshots from the repository but not write to the repository or create snapshots in it.\n\nOnly a cluster with write access can create snapshots in the repository.\nAll other clusters connected to the repository should have the `readonly` parameter set to `true`.\n\nIf `false`, the cluster can write to the repository and create snapshots in it.\n\nIMPORTANT: If you register the same snapshot repository with multiple clusters, only one cluster should have write access to the repository.\nHaving multiple clusters write to the repository at the same time risks corrupting the contents of the repository.", "type": "boolean" }, "server_side_encryption": { + "description": "When set to `true`m files are encrypted on server side using an AES256 algorithm.\nserver_default false", "type": "boolean" }, - "buffer_size": { - "$ref": "#/components/schemas/_types:ByteSize" - }, - "canned_acl": { - "type": "string" - }, "storage_class": { + "externalDocs": { + "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/repository-s3.html#repository-s3-storage-classes" + }, + "description": "The S3 storage class for objects written to the repository.\nValues may be `standard`, `reduced_redundancy`, `standard_ia`, `onezone_ia`, and `intelligent_tiering`.", "type": "string" + }, + "throttled_delete_retry.delay_increment": { + "$ref": "#/components/schemas/_types:Duration" + }, + "throttled_delete_retry.maximum_delay": { + "$ref": "#/components/schemas/_types:Duration" + }, + "throttled_delete_retry.maximum_number_of_retries": { + "description": "The number times to retry a throttled snapshot deletion.\nThe default is 10 and the minimum value is 0 which will disable retries altogether.\nNote that if retries are enabled in the Azure client, each of these retries comprises that many client-level retries.", + "type": "number" } }, "required": [ @@ -87500,6 +87610,10 @@ "type": "object", "properties": { "type": { + "externalDocs": { + "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/snapshots-filesystem-repository.html" + }, + "description": "The shared file system repository type.", "type": "string", "enum": [ "fs" @@ -87525,12 +87639,15 @@ "type": "object", "properties": { "location": { + "description": "The location of the shared filesystem used to store and retrieve snapshots.\nThis location must be registered in the `path.repo` setting on all master and data nodes in the cluster.\nUnlike `path.repo`, this setting supports only a single file path.", "type": "string" }, "max_number_of_snapshots": { + "description": "The maximum number of snapshots the repository can contain.\nThe default is `Integer.MAX_VALUE`, which is 2^31-1 or `2147483647`.", "type": "number" }, "readonly": { + "description": "If `true`, the repository is read-only.\nThe cluster can retrieve and restore snapshots from the repository but not write to the repository or create snapshots in it.\n\nOnly a cluster with write access can create snapshots in the repository.\nAll other clusters connected to the repository should have the `readonly` parameter set to `true`.\n\nIf `false`, the cluster can write to the repository and create snapshots in it.\n\nIMPORTANT: If you register the same snapshot repository with multiple clusters, only one cluster should have write access to the repository.\nHaving multiple clusters write to the repository at the same time risks corrupting the contents of the repository.", "type": "boolean" } }, @@ -87549,6 +87666,10 @@ "type": "object", "properties": { "type": { + "externalDocs": { + "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/snapshots-read-only-repository.html" + }, + "description": "The read-only URL repository type.", "type": "string", "enum": [ "url" @@ -87574,15 +87695,18 @@ "type": "object", "properties": { "http_max_retries": { + "description": "The maximum number of retries for HTTP and HTTPS URLs.", "type": "number" }, "http_socket_timeout": { "$ref": "#/components/schemas/_types:Duration" }, "max_number_of_snapshots": { + "description": "The maximum number of snapshots the repository can contain.\nThe default is `Integer.MAX_VALUE`, which is 2^31-1 or `2147483647`.", "type": "number" }, "url": { + "description": "The URL location of the root of the shared filesystem repository.\nThe following protocols are supported:\n\n* `file`\n* `ftp`\n* `http`\n* `https`\n* `jar`\n\nURLs using the HTTP, HTTPS, or FTP protocols must be explicitly allowed with the `repositories.url.allowed_urls` cluster setting.\nThis setting supports wildcards in the place of a host, path, query, or fragment in the URL.\n\nURLs using the file protocol must point to the location of a shared filesystem accessible to all master and data nodes in the cluster.\nThis location must be registered in the `path.repo` setting.\nYou don't need to register URLs using the FTP, HTTP, HTTPS, or JAR protocols in the `path.repo` setting.", "type": "string" } }, @@ -87601,6 +87725,10 @@ "type": "object", "properties": { "type": { + "externalDocs": { + "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/snapshots-source-only-repository.html" + }, + "description": "The source-only repository type.", "type": "string", "enum": [ "source" @@ -87626,12 +87754,15 @@ "type": "object", "properties": { "delegate_type": { + "description": "The delegated repository type. For valid values, refer to the `type` parameter.\nSource repositories can use `settings` properties for its delegated repository type.", "type": "string" }, "max_number_of_snapshots": { + "description": "The maximum number of snapshots the repository can contain.\nThe default is `Integer.MAX_VALUE`, which is 2^31-1 or `2147483647`.", "type": "number" }, "read_only": { + "description": "If `true`, the repository is read-only.\nThe cluster can retrieve and restore snapshots from the repository but not write to the repository or create snapshots in it.\n\nOnly a cluster with write access can create snapshots in the repository.\nAll other clusters connected to the repository should have the `readonly` parameter set to `true`.\n\nIf `false`, the cluster can write to the repository and create snapshots in it.\n\nIMPORTANT: If you register the same snapshot repository with multiple clusters, only one cluster should have write access to the repository.\nHaving multiple clusters write to the repository at the same time risks corrupting the contents of the repository.", "type": "boolean" } } @@ -87696,6 +87827,7 @@ "type": "object", "properties": { "include_global_state": { + "description": "Indicates whether the current cluster state is included in the snapshot.", "type": "boolean" }, "indices": { @@ -87705,15 +87837,18 @@ } }, "repository": { + "description": "The name of the repository that includes the snapshot.", "type": "string" }, "shards_stats": { "$ref": "#/components/schemas/snapshot._types:ShardsStats" }, "snapshot": { + "description": "The name of the snapshot.", "type": "string" }, "state": { + "description": "The current snapshot state:\n\n* `FAILED`: The snapshot finished with an error and failed to store any data.\n* `STARTED`: The snapshot is currently running.\n* `SUCCESS`: The snapshot completed.", "type": "string" }, "stats": { @@ -87826,21 +87961,27 @@ "type": "object", "properties": { "done": { + "description": "The number of shards that initialized, started, and finalized successfully.", "type": "number" }, "failed": { + "description": "The number of shards that failed to be included in the snapshot.", "type": "number" }, "finalizing": { + "description": "The number of shards that are finalizing but are not done.", "type": "number" }, "initializing": { + "description": "The number of shards that are still initializing.", "type": "number" }, "started": { + "description": "The number of shards that have started but are not finalized.", "type": "number" }, "total": { + "description": "The total number of shards included in the snapshot.", "type": "number" } }, @@ -104670,7 +104811,7 @@ "snapshot.create#repository": { "in": "path", "name": "repository", - "description": "Repository for the snapshot.", + "description": "The name of the repository for the snapshot.", "required": true, "deprecated": false, "schema": { @@ -104681,7 +104822,7 @@ "snapshot.create#snapshot": { "in": "path", "name": "snapshot", - "description": "Name of the snapshot. Must be unique in the repository.", + "description": "The name of the snapshot.\nIt supportes date math.\nIt must be unique in the repository.", "required": true, "deprecated": false, "schema": { @@ -104692,7 +104833,7 @@ "snapshot.create#master_timeout": { "in": "query", "name": "master_timeout", - "description": "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.", + "description": "The period to wait for a connection to the master node.\nIf no response is received before the timeout expires, the request fails and returns an error.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Duration" @@ -104702,7 +104843,7 @@ "snapshot.create#wait_for_completion": { "in": "query", "name": "wait_for_completion", - "description": "If `true`, the request returns a response when the snapshot is complete. If `false`, the request returns a response when the snapshot initializes.", + "description": "If `true`, the request returns a response when the snapshot is complete.\nIf `false`, the request returns a response when the snapshot initializes.", "deprecated": false, "schema": { "type": "boolean" @@ -104712,7 +104853,7 @@ "snapshot.create_repository#repository": { "in": "path", "name": "repository", - "description": "A repository name", + "description": "The name of the snapshot repository to register or update.", "required": true, "deprecated": false, "schema": { @@ -104723,7 +104864,7 @@ "snapshot.create_repository#master_timeout": { "in": "query", "name": "master_timeout", - "description": "Explicit operation timeout for connection to master node", + "description": "The period to wait for the master node.\nIf the master node is not available before the timeout expires, the request fails and returns an error.\nTo indicate that the request should never timeout, set it to `-1`.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Duration" @@ -104733,7 +104874,7 @@ "snapshot.create_repository#timeout": { "in": "query", "name": "timeout", - "description": "Explicit operation timeout", + "description": "The period to wait for a response from all relevant nodes in the cluster after updating the cluster metadata.\nIf 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.\nTo indicate that the request should never timeout, set it to `-1`.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Duration" @@ -104743,7 +104884,7 @@ "snapshot.create_repository#verify": { "in": "query", "name": "verify", - "description": "Whether to verify the repository after creation", + "description": "If `true`, the request verifies the repository is functional on all master and data nodes in the cluster.\nIf `false`, this verification is skipped.\nYou can also perform this verification with the verify snapshot repository API.", "deprecated": false, "schema": { "type": "boolean" @@ -104753,7 +104894,7 @@ "snapshot.get_repository#repository": { "in": "path", "name": "repository", - "description": "A comma-separated list of repository names", + "description": "A comma-separated list of snapshot repository names used to limit the request.\nWildcard (`*`) expressions are supported including combining wildcards with exclude patterns starting with `-`.\n\nTo get information about all snapshot repositories registered in the cluster, omit this parameter or use `*` or `_all`.", "required": true, "deprecated": false, "schema": { @@ -104764,7 +104905,7 @@ "snapshot.get_repository#local": { "in": "query", "name": "local", - "description": "Return local information, do not retrieve the state from master node (default: false)", + "description": "If `true`, the request gets information from the local node only.\nIf `false`, the request gets information from the master node.", "deprecated": false, "schema": { "type": "boolean" @@ -104774,7 +104915,7 @@ "snapshot.get_repository#master_timeout": { "in": "query", "name": "master_timeout", - "description": "Explicit operation timeout for connection to master node", + "description": "The period to wait for the master node.\nIf the master node is not available before the timeout expires, the request fails and returns an error.\nTo indicate that the request should never timeout, set it to `-1`.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Duration" @@ -104784,7 +104925,7 @@ "snapshot.status#repository": { "in": "path", "name": "repository", - "description": "A repository name", + "description": "The snapshot repository name used to limit the request.\nIt supports wildcards (`*`) if `` isn't specified.", "required": true, "deprecated": false, "schema": { @@ -104795,7 +104936,7 @@ "snapshot.status#snapshot": { "in": "path", "name": "snapshot", - "description": "A comma-separated list of snapshot names", + "description": "A comma-separated list of snapshots to retrieve status for.\nThe default is currently running snapshots.\nWildcards (`*`) are not supported.", "required": true, "deprecated": false, "schema": { @@ -104806,7 +104947,7 @@ "snapshot.status#ignore_unavailable": { "in": "query", "name": "ignore_unavailable", - "description": "Whether to ignore unavailable snapshots, defaults to false which means a SnapshotMissingException is thrown", + "description": "If `false`, the request returns an error for any snapshots that are unavailable.\nIf `true`, the request ignores snapshots that are unavailable, such as those that are corrupted or temporarily cannot be returned.", "deprecated": false, "schema": { "type": "boolean" @@ -104816,7 +104957,7 @@ "snapshot.status#master_timeout": { "in": "query", "name": "master_timeout", - "description": "Explicit operation timeout for connection to master node", + "description": "The period to wait for the master node.\nIf the master node is not available before the timeout expires, the request fails and returns an error.\nTo indicate that the request should never timeout, set it to `-1`.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Duration" @@ -107945,29 +108086,35 @@ "schema": { "type": "object", "properties": { + "expand_wildcards": { + "$ref": "#/components/schemas/_types:ExpandWildcards" + }, + "feature_states": { + "externalDocs": { + "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/snapshot-restore.html#feature-state" + }, + "description": "The feature states to include in the snapshot.\nEach feature state includes one or more system indices containing related data.\nYou can view a list of eligible features using the get features API.\n\nIf `include_global_state` is `true`, all current feature states are included by default.\nIf `include_global_state` is `false`, no feature states are included by default.\n\nNote that specifying an empty array will result in the default behavior.\nTo exclude all feature states, regardless of the `include_global_state` value, specify an array with only the value `none` (`[\"none\"]`).", + "type": "array", + "items": { + "type": "string" + } + }, "ignore_unavailable": { - "description": "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.", + "description": "If `true`, the request ignores data streams and indices in `indices` that are missing or closed.\nIf `false`, the request returns an error for any data stream or index that is missing or closed.", "type": "boolean" }, "include_global_state": { - "description": "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`).", + "description": "If `true`, the current cluster state is included in the snapshot.\nThe cluster state includes persistent cluster settings, composable index templates, legacy index templates, ingest pipelines, and ILM policies.\nIt also includes data stored in system indices, such as Watches and task records (configurable via `feature_states`).", "type": "boolean" }, "indices": { "$ref": "#/components/schemas/_types:Indices" }, - "feature_states": { - "description": "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.", - "type": "array", - "items": { - "type": "string" - } - }, "metadata": { "$ref": "#/components/schemas/_types:Metadata" }, "partial": { - "description": "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.", + "description": "If `true`, it enables you to restore a partial snapshot of indices with unavailable shards.\nOnly shards that were successfully included in the snapshot will be restored.\nAll missing shards will be recreated as empty.\n\nIf `false`, the entire restore operation will fail if one or more indices included in the snapshot do not have all primary shards available.", "type": "boolean" } } diff --git a/output/schema/schema.json b/output/schema/schema.json index 8c8417be05..a353999155 100644 --- a/output/schema/schema.json +++ b/output/schema/schema.json @@ -18959,8 +18959,9 @@ "stability": "stable" } }, - "description": "Create or update a snapshot repository.\nIMPORTANT: If you are migrating searchable snapshots, the repository name must be identical in the source and destination clusters.\nTo register a snapshot repository, the cluster's global metadata must be writeable.\nEnsure there are no cluster blocks (for example, `cluster.blocks.read_only` and `clsuter.blocks.read_only_allow_delete` settings) that prevent write access.", - "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/master/modules-snapshots.html", + "description": "Create or update a snapshot repository.\nIMPORTANT: If you are migrating searchable snapshots, the repository name must be identical in the source and destination clusters.\nTo register a snapshot repository, the cluster's global metadata must be writeable.\nEnsure there are no cluster blocks (for example, `cluster.blocks.read_only` and `clsuter.blocks.read_only_allow_delete` settings) that prevent write access.\n\nSeveral options for this API can be specified using a query parameter or a request body parameter.\nIf both parameters are specified, only the query parameter is used.", + "docId": "snapshot-repo-create", + "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/put-snapshot-repo-api.html", "extDocId": "register-repository", "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/snapshots-register-repository.html", "name": "snapshot.create_repository", @@ -19086,7 +19087,7 @@ "stability": "stable" } }, - "description": "Get snapshot information.", + "description": "Get snapshot information.\n\nNOTE: The `after` parameter and `next` field enable you to iterate through snapshots with some consistency guarantees regarding concurrent creation or deletion of snapshots.\nIt is guaranteed that any snapshot that exists at the beginning of the iteration and is not concurrently deleted will be seen during the iteration.\nSnapshots concurrently created may be seen during an iteration.", "docId": "snapshot-get", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/get-snapshot-api.html", "name": "snapshot.get", @@ -19196,7 +19197,7 @@ "visibility": "private" } }, - "description": "Verify the repository integrity.\nVerify the integrity of the contents of a snapshot repository.\n\nThis 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.\n\nIf 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.\nUntil you do so:\n\n* It may not be possible to restore some snapshots from this repository.\n* Searchable snapshots may report errors when searched or may have unassigned shards.\n* Taking snapshots into this repository may fail or may appear to succeed but have created a snapshot which cannot be restored.\n* Deleting snapshots from this repository may fail or may appear to succeed but leave the underlying data on disk.\n* Continuing to write to the repository while it is in an invalid state may causing additional damage to its contents.\n\nIf the API finds any problems with the integrity of the contents of your repository, Elasticsearch will not be able to repair the damage.\nThe 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.\nYou must also identify what caused the damage and take action to prevent it from happening again.\n\nIf you cannot restore a repository backup, register a new repository and use this for all future snapshot operations.\nIn 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.\n\nAvoid all operations which write to the repository while the verify repository integrity API is running.\nIf 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.\nIt may also incorrectly fail to report some anomalies that the concurrent writes prevented it from detecting.\n\nNOTE: This API is intended for exploratory use by humans. You should expect the request parameters and the response format to vary in future versions.\n\nNOTE: This API may not work correctly in a mixed-version cluster.", + "description": "Verify the repository integrity.\nVerify the integrity of the contents of a snapshot repository.\n\nThis 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.\n\nIf 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.\nUntil you do so:\n\n* It may not be possible to restore some snapshots from this repository.\n* Searchable snapshots may report errors when searched or may have unassigned shards.\n* Taking snapshots into this repository may fail or may appear to succeed but have created a snapshot which cannot be restored.\n* Deleting snapshots from this repository may fail or may appear to succeed but leave the underlying data on disk.\n* Continuing to write to the repository while it is in an invalid state may causing additional damage to its contents.\n\nIf the API finds any problems with the integrity of the contents of your repository, Elasticsearch will not be able to repair the damage.\nThe 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.\nYou must also identify what caused the damage and take action to prevent it from happening again.\n\nIf you cannot restore a repository backup, register a new repository and use this for all future snapshot operations.\nIn 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.\n\nAvoid all operations which write to the repository while the verify repository integrity API is running.\nIf 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.\nIt may also incorrectly fail to report some anomalies that the concurrent writes prevented it from detecting.\n\nNOTE: This API is intended for exploratory use by humans. You should expect the request parameters and the response format to vary in future versions.\n\nNOTE: This API may not work correctly in a mixed-version cluster.\n\nThe default values for the parameters of this API are designed to limit the impact of the integrity verification on other activities in your cluster.\nFor 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.\nIf you modify these parameters to speed up the verification process, you risk disrupting other snapshot-related operations in your cluster.\nFor large repositories, consider setting up a separate single-node Elasticsearch cluster just for running the integrity verification API.\n\nThe response exposes implementation details of the analysis which may change from version to version.\nThe response body format is therefore not considered stable and may be different in newer versions.", "docId": "snapshot-repo-verify-integrity", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/verify-repo-integrity-api.html", "name": "snapshot.repository_verify_integrity", @@ -19283,7 +19284,7 @@ "stability": "stable" } }, - "description": "Get the snapshot status.\nGet a detailed description of the current state for each shard participating in the snapshot.\nNote that this API should be used only to obtain detailed shard-level information for ongoing snapshots.\nIf this detail is not needed or you want to obtain information about one or more existing snapshots, use the get snapshot API.\n\nWARNING: Using the API to return the status of any snapshots other than currently running snapshots can be expensive.\nThe API requires a read from the repository for each shard in each snapshot.\nFor 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).\n\nDepending on the latency of your storage, such requests can take an extremely long time to return results.\nThese requests can also tax machine resources and, when using cloud storage, incur high processing costs.", + "description": "Get the snapshot status.\nGet a detailed description of the current state for each shard participating in the snapshot.\n\nNote that this API should be used only to obtain detailed shard-level information for ongoing snapshots.\nIf this detail is not needed or you want to obtain information about one or more existing snapshots, use the get snapshot API.\n\nIf you omit the `` request path parameter, the request retrieves information only for currently running snapshots.\nThis usage is preferred.\nIf needed, you can specify `` and `` to retrieve information for specific snapshots, even if they're not currently running.\n\nWARNING: Using the API to return the status of any snapshots other than currently running snapshots can be expensive.\nThe API requires a read from the repository for each shard in each snapshot.\nFor 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).\n\nDepending on the latency of your storage, such requests can take an extremely long time to return results.\nThese requests can also tax machine resources and, when using cloud storage, incur high processing costs.", "docId": "snapshot-status", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/get-snapshot-status-api.html", "name": "snapshot.status", @@ -205805,6 +205806,9 @@ }, "properties": [ { + "description": "The Azure repository type.", + "extDocId": "repository-azure", + "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/repository-azure.html", "name": "type", "required": true, "type": { @@ -205813,6 +205817,7 @@ } }, { + "description": "The repository settings.", "name": "settings", "required": true, "type": { @@ -205824,7 +205829,7 @@ } } ], - "specLocation": "snapshot/_types/SnapshotRepository.ts#L40-L43" + "specLocation": "snapshot/_types/SnapshotRepository.ts#L40-L50" }, { "kind": "interface", @@ -205840,7 +205845,8 @@ }, "properties": [ { - "name": "client", + "description": "The path to the repository data within the container.\nIt defaults to the root directory.\n\nNOTE: Don't set `base_path` when configuring a snapshot repository for Elastic Cloud Enterprise.\nElastic Cloud Enterprise automatically generates the `base_path` for each deployment so that multiple deployments can share the same bucket.", + "name": "base_path", "required": false, "type": { "kind": "instance_of", @@ -205851,8 +205857,10 @@ } }, { - "name": "container", + "description": "The name of the Azure repository client to use.", + "name": "client", "required": false, + "serverDefault": "default", "type": { "kind": "instance_of", "type": { @@ -205862,8 +205870,10 @@ } }, { - "name": "base_path", + "description": "The Azure container.", + "name": "container", "required": false, + "serverDefault": "elasticsearch-snapshots", "type": { "kind": "instance_of", "type": { @@ -205873,19 +205883,23 @@ } }, { - "name": "readonly", + "description": "The maxmimum batch size, between 1 and 256, used for `BlobBatch` requests.\nDefaults to 256 which is the maximum number supported by the Azure blob batch API.", + "name": "delete_objects_max_size", "required": false, + "serverDefault": 256, "type": { "kind": "instance_of", "type": { - "name": "boolean", - "namespace": "_builtins" + "name": "integer", + "namespace": "_types" } } }, { + "description": "Either `primary_only` or `secondary_only`.\nNote that if you set it to `secondary_only`, it will force `readonly` to `true`.", "name": "location_mode", "required": false, + "serverDefault": "primary_only", "type": { "kind": "instance_of", "type": { @@ -205893,9 +205907,35 @@ "namespace": "_builtins" } } + }, + { + "description": "The maximum number of concurrent batch delete requests that will be submitted for any individual bulk delete with `BlobBatch`.\nNote that the effective number of concurrent deletes is further limited by the Azure client connection and event loop thread limits.\nDefaults to 10, minimum is 1, maximum is 100.", + "name": "max_concurrent_batch_deletes", + "required": false, + "serverDefault": 10, + "type": { + "kind": "instance_of", + "type": { + "name": "integer", + "namespace": "_types" + } + } + }, + { + "description": "If `true`, the repository is read-only.\nThe cluster can retrieve and restore snapshots from the repository but not write to the repository or create snapshots in it.\n\nOnly a cluster with write access can create snapshots in the repository.\nAll other clusters connected to the repository should have the `readonly` parameter set to `true`.\nIf `false`, the cluster can write to the repository and create snapshots in it.\n\nIMPORTANT: If you register the same snapshot repository with multiple clusters, only one cluster should have write access to the repository.\nHaving multiple clusters write to the repository at the same time risks corrupting the contents of the repository.", + "name": "readonly", + "required": false, + "serverDefault": false, + "type": { + "kind": "instance_of", + "type": { + "name": "boolean", + "namespace": "_builtins" + } + } } ], - "specLocation": "snapshot/_types/SnapshotRepository.ts#L77-L83" + "specLocation": "snapshot/_types/SnapshotRepository.ts#L145-L196" }, { "kind": "interface", @@ -205943,6 +205983,9 @@ }, "properties": [ { + "description": "The Google Cloud Storage repository type.", + "extDocId": "repository-gcs", + "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/repository-gcs.html", "name": "type", "required": true, "type": { @@ -205951,6 +205994,7 @@ } }, { + "description": "The repository settings.", "name": "settings", "required": true, "type": { @@ -205962,7 +206006,7 @@ } } ], - "specLocation": "snapshot/_types/SnapshotRepository.ts#L45-L48" + "specLocation": "snapshot/_types/SnapshotRepository.ts#L52-L62" }, { "kind": "interface", @@ -205978,6 +206022,7 @@ }, "properties": [ { + "description": "The name of the bucket to be used for snapshots.", "name": "bucket", "required": true, "type": { @@ -205989,7 +206034,12 @@ } }, { - "name": "client", + "deprecation": { + "description": "", + "version": "6.3.0" + }, + "description": "The name used by the client when it uses the Google Cloud Storage service.", + "name": "application_name", "required": false, "type": { "kind": "instance_of", @@ -206000,6 +206050,7 @@ } }, { + "description": "The path to the repository data within the bucket.\nIt defaults to the root of the bucket.\n\nNOTE: Don't set `base_path` when configuring a snapshot repository for Elastic Cloud Enterprise.\nElastic Cloud Enterprise automatically generates the `base_path` for each deployment so that multiple deployments can share the same bucket.", "name": "base_path", "required": false, "type": { @@ -206011,29 +206062,33 @@ } }, { - "name": "readonly", + "description": "The name of the client to use to connect to Google Cloud Storage.", + "name": "client", "required": false, + "serverDefault": "default", "type": { "kind": "instance_of", "type": { - "name": "boolean", + "name": "string", "namespace": "_builtins" } } }, { - "name": "application_name", + "description": "If `true`, the repository is read-only.\nThe cluster can retrieve and restore snapshots from the repository but not write to the repository or create snapshots in it.\n\nOnly a cluster with write access can create snapshots in the repository.\nAll other clusters connected to the repository should have the `readonly` parameter set to `true`.\n\nIf `false`, the cluster can write to the repository and create snapshots in it.\n\nIMPORTANT: If you register the same snapshot repository with multiple clusters, only one cluster should have write access to the repository.\nHaving multiple clusters write to the repository at the same time risks corrupting the contents of the repository.", + "name": "readonly", "required": false, + "serverDefault": false, "type": { "kind": "instance_of", "type": { - "name": "string", + "name": "boolean", "namespace": "_builtins" } } } ], - "specLocation": "snapshot/_types/SnapshotRepository.ts#L85-L91" + "specLocation": "snapshot/_types/SnapshotRepository.ts#L198-L235" }, { "kind": "interface", @@ -206135,6 +206190,9 @@ }, "properties": [ { + "description": "The read-only URL repository type.", + "extDocId": "repository-read-only", + "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/snapshots-read-only-repository.html", "name": "type", "required": true, "type": { @@ -206143,6 +206201,7 @@ } }, { + "description": "The repository settings.", "name": "settings", "required": true, "type": { @@ -206154,7 +206213,7 @@ } } ], - "specLocation": "snapshot/_types/SnapshotRepository.ts#L60-L63" + "specLocation": "snapshot/_types/SnapshotRepository.ts#L92-L102" }, { "kind": "interface", @@ -206170,8 +206229,10 @@ }, "properties": [ { + "description": "The maximum number of retries for HTTP and HTTPS URLs.", "name": "http_max_retries", "required": false, + "serverDefault": 5, "type": { "kind": "instance_of", "type": { @@ -206181,8 +206242,10 @@ } }, { + "description": "The maximum wait time for data transfers over a connection.", "name": "http_socket_timeout", "required": false, + "serverDefault": "50s", "type": { "kind": "instance_of", "type": { @@ -206192,8 +206255,10 @@ } }, { + "description": "The maximum number of snapshots the repository can contain.\nThe default is `Integer.MAX_VALUE`, which is 2^31-1 or `2147483647`.", "name": "max_number_of_snapshots", "required": false, + "serverDefault": 2147483647, "type": { "kind": "instance_of", "type": { @@ -206203,6 +206268,7 @@ } }, { + "description": "The URL location of the root of the shared filesystem repository.\nThe following protocols are supported:\n\n* `file`\n* `ftp`\n* `http`\n* `https`\n* `jar`\n\nURLs using the HTTP, HTTPS, or FTP protocols must be explicitly allowed with the `repositories.url.allowed_urls` cluster setting.\nThis setting supports wildcards in the place of a host, path, query, or fragment in the URL.\n\nURLs using the file protocol must point to the location of a shared filesystem accessible to all master and data nodes in the cluster.\nThis location must be registered in the `path.repo` setting.\nYou don't need to register URLs using the FTP, HTTP, HTTPS, or JAR protocols in the `path.repo` setting.", "name": "url", "required": true, "type": { @@ -206214,7 +206280,7 @@ } } ], - "specLocation": "snapshot/_types/SnapshotRepository.ts#L110-L115" + "specLocation": "snapshot/_types/SnapshotRepository.ts#L377-L412" }, { "kind": "type_alias", @@ -206305,6 +206371,7 @@ }, "properties": [ { + "description": "Big files can be broken down into multiple smaller blobs in the blob store during snapshotting.\nIt is not recommended to change this value from its default unless there is an explicit reason for limiting the size of blobs in the repository.\nSetting a value lower than the default can result in an increased number of API calls to the blob store during snapshot create and restore operations compared to using the default value and thus make both operations slower and more costly.\nSpecify the chunk size as a byte unit, for example: `10MB`, `5KB`, 500B.\nThe default varies by repository type.", "name": "chunk_size", "required": false, "type": { @@ -206316,8 +206383,10 @@ } }, { + "description": "When set to `true`, metadata files are stored in compressed format.\nThis setting doesn't affect index files that are already compressed by default.", "name": "compress", "required": false, + "serverDefault": true, "type": { "kind": "instance_of", "type": { @@ -206327,6 +206396,7 @@ } }, { + "description": "The maximum snapshot restore rate per node.\nIt defaults to unlimited.\nNote that restores are also throttled through recovery settings.", "name": "max_restore_bytes_per_sec", "required": false, "type": { @@ -206338,6 +206408,7 @@ } }, { + "description": "The maximum snapshot creation rate per node.\nIt defaults to 40mb per second.\nNote that if the recovery settings for managed services are set, then it defaults to unlimited, and the rate is additionally throttled through recovery settings.", "name": "max_snapshot_bytes_per_sec", "required": false, "type": { @@ -206349,7 +206420,7 @@ } } ], - "specLocation": "snapshot/_types/SnapshotRepository.ts#L70-L75" + "specLocation": "snapshot/_types/SnapshotRepository.ts#L116-L143" }, { "kind": "interface", @@ -206365,6 +206436,9 @@ }, "properties": [ { + "description": "The S3 repository type.", + "extDocId": "repository-s3", + "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/repository-s3.html", "name": "type", "required": true, "type": { @@ -206373,6 +206447,7 @@ } }, { + "description": "The repository settings.\n\nNOTE: In addition to the specified settings, you can also use all non-secure client settings in the repository settings.\nIn this case, the client settings found in the repository settings will be merged with those of the named client used by the repository.\nConflicts between client and repository settings are resolved by the repository settings taking precedence over client settings.", "name": "settings", "required": true, "type": { @@ -206384,7 +206459,7 @@ } } ], - "specLocation": "snapshot/_types/SnapshotRepository.ts#L50-L53" + "specLocation": "snapshot/_types/SnapshotRepository.ts#L64-L78" }, { "kind": "interface", @@ -206400,6 +206475,9 @@ }, "properties": [ { + "description": "The name of the S3 bucket to use for snapshots.\nThe bucket name must adhere to Amazon's S3 bucket naming rules.", + "extDocId": "repository-s3-naming", + "extDocUrl": "https://docs.aws.amazon.com/AmazonS3/latest/userguide/BucketRestrictions.html#bucketnamingrules", "name": "bucket", "required": true, "type": { @@ -206411,7 +206489,8 @@ } }, { - "name": "client", + "description": "The path to the repository data within its bucket.\nIt defaults to an empty string, meaning that the repository is at the root of the bucket.\nThe value of this setting should not start or end with a forward slash (`/`).\n\nNOTE: Don't set base_path when configuring a snapshot repository for Elastic Cloud Enterprise.\nElastic Cloud Enterprise automatically generates the `base_path` for each deployment so that multiple deployments may share the same bucket.", + "name": "base_path", "required": false, "type": { "kind": "instance_of", @@ -206422,8 +206501,37 @@ } }, { - "name": "base_path", + "description": "The minimum threshold below which the chunk is uploaded using a single request.\nBeyond this threshold, the S3 repository will use the AWS Multipart Upload API to split the chunk into several parts, each of `buffer_size` length, and to upload each part in its own request.\nNote that setting a buffer size lower than 5mb is not allowed since it will prevent the use of the Multipart API and may result in upload errors.\nIt is also not possible to set a buffer size greater than 5gb as it is the maximum upload size allowed by S3.\nDefaults to `100mb` or 5% of JVM heap, whichever is smaller.", + "name": "buffer_size", + "required": false, + "type": { + "kind": "instance_of", + "type": { + "name": "ByteSize", + "namespace": "_types" + } + } + }, + { + "description": "The S3 repository supports all S3 canned ACLs: `private`, `public-read`, `public-read-write`, `authenticated-read`, `log-delivery-write`, `bucket-owner-read`, `bucket-owner-full-control`.\nYou could specify a canned ACL using the `canned_acl` setting.\nWhen the S3 repository creates buckets and objects, it adds the canned ACL into the buckets and objects.", + "extDocId": "repository-s3-canned-acl", + "extDocUrl": "https://docs.aws.amazon.com/AmazonS3/latest/userguide/acl-overview.html#canned-acl", + "name": "canned_acl", + "required": false, + "serverDefault": "private", + "type": { + "kind": "instance_of", + "type": { + "name": "string", + "namespace": "_builtins" + } + } + }, + { + "description": "The name of the S3 client to use to connect to S3.", + "name": "client", "required": false, + "serverDefault": "default", "type": { "kind": "instance_of", "type": { @@ -206433,8 +206541,66 @@ } }, { + "description": "The maxmimum batch size, between 1 and 1000, used for `DeleteObjects` requests.\nDefaults to 1000 which is the maximum number supported by the AWS DeleteObjects API.", + "extDocId": "repository-s3-delete-objects", + "extDocUrl": "https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteObjects.html", + "name": "delete_objects_max_size", + "required": false, + "serverDefault": 1000, + "type": { + "kind": "instance_of", + "type": { + "name": "integer", + "namespace": "_types" + } + } + }, + { + "description": "The time to wait before trying again if an attempt to read a linearizable register fails.", + "name": "get_register_retry_delay", + "required": false, + "serverDefault": "5s", + "type": { + "kind": "instance_of", + "type": { + "name": "Duration", + "namespace": "_types" + } + } + }, + { + "description": "The maximum number of parts that Elasticsearch will write during a multipart upload of a single object.\nFiles which are larger than `buffer_size × max_multipart_parts` will be chunked into several smaller objects.\nElasticsearch may also split a file across multiple objects to satisfy other constraints such as the `chunk_size` limit.\nDefaults to `10000` which is the maximum number of parts in a multipart upload in AWS S3.", + "name": "max_multipart_parts", + "required": false, + "serverDefault": 10000, + "type": { + "kind": "instance_of", + "type": { + "name": "integer", + "namespace": "_types" + } + } + }, + { + "description": "The maximum number of possibly-dangling multipart uploads to clean up in each batch of snapshot deletions.\nDefaults to 1000 which is the maximum number supported by the AWS ListMultipartUploads API.\nIf set to `0`, Elasticsearch will not attempt to clean up dangling multipart uploads.", + "extDocId": "repository-s3-list-multipart", + "extDocUrl": "https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListMultipartUploads.html", + "name": "max_multipart_upload_cleanup_size", + "required": false, + "serverDefault": 1000, + "type": { + "kind": "instance_of", + "type": { + "name": "integer", + "namespace": "_types" + } + } + }, + { + "description": "If true, the repository is read-only.\nThe cluster can retrieve and restore snapshots from the repository but not write to the repository or create snapshots in it.\n\nOnly a cluster with write access can create snapshots in the repository.\nAll other clusters connected to the repository should have the `readonly` parameter set to `true`.\n\nIf `false`, the cluster can write to the repository and create snapshots in it.\n\nIMPORTANT: If you register the same snapshot repository with multiple clusters, only one cluster should have write access to the repository.\nHaving multiple clusters write to the repository at the same time risks corrupting the contents of the repository.", "name": "readonly", "required": false, + "serverDefault": false, "type": { "kind": "instance_of", "type": { @@ -206444,6 +206610,7 @@ } }, { + "description": "When set to `true`m files are encrypted on server side using an AES256 algorithm.\nserver_default false", "name": "server_side_encryption", "required": false, "type": { @@ -206455,40 +206622,60 @@ } }, { - "name": "buffer_size", + "description": "The S3 storage class for objects written to the repository.\nValues may be `standard`, `reduced_redundancy`, `standard_ia`, `onezone_ia`, and `intelligent_tiering`.", + "extDocId": "repository-s3-storage-classes", + "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/repository-s3.html#repository-s3-storage-classes", + "name": "storage_class", "required": false, + "serverDefault": "standard", "type": { "kind": "instance_of", "type": { - "name": "ByteSize", + "name": "string", + "namespace": "_builtins" + } + } + }, + { + "description": "The delay before the first retry and the amount the delay is incremented by on each subsequent retry.\nThe default is 50ms and the minimum is 0ms.", + "name": "throttled_delete_retry.delay_increment", + "required": false, + "serverDefault": "50ms", + "type": { + "kind": "instance_of", + "type": { + "name": "Duration", "namespace": "_types" } } }, { - "name": "canned_acl", + "description": "The upper bound on how long the delays between retries will grow to.\nThe default is 5s and the minimum is 0ms.", + "name": "throttled_delete_retry.maximum_delay", "required": false, + "serverDefault": "5s", "type": { "kind": "instance_of", "type": { - "name": "string", - "namespace": "_builtins" + "name": "Duration", + "namespace": "_types" } } }, { - "name": "storage_class", + "description": "The number times to retry a throttled snapshot deletion.\nThe default is 10 and the minimum value is 0 which will disable retries altogether.\nNote that if retries are enabled in the Azure client, each of these retries comprises that many client-level retries.", + "name": "throttled_delete_retry.maximum_number_of_retries", "required": false, "type": { "kind": "instance_of", "type": { - "name": "string", - "namespace": "_builtins" + "name": "integer", + "namespace": "_types" } } } ], - "specLocation": "snapshot/_types/SnapshotRepository.ts#L93-L102" + "specLocation": "snapshot/_types/SnapshotRepository.ts#L237-L346" }, { "kind": "interface", @@ -206498,6 +206685,7 @@ }, "properties": [ { + "description": "The number of shards that initialized, started, and finalized successfully.", "name": "done", "required": true, "type": { @@ -206509,6 +206697,7 @@ } }, { + "description": "The number of shards that failed to be included in the snapshot.", "name": "failed", "required": true, "type": { @@ -206520,6 +206709,7 @@ } }, { + "description": "The number of shards that are finalizing but are not done.", "name": "finalizing", "required": true, "type": { @@ -206531,6 +206721,7 @@ } }, { + "description": "The number of shards that are still initializing.", "name": "initializing", "required": true, "type": { @@ -206542,6 +206733,7 @@ } }, { + "description": "The number of shards that have started but are not finalized.", "name": "started", "required": true, "type": { @@ -206553,6 +206745,7 @@ } }, { + "description": "The total number of shards included in the snapshot.", "name": "total", "required": true, "type": { @@ -206564,29 +206757,29 @@ } } ], - "specLocation": "snapshot/_types/SnapshotShardsStats.ts#L22-L29" + "specLocation": "snapshot/_types/SnapshotShardsStats.ts#L22-L47" }, { "kind": "enum", "members": [ { - "description": "Number of shards in the snapshot that were successfully stored in the repository.", + "description": "The number of shards in the snapshot that were successfully stored in the repository.", "name": "DONE" }, { - "description": "Number of shards in the snapshot that were not successfully stored in the repository.", + "description": "The number of shards in the snapshot that were not successfully stored in the repository.", "name": "FAILURE" }, { - "description": "Number of shards in the snapshot that are in the finalizing stage of being stored in the repository.", + "description": "The number of shards in the snapshot that are in the finalizing stage of being stored in the repository.", "name": "FINALIZE" }, { - "description": "Number of shards in the snapshot that are in the initializing stage of being stored in the repository.", + "description": "The number of shards in the snapshot that are in the initializing stage of being stored in the repository.", "name": "INIT" }, { - "description": "Number of shards in the snapshot that are in the started stage of being stored in the repository.", + "description": "The number of shards in the snapshot that are in the started stage of being stored in the repository.", "name": "STARTED" } ], @@ -206725,6 +206918,9 @@ }, "properties": [ { + "description": "The shared file system repository type.", + "extDocId": "repository-shared-fs", + "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/snapshots-filesystem-repository.html", "name": "type", "required": true, "type": { @@ -206733,6 +206929,7 @@ } }, { + "description": "The repository settings.", "name": "settings", "required": true, "type": { @@ -206744,7 +206941,7 @@ } } ], - "specLocation": "snapshot/_types/SnapshotRepository.ts#L55-L58" + "specLocation": "snapshot/_types/SnapshotRepository.ts#L80-L90" }, { "kind": "interface", @@ -206760,6 +206957,7 @@ }, "properties": [ { + "description": "The location of the shared filesystem used to store and retrieve snapshots.\nThis location must be registered in the `path.repo` setting on all master and data nodes in the cluster.\nUnlike `path.repo`, this setting supports only a single file path.", "name": "location", "required": true, "type": { @@ -206771,8 +206969,10 @@ } }, { + "description": "The maximum number of snapshots the repository can contain.\nThe default is `Integer.MAX_VALUE`, which is 2^31-1 or `2147483647`.", "name": "max_number_of_snapshots", "required": false, + "serverDefault": 2147483647, "type": { "kind": "instance_of", "type": { @@ -206782,8 +206982,10 @@ } }, { + "description": "If `true`, the repository is read-only.\nThe cluster can retrieve and restore snapshots from the repository but not write to the repository or create snapshots in it.\n\nOnly a cluster with write access can create snapshots in the repository.\nAll other clusters connected to the repository should have the `readonly` parameter set to `true`.\n\nIf `false`, the cluster can write to the repository and create snapshots in it.\n\nIMPORTANT: If you register the same snapshot repository with multiple clusters, only one cluster should have write access to the repository.\nHaving multiple clusters write to the repository at the same time risks corrupting the contents of the repository.", "name": "readonly", "required": false, + "serverDefault": false, "type": { "kind": "instance_of", "type": { @@ -206793,7 +206995,7 @@ } } ], - "specLocation": "snapshot/_types/SnapshotRepository.ts#L104-L108" + "specLocation": "snapshot/_types/SnapshotRepository.ts#L348-L375" }, { "kind": "interface", @@ -207317,6 +207519,7 @@ }, "properties": [ { + "description": "The number and size of files that still need to be copied as part of the incremental snapshot.\nFor completed snapshots, this property indicates the number and size of files that were not already in the repository and were copied as part of the incremental snapshot.", "name": "incremental", "required": true, "type": { @@ -207328,6 +207531,7 @@ } }, { + "description": "The time, in milliseconds, when the snapshot creation process started.", "name": "start_time_in_millis", "required": true, "type": { @@ -207359,6 +207563,7 @@ } }, { + "description": "The total time, in milliseconds, that it took for the snapshot process to complete.", "name": "time_in_millis", "required": true, "type": { @@ -207379,6 +207584,7 @@ } }, { + "description": "The total number and size of files that are referenced by the snapshot.", "name": "total", "required": true, "type": { @@ -207390,7 +207596,7 @@ } } ], - "specLocation": "snapshot/_types/SnapshotStats.ts#L23-L29" + "specLocation": "snapshot/_types/SnapshotStats.ts#L23-L42" }, { "kind": "interface", @@ -207406,6 +207612,9 @@ }, "properties": [ { + "description": "The source-only repository type.", + "extDocId": "repository-source-only", + "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/snapshots-source-only-repository.html", "name": "type", "required": true, "type": { @@ -207414,6 +207623,7 @@ } }, { + "description": "The repository settings.", "name": "settings", "required": true, "type": { @@ -207425,7 +207635,7 @@ } } ], - "specLocation": "snapshot/_types/SnapshotRepository.ts#L65-L68" + "specLocation": "snapshot/_types/SnapshotRepository.ts#L104-L114" }, { "kind": "interface", @@ -207441,6 +207651,7 @@ }, "properties": [ { + "description": "The delegated repository type. For valid values, refer to the `type` parameter.\nSource repositories can use `settings` properties for its delegated repository type.", "name": "delegate_type", "required": false, "type": { @@ -207452,8 +207663,10 @@ } }, { + "description": "The maximum number of snapshots the repository can contain.\nThe default is `Integer.MAX_VALUE`, which is 2^31-1 or `2147483647`.", "name": "max_number_of_snapshots", "required": false, + "serverDefault": 2147483647, "type": { "kind": "instance_of", "type": { @@ -207466,8 +207679,10 @@ "aliases": [ "readonly" ], + "description": "If `true`, the repository is read-only.\nThe cluster can retrieve and restore snapshots from the repository but not write to the repository or create snapshots in it.\n\nOnly a cluster with write access can create snapshots in the repository.\nAll other clusters connected to the repository should have the `readonly` parameter set to `true`.\n\nIf `false`, the cluster can write to the repository and create snapshots in it.\n\nIMPORTANT: If you register the same snapshot repository with multiple clusters, only one cluster should have write access to the repository.\nHaving multiple clusters write to the repository at the same time risks corrupting the contents of the repository.", "name": "read_only", "required": false, + "serverDefault": false, "type": { "kind": "instance_of", "type": { @@ -207477,7 +207692,7 @@ } } ], - "specLocation": "snapshot/_types/SnapshotRepository.ts#L117-L124" + "specLocation": "snapshot/_types/SnapshotRepository.ts#L414-L441" }, { "kind": "interface", @@ -207487,6 +207702,7 @@ }, "properties": [ { + "description": "Indicates whether the current cluster state is included in the snapshot.", "name": "include_global_state", "required": true, "type": { @@ -207520,6 +207736,7 @@ } }, { + "description": "The name of the repository that includes the snapshot.", "name": "repository", "required": true, "type": { @@ -207531,6 +207748,7 @@ } }, { + "description": "Statistics for the shards in the snapshot.", "name": "shards_stats", "required": true, "type": { @@ -207542,6 +207760,7 @@ } }, { + "description": "The name of the snapshot.", "name": "snapshot", "required": true, "type": { @@ -207553,6 +207772,7 @@ } }, { + "description": "The current snapshot state:\n\n* `FAILED`: The snapshot finished with an error and failed to store any data.\n* `STARTED`: The snapshot is currently running.\n* `SUCCESS`: The snapshot completed.", "name": "state", "required": true, "type": { @@ -207564,6 +207784,7 @@ } }, { + "description": "Details about the number (`file_count`) and size (`size_in_bytes`) of files included in the snapshot.", "name": "stats", "required": true, "type": { @@ -207575,6 +207796,7 @@ } }, { + "description": "The universally unique identifier (UUID) for the snapshot.", "name": "uuid", "required": true, "type": { @@ -207586,7 +207808,7 @@ } } ], - "specLocation": "snapshot/_types/SnapshotStatus.ts#L26-L35" + "specLocation": "snapshot/_types/SnapshotStatus.ts#L26-L60" }, { "kind": "interface", @@ -207596,7 +207818,7 @@ }, "properties": [ { - "description": "Number of binary large objects (blobs) removed during cleanup.", + "description": "The number of binary large objects (blobs) removed from the snapshot repository during cleanup operations.\nA non-zero value indicates that unreferenced blobs were found and subsequently cleaned up.", "name": "deleted_blobs", "required": true, "type": { @@ -207608,7 +207830,7 @@ } }, { - "description": "Number of bytes freed by cleanup operations.", + "description": "The number of bytes freed by cleanup operations.", "name": "deleted_bytes", "required": true, "type": { @@ -207620,7 +207842,7 @@ } } ], - "specLocation": "snapshot/cleanup_repository/SnapshotCleanupRepositoryResponse.ts#L29-L34" + "specLocation": "snapshot/cleanup_repository/SnapshotCleanupRepositoryResponse.ts#L29-L37" }, { "kind": "request", @@ -207644,7 +207866,7 @@ "path": [ { "codegenName": "name", - "description": "Snapshot repository to clean up.", + "description": "The name of the snapshot repository to clean up.", "name": "repository", "required": true, "type": { @@ -207658,7 +207880,7 @@ ], "query": [ { - "description": "Period to wait for a connection to the master node.", + "description": "The period to wait for a connection to the master node.\nIf the master node is not available before the timeout expires, the request fails and returns an error.\nTo indicate that the request should never timeout, set it to `-1`", "name": "master_timeout", "required": false, "serverDefault": "30s", @@ -207671,7 +207893,7 @@ } }, { - "description": "Period to wait for a response.", + "description": "The period to wait for a response from all relevant nodes in the cluster after updating the cluster metadata.\nIf 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.\nTo indicate that the request should never timeout, set it to `-1`.", "name": "timeout", "required": false, "serverDefault": "30s", @@ -207684,7 +207906,7 @@ } } ], - "specLocation": "snapshot/cleanup_repository/SnapshotCleanupRepositoryRequest.ts#L24-L53" + "specLocation": "snapshot/cleanup_repository/SnapshotCleanupRepositoryRequest.ts#L24-L57" }, { "kind": "response", @@ -207720,6 +207942,7 @@ "kind": "properties", "properties": [ { + "description": "A comma-separated list of indices to include in the snapshot.\nMulti-target syntax is supported.", "name": "indices", "required": true, "type": { @@ -207745,7 +207968,7 @@ }, "path": [ { - "description": "A repository name", + "description": "The name of the snapshot repository that both source and target snapshot belong to.", "name": "repository", "required": true, "type": { @@ -207757,7 +207980,7 @@ } }, { - "description": "The name of the snapshot to clone from", + "description": "The source snapshot name.", "name": "snapshot", "required": true, "type": { @@ -207769,7 +207992,7 @@ } }, { - "description": "The name of the cloned snapshot to create", + "description": "The target snapshot name.", "name": "target_snapshot", "required": true, "type": { @@ -207783,9 +208006,23 @@ ], "query": [ { - "description": "Explicit operation timeout for connection to master node", + "description": "The period to wait for the master node.\nIf the master node is not available before the timeout expires, the request fails and returns an error.\nTo indicate that the request should never timeout, set it to `-1`.", "name": "master_timeout", "required": false, + "serverDefault": "30s", + "type": { + "kind": "instance_of", + "type": { + "name": "Duration", + "namespace": "_types" + } + } + }, + { + "description": "The period of time to wait for a response.\nIf no response is received before the timeout expires, the request fails and returns an error.", + "name": "timeout", + "required": false, + "serverDefault": "30s", "type": { "kind": "instance_of", "type": { @@ -207795,7 +208032,7 @@ } } ], - "specLocation": "snapshot/clone/SnapshotCloneRequest.ts#L24-L45" + "specLocation": "snapshot/clone/SnapshotCloneRequest.ts#L24-L70" }, { "kind": "response", @@ -207824,7 +208061,37 @@ "kind": "properties", "properties": [ { - "description": "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.", + "description": "Determines how wildcard patterns in the `indices` parameter match data streams and indices.\nIt supports comma-separated values such as `open,hidden`.", + "name": "expand_wildcards", + "required": false, + "serverDefault": "all", + "type": { + "kind": "instance_of", + "type": { + "name": "ExpandWildcards", + "namespace": "_types" + } + } + }, + { + "description": "The feature states to include in the snapshot.\nEach feature state includes one or more system indices containing related data.\nYou can view a list of eligible features using the get features API.\n\nIf `include_global_state` is `true`, all current feature states are included by default.\nIf `include_global_state` is `false`, no feature states are included by default.\n\nNote that specifying an empty array will result in the default behavior.\nTo exclude all feature states, regardless of the `include_global_state` value, specify an array with only the value `none` (`[\"none\"]`).", + "extDocId": "snapshot-restore-feature-state", + "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/snapshot-restore.html#feature-state", + "name": "feature_states", + "required": false, + "type": { + "kind": "array_of", + "value": { + "kind": "instance_of", + "type": { + "name": "string", + "namespace": "_builtins" + } + } + } + }, + { + "description": "If `true`, the request ignores data streams and indices in `indices` that are missing or closed.\nIf `false`, the request returns an error for any data stream or index that is missing or closed.", "name": "ignore_unavailable", "required": false, "serverDefault": false, @@ -207837,7 +208104,7 @@ } }, { - "description": "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`).", + "description": "If `true`, the current cluster state is included in the snapshot.\nThe cluster state includes persistent cluster settings, composable index templates, legacy index templates, ingest pipelines, and ILM policies.\nIt also includes data stored in system indices, such as Watches and task records (configurable via `feature_states`).", "name": "include_global_state", "required": false, "serverDefault": true, @@ -207850,7 +208117,7 @@ } }, { - "description": "Data streams and indices to include in the snapshot. Supports multi-target syntax. Includes all data streams and indices by default.", + "description": "A comma-separated list of data streams and indices to include in the snapshot.\nIt supports a multi-target syntax.\nThe default is an empty array (`[]`), which includes all regular data streams and regular indices.\nTo exclude all data streams and indices, use `-*`.\n\nYou can't use this parameter to include or exclude system indices or system data streams from a snapshot.\nUse `feature_states` instead.", "name": "indices", "required": false, "type": { @@ -207862,22 +208129,7 @@ } }, { - "description": "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.", - "name": "feature_states", - "required": false, - "type": { - "kind": "array_of", - "value": { - "kind": "instance_of", - "type": { - "name": "string", - "namespace": "_builtins" - } - } - } - }, - { - "description": "Optional metadata for the snapshot. May have any contents. Must be less than 1024 bytes. This map is not automatically generated by Elasticsearch.", + "description": "Arbitrary metadata to the snapshot, such as a record of who took the snapshot, why it was taken, or any other useful data.\nIt can have any contents but it must be less than 1024 bytes.\nThis information is not automatically generated by Elasticsearch.", "name": "metadata", "required": false, "type": { @@ -207889,7 +208141,7 @@ } }, { - "description": "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.", + "description": "If `true`, it enables you to restore a partial snapshot of indices with unavailable shards.\nOnly shards that were successfully included in the snapshot will be restored.\nAll missing shards will be recreated as empty.\n\nIf `false`, the entire restore operation will fail if one or more indices included in the snapshot do not have all primary shards available.", "name": "partial", "required": false, "serverDefault": false, @@ -207916,7 +208168,7 @@ }, "path": [ { - "description": "Repository for the snapshot.", + "description": "The name of the repository for the snapshot.", "name": "repository", "required": true, "type": { @@ -207928,7 +208180,7 @@ } }, { - "description": "Name of the snapshot. Must be unique in the repository.", + "description": "The name of the snapshot.\nIt supportes date math.\nIt must be unique in the repository.", "name": "snapshot", "required": true, "type": { @@ -207942,7 +208194,7 @@ ], "query": [ { - "description": "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.", + "description": "The period to wait for a connection to the master node.\nIf no response is received before the timeout expires, the request fails and returns an error.", "name": "master_timeout", "required": false, "serverDefault": "30s", @@ -207955,7 +208207,7 @@ } }, { - "description": "If `true`, the request returns a response when the snapshot is complete. If `false`, the request returns a response when the snapshot initializes.", + "description": "If `true`, the request returns a response when the snapshot is complete.\nIf `false`, the request returns a response when the snapshot initializes.", "name": "wait_for_completion", "required": false, "serverDefault": false, @@ -207968,7 +208220,7 @@ } } ], - "specLocation": "snapshot/create/SnapshotCreateRequest.ts#L24-L86" + "specLocation": "snapshot/create/SnapshotCreateRequest.ts#L24-L120" }, { "kind": "response", @@ -208029,7 +208281,7 @@ } } }, - "description": "Create or update a snapshot repository.\nIMPORTANT: If you are migrating searchable snapshots, the repository name must be identical in the source and destination clusters.\nTo register a snapshot repository, the cluster's global metadata must be writeable.\nEnsure there are no cluster blocks (for example, `cluster.blocks.read_only` and `clsuter.blocks.read_only_allow_delete` settings) that prevent write access.", + "description": "Create or update a snapshot repository.\nIMPORTANT: If you are migrating searchable snapshots, the repository name must be identical in the source and destination clusters.\nTo register a snapshot repository, the cluster's global metadata must be writeable.\nEnsure there are no cluster blocks (for example, `cluster.blocks.read_only` and `clsuter.blocks.read_only_allow_delete` settings) that prevent write access.\n\nSeveral options for this API can be specified using a query parameter or a request body parameter.\nIf both parameters are specified, only the query parameter is used.", "inherits": { "type": { "name": "RequestBase", @@ -208043,7 +208295,7 @@ "path": [ { "codegenName": "name", - "description": "A repository name", + "description": "The name of the snapshot repository to register or update.", "name": "repository", "required": true, "type": { @@ -208057,9 +208309,10 @@ ], "query": [ { - "description": "Explicit operation timeout for connection to master node", + "description": "The period to wait for the master node.\nIf the master node is not available before the timeout expires, the request fails and returns an error.\nTo indicate that the request should never timeout, set it to `-1`.", "name": "master_timeout", "required": false, + "serverDefault": "30s", "type": { "kind": "instance_of", "type": { @@ -208069,9 +208322,10 @@ } }, { - "description": "Explicit operation timeout", + "description": "The period to wait for a response from all relevant nodes in the cluster after updating the cluster metadata.\nIf 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.\nTo indicate that the request should never timeout, set it to `-1`.", "name": "timeout", "required": false, + "serverDefault": "30s", "type": { "kind": "instance_of", "type": { @@ -208081,9 +208335,10 @@ } }, { - "description": "Whether to verify the repository after creation", + "description": "If `true`, the request verifies the repository is functional on all master and data nodes in the cluster.\nIf `false`, this verification is skipped.\nYou can also perform this verification with the verify snapshot repository API.", "name": "verify", "required": false, + "serverDefault": true, "type": { "kind": "instance_of", "type": { @@ -208093,7 +208348,7 @@ } } ], - "specLocation": "snapshot/create_repository/SnapshotCreateRepositoryRequest.ts#L25-L48" + "specLocation": "snapshot/create_repository/SnapshotCreateRepositoryRequest.ts#L25-L73" }, { "kind": "response", @@ -208134,7 +208389,7 @@ }, "path": [ { - "description": "A repository name", + "description": "The name of the repository to delete a snapshot from.", "name": "repository", "required": true, "type": { @@ -208146,7 +208401,7 @@ } }, { - "description": "A comma-separated list of snapshot names", + "description": "A comma-separated list of snapshot names to delete.\nIt also accepts wildcards (`*`).", "name": "snapshot", "required": true, "type": { @@ -208160,9 +208415,10 @@ ], "query": [ { - "description": "Explicit operation timeout for connection to master node", + "description": "The period to wait for the master node.\nIf the master node is not available before the timeout expires, the request fails and returns an error.\nTo indicate that the request should never timeout, set it to `-1`.", "name": "master_timeout", "required": false, + "serverDefault": "30s", "type": { "kind": "instance_of", "type": { @@ -208172,7 +208428,7 @@ } } ], - "specLocation": "snapshot/delete/SnapshotDeleteRequest.ts#L24-L40" + "specLocation": "snapshot/delete/SnapshotDeleteRequest.ts#L24-L53" }, { "kind": "response", @@ -208214,7 +208470,7 @@ "path": [ { "codegenName": "name", - "description": "Name of the snapshot repository to unregister. Wildcard (`*`) patterns are supported.", + "description": "The ame of the snapshot repositories to unregister.\nWildcard (`*`) patterns are supported.", "name": "repository", "required": true, "type": { @@ -208228,9 +208484,10 @@ ], "query": [ { - "description": "Explicit operation timeout for connection to master node", + "description": "The period to wait for the master node.\nIf the master node is not available before the timeout expires, the request fails and returns an error.\nTo indicate that the request should never timeout, set it to `-1`.", "name": "master_timeout", "required": false, + "serverDefault": "30s", "type": { "kind": "instance_of", "type": { @@ -208240,9 +208497,10 @@ } }, { - "description": "Explicit operation timeout", + "description": "The period to wait for a response from all relevant nodes in the cluster after updating the cluster metadata.\nIf 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.\nTo indicate that the request should never timeout, set it to `-1`.", "name": "timeout", "required": false, + "serverDefault": "30s", "type": { "kind": "instance_of", "type": { @@ -208252,7 +208510,7 @@ } } ], - "specLocation": "snapshot/delete_repository/SnapshotDeleteRepositoryRequest.ts#L24-L43" + "specLocation": "snapshot/delete_repository/SnapshotDeleteRepositoryRequest.ts#L24-L58" }, { "kind": "response", @@ -208280,7 +208538,7 @@ "body": { "kind": "no_body" }, - "description": "Get snapshot information.", + "description": "Get snapshot information.\n\nNOTE: The `after` parameter and `next` field enable you to iterate through snapshots with some consistency guarantees regarding concurrent creation or deletion of snapshots.\nIt is guaranteed that any snapshot that exists at the beginning of the iteration and is not concurrently deleted will be seen during the iteration.\nSnapshots concurrently created may be seen during an iteration.", "inherits": { "type": { "name": "RequestBase", @@ -208293,7 +208551,7 @@ }, "path": [ { - "description": "Comma-separated list of snapshot repository names used to limit the request. Wildcard (*) expressions are supported.", + "description": "A comma-separated list of snapshot repository names used to limit the request.\nWildcard (`*`) expressions are supported.", "name": "repository", "required": true, "type": { @@ -208305,7 +208563,7 @@ } }, { - "description": "Comma-separated list of snapshot names to retrieve. Also accepts wildcards (*).\n- To get information about all snapshots in a registered repository, use a wildcard (*) or _all.\n- To get information about any snapshots that are currently running, use _current.", + "description": "A comma-separated list of snapshot names to retrieve\nWildcards (`*`) are supported.\n\n* To get information about all snapshots in a registered repository, use a wildcard (`*`) or `_all`.\n* To get information about any snapshots that are currently running, use `_current`.", "name": "snapshot", "required": true, "type": { @@ -208319,36 +208577,46 @@ ], "query": [ { - "description": "If false, the request returns an error for any snapshots that are unavailable.", - "name": "ignore_unavailable", + "availability": { + "serverless": {}, + "stack": { + "since": "7.14.0" + } + }, + "description": "An offset identifier to start pagination from as returned by the next field in the response body.", + "name": "after", "required": false, - "serverDefault": false, "type": { "kind": "instance_of", "type": { - "name": "boolean", + "name": "string", "namespace": "_builtins" } } }, { - "description": "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.", - "name": "master_timeout", + "availability": { + "serverless": {}, + "stack": { + "since": "7.16.0" + } + }, + "description": "The value of the current sort column at which to start retrieval.\nIt can be a string `snapshot-` or a repository name when sorting by snapshot or repository name.\nIt can be a millisecond time value or a number when sorting by `index-` or shard count.", + "name": "from_sort_value", "required": false, - "serverDefault": "30s", "type": { "kind": "instance_of", "type": { - "name": "Duration", - "namespace": "_types" + "name": "string", + "namespace": "_builtins" } } }, { - "description": "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.", - "name": "verbose", + "description": "If `false`, the request returns an error for any snapshots that are unavailable.", + "name": "ignore_unavailable", "required": false, - "serverDefault": true, + "serverDefault": false, "type": { "kind": "instance_of", "type": { @@ -208364,7 +208632,7 @@ "since": "7.13.0" } }, - "description": "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.", + "description": "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.\nThe default is `false`, meaning that this information is omitted.", "name": "index_details", "required": false, "serverDefault": false, @@ -208383,7 +208651,7 @@ "since": "8.3.0" } }, - "description": "If true, returns the name of each index in each snapshot.", + "description": "If `true`, the response includes the name of each index in each snapshot.", "name": "index_names", "required": false, "serverDefault": true, @@ -208396,7 +208664,7 @@ } }, { - "description": "If true, returns the repository name in each snapshot.", + "description": "If `true`, the response includes the repository name in each snapshot.", "name": "include_repository", "required": false, "serverDefault": true, @@ -208409,21 +208677,15 @@ } }, { - "availability": { - "serverless": {}, - "stack": { - "since": "7.14.0" - } - }, - "description": "Allows setting a sort order for the result. Defaults to start_time, i.e. sorting by snapshot start time stamp.", - "name": "sort", + "description": "The period to wait for a connection to the master node.\nIf no response is received before the timeout expires, the request fails and returns an error.", + "name": "master_timeout", "required": false, - "serverDefault": "start_time", + "serverDefault": "30s", "type": { "kind": "instance_of", "type": { - "name": "SnapshotSort", - "namespace": "snapshot._types" + "name": "Duration", + "namespace": "_types" } } }, @@ -208434,14 +208696,14 @@ "since": "7.14.0" } }, - "description": "Maximum number of snapshots to return. Defaults to 0 which means return all that match the request without limit.", - "name": "size", + "description": "The sort order.\nValid values are `asc` for ascending and `desc` for descending order.\nThe default behavior is ascending order.", + "name": "order", "required": false, - "serverDefault": 0, + "serverDefault": "asc", "type": { "kind": "instance_of", "type": { - "name": "integer", + "name": "SortOrder", "namespace": "_types" } } @@ -208450,17 +208712,17 @@ "availability": { "serverless": {}, "stack": { - "since": "7.14.0" + "since": "7.15.0" } }, - "description": "Sort order. Valid values are asc for ascending and desc for descending order. Defaults to asc, meaning ascending order.", - "name": "order", + "description": "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.", + "name": "offset", "required": false, - "serverDefault": "asc", + "serverDefault": 0, "type": { "kind": "instance_of", "type": { - "name": "SortOrder", + "name": "integer", "namespace": "_types" } } @@ -208472,14 +208734,15 @@ "since": "7.14.0" } }, - "description": "Offset identifier to start pagination from as returned by the next field in the response body.", - "name": "after", + "description": "The maximum number of snapshots to return.\nThe default is 0, which means to return all that match the request without limit.", + "name": "size", "required": false, + "serverDefault": 0, "type": { "kind": "instance_of", "type": { - "name": "string", - "namespace": "_builtins" + "name": "integer", + "namespace": "_types" } } }, @@ -208487,17 +208750,16 @@ "availability": { "serverless": {}, "stack": { - "since": "7.15.0" + "since": "7.16.0" } }, - "description": "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.", - "name": "offset", + "description": "Filter snapshots by a comma-separated list of snapshot lifecycle management (SLM) policy names that snapshots belong to.\n\nYou can use wildcards (`*`) and combinations of wildcards followed by exclude patterns starting with `-`.\nFor 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-`.\nNote that the wildcard pattern `*` matches all snapshots created by an SLM policy but not those snapshots that were not created by an SLM policy.\nTo 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.", + "name": "slm_policy_filter", "required": false, - "serverDefault": 0, "type": { "kind": "instance_of", "type": { - "name": "integer", + "name": "Name", "namespace": "_types" } } @@ -208506,74 +208768,42 @@ "availability": { "serverless": {}, "stack": { - "since": "7.16.0" + "since": "7.14.0" } }, - "description": "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.", - "name": "from_sort_value", + "description": "The sort order for the result.\nThe default behavior is sorting by snapshot start time stamp.", + "name": "sort", "required": false, + "serverDefault": "start_time", "type": { "kind": "instance_of", "type": { - "name": "string", - "namespace": "_builtins" + "name": "SnapshotSort", + "namespace": "snapshot._types" } } }, { - "availability": { - "serverless": {}, - "stack": { - "since": "7.16.0" - } - }, - "description": "Filter snapshots by a comma-separated list of SLM policy names that snapshots belong to. Also accepts wildcards (*) and combinations of wildcards followed by exclude patterns starting with -. To include snapshots not created by an SLM policy you can use the special pattern _none that will match all snapshots without an SLM policy.", - "name": "slm_policy_filter", + "description": "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.\n\nNOTE: 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.", + "name": "verbose", "required": false, + "serverDefault": true, "type": { "kind": "instance_of", "type": { - "name": "Name", - "namespace": "_types" + "name": "boolean", + "namespace": "_builtins" } } } ], - "specLocation": "snapshot/get/SnapshotGetRequest.ts#L27-L130" + "specLocation": "snapshot/get/SnapshotGetRequest.ts#L27-L152" }, { "kind": "response", "body": { "kind": "properties", "properties": [ - { - "name": "responses", - "required": false, - "type": { - "kind": "array_of", - "value": { - "kind": "instance_of", - "type": { - "name": "SnapshotResponseItem", - "namespace": "snapshot.get" - } - } - } - }, - { - "name": "snapshots", - "required": false, - "type": { - "kind": "array_of", - "value": { - "kind": "instance_of", - "type": { - "name": "SnapshotInfo", - "namespace": "snapshot._types" - } - } - } - }, { "availability": { "serverless": {}, @@ -208581,8 +208811,8 @@ "since": "7.15.0" } }, - "description": "The total number of snapshots that match the request when ignoring size limit or after query parameter.", - "name": "total", + "description": "The number of remaining snapshots that were not returned due to size limits and that can be fetched by additional requests using the `next` field value.", + "name": "remaining", "required": true, "type": { "kind": "instance_of", @@ -208599,8 +208829,8 @@ "since": "7.15.0" } }, - "description": "The number of remaining snapshots that were not returned due to size limits and that can be fetched by additional requests using the next field value.", - "name": "remaining", + "description": "The total number of snapshots that match the request when ignoring the size limit or `after` query parameter.", + "name": "total", "required": true, "type": { "kind": "instance_of", @@ -208609,6 +208839,46 @@ "namespace": "_types" } } + }, + { + "description": "If the request contained a size limit and there might be more results, a `next` field will be added to the response.\nIt can be used as the `after` query parameter to fetch additional results.", + "name": "next", + "required": false, + "type": { + "kind": "instance_of", + "type": { + "name": "string", + "namespace": "_builtins" + } + } + }, + { + "name": "responses", + "required": false, + "type": { + "kind": "array_of", + "value": { + "kind": "instance_of", + "type": { + "name": "SnapshotResponseItem", + "namespace": "snapshot.get" + } + } + } + }, + { + "name": "snapshots", + "required": false, + "type": { + "kind": "array_of", + "value": { + "kind": "instance_of", + "type": { + "name": "SnapshotInfo", + "namespace": "snapshot._types" + } + } + } } ] }, @@ -208616,7 +208886,7 @@ "name": "Response", "namespace": "snapshot.get" }, - "specLocation": "snapshot/get/SnapshotGetResponse.ts#L25-L42" + "specLocation": "snapshot/get/SnapshotGetResponse.ts#L25-L47" }, { "kind": "interface", @@ -208662,7 +208932,7 @@ } } ], - "specLocation": "snapshot/get/SnapshotGetResponse.ts#L44-L48" + "specLocation": "snapshot/get/SnapshotGetResponse.ts#L49-L53" }, { "kind": "request", @@ -208686,7 +208956,7 @@ "path": [ { "codegenName": "name", - "description": "A comma-separated list of repository names", + "description": "A comma-separated list of snapshot repository names used to limit the request.\nWildcard (`*`) expressions are supported including combining wildcards with exclude patterns starting with `-`.\n\nTo get information about all snapshot repositories registered in the cluster, omit this parameter or use `*` or `_all`.", "name": "repository", "required": false, "type": { @@ -208700,9 +208970,10 @@ ], "query": [ { - "description": "Return local information, do not retrieve the state from master node (default: false)", + "description": "If `true`, the request gets information from the local node only.\nIf `false`, the request gets information from the master node.", "name": "local", "required": false, + "serverDefault": false, "type": { "kind": "instance_of", "type": { @@ -208712,9 +208983,10 @@ } }, { - "description": "Explicit operation timeout for connection to master node", + "description": "The period to wait for the master node.\nIf the master node is not available before the timeout expires, the request fails and returns an error.\nTo indicate that the request should never timeout, set it to `-1`.", "name": "master_timeout", "required": false, + "serverDefault": "to 30s", "type": { "kind": "instance_of", "type": { @@ -208724,7 +208996,7 @@ } } ], - "specLocation": "snapshot/get_repository/SnapshotGetRepositoryRequest.ts#L24-L41" + "specLocation": "snapshot/get_repository/SnapshotGetRepositoryRequest.ts#L24-L58" }, { "kind": "response", @@ -208763,7 +209035,7 @@ "body": { "kind": "no_body" }, - "description": "Verify the repository integrity.\nVerify the integrity of the contents of a snapshot repository.\n\nThis 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.\n\nIf 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.\nUntil you do so:\n\n* It may not be possible to restore some snapshots from this repository.\n* Searchable snapshots may report errors when searched or may have unassigned shards.\n* Taking snapshots into this repository may fail or may appear to succeed but have created a snapshot which cannot be restored.\n* Deleting snapshots from this repository may fail or may appear to succeed but leave the underlying data on disk.\n* Continuing to write to the repository while it is in an invalid state may causing additional damage to its contents.\n\nIf the API finds any problems with the integrity of the contents of your repository, Elasticsearch will not be able to repair the damage.\nThe 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.\nYou must also identify what caused the damage and take action to prevent it from happening again.\n\nIf you cannot restore a repository backup, register a new repository and use this for all future snapshot operations.\nIn 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.\n\nAvoid all operations which write to the repository while the verify repository integrity API is running.\nIf 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.\nIt may also incorrectly fail to report some anomalies that the concurrent writes prevented it from detecting.\n\nNOTE: This API is intended for exploratory use by humans. You should expect the request parameters and the response format to vary in future versions.\n\nNOTE: This API may not work correctly in a mixed-version cluster.", + "description": "Verify the repository integrity.\nVerify the integrity of the contents of a snapshot repository.\n\nThis 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.\n\nIf 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.\nUntil you do so:\n\n* It may not be possible to restore some snapshots from this repository.\n* Searchable snapshots may report errors when searched or may have unassigned shards.\n* Taking snapshots into this repository may fail or may appear to succeed but have created a snapshot which cannot be restored.\n* Deleting snapshots from this repository may fail or may appear to succeed but leave the underlying data on disk.\n* Continuing to write to the repository while it is in an invalid state may causing additional damage to its contents.\n\nIf the API finds any problems with the integrity of the contents of your repository, Elasticsearch will not be able to repair the damage.\nThe 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.\nYou must also identify what caused the damage and take action to prevent it from happening again.\n\nIf you cannot restore a repository backup, register a new repository and use this for all future snapshot operations.\nIn 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.\n\nAvoid all operations which write to the repository while the verify repository integrity API is running.\nIf 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.\nIt may also incorrectly fail to report some anomalies that the concurrent writes prevented it from detecting.\n\nNOTE: This API is intended for exploratory use by humans. You should expect the request parameters and the response format to vary in future versions.\n\nNOTE: This API may not work correctly in a mixed-version cluster.\n\nThe default values for the parameters of this API are designed to limit the impact of the integrity verification on other activities in your cluster.\nFor 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.\nIf you modify these parameters to speed up the verification process, you risk disrupting other snapshot-related operations in your cluster.\nFor large repositories, consider setting up a separate single-node Elasticsearch cluster just for running the integrity verification API.\n\nThe response exposes implementation details of the analysis which may change from version to version.\nThe response body format is therefore not considered stable and may be different in newer versions.", "inherits": { "type": { "name": "RequestBase", @@ -208777,7 +209049,7 @@ "path": [ { "codegenName": "name", - "description": "A repository name", + "description": "The name of the snapshot repository.", "name": "repository", "required": true, "type": { @@ -208791,9 +209063,10 @@ ], "query": [ { - "description": "Number of threads to use for reading metadata", - "name": "meta_thread_pool_concurrency", + "description": "If `verify_blob_contents` is `true`, this parameter specifies how many blobs to verify at once.", + "name": "blob_thread_pool_concurrency", "required": false, + "serverDefault": 1, "type": { "kind": "instance_of", "type": { @@ -208803,9 +209076,10 @@ } }, { - "description": "Number of threads to use for reading blob contents", - "name": "blob_thread_pool_concurrency", + "description": "The maximum number of index snapshots to verify concurrently within each index verification.", + "name": "index_snapshot_verification_concurrency", "required": false, + "serverDefault": 1, "type": { "kind": "instance_of", "type": { @@ -208815,9 +209089,10 @@ } }, { - "description": "Number of snapshots to verify concurrently", - "name": "snapshot_verification_concurrency", + "description": "The number of indices to verify concurrently.\nThe default behavior is to use the entire `snapshot_meta` thread pool.", + "name": "index_verification_concurrency", "required": false, + "serverDefault": 0, "type": { "kind": "instance_of", "type": { @@ -208827,21 +209102,23 @@ } }, { - "description": "Number of indices to verify concurrently", - "name": "index_verification_concurrency", + "description": "If `verify_blob_contents` is `true`, this parameter specifies the maximum amount of data that Elasticsearch will read from the repository every second.", + "name": "max_bytes_per_sec", "required": false, + "serverDefault": "10mb", "type": { "kind": "instance_of", "type": { - "name": "integer", - "namespace": "_types" + "name": "string", + "namespace": "_builtins" } } }, { - "description": "Number of snapshots to verify concurrently within each index", - "name": "index_snapshot_verification_concurrency", + "description": "The number of shard snapshot failures to track during integrity verification, in order to avoid excessive resource usage.\nIf your repository contains more than this number of shard snapshot failures, the verification will fail.", + "name": "max_failed_shard_snapshots", "required": false, + "serverDefault": 10000, "type": { "kind": "instance_of", "type": { @@ -208851,9 +209128,10 @@ } }, { - "description": "Maximum permitted number of failed shard snapshots", - "name": "max_failed_shard_snapshots", + "description": "The maximum number of snapshot metadata operations to run concurrently.\nThe default behavior is to use at most half of the `snapshot_meta` thread pool at once.", + "name": "meta_thread_pool_concurrency", "required": false, + "serverDefault": 0, "type": { "kind": "instance_of", "type": { @@ -208863,31 +209141,33 @@ } }, { - "description": "Whether to verify the contents of individual blobs", - "name": "verify_blob_contents", + "description": "The number of snapshots to verify concurrently.\nThe default behavior is to use at most half of the `snapshot_meta` thread pool at once.", + "name": "snapshot_verification_concurrency", "required": false, + "serverDefault": 0, "type": { "kind": "instance_of", "type": { - "name": "boolean", - "namespace": "_builtins" + "name": "integer", + "namespace": "_types" } } }, { - "description": "Rate limit for individual blob verification", - "name": "max_bytes_per_sec", + "description": "Indicates whether to verify the checksum of every data blob in the repository.\nIf this feature is enabled, Elasticsearch will read the entire repository contents, which may be extremely slow and expensive.", + "name": "verify_blob_contents", "required": false, + "serverDefault": false, "type": { "kind": "instance_of", "type": { - "name": "string", + "name": "boolean", "namespace": "_builtins" } } } ], - "specLocation": "snapshot/repository_verify_integrity/SnapshotRepositoryVerifyIntegrityRequest.ts#L24-L73" + "specLocation": "snapshot/repository_verify_integrity/SnapshotRepositoryVerifyIntegrityRequest.ts#L24-L120" }, { "kind": "response", @@ -208912,6 +209192,9 @@ "kind": "properties", "properties": [ { + "description": "The feature states to restore.\nIf `include_global_state` is `true`, the request restores all feature states in the snapshot by default.\nIf `include_global_state` is `false`, the request restores no feature states by default.\nNote that specifying an empty array will result in the default behavior.\nTo restore no feature states, regardless of the `include_global_state` value, specify an array containing only the value `none` (`[\"none\"]`).", + "extDocId": "snapshot-restore-feature-state", + "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/snapshot-restore.html#feature-state", "name": "feature_states", "required": false, "type": { @@ -208926,6 +209209,7 @@ } }, { + "description": "The index settings to not restore from the snapshot.\nYou can't use this option to ignore `index.number_of_shards`.\n\nFor data streams, this option applies only to restored backing indices.\nNew backing indices are configured using the data stream's matching index template.", "name": "ignore_index_settings", "required": false, "type": { @@ -208940,8 +209224,10 @@ } }, { + "description": "If `true`, the request ignores any index or data stream in indices that's missing from the snapshot.\nIf `false`, the request returns an error for any missing index or data stream.", "name": "ignore_unavailable", "required": false, + "serverDefault": false, "type": { "kind": "instance_of", "type": { @@ -208951,8 +209237,10 @@ } }, { + "description": "If `true`, the request restores aliases for any restored data streams and indices.\nIf `false`, the request doesn’t restore aliases.", "name": "include_aliases", "required": false, + "serverDefault": true, "type": { "kind": "instance_of", "type": { @@ -208962,8 +209250,10 @@ } }, { + "description": "If `true`, restore the cluster state. The cluster state includes:\n\n* Persistent cluster settings\n* Index templates\n* Legacy index templates\n* Ingest pipelines\n* Index lifecycle management (ILM) policies\n* Stored scripts\n* For snapshots taken after 7.12.0, feature states\n\nIf `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.\nIt 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.\n\nUse the `feature_states` parameter to configure how feature states are restored.\n\nIf `include_global_state` is `true` and a snapshot was created without a global state then the restore request will fail.", "name": "include_global_state", "required": false, + "serverDefault": false, "type": { "kind": "instance_of", "type": { @@ -208973,6 +209263,7 @@ } }, { + "description": "Index settings to add or change in restored indices, including backing indices.\nYou can't use this option to change `index.number_of_shards`.\n\nFor data streams, this option applies only to restored backing indices.\nNew backing indices are configured using the data stream's matching index template.", "name": "index_settings", "required": false, "type": { @@ -208984,6 +209275,7 @@ } }, { + "description": "A comma-separated list of indices and data streams to restore.\nIt supports a multi-target syntax.\nThe default behavior is all regular indices and regular data streams in the snapshot.\n\nYou can't use this parameter to restore system indices or system data streams.\nUse `feature_states` instead.", "name": "indices", "required": false, "type": { @@ -208995,8 +209287,10 @@ } }, { + "description": "If `false`, the entire restore operation will fail if one or more indices included in the snapshot do not have all primary shards available.\n\nIf true, it allows restoring a partial snapshot of indices with unavailable shards.\nOnly shards that were successfully included in the snapshot will be restored.\nAll missing shards will be recreated as empty.", "name": "partial", "required": false, + "serverDefault": false, "type": { "kind": "instance_of", "type": { @@ -209006,6 +209300,9 @@ } }, { + "description": "A rename pattern to apply to restored data streams and indices.\nData streams and indices matching the rename pattern will be renamed according to `rename_replacement`.\n\nThe rename pattern is applied as defined by the regular expression that supports referencing the original text, according to the `appendReplacement` logic.", + "extDocId": "snapshot-restore-amend-replacement", + "extDocUrl": "https://docs.oracle.com/javase/8/docs/api/java/util/regex/Matcher.html#appendReplacement-java.lang.StringBuffer-java.lang.String-", "name": "rename_pattern", "required": false, "type": { @@ -209017,6 +209314,7 @@ } }, { + "description": "The rename replacement string that is used with the `rename_pattern`.", "name": "rename_replacement", "required": false, "type": { @@ -209042,7 +209340,7 @@ }, "path": [ { - "description": "A repository name", + "description": "The name of the repository to restore a snapshot from.", "name": "repository", "required": true, "type": { @@ -209054,7 +209352,7 @@ } }, { - "description": "A snapshot name", + "description": "The name of the snapshot to restore.", "name": "snapshot", "required": true, "type": { @@ -209068,9 +209366,10 @@ ], "query": [ { - "description": "Explicit operation timeout for connection to master node", + "description": "The period to wait for the master node.\nIf the master node is not available before the timeout expires, the request fails and returns an error.\nTo indicate that the request should never timeout, set it to `-1`.", "name": "master_timeout", "required": false, + "serverDefault": "30s", "type": { "kind": "instance_of", "type": { @@ -209080,9 +209379,10 @@ } }, { - "description": "Should this request wait until the operation has completed before returning", + "description": "If `true`, the request returns a response when the restore operation completes.\nThe operation is complete when it finishes all attempts to recover primary shards for restored indices.\nThis applies even if one or more of the recovery attempts fail.\n\nIf `false`, the request returns a response when the restore operation initializes.", "name": "wait_for_completion", "required": false, + "serverDefault": false, "type": { "kind": "instance_of", "type": { @@ -209092,7 +209392,7 @@ } } ], - "specLocation": "snapshot/restore/SnapshotRestoreRequest.ts#L25-L72" + "specLocation": "snapshot/restore/SnapshotRestoreRequest.ts#L25-L169" }, { "kind": "response", @@ -209183,7 +209483,7 @@ "body": { "kind": "no_body" }, - "description": "Get the snapshot status.\nGet a detailed description of the current state for each shard participating in the snapshot.\nNote that this API should be used only to obtain detailed shard-level information for ongoing snapshots.\nIf this detail is not needed or you want to obtain information about one or more existing snapshots, use the get snapshot API.\n\nWARNING: Using the API to return the status of any snapshots other than currently running snapshots can be expensive.\nThe API requires a read from the repository for each shard in each snapshot.\nFor 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).\n\nDepending on the latency of your storage, such requests can take an extremely long time to return results.\nThese requests can also tax machine resources and, when using cloud storage, incur high processing costs.", + "description": "Get the snapshot status.\nGet a detailed description of the current state for each shard participating in the snapshot.\n\nNote that this API should be used only to obtain detailed shard-level information for ongoing snapshots.\nIf this detail is not needed or you want to obtain information about one or more existing snapshots, use the get snapshot API.\n\nIf you omit the `` request path parameter, the request retrieves information only for currently running snapshots.\nThis usage is preferred.\nIf needed, you can specify `` and `` to retrieve information for specific snapshots, even if they're not currently running.\n\nWARNING: Using the API to return the status of any snapshots other than currently running snapshots can be expensive.\nThe API requires a read from the repository for each shard in each snapshot.\nFor 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).\n\nDepending on the latency of your storage, such requests can take an extremely long time to return results.\nThese requests can also tax machine resources and, when using cloud storage, incur high processing costs.", "inherits": { "type": { "name": "RequestBase", @@ -209196,7 +209496,7 @@ }, "path": [ { - "description": "A repository name", + "description": "The snapshot repository name used to limit the request.\nIt supports wildcards (`*`) if `` isn't specified.", "name": "repository", "required": false, "type": { @@ -209208,7 +209508,7 @@ } }, { - "description": "A comma-separated list of snapshot names", + "description": "A comma-separated list of snapshots to retrieve status for.\nThe default is currently running snapshots.\nWildcards (`*`) are not supported.", "name": "snapshot", "required": false, "type": { @@ -209222,9 +209522,10 @@ ], "query": [ { - "description": "Whether to ignore unavailable snapshots, defaults to false which means a SnapshotMissingException is thrown", + "description": "If `false`, the request returns an error for any snapshots that are unavailable.\nIf `true`, the request ignores snapshots that are unavailable, such as those that are corrupted or temporarily cannot be returned.", "name": "ignore_unavailable", "required": false, + "serverDefault": false, "type": { "kind": "instance_of", "type": { @@ -209234,9 +209535,10 @@ } }, { - "description": "Explicit operation timeout for connection to master node", + "description": "The period to wait for the master node.\nIf the master node is not available before the timeout expires, the request fails and returns an error.\nTo indicate that the request should never timeout, set it to `-1`.", "name": "master_timeout", "required": false, + "serverDefault": "30s", "type": { "kind": "instance_of", "type": { @@ -209246,7 +209548,7 @@ } } ], - "specLocation": "snapshot/status/SnapshotStatusRequest.ts#L24-L51" + "specLocation": "snapshot/status/SnapshotStatusRequest.ts#L24-L76" }, { "kind": "response", @@ -209283,6 +209585,7 @@ }, "properties": [ { + "description": "A human-readable name for the node.\nYou can set this name using the `node.name` property in `elasticsearch.yml`.\nThe default value is the machine's hostname.", "name": "name", "required": true, "type": { @@ -209294,7 +209597,7 @@ } } ], - "specLocation": "snapshot/verify_repository/SnapshotVerifyRepositoryResponse.ts#L27-L29" + "specLocation": "snapshot/verify_repository/SnapshotVerifyRepositoryResponse.ts#L33-L40" }, { "kind": "request", @@ -209318,7 +209621,7 @@ "path": [ { "codegenName": "name", - "description": "A repository name", + "description": "The name of the snapshot repository to verify.", "name": "repository", "required": true, "type": { @@ -209332,9 +209635,10 @@ ], "query": [ { - "description": "Explicit operation timeout for connection to master node", + "description": "The period to wait for the master node.\nIf the master node is not available before the timeout expires, the request fails and returns an error.\nTo indicate that the request should never timeout, set it to `-1`.", "name": "master_timeout", "required": false, + "serverDefault": "30s", "type": { "kind": "instance_of", "type": { @@ -209344,9 +209648,10 @@ } }, { - "description": "Explicit operation timeout", + "description": "The period to wait for a response from all relevant nodes in the cluster after updating the cluster metadata.\nIf 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.\nTo indicate that the request should never timeout, set it to `-1`.", "name": "timeout", "required": false, + "serverDefault": "30s", "type": { "kind": "instance_of", "type": { @@ -209356,7 +209661,7 @@ } } ], - "specLocation": "snapshot/verify_repository/SnapshotVerifyRepositoryRequest.ts#L24-L43" + "specLocation": "snapshot/verify_repository/SnapshotVerifyRepositoryRequest.ts#L24-L57" }, { "kind": "response", @@ -209364,6 +209669,7 @@ "kind": "properties", "properties": [ { + "description": "Information about the nodes connected to the snapshot repository.\nThe key is the ID of the node.", "name": "nodes", "required": true, "type": { @@ -209391,7 +209697,7 @@ "name": "Response", "namespace": "snapshot.verify_repository" }, - "specLocation": "snapshot/verify_repository/SnapshotVerifyRepositoryResponse.ts#L23-L25" + "specLocation": "snapshot/verify_repository/SnapshotVerifyRepositoryResponse.ts#L23-L31" }, { "kind": "interface", diff --git a/output/schema/validation-errors.json b/output/schema/validation-errors.json index dce85290f9..2aa021caef 100644 --- a/output/schema/validation-errors.json +++ b/output/schema/validation-errors.json @@ -392,6 +392,12 @@ ], "response": [] }, + "snapshot.clone": { + "request": [ + "Request: query parameter 'timeout' does not exist in the json spec" + ], + "response": [] + }, "snapshot.delete": { "request": [ "Request: missing json spec query parameter 'wait_for_completion'" diff --git a/output/typescript/types.ts b/output/typescript/types.ts index 2dc6adf58c..aa2f6454bd 100644 --- a/output/typescript/types.ts +++ b/output/typescript/types.ts @@ -19389,11 +19389,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 { @@ -19408,10 +19410,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 { @@ -19458,13 +19460,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 { @@ -19599,6 +19608,7 @@ export interface SnapshotCloneRequest extends RequestBase { snapshot: Name target_snapshot: Name master_timeout?: Duration + timeout?: Duration body?: { indices: string } @@ -19612,10 +19622,11 @@ export interface SnapshotCreateRequest extends RequestBase { master_timeout?: Duration wait_for_completion?: boolean body?: { + expand_wildcards?: ExpandWildcards + feature_states?: string[] ignore_unavailable?: boolean include_global_state?: boolean indices?: Indices - feature_states?: string[] metadata?: Metadata partial?: boolean } @@ -19655,26 +19666,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 { @@ -19693,14 +19705,14 @@ export type SnapshotGetRepositoryResponse = Record 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/specification/_doc_ids/table.csv b/specification/_doc_ids/table.csv index 3cc5976619..67196e7686 100644 --- a/specification/_doc_ids/table.csv +++ b/specification/_doc_ids/table.csv @@ -474,6 +474,17 @@ registered-domain-processor,https://www.elastic.co/guide/en/elasticsearch/refere remove-processor,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/remove-processor.html remote-clusters-api-key,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/remote-clusters-api-key.html rename-processor,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/rename-processor.html +repository-azure,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/repository-azure.html +repository-gcs,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/repository-gcs.html +repository-read-only,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/snapshots-read-only-repository.html +repository-s3,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/repository-s3.html +repository-s3-canned-acl,https://docs.aws.amazon.com/AmazonS3/latest/userguide/acl-overview.html#canned-acl +repository-s3-delete-objects,https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteObjects.html +repository-s3-list-multipart,https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListMultipartUploads.html +repository-s3-naming,https://docs.aws.amazon.com/AmazonS3/latest/userguide/BucketRestrictions.html#bucketnamingrules +repository-s3-storage-classes,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/repository-s3.html#repository-s3-storage-classes +repository-shared-fs,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/snapshots-filesystem-repository.html +repository-source-only,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/snapshots-source-only-repository.html reroute-processor,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/reroute-processor.html render-search-template-api,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/render-search-template-api.html reset-transform,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/reset-transform.html @@ -670,10 +681,13 @@ snapshot-get,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/ge snapshot-restore-api,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/restore-snapshot-api.html snapshot-status,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/get-snapshot-status-api.html snapshot-repo-cleanup,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/clean-up-snapshot-repo-api.html +snapshot-repo-create,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/put-snapshot-repo-api.html snapshot-repo-delete,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/delete-snapshot-repo-api.html snapshot-repo-get,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/get-snapshot-repo-api.html snapshot-repo-verify,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/verify-snapshot-repo-api.html snapshot-repo-verify-integrity,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/verify-repo-integrity-api.html +snapshot-restore-amend-replacement,https://docs.oracle.com/javase/8/docs/api/java/util/regex/Matcher.html#appendReplacement-java.lang.StringBuffer-java.lang.String- +snapshot-restore-feature-state,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/snapshot-restore.html#feature-state sort-processor,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/sort-processor.html sort-search-results,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/sort-search-results.html sort-tiebreaker,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/eql.html#eql-search-specify-a-sort-tiebreaker diff --git a/specification/snapshot/_types/SnapshotRepository.ts b/specification/snapshot/_types/SnapshotRepository.ts index 67b294bcfc..35c8bdf03c 100644 --- a/specification/snapshot/_types/SnapshotRepository.ts +++ b/specification/snapshot/_types/SnapshotRepository.ts @@ -38,87 +38,404 @@ export class RepositoryBase { } export class AzureRepository extends RepositoryBase { + /** + * The Azure repository type. + * @ext_doc_id repository-azure + */ type: 'azure' + /** + * The repository settings. + */ settings: AzureRepositorySettings } export class GcsRepository extends RepositoryBase { + /** + * The Google Cloud Storage repository type. + * @ext_doc_id repository-gcs + */ type: 'gcs' + /** + * The repository settings. + */ settings: GcsRepositorySettings } export class S3Repository extends RepositoryBase { + /** + * The S3 repository type. + * @ext_doc_id repository-s3 + */ type: 's3' + /** + * The repository settings. + * + * NOTE: In addition to the specified settings, you can also use all non-secure client settings in the repository settings. + * In this case, the client settings found in the repository settings will be merged with those of the named client used by the repository. + * Conflicts between client and repository settings are resolved by the repository settings taking precedence over client settings. + */ settings: S3RepositorySettings } export class SharedFileSystemRepository extends RepositoryBase { + /** + * The shared file system repository type. + * @ext_doc_id repository-shared-fs + */ type: 'fs' + /** + * The repository settings. + */ settings: SharedFileSystemRepositorySettings } export class ReadOnlyUrlRepository extends RepositoryBase { + /** + * The read-only URL repository type. + * @ext_doc_id repository-read-only + */ type: 'url' + /** + * The repository settings. + */ settings: ReadOnlyUrlRepositorySettings } export class SourceOnlyRepository extends RepositoryBase { + /** + * The source-only repository type. + * @ext_doc_id repository-source-only + */ type: 'source' + /** + * The repository settings. + */ settings: SourceOnlyRepositorySettings } export class RepositorySettingsBase { + /** + * Big files can be broken down into multiple smaller blobs in the blob store during snapshotting. + * It is not recommended to change this value from its default unless there is an explicit reason for limiting the size of blobs in the repository. + * Setting a value lower than the default can result in an increased number of API calls to the blob store during snapshot create and restore operations compared to using the default value and thus make both operations slower and more costly. + * Specify the chunk size as a byte unit, for example: `10MB`, `5KB`, 500B. + * The default varies by repository type. + */ chunk_size?: ByteSize + /** + * When set to `true`, metadata files are stored in compressed format. + * This setting doesn't affect index files that are already compressed by default. + * @server_default true + */ compress?: boolean + /** + * The maximum snapshot restore rate per node. + * It defaults to unlimited. + * Note that restores are also throttled through recovery settings. + */ max_restore_bytes_per_sec?: ByteSize + /** + * The maximum snapshot creation rate per node. + * It defaults to 40mb per second. + * Note that if the recovery settings for managed services are set, then it defaults to unlimited, and the rate is additionally throttled through recovery settings. + */ max_snapshot_bytes_per_sec?: ByteSize } export class AzureRepositorySettings extends RepositorySettingsBase { + /** + * The path to the repository data within the container. + * It defaults to the root directory. + * + * NOTE: Don't set `base_path` when configuring a snapshot repository for Elastic Cloud Enterprise. + * Elastic Cloud Enterprise automatically generates the `base_path` for each deployment so that multiple deployments can share the same bucket. + */ + base_path?: string + /** + * The name of the Azure repository client to use. + * @server_default default + */ client?: string + /** + * The Azure container. + * @server_default elasticsearch-snapshots + */ container?: string - base_path?: string - readonly?: boolean + /** + * The maxmimum batch size, between 1 and 256, used for `BlobBatch` requests. + * Defaults to 256 which is the maximum number supported by the Azure blob batch API. + * @server_default 256 + */ + delete_objects_max_size?: integer + /** + * Either `primary_only` or `secondary_only`. + * Note that if you set it to `secondary_only`, it will force `readonly` to `true`. + * @server_default primary_only + */ location_mode?: string + /** + * The maximum number of concurrent batch delete requests that will be submitted for any individual bulk delete with `BlobBatch`. + * Note that the effective number of concurrent deletes is further limited by the Azure client connection and event loop thread limits. + * Defaults to 10, minimum is 1, maximum is 100. + * @server_default 10 + */ + max_concurrent_batch_deletes?: integer + /** + * If `true`, the repository is read-only. + * The cluster can retrieve and restore snapshots from the repository but not write to the repository or create snapshots in it. + * + * Only a cluster with write access can create snapshots in the repository. + * All other clusters connected to the repository should have the `readonly` parameter set to `true`. + * If `false`, the cluster can write to the repository and create snapshots in it. + * + * IMPORTANT: If you register the same snapshot repository with multiple clusters, only one cluster should have write access to the repository. + * Having multiple clusters write to the repository at the same time risks corrupting the contents of the repository. + * @server_default false + */ + readonly?: boolean } export class GcsRepositorySettings extends RepositorySettingsBase { + /** + * The name of the bucket to be used for snapshots. + */ bucket: string - client?: string + /** + * The name used by the client when it uses the Google Cloud Storage service. + * @deprecated 6.3.0 + */ + application_name?: string + /** + * The path to the repository data within the bucket. + * It defaults to the root of the bucket. + * + * NOTE: Don't set `base_path` when configuring a snapshot repository for Elastic Cloud Enterprise. + * Elastic Cloud Enterprise automatically generates the `base_path` for each deployment so that multiple deployments can share the same bucket. + */ base_path?: string + /** + * The name of the client to use to connect to Google Cloud Storage. + * @server_default default + */ + client?: string + /** + * If `true`, the repository is read-only. + * The cluster can retrieve and restore snapshots from the repository but not write to the repository or create snapshots in it. + * + * Only a cluster with write access can create snapshots in the repository. + * All other clusters connected to the repository should have the `readonly` parameter set to `true`. + * + * If `false`, the cluster can write to the repository and create snapshots in it. + * + * IMPORTANT: If you register the same snapshot repository with multiple clusters, only one cluster should have write access to the repository. + * Having multiple clusters write to the repository at the same time risks corrupting the contents of the repository. + * @server_default false + */ readonly?: boolean - application_name?: string } export class S3RepositorySettings extends RepositorySettingsBase { + /** + * The name of the S3 bucket to use for snapshots. + * The bucket name must adhere to Amazon's S3 bucket naming rules. + * @ext_doc_id repository-s3-naming + */ bucket: string - client?: string + /** + * The path to the repository data within its bucket. + * It defaults to an empty string, meaning that the repository is at the root of the bucket. + * The value of this setting should not start or end with a forward slash (`/`). + * + * NOTE: Don't set base_path when configuring a snapshot repository for Elastic Cloud Enterprise. + * Elastic Cloud Enterprise automatically generates the `base_path` for each deployment so that multiple deployments may share the same bucket. + */ base_path?: string - readonly?: boolean - server_side_encryption?: boolean + /** + * The minimum threshold below which the chunk is uploaded using a single request. + * Beyond this threshold, the S3 repository will use the AWS Multipart Upload API to split the chunk into several parts, each of `buffer_size` length, and to upload each part in its own request. + * Note that setting a buffer size lower than 5mb is not allowed since it will prevent the use of the Multipart API and may result in upload errors. + * It is also not possible to set a buffer size greater than 5gb as it is the maximum upload size allowed by S3. + * Defaults to `100mb` or 5% of JVM heap, whichever is smaller. + */ buffer_size?: ByteSize + /** + * The S3 repository supports all S3 canned ACLs: `private`, `public-read`, `public-read-write`, `authenticated-read`, `log-delivery-write`, `bucket-owner-read`, `bucket-owner-full-control`. + * You could specify a canned ACL using the `canned_acl` setting. + * When the S3 repository creates buckets and objects, it adds the canned ACL into the buckets and objects. + * @server_default private + * @ext_doc_id repository-s3-canned-acl + */ canned_acl?: string + /** + * The name of the S3 client to use to connect to S3. + * @server_default default + */ + client?: string + /** + * The maxmimum batch size, between 1 and 1000, used for `DeleteObjects` requests. + * Defaults to 1000 which is the maximum number supported by the AWS DeleteObjects API. + * @server_default 1000 + * @ext_doc_id repository-s3-delete-objects + */ + delete_objects_max_size?: integer + /** + * The time to wait before trying again if an attempt to read a linearizable register fails. + * @server_default 5s + */ + get_register_retry_delay?: Duration + /** + * The maximum number of parts that Elasticsearch will write during a multipart upload of a single object. + * Files which are larger than `buffer_size × max_multipart_parts` will be chunked into several smaller objects. + * Elasticsearch may also split a file across multiple objects to satisfy other constraints such as the `chunk_size` limit. + * Defaults to `10000` which is the maximum number of parts in a multipart upload in AWS S3. + * @server_default 10000 + */ + max_multipart_parts?: integer + /** + * The maximum number of possibly-dangling multipart uploads to clean up in each batch of snapshot deletions. + * Defaults to 1000 which is the maximum number supported by the AWS ListMultipartUploads API. + * If set to `0`, Elasticsearch will not attempt to clean up dangling multipart uploads. + * @server_default 1000 + * @ext_doc_id repository-s3-list-multipart + */ + max_multipart_upload_cleanup_size?: integer + /** + * If true, the repository is read-only. + * The cluster can retrieve and restore snapshots from the repository but not write to the repository or create snapshots in it. + * + * Only a cluster with write access can create snapshots in the repository. + * All other clusters connected to the repository should have the `readonly` parameter set to `true`. + * + * If `false`, the cluster can write to the repository and create snapshots in it. + * + * IMPORTANT: If you register the same snapshot repository with multiple clusters, only one cluster should have write access to the repository. + * Having multiple clusters write to the repository at the same time risks corrupting the contents of the repository. + * @server_default false + */ + readonly?: boolean + /** + * When set to `true`m files are encrypted on server side using an AES256 algorithm. + * server_default false + */ + server_side_encryption?: boolean + /** + * The S3 storage class for objects written to the repository. + * Values may be `standard`, `reduced_redundancy`, `standard_ia`, `onezone_ia`, and `intelligent_tiering`. + * @server_default standard + * @ext_doc_id repository-s3-storage-classes + */ storage_class?: string + /** + * The delay before the first retry and the amount the delay is incremented by on each subsequent retry. + * The default is 50ms and the minimum is 0ms. + * @server_default 50ms + */ + 'throttled_delete_retry.delay_increment'?: Duration + /** + * The upper bound on how long the delays between retries will grow to. + * The default is 5s and the minimum is 0ms. + * @server_default 5s + */ + 'throttled_delete_retry.maximum_delay'?: Duration + /** + * The number times to retry a throttled snapshot deletion. + * The default is 10 and the minimum value is 0 which will disable retries altogether. + * Note that if retries are enabled in the Azure client, each of these retries comprises that many client-level retries. + */ + 'throttled_delete_retry.maximum_number_of_retries'?: integer } export class SharedFileSystemRepositorySettings extends RepositorySettingsBase { + /** + * The location of the shared filesystem used to store and retrieve snapshots. + * This location must be registered in the `path.repo` setting on all master and data nodes in the cluster. + * Unlike `path.repo`, this setting supports only a single file path. + */ location: string + /** + * The maximum number of snapshots the repository can contain. + * The default is `Integer.MAX_VALUE`, which is 2^31-1 or `2147483647`. + * @server_default 2147483647 + */ max_number_of_snapshots?: integer + /** + * If `true`, the repository is read-only. + * The cluster can retrieve and restore snapshots from the repository but not write to the repository or create snapshots in it. + * + * Only a cluster with write access can create snapshots in the repository. + * All other clusters connected to the repository should have the `readonly` parameter set to `true`. + * + * If `false`, the cluster can write to the repository and create snapshots in it. + * + * IMPORTANT: If you register the same snapshot repository with multiple clusters, only one cluster should have write access to the repository. + * Having multiple clusters write to the repository at the same time risks corrupting the contents of the repository. + * @server_default false + */ readonly?: boolean } export class ReadOnlyUrlRepositorySettings extends RepositorySettingsBase { + /** + * The maximum number of retries for HTTP and HTTPS URLs. + * @server_default 5 + */ http_max_retries?: integer + /** + * The maximum wait time for data transfers over a connection. + * @server_default 50s + */ http_socket_timeout?: Duration + /** + * The maximum number of snapshots the repository can contain. + * The default is `Integer.MAX_VALUE`, which is 2^31-1 or `2147483647`. + * @server_default 2147483647 + */ max_number_of_snapshots?: integer + /** + * The URL location of the root of the shared filesystem repository. + * The following protocols are supported: + * + * * `file` + * * `ftp` + * * `http` + * * `https` + * * `jar` + * + * URLs using the HTTP, HTTPS, or FTP protocols must be explicitly allowed with the `repositories.url.allowed_urls` cluster setting. + * This setting supports wildcards in the place of a host, path, query, or fragment in the URL. + * + * URLs using the file protocol must point to the location of a shared filesystem accessible to all master and data nodes in the cluster. + * This location must be registered in the `path.repo` setting. + * You don't need to register URLs using the FTP, HTTP, HTTPS, or JAR protocols in the `path.repo` setting. + */ url: string } export class SourceOnlyRepositorySettings extends RepositorySettingsBase { + /** + * The delegated repository type. For valid values, refer to the `type` parameter. + * Source repositories can use `settings` properties for its delegated repository type. + */ delegate_type?: string + /** + * The maximum number of snapshots the repository can contain. + * The default is `Integer.MAX_VALUE`, which is 2^31-1 or `2147483647`. + * @server_default 2147483647 + */ max_number_of_snapshots?: integer /** + * If `true`, the repository is read-only. + * The cluster can retrieve and restore snapshots from the repository but not write to the repository or create snapshots in it. + * + * Only a cluster with write access can create snapshots in the repository. + * All other clusters connected to the repository should have the `readonly` parameter set to `true`. + * + * If `false`, the cluster can write to the repository and create snapshots in it. + * + * IMPORTANT: If you register the same snapshot repository with multiple clusters, only one cluster should have write access to the repository. + * Having multiple clusters write to the repository at the same time risks corrupting the contents of the repository. * @aliases readonly + * @server_default false */ read_only?: boolean } diff --git a/specification/snapshot/_types/SnapshotShardsStats.ts b/specification/snapshot/_types/SnapshotShardsStats.ts index 103c7683ce..03843b528f 100644 --- a/specification/snapshot/_types/SnapshotShardsStats.ts +++ b/specification/snapshot/_types/SnapshotShardsStats.ts @@ -20,10 +20,28 @@ import { long } from '@_types/Numeric' export class ShardsStats { + /** + * The number of shards that initialized, started, and finalized successfully. + */ done: long + /** + * The number of shards that failed to be included in the snapshot. + */ failed: long + /** + * The number of shards that are finalizing but are not done. + */ finalizing: long + /** + * The number of shards that are still initializing. + */ initializing: long + /** + * The number of shards that have started but are not finalized. + */ started: long + /** + * The total number of shards included in the snapshot. + */ total: long } diff --git a/specification/snapshot/_types/SnapshotShardsStatsStage.ts b/specification/snapshot/_types/SnapshotShardsStatsStage.ts index 34b048fd71..aebe460bca 100644 --- a/specification/snapshot/_types/SnapshotShardsStatsStage.ts +++ b/specification/snapshot/_types/SnapshotShardsStatsStage.ts @@ -18,14 +18,14 @@ */ export enum ShardsStatsStage { - /** Number of shards in the snapshot that were successfully stored in the repository. */ + /** The number of shards in the snapshot that were successfully stored in the repository. */ DONE, - /** Number of shards in the snapshot that were not successfully stored in the repository. */ + /** The number of shards in the snapshot that were not successfully stored in the repository. */ FAILURE, - /** Number of shards in the snapshot that are in the finalizing stage of being stored in the repository. */ + /** The number of shards in the snapshot that are in the finalizing stage of being stored in the repository. */ FINALIZE, - /** Number of shards in the snapshot that are in the initializing stage of being stored in the repository. */ + /** The number of shards in the snapshot that are in the initializing stage of being stored in the repository. */ INIT, - /** Number of shards in the snapshot that are in the started stage of being stored in the repository. */ + /** The number of shards in the snapshot that are in the started stage of being stored in the repository. */ STARTED } diff --git a/specification/snapshot/_types/SnapshotStats.ts b/specification/snapshot/_types/SnapshotStats.ts index 7ced0386a0..5efcdc8b9f 100644 --- a/specification/snapshot/_types/SnapshotStats.ts +++ b/specification/snapshot/_types/SnapshotStats.ts @@ -21,9 +21,22 @@ import { Duration, DurationValue, EpochTime, UnitMillis } from '@_types/Time' import { FileCountSnapshotStats } from './FileCountSnapshotStats' export class SnapshotStats { + /** + * The number and size of files that still need to be copied as part of the incremental snapshot. + * For completed snapshots, this property indicates the number and size of files that were not already in the repository and were copied as part of the incremental snapshot. + */ incremental: FileCountSnapshotStats + /** + * The time, in milliseconds, when the snapshot creation process started. + */ start_time_in_millis: EpochTime time?: Duration + /** + * The total time, in milliseconds, that it took for the snapshot process to complete. + */ time_in_millis: DurationValue + /** + * The total number and size of files that are referenced by the snapshot. + */ total: FileCountSnapshotStats } diff --git a/specification/snapshot/_types/SnapshotStatus.ts b/specification/snapshot/_types/SnapshotStatus.ts index 5b95ac8a12..9dfc9af5fd 100644 --- a/specification/snapshot/_types/SnapshotStatus.ts +++ b/specification/snapshot/_types/SnapshotStatus.ts @@ -24,12 +24,37 @@ import { ShardsStats } from './SnapshotShardsStats' import { SnapshotStats } from './SnapshotStats' export class Status { + /** + * Indicates whether the current cluster state is included in the snapshot. + */ include_global_state: boolean indices: Dictionary + /** + * The name of the repository that includes the snapshot. + */ repository: string + /** + * Statistics for the shards in the snapshot. + */ shards_stats: ShardsStats + /** + * The name of the snapshot. + */ snapshot: string + /** + * The current snapshot state: + * + * * `FAILED`: The snapshot finished with an error and failed to store any data. + * * `STARTED`: The snapshot is currently running. + * * `SUCCESS`: The snapshot completed. + */ state: string + /** + * Details about the number (`file_count`) and size (`size_in_bytes`) of files included in the snapshot. + */ stats: SnapshotStats + /** + * The universally unique identifier (UUID) for the snapshot. + */ uuid: Uuid } diff --git a/specification/snapshot/cleanup_repository/SnapshotCleanupRepositoryRequest.ts b/specification/snapshot/cleanup_repository/SnapshotCleanupRepositoryRequest.ts index 4e325bca62..0badce303a 100644 --- a/specification/snapshot/cleanup_repository/SnapshotCleanupRepositoryRequest.ts +++ b/specification/snapshot/cleanup_repository/SnapshotCleanupRepositoryRequest.ts @@ -34,18 +34,22 @@ import { Duration } from '@_types/Time' export interface Request extends RequestBase { path_parts: { /** - * Snapshot repository to clean up. + * The name of the snapshot repository to clean up. * @codegen_name name */ repository: Name } query_parameters: { /** - * Period to wait for a connection to the master node. + * 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` * @server_default 30s */ master_timeout?: Duration /** - * Period to wait for a response. + * 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`. * @server_default 30s */ timeout?: Duration diff --git a/specification/snapshot/cleanup_repository/SnapshotCleanupRepositoryResponse.ts b/specification/snapshot/cleanup_repository/SnapshotCleanupRepositoryResponse.ts index 5e215730a7..cbb21daae0 100644 --- a/specification/snapshot/cleanup_repository/SnapshotCleanupRepositoryResponse.ts +++ b/specification/snapshot/cleanup_repository/SnapshotCleanupRepositoryResponse.ts @@ -27,8 +27,11 @@ export class Response { } export class CleanupRepositoryResults { - /** Number of binary large objects (blobs) removed during cleanup. */ + /** + * The number of binary large objects (blobs) removed from the snapshot repository during cleanup operations. + * A non-zero value indicates that unreferenced blobs were found and subsequently cleaned up. + */ deleted_blobs: long - /** Number of bytes freed by cleanup operations. */ + /** The number of bytes freed by cleanup operations. */ deleted_bytes: long } diff --git a/specification/snapshot/clone/SnapshotCloneRequest.ts b/specification/snapshot/clone/SnapshotCloneRequest.ts index 16125ac4bb..7442d6f4ee 100644 --- a/specification/snapshot/clone/SnapshotCloneRequest.ts +++ b/specification/snapshot/clone/SnapshotCloneRequest.ts @@ -32,14 +32,39 @@ import { Duration } from '@_types/Time' */ export interface Request extends RequestBase { path_parts: { + /** + * The name of the snapshot repository that both source and target snapshot belong to. + */ repository: Name + /** + * The source snapshot name. + */ snapshot: Name + /** + * The target snapshot name. + */ target_snapshot: Name } query_parameters: { + /** + * 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`. + * @server_default 30s + */ master_timeout?: Duration + /** + * The period of time to wait for a response. + * If no response is received before the timeout expires, the request fails and returns an error. + * @server_default 30s + */ + timeout?: Duration } body: { + /** + * A comma-separated list of indices to include in the snapshot. + * Multi-target syntax is supported. + */ indices: string } } diff --git a/specification/snapshot/create/SnapshotCreateRequest.ts b/specification/snapshot/create/SnapshotCreateRequest.ts index 670b21f526..13c5c39f0d 100644 --- a/specification/snapshot/create/SnapshotCreateRequest.ts +++ b/specification/snapshot/create/SnapshotCreateRequest.ts @@ -18,7 +18,7 @@ */ import { RequestBase } from '@_types/Base' -import { Indices, Metadata, Name } from '@_types/common' +import { ExpandWildcards, Indices, Metadata, Name } from '@_types/common' import { Duration } from '@_types/Time' /** @@ -34,51 +34,85 @@ import { Duration } from '@_types/Time' export interface Request extends RequestBase { path_parts: { /** - * Repository for the snapshot. + * The name of the repository for the snapshot. */ repository: Name /** - * Name of the snapshot. Must be unique in the repository. + * The name of the snapshot. + * It supportes date math. + * It must be unique in the repository. */ snapshot: Name } query_parameters: { /** - * 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. + * 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. * @server_default 30s */ master_timeout?: Duration /** - * If `true`, the request returns a response when the snapshot is complete. If `false`, the request returns a response when the snapshot initializes. + * If `true`, the request returns a response when the snapshot is complete. + * If `false`, the request returns a response when the snapshot initializes. * @server_default false */ wait_for_completion?: boolean } body: { /** - * 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. + * Determines how wildcard patterns in the `indices` parameter match data streams and indices. + * It supports comma-separated values such as `open,hidden`. + * @server_default all + */ + expand_wildcards?: ExpandWildcards + /** + * 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"]`). + * @ext_doc_id snapshot-restore-feature-state + */ + feature_states?: string[] + /** + * 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. * @server_default false */ ignore_unavailable?: 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`). + * 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`). * @server_default true */ include_global_state?: boolean /** - * Data streams and indices to include in the snapshot. Supports multi-target syntax. Includes all data streams and indices by default. + * A comma-separated list of data streams and indices to include in the snapshot. + * It supports a multi-target syntax. + * The default is an empty array (`[]`), which includes all regular data streams and regular indices. + * To exclude all data streams and indices, use `-*`. + * + * You can't use this parameter to include or exclude system indices or system data streams from a snapshot. + * Use `feature_states` instead. */ indices?: Indices /** - * 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. - */ - feature_states?: string[] - /** - * Optional metadata for the snapshot. May have any contents. Must be less than 1024 bytes. This map is not automatically generated by Elasticsearch. + * 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. */ metadata?: Metadata /** - * 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. + * 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. * @server_default false */ partial?: boolean diff --git a/specification/snapshot/create_repository/SnapshotCreateRepositoryRequest.ts b/specification/snapshot/create_repository/SnapshotCreateRepositoryRequest.ts index b5eb7782bd..2810dd739b 100644 --- a/specification/snapshot/create_repository/SnapshotCreateRepositoryRequest.ts +++ b/specification/snapshot/create_repository/SnapshotCreateRepositoryRequest.ts @@ -27,20 +27,45 @@ import { Duration } from '@_types/Time' * 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. * @rest_spec_name snapshot.create_repository * @availability stack since=0.0.0 stability=stable * @availability serverless stability=stable visibility=private * @cluster_privileges manage + * @doc_id snapshot-repo-create * @ext_doc_id register-repository */ export interface Request extends RequestBase { path_parts: { - /** @codegen_name name */ + /** + * The name of the snapshot repository to register or update. + * @codegen_name name + */ repository: Name } query_parameters: { + /** + * 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`. + * @server_default 30s + */ master_timeout?: Duration + /** + * 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`. + * @server_default 30s + */ timeout?: Duration + /** + * 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. + * @server_default true + */ verify?: boolean } /** @codegen_name repository */ diff --git a/specification/snapshot/delete/SnapshotDeleteRequest.ts b/specification/snapshot/delete/SnapshotDeleteRequest.ts index b0a022b91d..8bf08048b3 100644 --- a/specification/snapshot/delete/SnapshotDeleteRequest.ts +++ b/specification/snapshot/delete/SnapshotDeleteRequest.ts @@ -31,10 +31,23 @@ import { Duration } from '@_types/Time' */ export interface Request extends RequestBase { path_parts: { + /** + * The name of the repository to delete a snapshot from. + */ repository: Name + /** + * A comma-separated list of snapshot names to delete. + * It also accepts wildcards (`*`). + */ snapshot: Name } query_parameters: { + /** + * 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`. + * @server_default 30s + */ master_timeout?: Duration } } diff --git a/specification/snapshot/delete_repository/SnapshotDeleteRepositoryRequest.ts b/specification/snapshot/delete_repository/SnapshotDeleteRepositoryRequest.ts index 3f10a3cb57..6e2816995d 100644 --- a/specification/snapshot/delete_repository/SnapshotDeleteRepositoryRequest.ts +++ b/specification/snapshot/delete_repository/SnapshotDeleteRepositoryRequest.ts @@ -33,11 +33,26 @@ import { Duration } from '@_types/Time' */ export interface Request extends RequestBase { path_parts: { - /** @codegen_name name */ + /** + * The ame of the snapshot repositories to unregister. + * Wildcard (`*`) patterns are supported. + * @codegen_name name */ repository: Names } query_parameters: { + /** + * 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`. + * @server_default 30s + */ master_timeout?: Duration + /** + * 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`. + * @server_default 30s + */ timeout?: Duration } } diff --git a/specification/snapshot/get/SnapshotGetRequest.ts b/specification/snapshot/get/SnapshotGetRequest.ts index 4c02547a2c..5e8ae8208c 100644 --- a/specification/snapshot/get/SnapshotGetRequest.ts +++ b/specification/snapshot/get/SnapshotGetRequest.ts @@ -26,6 +26,10 @@ import { Duration } from '@_types/Time' /** * 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. * @rest_spec_name snapshot.get * @availability stack since=0.0.0 stability=stable * @availability serverless stability=stable visibility=private @@ -35,78 +39,74 @@ import { Duration } from '@_types/Time' export interface Request extends RequestBase { path_parts: { /** - * Comma-separated list of snapshot repository names used to limit the request. Wildcard (*) expressions are supported. + * A comma-separated list of snapshot repository names used to limit the request. + * Wildcard (`*`) expressions are supported. */ repository: Name /** - * Comma-separated list of snapshot names to retrieve. Also accepts wildcards (*). - * - To get information about all snapshots in a registered repository, use a wildcard (*) or _all. - * - To get information about any snapshots that are currently running, use _current. + * A comma-separated list of snapshot names to retrieve + * Wildcards (`*`) are supported. + * + * * To get information about all snapshots in a registered repository, use a wildcard (`*`) or `_all`. + * * To get information about any snapshots that are currently running, use `_current`. */ snapshot: Names } query_parameters: { /** - * If false, the request returns an error for any snapshots that are unavailable. - * @server_default false + * An offset identifier to start pagination from as returned by the next field in the response body. + * @availability stack since=7.14.0 + * @availability serverless */ - ignore_unavailable?: boolean + after?: string /** - * 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. - * @server_default 30s + * 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. + * @availability stack since=7.16.0 + * @availability serverless */ - master_timeout?: Duration + from_sort_value?: string /** - * 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. - * @server_default true + * If `false`, the request returns an error for any snapshots that are unavailable. + * @server_default false */ - verbose?: boolean + ignore_unavailable?: 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. + * 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. * @server_default false * @availability stack since=7.13.0 * @availability serverless */ index_details?: boolean /** - * If true, returns the name of each index in each snapshot. + * If `true`, the response includes the name of each index in each snapshot. * @server_default true * @availability stack since=8.3.0 * @availability serverless */ index_names?: boolean /** - * If true, returns the repository name in each snapshot. + * If `true`, the response includes the repository name in each snapshot. * @server_default true */ include_repository?: boolean /** - * Allows setting a sort order for the result. Defaults to start_time, i.e. sorting by snapshot start time stamp. - * @server_default start_time - * @availability stack since=7.14.0 - * @availability serverless - */ - sort?: SnapshotSort - /** - * Maximum number of snapshots to return. Defaults to 0 which means return all that match the request without limit. - * @server_default 0 - * @availability stack since=7.14.0 - * @availability serverless + * 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. + * @server_default 30s */ - size?: integer + master_timeout?: Duration /** - * Sort order. Valid values are asc for ascending and desc for descending order. Defaults to asc, meaning ascending order. + * The sort order. + * Valid values are `asc` for ascending and `desc` for descending order. + * The default behavior is ascending order. * @server_default asc * @availability stack since=7.14.0 * @availability serverless */ order?: SortOrder - /** - * Offset identifier to start pagination from as returned by the next field in the response body. - * @availability stack since=7.14.0 - * @availability serverless - */ - after?: string /** * 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. * @server_default 0 @@ -115,16 +115,38 @@ export interface Request extends RequestBase { */ offset?: integer /** - * 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. - * @availability stack since=7.16.0 + * The maximum number of snapshots to return. + * The default is 0, which means to return all that match the request without limit. + * @server_default 0 + * @availability stack since=7.14.0 * @availability serverless */ - from_sort_value?: string + size?: integer /** - * Filter snapshots by a comma-separated list of SLM policy names that snapshots belong to. Also accepts wildcards (*) and combinations of wildcards followed by exclude patterns starting with -. To include snapshots not created by an SLM policy you can use the special pattern _none that will match all snapshots without an SLM policy. + * Filter snapshots by a comma-separated list of snapshot lifecycle management (SLM) policy names that snapshots belong to. + * + * You can use wildcards (`*`) and combinations of wildcards followed by exclude patterns starting with `-`. + * For example, the pattern `*,-policy-a-\*` will return all snapshots except for those that were created by an SLM policy with a name starting with `policy-a-`. + * Note that the wildcard pattern `*` matches all snapshots created by an SLM policy but not those snapshots that were not created by an SLM policy. + * To include snapshots that were not created by an SLM policy, you can use the special pattern `_none` that will match all snapshots without an SLM policy. * @availability stack since=7.16.0 * @availability serverless */ slm_policy_filter?: Name + /** + * The sort order for the result. + * The default behavior is sorting by snapshot start time stamp. + * @server_default start_time + * @availability stack since=7.14.0 + * @availability serverless + */ + sort?: SnapshotSort + /** + * 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. + * @server_default true + */ + verbose?: boolean } } diff --git a/specification/snapshot/get/SnapshotGetResponse.ts b/specification/snapshot/get/SnapshotGetResponse.ts index 6646a7bf4e..0de468d134 100644 --- a/specification/snapshot/get/SnapshotGetResponse.ts +++ b/specification/snapshot/get/SnapshotGetResponse.ts @@ -24,20 +24,25 @@ import { integer } from '@_types/Numeric' export class Response { body: { - responses?: SnapshotResponseItem[] - snapshots?: SnapshotInfo[] /** - * The total number of snapshots that match the request when ignoring size limit or after query parameter. + * The number of remaining snapshots that were not returned due to size limits and that can be fetched by additional requests using the `next` field value. * @availability stack since=7.15.0 * @availability serverless */ - total: integer + remaining: integer /** - * The number of remaining snapshots that were not returned due to size limits and that can be fetched by additional requests using the next field value. + * The total number of snapshots that match the request when ignoring the size limit or `after` query parameter. * @availability stack since=7.15.0 * @availability serverless */ - remaining: integer + total: integer + /** + * If the request contained a size limit and there might be more results, a `next` field will be added to the response. + * It can be used as the `after` query parameter to fetch additional results. + */ + next?: string + responses?: SnapshotResponseItem[] + snapshots?: SnapshotInfo[] } } diff --git a/specification/snapshot/get_repository/SnapshotGetRepositoryRequest.ts b/specification/snapshot/get_repository/SnapshotGetRepositoryRequest.ts index 1c984091bf..dd0d2a7d5c 100644 --- a/specification/snapshot/get_repository/SnapshotGetRepositoryRequest.ts +++ b/specification/snapshot/get_repository/SnapshotGetRepositoryRequest.ts @@ -31,11 +31,28 @@ import { Duration } from '@_types/Time' */ export interface Request extends RequestBase { path_parts: { - /** @codegen_name name */ + /** + * A comma-separated list of snapshot repository names used to limit the request. + * Wildcard (`*`) expressions are supported including combining wildcards with exclude patterns starting with `-`. + * + * To get information about all snapshot repositories registered in the cluster, omit this parameter or use `*` or `_all`. + * @codegen_name name + */ repository?: Names } query_parameters: { + /** + * If `true`, the request gets information from the local node only. + * If `false`, the request gets information from the master node. + * @server_default false + */ local?: boolean + /** + * 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`. + * @server_default to 30s + */ master_timeout?: Duration } } diff --git a/specification/snapshot/repository_verify_integrity/SnapshotRepositoryVerifyIntegrityRequest.ts b/specification/snapshot/repository_verify_integrity/SnapshotRepositoryVerifyIntegrityRequest.ts index 9b2e7b48f3..b1971a050c 100644 --- a/specification/snapshot/repository_verify_integrity/SnapshotRepositoryVerifyIntegrityRequest.ts +++ b/specification/snapshot/repository_verify_integrity/SnapshotRepositoryVerifyIntegrityRequest.ts @@ -50,6 +50,14 @@ import { integer } from '@_types/Numeric' * 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. * @rest_spec_name snapshot.repository_verify_integrity * @availability stack since=8.16.0 stability=experimental visibility=private * @cluster_privileges manage @@ -57,17 +65,56 @@ import { integer } from '@_types/Numeric' */ export interface Request extends RequestBase { path_parts: { - /** @codegen_name name */ + /** + * The name of the snapshot repository. + * @codegen_name name */ repository: Names } query_parameters: { - meta_thread_pool_concurrency?: integer + /** + * If `verify_blob_contents` is `true`, this parameter specifies how many blobs to verify at once. + * @server_default 1 + */ blob_thread_pool_concurrency?: integer - snapshot_verification_concurrency?: integer - index_verification_concurrency?: integer + /** + * The maximum number of index snapshots to verify concurrently within each index verification. + * @server_default 1 + */ index_snapshot_verification_concurrency?: integer + /** + * The number of indices to verify concurrently. + * The default behavior is to use the entire `snapshot_meta` thread pool. + * @server_default 0 + */ + index_verification_concurrency?: integer + /** + * If `verify_blob_contents` is `true`, this parameter specifies the maximum amount of data that Elasticsearch will read from the repository every second. + * @server_default 10mb + */ + max_bytes_per_sec?: string + /** + * The number of shard snapshot failures to track during integrity verification, in order to avoid excessive resource usage. + * If your repository contains more than this number of shard snapshot failures, the verification will fail. + * @server_default 10000 + */ max_failed_shard_snapshots?: integer + /** + * The maximum number of snapshot metadata operations to run concurrently. + * The default behavior is to use at most half of the `snapshot_meta` thread pool at once. + * @server_default 0 + */ + meta_thread_pool_concurrency?: integer + /** + * The number of snapshots to verify concurrently. + * The default behavior is to use at most half of the `snapshot_meta` thread pool at once. + * @server_default 0 + */ + snapshot_verification_concurrency?: integer + /** + * Indicates whether to verify the checksum of every data blob in the repository. + * If this feature is enabled, Elasticsearch will read the entire repository contents, which may be extremely slow and expensive. + * @server_default false + */ verify_blob_contents?: boolean - max_bytes_per_sec?: string } } diff --git a/specification/snapshot/restore/SnapshotRestoreRequest.ts b/specification/snapshot/restore/SnapshotRestoreRequest.ts index 0b76f3409f..c2dc87d01b 100644 --- a/specification/snapshot/restore/SnapshotRestoreRequest.ts +++ b/specification/snapshot/restore/SnapshotRestoreRequest.ts @@ -50,23 +50,120 @@ import { Duration } from '@_types/Time' */ export interface Request extends RequestBase { path_parts: { + /** + * The name of the repository to restore a snapshot from. + */ repository: Name + /** + * The name of the snapshot to restore. + */ snapshot: Name } query_parameters: { + /** + * 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`. + * @server_default 30s + */ master_timeout?: Duration + /** + * 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. + * @server_default false + */ wait_for_completion?: boolean } body: { + /** + * 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"]`). + * @ext_doc_id snapshot-restore-feature-state + */ feature_states?: 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_index_settings?: string[] + /** + * 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. + * @server_default false + */ ignore_unavailable?: boolean + /** + * If `true`, the request restores aliases for any restored data streams and indices. + * If `false`, the request doesn’t restore aliases. + * @server_default true + */ include_aliases?: 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. + * @server_default false + */ include_global_state?: boolean + /** + * 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. + */ index_settings?: IndexSettings + /** + * A comma-separated list of indices and data streams to restore. + * It supports a multi-target syntax. + * The default behavior is all regular indices and regular data streams in the snapshot. + * + * You can't use this parameter to restore system indices or system data streams. + * Use `feature_states` instead. + */ indices?: Indices + /** + * 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. + * @server_default false + */ partial?: boolean + /** + * 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. + * @ext_doc_id snapshot-restore-amend-replacement + */ rename_pattern?: string + /** + * The rename replacement string that is used with the `rename_pattern`. + */ rename_replacement?: string } } diff --git a/specification/snapshot/status/SnapshotStatusRequest.ts b/specification/snapshot/status/SnapshotStatusRequest.ts index 1ec4028cab..3f111fee2d 100644 --- a/specification/snapshot/status/SnapshotStatusRequest.ts +++ b/specification/snapshot/status/SnapshotStatusRequest.ts @@ -24,9 +24,14 @@ import { Duration } from '@_types/Time' /** * 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). @@ -41,11 +46,31 @@ import { Duration } from '@_types/Time' */ export interface Request extends RequestBase { path_parts: { + /** + * The snapshot repository name used to limit the request. + * It supports wildcards (`*`) if `` isn't specified. + */ repository?: Name + /** + * A comma-separated list of snapshots to retrieve status for. + * The default is currently running snapshots. + * Wildcards (`*`) are not supported. + */ snapshot?: Names } query_parameters: { + /** + * 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. + * @server_default false + */ ignore_unavailable?: boolean // default: false + /** + * 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`. + * @server_default 30s + */ master_timeout?: Duration } } diff --git a/specification/snapshot/verify_repository/SnapshotVerifyRepositoryRequest.ts b/specification/snapshot/verify_repository/SnapshotVerifyRepositoryRequest.ts index 45598ca34b..29ebd1da8f 100644 --- a/specification/snapshot/verify_repository/SnapshotVerifyRepositoryRequest.ts +++ b/specification/snapshot/verify_repository/SnapshotVerifyRepositoryRequest.ts @@ -33,11 +33,25 @@ import { Duration } from '@_types/Time' */ export interface Request extends RequestBase { path_parts: { - /** @codegen_name name */ + /** + * The name of the snapshot repository to verify. + * @codegen_name name */ repository: Name } query_parameters: { + /** + * 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`. + * @server_default 30s + */ master_timeout?: Duration + /** + * 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`. + * @server_default 30s + */ timeout?: Duration } } diff --git a/specification/snapshot/verify_repository/SnapshotVerifyRepositoryResponse.ts b/specification/snapshot/verify_repository/SnapshotVerifyRepositoryResponse.ts index 144e6ae9f5..3c7946fe82 100644 --- a/specification/snapshot/verify_repository/SnapshotVerifyRepositoryResponse.ts +++ b/specification/snapshot/verify_repository/SnapshotVerifyRepositoryResponse.ts @@ -21,9 +21,20 @@ import { Dictionary } from '@spec_utils/Dictionary' import { Name } from '@_types/common' export class Response { - body: { nodes: Dictionary } + body: { + /** + * Information about the nodes connected to the snapshot repository. + * The key is the ID of the node. + */ + nodes: Dictionary + } } export class CompactNodeInfo { + /** + * A human-readable name for the node. + * You can set this name using the `node.name` property in `elasticsearch.yml`. + * The default value is the machine's hostname. + */ name: Name }