diff --git a/_api-reference/snapshots/cleanup-snapshot-repository.md b/_api-reference/snapshots/cleanup-snapshot-repository.md index 202410c758a..70e4381460d 100644 --- a/_api-reference/snapshots/cleanup-snapshot-repository.md +++ b/_api-reference/snapshots/cleanup-snapshot-repository.md @@ -1,37 +1,92 @@ --- layout: default -title: Cleanup Snapshot Repository +title: Cleanup snapshot repository parent: Snapshot APIs nav_order: 11 --- -# Cleanup Snapshot Repository +# Cleanup snapshot repository Introduced 1.0 {: .label .label-purple } -The Cleanup Snapshot Repository API clears a snapshot repository of data no longer referenced by any existing snapshot. +The Cleanup Snapshot Repository API removes data from a snapshot repository that is no longer referenced by any existing snapshot. This helps reclaim storage space and optimize repository performance. + ## Endpoints - ```json -POST /_snapshot//_cleanup +POST /_snapshot/{repository}/_cleanup ``` + + ## Path parameters -| Parameter | Data type | Description | -| :--- | :--- | :--- | -| `repository` | String | The name of the snapshot repository. | +The following table lists the available path parameters. + +| Parameter | Required | Data type | Description | +| :--- | :--- | :--- | :--- | +| `repository` | **Required** | String | Snapshot repository to clean up. | + + + ## Query parameters The following table lists the available query parameters. All query parameters are optional. -| Parameter | Data type | Description | +| Parameter | Data type | Description | | :--- | :--- | :--- | -| `cluster_manager_timeout` | Time | The amount of time to wait for a response from the cluster manager node. Formerly called `master_timeout`. Optional. Default is 30 seconds. | -| `timeout` | Time | The amount of time to wait for the operation to complete. Optional.| +| `cluster_manager_timeout` | String | The amount of time to wait for a response from the cluster manager node. For more information about supported time units, see [Common parameters]({{site.url}}{{site.baseurl}}/api-reference/common-parameters/#time-units). | +| `timeout` | String | The amount of time to wait for a response. | + + + + + + + + +## Response body fields + +The response body is a JSON object with the following fields. + +| Property | Required | Data type | Description | +| :--- | :--- | :--- | :--- | +| `results` | **Required** | Object | Details the results and metrics of the snapshot cleanup operation. | + +
+ + Response body fields: results + + {: .text-delta} + +`results` is a JSON object with the following fields. + +| Property | Required | Data type | Description | +| :--- | :--- | :--- | :--- | +| `deleted_blobs` | **Required** | Integer | The number of binary large objects (blobs) removed during cleanup. | +| `deleted_bytes` | **Required** | Integer | The number of bytes freed by cleanup operations. | + +
+ + ## Example request @@ -54,10 +109,4 @@ POST /_snapshot/my_backup/_cleanup } ``` -## Response body fields - -| Field | Data type | Description | -| :--- | :--- | :--- | -| `deleted_bytes` | Integer | The number of bytes made available in the snapshot after data deletion. | -| `deleted_blobs` | Integer | The number of binary large objects (BLOBs) cleared from the repository by the request. | diff --git a/_api-reference/snapshots/clone-snapshot.md b/_api-reference/snapshots/clone-snapshot.md index d220eb266bf..ce2475cf514 100644 --- a/_api-reference/snapshots/clone-snapshot.md +++ b/_api-reference/snapshots/clone-snapshot.md @@ -9,8 +9,7 @@ nav_order: 10 Introduced 1.0 {: .label .label-purple } -Creates a clone of all or part of a snapshot in the same repository as the original. - +The Clone Snapshot API creates a copy of all or part of an existing snapshot within the same repository. This is useful when you want to preserve a specific version of a snapshot while continuing to modify the original. + +## Request body fields + +The snapshot clone definition. + +The request body is __required__. It is a JSON object with the following fields. + +| Property | Required | Data type | Description | +| :--- | :--- | :--- | :--- | +| `indices` | **Required** | String | A comma-separated list of index patterns to clone from the source snapshot. Wildcards are supported. | + + + + ## Example request The following request clones indexes `index_a` and `index_b` from `my_snapshot`, a snapshot located in the snapshot repository `my-opensearch-repo`, into a new snapshot in the same repository called `my_new_snapshot`: diff --git a/_api-reference/snapshots/create-repository.md b/_api-reference/snapshots/create-repository.md index 3567b56f881..23181b3b574 100644 --- a/_api-reference/snapshots/create-repository.md +++ b/_api-reference/snapshots/create-repository.md @@ -1,49 +1,149 @@ --- layout: default -title: Register Snapshot Repository +title: Register or update snapshot repository parent: Snapshot APIs nav_order: 1 --- -# Registering or updating a snapshot repository +# Register or update snapshot reposity **Introduced 1.0** {: .label .label-purple } -You can register a new repository in which to store snapshots or update information for an existing repository by using the snapshots API. +The Register Snapshot Repository API lets you register a new repository for storing snapshots or update information for an existing repository. There are two types of snapshot repositories: -* File system (`fs`): For instructions on creating an `fs` repository, see [Register repository shared file system]({{site.url}}{{site.baseurl}}/tuning-your-cluster/availability-and-recovery/snapshots/snapshot-restore/#shared-file-system). +* File system (`fs`): Stores snapshots in a shared file system accessible to all cluster nodes. For instructions on creating an `fs` repository, see [Register repository shared file system]({{site.url}}{{site.baseurl}}/tuning-your-cluster/availability-and-recovery/snapshots/snapshot-restore/#shared-file-system). -* Amazon Simple Storage Service (Amazon S3) bucket (`s3`): For instructions on creating an `s3` repository, see [Register repository Amazon S3]({{site.url}}{{site.baseurl}}/tuning-your-cluster/availability-and-recovery/snapshots/snapshot-restore/#amazon-s3). +* Amazon Simple Storage Service (`s3`): Stores snapshots in an Amazon S3 bucket. For instructions on creating an `s3` repository, see [Register repository Amazon S3]({{site.url}}{{site.baseurl}}/tuning-your-cluster/availability-and-recovery/snapshots/snapshot-restore/#amazon-s3). -For instructions on creating a repository, see [Register repository]({{site.url}}{{site.baseurl}}/opensearch/snapshots/snapshot-restore#register-repository). +For general repository creation instructions, see [Register repository]({{site.url}}{{site.baseurl}}/opensearch/snapshots/snapshot-restore#register-repository). + ## Endpoints - ```json -POST /_snapshot// -PUT /_snapshot// +POST /_snapshot/{repository} +PUT /_snapshot/{repository} ``` + + + ## Path parameters -Parameter | Data type | Description -:--- | :--- | :--- -`repository` | String | Repository name | +The following table lists the available path parameters. + +| Parameter | Required | Data type | Description | +| :--- | :--- | :--- | :--- | +| `repository` | **Required** | String | The name for the newly registered repository. | + + + + +## Query parameters + +The following table lists the available query parameters. All query parameters are optional. + +| Parameter | Data type | Description | +| :--- | :--- | :--- | +| `cluster_manager_timeout` | String | The amount of time to wait for a response from the cluster manager node. For more information about supported time units, see [Common parameters]({{site.url}}{{site.baseurl}}/api-reference/common-parameters/#time-units). | +| `timeout` | String | The amount of time to wait for a response. | +| `verify` | Boolean | When `true`, verifies the repository is accessible on all nodes in the cluster. Default is `true`. | + + + + +## Request body fields + +The repository definition. + +The request body is __required__. It is a JSON object with the following fields. + +| Property | Required | Data type | Description | +| :--- | :--- | :--- | :--- | +| `type` | **Required** | String | The type of repository to register, either `fs` or `s3`. | +| `settings` | **Required** | Object | The settings for the snapshot repository. See [Repository specific parameters](#repository-specific-parameters) for available options. | +| `repository` | Optional | Object | The name of the repository to store the snapshot. | + +
+ + Request body fields: repository + + {: .text-delta} -## Request parameters +The name of the repository to store the snapshot. -Request parameters depend on the type of repository: `fs` or `s3`. +`repository` is a JSON object with the following fields. -### Common parameters +| Property | Data type | Description | +| :--- | :--- | :--- | +| `settings` | Object | The settings for the snapshot repository. | +| `type` | String | The type of the snapshot repository. | +| `uuid` | String | The universally unique identifier. | + +
+
+ + Request body fields: repository > settings + + {: .text-delta} + +The settings for the snapshot repository. + +`settings` is a JSON object with the following fields. + +| Property | Data type | Description | +| :--- | :--- | :--- | +| `chunk_size` | String | The chunk size for the repository. | +| `compress` | Boolean or String | Whether to compress metadata files. | +| `concurrent_streams` | Integer or String | The number of concurrent streams for repository operations. | +| `location` | String | The location where snapshots are stored. | +| `read_only` | Boolean or String | Whether the repository is read-only. | + +
+
+ + Request body fields: settings + + {: .text-delta} + +The settings for the snapshot repository. + +`settings` is a JSON object with the following fields. + +| Property | Data type | Description | +| :--- | :--- | :--- | +| `chunk_size` | String | The chunk size for the repository. | +| `compress` | Boolean or String | Whether to compress metadata files. | +| `concurrent_streams` | Integer or String | The number of concurrent streams for repository operations. | +| `location` | String | The location where snapshots are stored. | +| `read_only` | Boolean or String | Whether the repository is read-only. | + +
+ + + +### Repository specific parameters The following table lists parameters that can be used with both the `fs` and `s3` repositories. -Request field | Description -:--- | :--- -`prefix_mode_verification` | When enabled, adds a hashed value of a random seed to the prefix for repository verification. For remote-store-enabled clusters, you can add the `setting.prefix_mode_verification` setting to the node attributes for the supplied repository. This field works with both new and existing repositories. Optional. -`shard_path_type` | Controls the path structure of shard-level blobs. Supported values are `FIXED`, `HASHED_PREFIX`, and `HASHED_INFIX`. For more information about each value, see [shard_path_type values](#shard_path_type-values)/. Default is `FIXED`. Optional. +| Request field | Data type | Description | +|:--- | :--- | :--- | +| `prefix_mode_verification` | Boolean | When enabled, adds a hashed value of a random seed to the prefix for repository verification. For remote-store-enabled clusters, you can add the `setting.prefix_mode_verification` setting to the node attributes for the supplied repository. This field works with both new and existing repositories. Optional. | +| `shard_path_type` | String | Controls the path structure of shard-level blobs. Supported values are `FIXED`, `HASHED_PREFIX`, and `HASHED_INFIX`. For more information about each value, see [shard_path_type values](#shard_path_type-values). Default is `FIXED`. Optional. | #### shard_path_type values @@ -55,37 +155,41 @@ The following values are supported in the `shard_path_type` setting: ### fs repository -Request field | Description -:--- | :--- -`location` | The file system directory for snapshots, such as a mounted directory from a file server or a Samba share. Must be accessible by all nodes. Required. -`chunk_size` | Breaks large files into chunks during snapshot operations (e.g. `64mb`, `1gb`), which is important for cloud storage providers and far less important for shared file systems. Default is `null` (unlimited). Optional. -`compress` | Whether to compress metadata files. This setting does not affect data files, which might already be compressed, depending on your index settings. Default is `false`. Optional. -`max_restore_bytes_per_sec` | The maximum rate at which snapshots restore. Default is 40 MB per second (`40m`). Optional. -`max_snapshot_bytes_per_sec` | The maximum rate at which snapshots take. Default is 40 MB per second (`40m`). Optional. -`remote_store_index_shallow_copy` | Boolean | Determines whether the snapshot of the remote store indexes are captured as a shallow copy. Default is `false`. -`shallow_snapshot_v2` | Boolean | Determines whether the snapshots of the remote store indexes are captured as a [shallow copy v2]({{site.url}}{{site.baseurl}}/tuning-your-cluster/availability-and-recovery/remote-store/snapshot-interoperability/#shallow-snapshot-v2). Default is `false`. -`readonly` | Whether the repository is read-only. Useful when migrating from one cluster (`"readonly": false` when registering) to another cluster (`"readonly": true` when registering). Optional. +The following table lists parameters specific to `fs` repositories: + +| Request field | Data type | Description | +|:--- | :--- | :--- | +| `location` | String | The file system directory for snapshots, such as a mounted directory from a file server or a Samba share. Must be accessible by all nodes. Required. | +| `chunk_size` | String | Breaks large files into chunks during snapshot operations (e.g. `64mb`, `1gb`), which is important for cloud storage providers and far less important for shared file systems. Default is `null` (unlimited). Optional. | +| `compress` | Boolean | Whether to compress metadata files. This setting does not affect data files, which might already be compressed, depending on your index settings. Default is `false`. Optional. | +| `max_restore_bytes_per_sec` | String | The maximum rate at which snapshots restore. Default is 40 MB per second (`40m`). Optional. | +| `max_snapshot_bytes_per_sec` | String | The maximum rate at which snapshots take. Default is 40 MB per second (`40m`). Optional. | +| `remote_store_index_shallow_copy` | Boolean | Determines whether the snapshot of the remote store indexes are captured as a shallow copy. Default is `false`. Optional. | +| `shallow_snapshot_v2` | Boolean | Determines whether the snapshots of the remote store indexes are captured as a [shallow copy v2]({{site.url}}{{site.baseurl}}/tuning-your-cluster/availability-and-recovery/remote-store/snapshot-interoperability/#shallow-snapshot-v2). Default is `false`. Optional. | +| `readonly` | Boolean | Whether the repository is read-only. Useful when migrating from one cluster (`"readonly": false` when registering) to another cluster (`"readonly": true` when registering). Optional. | #### s3 repository -Request field | Description -:--- | :--- -`base_path` | The path within the bucket in which you want to store snapshots (for example, `my/snapshot/directory`). Optional. If not specified, snapshots are stored in the S3 bucket root. -`bucket` | Name of the S3 bucket. Required. -`buffer_size` | The threshold beyond which chunks (of `chunk_size`) should be broken into pieces (of `buffer_size`) and sent to S3 using a different API. Default is the smaller of two values: 100 MB or 5% of the Java heap. Valid values are between `5mb` and `5gb`. We don't recommend changing this option. -`canned_acl` | S3 has several [canned ACLs](https://docs.aws.amazon.com/AmazonS3/latest/dev/acl-overview.html#canned-acl) that the `repository-s3` plugin can add to objects as it creates them in S3. Default is `private`. Optional. -`chunk_size` | Breaks files into chunks during snapshot operations (e.g. `64mb`, `1gb`), which is important for cloud storage providers and far less important for shared file systems. Default is `1gb`. Optional. -`client` | When specifying client settings (e.g. `s3.client.default.access_key`), you can use a string other than `default` (e.g. `s3.client.backup-role.access_key`). If you used an alternate name, change this value to match. Default and recommended value is `default`. Optional. -`compress` | Whether to compress metadata files. This setting does not affect data files, which might already be compressed, depending on your index settings. Default is `false`. Optional. -`disable_chunked_encoding` | Disables chunked encoding for compatibility with some storage services. Default is `false`. Optional. -`max_restore_bytes_per_sec` | The maximum rate at which snapshots restore. Default is 40 MB per second (`40m`). Optional. -`max_snapshot_bytes_per_sec` | The maximum rate at which snapshots take. Default is 40 MB per second (`40m`). Optional. -`readonly` | Whether the repository is read-only. Useful when migrating from one cluster (`"readonly": false` when registering) to another cluster (`"readonly": true` when registering). Optional. -`remote_store_index_shallow_copy` | Boolean | Whether the snapshot of the remote store indexes is captured as a shallow copy. Default is `false`. -`shallow_snapshot_v2` | Boolean | Determines whether the snapshots of the remote store indexes are captured as a [shallow copy v2]([shallow copy v2]({{site.url}}{{site.baseurl}}/tuning-your-cluster/availability-and-recovery/remote-store/snapshot-interoperability/#shallow-snapshot-v2). Default is `false`. -`server_side_encryption` | Whether to encrypt snapshot files in the S3 bucket. This setting uses AES-256 with S3-managed keys. See [Protecting data using server-side encryption](https://docs.aws.amazon.com/AmazonS3/latest/dev/serv-side-encryption.html). Default is `false`. Optional. -`storage_class` | Specifies the [S3 storage class](https://docs.aws.amazon.com/AmazonS3/latest/dev/storage-class-intro.html) for the snapshots files. Default is `standard`. Do not use the `glacier` and `deep_archive` storage classes. Optional. +The following table lists parameters specific to `s3` repositories: + +| Request field | Data type | Description | +|:--- | :--- | :--- | +| `bucket` | String | Name of the S3 bucket. Required. | +| `base_path` | String | The path within the bucket in which to store snapshots (for example, `my/snapshot/directory`). Optional. If not specified, snapshots are stored in the S3 bucket root. | +| `buffer_size` | String | The threshold beyond which chunks (of `chunk_size`) should be broken into pieces (of `buffer_size`) and sent to S3 using a different API. Default is the smaller of two values: 100 MB or 5% of the Java heap. Valid values are between `5mb` and `5gb`. We don't recommend changing this option. | +| `canned_acl` | String | S3 has several [canned ACLs](https://docs.aws.amazon.com/AmazonS3/latest/dev/acl-overview.html#canned-acl) that the `repository-s3` plugin can add to objects as it creates them in S3. Default is `private`. Optional. | +| `chunk_size` | String | Breaks files into chunks during snapshot operations (e.g. `64mb`, `1gb`), which is important for cloud storage providers and far less important for shared file systems. Default is `1gb`. Optional. | +| `client` | String | When specifying client settings (e.g. `s3.client.default.access_key`), you can use a string other than `default` (e.g. `s3.client.backup-role.access_key`). If you used an alternate name, change this value to match. Default and recommended value is `default`. Optional. | +| `compress` | Boolean | Whether to compress metadata files. This setting does not affect data files, which might already be compressed, depending on your index settings. Default is `false`. Optional. | +| `disable_chunked_encoding` | Boolean | Disables chunked encoding for compatibility with some storage services. Default is `false`. Optional. | +| `max_restore_bytes_per_sec` | String | The maximum rate at which snapshots restore. Default is 40 MB per second (`40m`). Optional. | +| `max_snapshot_bytes_per_sec` | String | The maximum rate at which snapshots take. Default is 40 MB per second (`40m`). Optional. | +| `readonly` | Boolean | Whether the repository is read-only. Useful when migrating from one cluster (`"readonly": false` when registering) to another cluster (`"readonly": true` when registering). Optional. | +| `remote_store_index_shallow_copy` | Boolean | Whether the snapshot of the remote store indexes is captured as a shallow copy. Default is `false`. Optional. | +| `shallow_snapshot_v2` | Boolean | Determines whether the snapshots of the remote store indexes are captured as a [shallow copy v2]({{site.url}}{{site.baseurl}}/tuning-your-cluster/availability-and-recovery/remote-store/snapshot-interoperability/#shallow-snapshot-v2). Default is `false`. Optional. | +| `server_side_encryption` | Boolean | Whether to encrypt snapshot files in the S3 bucket. This setting uses AES-256 with S3-managed keys. See [Protecting data using server-side encryption](https://docs.aws.amazon.com/AmazonS3/latest/dev/serv-side-encryption.html). Default is `false`. Optional. | +| `storage_class` | String | Specifies the [S3 storage class](https://docs.aws.amazon.com/AmazonS3/latest/dev/storage-class-intro.html) for the snapshots files. Default is `standard`. Do not use the `glacier` and `deep_archive` storage classes. Optional. | For the `base_path` parameter, do not enter the `s3://` prefix when entering your S3 bucket details. Only the name of the bucket is required. {: .note} @@ -136,3 +240,4 @@ Upon success, the following JSON object is returned: To verify that the repository was registered, use the [Get snapshot repository]({{site.url}}{{site.baseurl}}/api-reference/snapshots/get-snapshot-repository) API, passing the repository name as the `repository` path parameter. {: .note} + diff --git a/_api-reference/snapshots/create-snapshot.md b/_api-reference/snapshots/create-snapshot.md index ce96bd6442f..98e84319cf3 100644 --- a/_api-reference/snapshots/create-snapshot.md +++ b/_api-reference/snapshots/create-snapshot.md @@ -9,57 +9,81 @@ nav_order: 5 **Introduced 1.0** {: .label .label-purple } -Creates a snapshot within an existing repository. +The Create Snapshot API creates a snapshot of your cluster's data within an existing repository. Snapshots serve as backups that you can use to restore your data or migrate it between clusters. -* To learn more about snapshots, see [Snapshots]({{site.url}}{{site.baseurl}}/opensearch/snapshots/index). - -* To view a list of your repositories, see [Get snapshot repository]({{site.url}}{{site.baseurl}}/api-reference/snapshots/get-snapshot-repository). +* For more information about snapshots, see [Snapshots]({{site.url}}{{site.baseurl}}/opensearch/snapshots/index/). +* To view a list of your repositories, see [Get Snapshot Repository]({{site.url}}{{site.baseurl}}/api-reference/snapshots/get-snapshot-repository/). + ## Endpoints - ```json -PUT /_snapshot// -POST /_snapshot// +POST /_snapshot/{repository}/{snapshot} +PUT /_snapshot/{repository}/{snapshot} ``` + + + ## Path parameters -Parameter | Data type | Description -:--- | :--- | :--- -repository | String | Repository name to store the snapshot. | -snapshot | String | Name of Snapshot to create. | +The following table lists the available path parameters. +| Parameter | Required | Data type | Description | +| :--- | :--- | :--- | :--- | +| `repository` | **Required** | String | The name of the repository where the snapshot will be stored. | +| `snapshot` | **Required** | String | The name of the snapshot. Must be unique in the repository. | + + + + ## Query parameters -Parameter | Data type | Description -:--- | :--- | :--- -wait_for_completion | Boolean | Whether to wait for snapshot creation to complete before continuing. If you include this parameter, the snapshot definition is returned after completion. | +The following table lists the available query parameters. All query parameters are optional. + +| Parameter | Data type | Description | +| :--- | :--- | :--- | +| `cluster_manager_timeout` | String | The amount of time to wait for a response from the cluster manager node. For more information about supported time units, see [Common parameters]({{site.url}}{{site.baseurl}}/api-reference/common-parameters/#time-units). | +| `wait_for_completion` | Boolean | When `true`, the request returns a response when the snapshot is complete. When `false`, the request returns a response when the snapshot initializes. _(Default: `false`)_ | + + + ## Request body fields -The request body is optional. +The request body is optional. It is a JSON object with the following fields. -Field | Data type | Description -:--- | :--- | :--- -`indices` | String | The indices you want to include in the snapshot. You can use `,` to create a list of indices, `*` to specify an index pattern, and `-` to exclude certain indices. Don't put spaces between items. Default is all indices. -`ignore_unavailable` | Boolean | If an index from the `indices` list doesn't exist, whether to ignore it rather than fail the snapshot. Default is `false`. -`include_global_state` | Boolean | Whether to include cluster state in the snapshot. Default is `true`. -`partial` | Boolean | Whether to allow partial snapshots. Default is `false`, which fails the entire snapshot if one or more shards fails to stor +| Property | Data type | Description | Default | +| :--- | :--- | :--- | :--- | +| `indices` | String or Array of Strings | A comma-separated list of data streams, indexes, and aliases to include in the snapshot. Supports wildcards (`*`). To include all data streams and indexes, omit this parameter or use `*` or `_all`. | N/A | +| `ignore_unavailable` | Boolean | When `true`, the request ignores any data streams and indexes that are missing or closed. When `false`, the request returns an error for any data streams or indexes that are missing or closed. | `false` | +| `include_global_state` | Boolean | When `true`, includes the current cluster state in the snapshot. The cluster state includes persistent cluster settings, composable index templates, legacy index templates, ingest pipelines, and ILM policies. The cluster state also includes data stored in system indexes, such as watches and task records (configurable with `feature_states`). | `true` | +| `partial` | Boolean | When `true`, allows the restoration of a partial snapshot if some shards are unavailable. Only shards that were successfully included in the snapshot will be restored. All missing shards will be recreated as empty. When `false`, the entire restore operation will fail if one or more indexes included in the snapshot do not have all primary shards available. | `false` | +| `feature_states` | Array of Strings | A list of feature states to include in the snapshot. Each feature state includes one or more system indexes which contain related data. You can view a list of features using the Get Feature 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. | N/A | +| `metadata` | Object | Custom metadata to attach to the snapshot. | N/A | -## Example requests -### Request without a body +## Example requests -The following request creates a snapshot called `my-first-snapshot` in an S3 repository called `my-s3-repository`. A request body is not included because it is optional. +The following request creates a snapshot called `my-first-snapshot` in an S3 repository called `my-s3-repository`: ```json POST _snapshot/my-s3-repository/my-first-snapshot ``` {% include copy-curl.html %} -### Request with a body +### Request with configuration -You can also add a request body to include or exclude certain indices or specify other settings: +You can add a request body to include or exclude specific indexes or specify other settings: ```json PUT _snapshot/my-s3-repository/2 @@ -74,9 +98,11 @@ PUT _snapshot/my-s3-repository/2 ## Example responses -Upon success, the response content depends on whether you include the `wait_for_completion` query parameter. +The response content depends on whether you include the `wait_for_completion` query parameter. + +### Without `wait_for_completion` -##### `wait_for_completion` not included +When `wait_for_completion=false` (the default), the API returns a simple acknowledgment that the snapshot creation has started: ```json { @@ -84,21 +110,21 @@ Upon success, the response content depends on whether you include the `wait_for_ } ``` -To verify that the snapshot was created, use the [Get snapshot]({{site.url}}{{site.baseurl}}/api-reference/snapshots/get-snapshot) API, passing the snapshot name as the `snapshot` path parameter. +To verify that the snapshot was created, use the [Get Snapshot]({{site.url}}{{site.baseurl}}/api-reference/snapshots/get-snapshot/) API, passing the snapshot name as the `snapshot` path parameter. {: .note} -### `wait_for_completion` included +### With `wait_for_completion=true` -The snapshot definition is returned. +When `wait_for_completion=true`, the API returns detailed information about the completed snapshot: ```json { - "snapshot" : { - "snapshot" : "5", - "uuid" : "ZRH4Zv7cSnuYev2JpLMJGw", - "version_id" : 136217927, - "version" : "2.0.1", - "indices" : [ + "snapshot": { + "snapshot": "5", + "uuid": "ZRH4Zv7cSnuYev2JpLMJGw", + "version_id": 136217927, + "version": "2.0.1", + "indices": [ ".opendistro-reports-instances", ".opensearch-observability", ".kibana_1", @@ -107,42 +133,59 @@ The snapshot definition is returned. ".opendistro-reports-definitions", "shakespeare" ], - "data_streams" : [ ], - "include_global_state" : true, - "state" : "SUCCESS", - "start_time" : "2022-08-10T16:52:15.277Z", - "start_time_in_millis" : 1660150335277, - "end_time" : "2022-08-10T16:52:18.699Z", - "end_time_in_millis" : 1660150338699, - "duration_in_millis" : 3422, - "failures" : [ ], - "shards" : { - "total" : 7, - "failed" : 0, - "successful" : 7 + "data_streams": [], + "include_global_state": true, + "state": "SUCCESS", + "start_time": "2022-08-10T16:52:15.277Z", + "start_time_in_millis": 1660150335277, + "end_time": "2022-08-10T16:52:18.699Z", + "end_time_in_millis": 1660150338699, + "duration_in_millis": 3422, + "failures": [], + "shards": { + "total": 7, + "failed": 0, + "successful": 7 } } } ``` -## Response body fields - -| Field | Data type | Description | -| :--- | :--- | :--- | -| snapshot | string | Snapshot name. | -| uuid | string | Snapshot's universally unique identifier (UUID). | -| version_id | int | Build ID of the Open Search version that created the snapshot. | -| version | float | Open Search version that created the snapshot. | -| indices | array | Indices in the snapshot. | -| data_streams | array | Data streams in the snapshot. | -| include_global_state | boolean | Whether the current cluster state is included in the snapshot. | -| start_time | string | Date/time when the snapshot creation process began. | -| start_time_in_millis | long | Time (in milliseconds) when the snapshot creation process began. | -| end_time | string | Date/time when the snapshot creation process ended. | -| end_time_in_millis | long | Time (in milliseconds) when the snapshot creation process ended. | -| duration_in_millis | long | Total time (in milliseconds) that the snapshot creation process lasted. | -| failures | array | Failures, if any, that occured during snapshot creation. | -| shards | object | Total number of shards created along with number of successful and failed shards. | -| state | string | Snapshot status. Possible values: `IN_PROGRESS`, `SUCCESS`, `FAILED`, `PARTIAL`. | -| remote_store_index_shallow_copy | Boolean | Whether the snapshots of the remote store indexes is captured as a shallow copy. Default is `false`. | -| pinned_timestamp | long | A timestamp (in milliseconds) pinned by the snapshot for the implicit locking of remote store files referenced by the snapshot. | \ No newline at end of file +The response body is a JSON object with the following fields. + +| Property | Data type | Description | +| :--- | :--- | :--- | +| `accepted` | Boolean | Returns `true` if the snapshot was accepted. Present when the request had `wait_for_completion` set to `false`. | +| `snapshot` | Object | The snapshot creation results. | + +
+ + Response body fields: snapshot + + {: .text-delta} + +`snapshot` is a JSON object with the following fields. + +| Property | Data type | Description | +| :--- | :--- | :--- | +| `data_streams` | Array of Strings | The list of data streams included in the snapshot. | +| `duration` | String | A duration. Units can be `nanos`, `micros`, `ms` (milliseconds), `s` (seconds), `m` (minutes), `h` (hours) and `d` (days). Also accepts `0` without a unit and `-1` to indicate an unspecified value. | +| `duration_in_millis` | Integer | The time unit for milliseconds. | +| `end_time` | Object or String | A date and time, either as a string whose format depends on the context (defaulting to ISO_8601) or the number of milliseconds since the epoch. OpenSearch accepts both as an input but will generally output a string. representation. | +| `end_time_in_millis` | Integer | The time unit for milliseconds. | +| `failures` | Array of Objects | The list of shard failures that occurred during the snapshot. | +| `include_global_state` | Boolean | Whether the snapshot includes the cluster state. | +| `indices` | Array of Strings | The list of indexes included in the snapshot. | +| `metadata` | Object | The custom metadata attached to a resource. | +| `pinned_timestamp` | Integer | The time unit for milliseconds. | +| `reason` | String | The reason for the snapshot creation. | +| `remote_store_index_shallow_copy` | Boolean | Whether the snapshot uses remote store index shallow copy. | +| `shards` | Object | The statistics about the shards included in the snapshot. | +| `snapshot` | String | The name of a resource or configuration element. | +| `start_time` | Object or String | A date and time, either as a string whose format depends on the context (defaulting to ISO_8601) or the number of milliseconds since the epoch. OpenSearch accepts both as an input but will generally output a string. representation. | +| `start_time_in_millis` | Integer | The time unit for milliseconds. | +| `state` | String | The current state of the snapshot. | +| `uuid` | String | The universally unique identifier. | +| `version` | String | The version of OpenSearch when the snapshot was created. | +| `version_id` | Integer | The internal version number of OpenSearch when the snapshot was created. | + diff --git a/_api-reference/snapshots/delete-snapshot-repository.md b/_api-reference/snapshots/delete-snapshot-repository.md index 14c2b6c86a8..497624b4a26 100644 --- a/_api-reference/snapshots/delete-snapshot-repository.md +++ b/_api-reference/snapshots/delete-snapshot-repository.md @@ -9,23 +9,61 @@ nav_order: 3 **Introduced 1.0** {: .label .label-purple } -Deletes a snapshot repository configuration. - -A repository in OpenSearch is simply a configuration that maps a repository name to a type (file system or s3 repository) along with other information depending on the type. The configuration is backed by a file system location or an s3 bucket. When you invoke the API, the physical file system or s3 bucket itself is not deleted. Only the configuration is deleted. +The Delete Snapshot Repository API removes a snapshot repository configuration from the OpenSearch cluster. -To learn more about repositories, see [Register or update snapshot repository]({{site.url}}{{site.baseurl}}/api-reference/snapshots/create-repository). +A repository in OpenSearch is a configuration that maps a repository name to a type (file system or S3) along with storage location information. When you delete a repository, only the configuration is removed from OpenSearch—the physical storage location (file system directory or S3 bucket) and any snapshots it contains remain intact. -## Endpoints +For more information about repositories, see [Register Snapshot Repository]({{site.url}}{{site.baseurl}}/api-reference/snapshots/create-repository/). + +## Endpoints ```json -DELETE _snapshot/ +DELETE /_snapshot/{repository} ``` + + + ## Path parameters -Parameter | Data type | Description -:--- | :--- | :--- -repository | String | Repository to delete. | +The following table lists the available path parameters. + +| Parameter | Required | Data type | Description | +| :--- | :--- | :--- | :--- | +| `repository` | **Required** | List or String | The name of the snapshot repository to unregister. Wildcard (`*`) patterns are supported. | + + + + +## Query parameters + +The following table lists the available query parameters. All query parameters are optional. + +| Parameter | Data type | Description | +| :--- | :--- | :--- | +| `cluster_manager_timeout` | String | The amount of time to wait for a response from the cluster manager node. For more information about supported time units, see [Common parameters]({{site.url}}{{site.baseurl}}/api-reference/common-parameters/#time-units). | +| `timeout` | String | The amount of time to wait for a response. | + + + + + + + + ## Example request @@ -47,4 +85,5 @@ Upon success, the response returns the following JSON object: ```` To verify that the repository was deleted, use the [Get snapshot repository]({{site.url}}{{site.baseurl}}/api-reference/snapshots/get-snapshot-repository) API, passing the repository name as the `repository` path parameter. -{: .note} \ No newline at end of file +{: .note} + diff --git a/_api-reference/snapshots/delete-snapshot.md b/_api-reference/snapshots/delete-snapshot.md index 57cf5347fd4..b9bc4c57f1e 100644 --- a/_api-reference/snapshots/delete-snapshot.md +++ b/_api-reference/snapshots/delete-snapshot.md @@ -9,28 +9,57 @@ nav_order: 7 **Introduced 1.0** {: .label .label-purple } -Deletes a snapshot from a repository. +The Delete Snapshot API permanently removes a snapshot from a repository. Deleting snapshots that are no longer needed helps free up storage space and keep your repository organized. -Deleting a snapshot that is in progress stops the snapshot operation and deletes the partially created snapshot. +* For more information about snapshots, see [Snapshots]({{site.url}}{{site.baseurl}}/opensearch/snapshots/index/). +* To view a list of your repositories, see [Cat Repositories]({{site.url}}{{site.baseurl}}/api-reference/cat/cat-repositories/). +* To view a list of your snapshots, see [Cat Snapshots]({{site.url}}{{site.baseurl}}/api-reference/cat/cat-snapshots/). -* To learn more about snapshots, see [Snapshots]({{site.url}}{{site.baseurl}}/opensearch/snapshots/index). -* To view a list of your repositories, see [cat repositories]({{site.url}}{{site.baseurl}}/api-reference/cat/cat-repositories). - -* To view a list of your snapshots, see [cat snapshots]({{site.url}}{{site.baseurl}}/api-reference/cat/cat-snapshots). - -## Path and HTTP method +## Endpoints ```json -DELETE _snapshot// +DELETE /_snapshot/{repository}/{snapshot} ``` + + + ## Path parameters -Parameter | Data type | Description -:--- | :--- | :--- -repository | String | Repository that contains the snapshot. | -snapshot | String | Snapshot to delete. | +The following table lists the available path parameters. + +| Parameter | Required | Data type | Description | +| :--- | :--- | :--- | :--- | +| `repository` | **Required** | String | The name of the repository containing the snapshot to delete. | +| `snapshot` | **Required** | String | A comma-separated list of snapshot names to delete from the repository. | + + + + +## Query parameters + +The following table lists the available query parameters. All query parameters are optional. + +| Parameter | Data type | Description | +| :--- | :--- | :--- | +| `cluster_manager_timeout` | String | The amount of time to wait for a response from the cluster manager node. For more information about supported time units, see [Common parameters]({{site.url}}{{site.baseurl}}/api-reference/common-parameters/#time-units). | + + + + + + ## Example request @@ -51,5 +80,5 @@ Upon success, the response returns the following JSON object: } ``` -To verify that the snapshot was deleted, use the [Get snapshot]({{site.url}}{{site.baseurl}}/api-reference/snapshots/get-snapshot) API, passing the snapshot name as the `snapshot` path parameter. +To verify that the snapshot was deleted, use the [Get Snapshot]({{site.url}}{{site.baseurl}}/api-reference/snapshots/get-snapshot/) API, passing the repository name and snapshot name as path parameters. {: .note} diff --git a/_api-reference/snapshots/get-snapshot-repository.md b/_api-reference/snapshots/get-snapshot-repository.md index 522ea0c6599..8c1f9076afc 100644 --- a/_api-reference/snapshots/get-snapshot-repository.md +++ b/_api-reference/snapshots/get-snapshot-repository.md @@ -1,39 +1,64 @@ --- layout: default -title: Get Snapshot Repository +title: Get snapshot repository parent: Snapshot APIs nav_order: 2 --- -# Get snapshot repository. +# Get snapshot repository **Introduced 1.0** {: .label .label-purple } -Retrieves information about a snapshot repository. +The Get Snapshot Repository API retrieves information about one or more snapshot repositories in your OpenSearch cluster. -To learn more about repositories, see [Register repository]({{site.url}}{{site.baseurl}}/opensearch/snapshots/snapshot-restore#register-repository). +For more information about repositories, see [Register repository]({{site.url}}{{site.baseurl}}/opensearch/snapshots/snapshot-restore#register-repository). -You can also get details about a snapshot during and after snapshot creation. See [Get snapshot status]({{site.url}}{{site.baseurl}}/api-reference/snapshots/get-snapshot-status/). +You can also get details about a snapshot during and after snapshot creation. See [Get Snapshot Status]({{site.url}}{{site.baseurl}}/api-reference/snapshots/get-snapshot-status/). {: .note} + ## Endpoints - ```json -GET /_snapshot/ +GET /_snapshot +GET /_snapshot/{repository} ``` + + + ## Path parameters +The following table lists the available path parameters. All path parameters are optional. + | Parameter | Data type | Description | | :--- | :--- | :--- | -| repository | String | A comma-separated list of snapshot repository names to retrieve. Wildcard (`*`) expressions are supported including combining wildcards with exclude patterns starting with `-`. | +| `repository` | List or String | A comma-separated list of repository names. | + + + ## Query parameters -| Parameter | Data type | Description | -:--- | :--- | :--- -| local | Boolean | Whether to get information from the local node. Optional, defaults to `false`.| -| cluster_manager_timeout | Time | Amount of time to wait for a connection to the cluster manager node. Optional, defaults to 30 seconds. | +The following table lists the available query parameters. All query parameters are optional. + +| Parameter | Data type | Description | +| :--- | :--- | :--- | +| `cluster_manager_timeout` | String | The amount of time to wait for a response from the cluster manager node. For more information about supported time units, see [Common parameters]({{site.url}}{{site.baseurl}}/api-reference/common-parameters/#time-units). | +| `local` | Boolean | Whether to get information from the local node. _(Default: `false`)_ | + + + + ## Example request @@ -62,8 +87,43 @@ Upon success, the response returns repositry information. This sample is for an ## Response body fields -| Field | Data type | Description | -| :--- | :--- | :--- | -| type | string | Bucket type: `fs` (file system) or `s3` (s3 bucket) | -| bucket | string | S3 bucket name. | -| base_path | string | Folder within the bucket where snapshots are stored. | \ No newline at end of file +The response body is a JSON object where each key is a repository name and each value contains information about that repository. + +For each repository, the response includes the following fields: + +| Property | Data type | Description | +| :--- | :--- | :--- | +| `type` | String | The type of the snapshot repository (e.g., `fs` or `s3`). | +| `settings` | Object | The settings configured for the snapshot repository. | +| `uuid` | String | The universally unique identifier for the repository, if applicable. | + +
+ + Repository settings fields + + {: .text-delta} + +The `settings` object contains fields specific to the repository type: + +**For `fs` repositories:** + +| Property | Data type | Description | +| :--- | :--- | :--- | +| `location` | String | The file system location where snapshots are stored. | +| `chunk_size` | String | The chunk size used for the repository. | +| `compress` | Boolean | Whether metadata files are compressed. | +| `readonly` | Boolean | Whether the repository is read-only. | + +**For `s3` repositories:** + +| Property | Data type | Description | +| :--- | :--- | :--- | +| `bucket` | String | The S3 bucket name. | +| `base_path` | String | The path within the bucket where snapshots are stored. | +| `chunk_size` | String | The chunk size used for the repository. | +| `compress` | Boolean | Whether metadata files are compressed. | +| `readonly` | Boolean | Whether the repository is read-only. | + +Additional settings may be present depending on the repository configuration. + +
diff --git a/_api-reference/snapshots/get-snapshot-status.md b/_api-reference/snapshots/get-snapshot-status.md index 83043b7684f..84d2cc0504b 100644 --- a/_api-reference/snapshots/get-snapshot-status.md +++ b/_api-reference/snapshots/get-snapshot-status.md @@ -1,6 +1,6 @@ --- layout: default -title: Get Snapshot Status +title: Get snapshot status parent: Snapshot APIs nav_order: 8 --- @@ -9,52 +9,57 @@ nav_order: 8 **Introduced 1.0** {: .label .label-purple } -Returns details about a snapshot’s state during and after snapshot creation. +The Get Snapshot Status API returns detailed information about a snapshot's state during and after snapshot creation. This API is useful for monitoring snapshot progress and troubleshooting issues. -To learn about snapshot creation, see [Create snapshot]({{site.url}}{{site.baseurl}}/api-reference/snapshots/create-snapshot). +For information about creating snapshots, see [Create Snapshot]({{site.url}}{{site.baseurl}}/api-reference/snapshots/create-snapshot/). If you use the Security plugin, you must have the `monitor_snapshot`, `create_snapshot`, or `manage cluster` privileges. {: .note} -## Endpoints + +## Endpoints ```json -GET _snapshot///_status +GET /_snapshot/_status +GET /_snapshot/{repository}/_status +GET /_snapshot/{repository}/{snapshot}/_status ``` + -## Path parameters - -Path parameters are optional. - -| Parameter | Data type | Description | -:--- | :--- | :--- -| repository | String | The repository containing the snapshot. | -| snapshot | List | The snapshot(s) to return. | -| index | List | The indexes to include in the response. | - -Three request variants provide flexibility: -* `GET _snapshot/_status` returns the status of all currently running snapshots in all repositories. - -* `GET _snapshot//_status` returns all currently running snapshots in the specified repository. This is the preferred variant. - -* `GET _snapshot///_status` returns detailed status information for a specific snapshot(s) in the specified repository, regardless of whether it's currently running. + +## Path parameters -* `GET /_snapshot////_status` returns detailed status information only for the specified indexes in a specific snapshot in the specified repository. Note that this endpoint works only for indexes belonging to a specific snapshot. +The following table lists the available path parameters. All path parameters are optional. -Snapshot API calls only work if the total number of shards across the requested resources, such as snapshots and indexes created from snapshots, is smaller than the limit specified by the following cluster setting: +| Parameter | Data type | Description | +| :--- | :--- | :--- | +| `repository` | String | The name of the repository containing the snapshot. | +| `snapshot` | List or String | A comma-separated list of snapshot names. | -- `snapshot.max_shards_allowed_in_status_api`(Dynamic, integer): The maximum number of shards that can be included in the Snapshot Status API response. Default value is `200000`. Not applicable for [shallow snapshots v2]({{site.url}}{{site.baseurl}}/tuning-your-cluster/availability-and-recovery/remote-store/snapshot-interoperability##shallow-snapshot-v2), where the total number and sizes of files are returned as 0. + + +## Query parameters -Using the API to return the state of snapshots that are not currently running can be very costly in terms of both machine resources and processing time when querying data in the cloud. For each snapshot, each request causes a file read of all of the snapshot's shards. -{: .warning} +The following table lists the available query parameters. All query parameters are optional. -## Request body fields +| Parameter | Data type | Description | +| :--- | :--- | :--- | +| `cluster_manager_timeout` | String | The amount of time to wait for a response from the cluster manager node. For more information about supported time units, see [Common parameters]({{site.url}}{{site.baseurl}}/api-reference/common-parameters/#time-units). | +| `ignore_unavailable` | Boolean | Whether to ignore any unavailable snapshots, When `false`, a `SnapshotMissingException` is thrown. _(Default: `false`)_ | -| Field | Data type | Description | -:--- | :--- | :--- -| ignore_unavailable | Boolean | How to handle requests for unavailable snapshots and indexes. If `false`, the request returns an error for unavailable snapshots and indexes. If `true`, the request ignores unavailable snapshots and indexes, such as those that are corrupted or temporarily cannot be returned. Default is `false`.| + ## Example request @@ -70,368 +75,156 @@ GET _snapshot/my-opensearch-repo/my-first-snapshot/_status ## Example response -The example that follows corresponds to the request above in the [Example request](#example-request) section. +The following response shows detailed information about the snapshot's status: -The `GET _snapshot/my-opensearch-repo/my-first-snapshot/_status` request returns the following fields: - -````json +```json { - "snapshots" : [ + "snapshots": [ { - "snapshot" : "my-first-snapshot", - "repository" : "my-opensearch-repo", - "uuid" : "dCK4Qth-TymRQ7Tu7Iga0g", - "state" : "SUCCESS", - "include_global_state" : true, - "shards_stats" : { - "initializing" : 0, - "started" : 0, - "finalizing" : 0, - "done" : 7, - "failed" : 0, - "total" : 7 + "snapshot": "my-first-snapshot", + "repository": "my-opensearch-repo", + "uuid": "dCK4Qth-TymRQ7Tu7Iga0g", + "state": "SUCCESS", + "include_global_state": true, + "shards_stats": { + "initializing": 0, + "started": 0, + "finalizing": 0, + "done": 7, + "failed": 0, + "total": 7 }, - "stats" : { - "incremental" : { - "file_count" : 31, - "size_in_bytes" : 24488927 + "stats": { + "incremental": { + "file_count": 31, + "size_in_bytes": 24488927 }, - "total" : { - "file_count" : 31, - "size_in_bytes" : 24488927 + "total": { + "file_count": 31, + "size_in_bytes": 24488927 }, - "start_time_in_millis" : 1660666841667, - "time_in_millis" : 14054 + "start_time_in_millis": 1660666841667, + "time_in_millis": 14054 }, - "indices" : { - ".opensearch-observability" : { - "shards_stats" : { - "initializing" : 0, - "started" : 0, - "finalizing" : 0, - "done" : 1, - "failed" : 0, - "total" : 1 - }, - "stats" : { - "incremental" : { - "file_count" : 1, - "size_in_bytes" : 208 - }, - "total" : { - "file_count" : 1, - "size_in_bytes" : 208 - }, - "start_time_in_millis" : 1660666841868, - "time_in_millis" : 201 - }, - "shards" : { - "0" : { - "stage" : "DONE", - "stats" : { - "incremental" : { - "file_count" : 1, - "size_in_bytes" : 208 - }, - "total" : { - "file_count" : 1, - "size_in_bytes" : 208 - }, - "start_time_in_millis" : 1660666841868, - "time_in_millis" : 201 - } - } - } - }, - "shakespeare" : { - "shards_stats" : { - "initializing" : 0, - "started" : 0, - "finalizing" : 0, - "done" : 1, - "failed" : 0, - "total" : 1 - }, - "stats" : { - "incremental" : { - "file_count" : 4, - "size_in_bytes" : 18310117 - }, - "total" : { - "file_count" : 4, - "size_in_bytes" : 18310117 - }, - "start_time_in_millis" : 1660666842470, - "time_in_millis" : 13050 - }, - "shards" : { - "0" : { - "stage" : "DONE", - "stats" : { - "incremental" : { - "file_count" : 4, - "size_in_bytes" : 18310117 - }, - "total" : { - "file_count" : 4, - "size_in_bytes" : 18310117 - }, - "start_time_in_millis" : 1660666842470, - "time_in_millis" : 13050 - } - } - } - }, - "opensearch_dashboards_sample_data_flights" : { - "shards_stats" : { - "initializing" : 0, - "started" : 0, - "finalizing" : 0, - "done" : 1, - "failed" : 0, - "total" : 1 - }, - "stats" : { - "incremental" : { - "file_count" : 10, - "size_in_bytes" : 6132245 - }, - "total" : { - "file_count" : 10, - "size_in_bytes" : 6132245 - }, - "start_time_in_millis" : 1660666843476, - "time_in_millis" : 6221 - }, - "shards" : { - "0" : { - "stage" : "DONE", - "stats" : { - "incremental" : { - "file_count" : 10, - "size_in_bytes" : 6132245 - }, - "total" : { - "file_count" : 10, - "size_in_bytes" : 6132245 - }, - "start_time_in_millis" : 1660666843476, - "time_in_millis" : 6221 - } - } - } - }, - ".opendistro-reports-definitions" : { - "shards_stats" : { - "initializing" : 0, - "started" : 0, - "finalizing" : 0, - "done" : 1, - "failed" : 0, - "total" : 1 - }, - "stats" : { - "incremental" : { - "file_count" : 1, - "size_in_bytes" : 208 - }, - "total" : { - "file_count" : 1, - "size_in_bytes" : 208 - }, - "start_time_in_millis" : 1660666843076, - "time_in_millis" : 200 - }, - "shards" : { - "0" : { - "stage" : "DONE", - "stats" : { - "incremental" : { - "file_count" : 1, - "size_in_bytes" : 208 - }, - "total" : { - "file_count" : 1, - "size_in_bytes" : 208 - }, - "start_time_in_millis" : 1660666843076, - "time_in_millis" : 200 - } - } - } - }, - ".opendistro-reports-instances" : { - "shards_stats" : { - "initializing" : 0, - "started" : 0, - "finalizing" : 0, - "done" : 1, - "failed" : 0, - "total" : 1 - }, - "stats" : { - "incremental" : { - "file_count" : 1, - "size_in_bytes" : 208 - }, - "total" : { - "file_count" : 1, - "size_in_bytes" : 208 - }, - "start_time_in_millis" : 1660666841667, - "time_in_millis" : 201 - }, - "shards" : { - "0" : { - "stage" : "DONE", - "stats" : { - "incremental" : { - "file_count" : 1, - "size_in_bytes" : 208 - }, - "total" : { - "file_count" : 1, - "size_in_bytes" : 208 - }, - "start_time_in_millis" : 1660666841667, - "time_in_millis" : 201 - } - } - } - }, - ".kibana_1" : { - "shards_stats" : { - "initializing" : 0, - "started" : 0, - "finalizing" : 0, - "done" : 1, - "failed" : 0, - "total" : 1 - }, - "stats" : { - "incremental" : { - "file_count" : 13, - "size_in_bytes" : 45733 - }, - "total" : { - "file_count" : 13, - "size_in_bytes" : 45733 - }, - "start_time_in_millis" : 1660666842673, - "time_in_millis" : 2007 - }, - "shards" : { - "0" : { - "stage" : "DONE", - "stats" : { - "incremental" : { - "file_count" : 13, - "size_in_bytes" : 45733 - }, - "total" : { - "file_count" : 13, - "size_in_bytes" : 45733 - }, - "start_time_in_millis" : 1660666842673, - "time_in_millis" : 2007 - } - } - } - }, - ".opensearch-notifications-config" : { - "shards_stats" : { - "initializing" : 0, - "started" : 0, - "finalizing" : 0, - "done" : 1, - "failed" : 0, - "total" : 1 + "indices": { + ".opensearch-observability": { + "shards_stats": { + "initializing": 0, + "started": 0, + "finalizing": 0, + "done": 1, + "failed": 0, + "total": 1 }, - "stats" : { - "incremental" : { - "file_count" : 1, - "size_in_bytes" : 208 + "stats": { + "incremental": { + "file_count": 1, + "size_in_bytes": 208 }, - "total" : { - "file_count" : 1, - "size_in_bytes" : 208 + "total": { + "file_count": 1, + "size_in_bytes": 208 }, - "start_time_in_millis" : 1660666842270, - "time_in_millis" : 200 + "start_time_in_millis": 1660666841868, + "time_in_millis": 201 }, - "shards" : { - "0" : { - "stage" : "DONE", - "stats" : { - "incremental" : { - "file_count" : 1, - "size_in_bytes" : 208 + "shards": { + "0": { + "stage": "DONE", + "stats": { + "incremental": { + "file_count": 1, + "size_in_bytes": 208 }, - "total" : { - "file_count" : 1, - "size_in_bytes" : 208 + "total": { + "file_count": 1, + "size_in_bytes": 208 }, - "start_time_in_millis" : 1660666842270, - "time_in_millis" : 200 + "start_time_in_millis": 1660666841868, + "time_in_millis": 201 } } } } + // Additional indices data omitted for brevity } } ] } -```` +``` ## Response body fields -| Field | Data type | Description | -:--- | :--- | :--- -| repository | String | Name of repository that contains the snapshot. | -| snapshot | String | Snapshot name. | -| uuid | String | A snapshot's universally unique identifier (UUID). | -| state | String | Snapshot's current status. See [Snapshot states](#snapshot-states). | -| include_global_state | Boolean | Whether the current cluster state is included in the snapshot. | -| shards_stats | Object | Snapshot's shard counts. See [Shard stats](#shard-stats). | -| stats | Object | Information about files included in the snapshot. `file_count`: number of files. `size_in_bytes`: total size of all files. See [Snapshot file stats](#snapshot-file-stats). | -| index | list of Objects | List of objects that contain information about the indices in the snapshot. See [Index objects](#index-objects).| - -### Snapshot states - -| State | Description | -:--- | :--- | -| FAILED | The snapshot terminated in an error and no data was stored. | -| IN_PROGRESS | The snapshot is currently running. | -| PARTIAL | The global cluster state was stored, but data from at least one shard was not stored. The `failures` property of the [Create snapshot]({{site.url}}{{site.baseurl}}/api-reference/snapshots/create-snapshot) response contains additional details. | -| SUCCESS | The snapshot finished and all shards were stored successfully. | - -### Shard stats - -All property values are integers. - -| Property | Description | -:--- | :--- | -| initializing | Number of shards that are still initializing. | -| started | Number of shards that have started but not are not finalized. | -| finalizing | Number of shards that are finalizing but are not done. | -| done | Number of shards that initialized, started, and finalized successfully. | -| failed | Number of shards that failed to be included in the snapshot. | -| total | Total number of shards included in the snapshot. | - -### Snapshot file stats - -| Property | Type | Description | -:--- | :--- | :--- | -| incremental | Object | Number and size of files that still need to be copied during snapshot creation. For completed snapshots, `incremental` provides the number and size of files that were not already in the repository and were copied as part of the incremental snapshot. | -| processed | Object | Number and size of files already uploaded to the snapshot. The processed `file_count` and `size_in_bytes` are incremented in stats after a file is uploaded. | -| total | Object | Total number and size of files that are referenced by the snapshot. | -| start_time_in_millis | Long | Time (in milliseconds) when snapshot creation began. | -| time_in_millis | Long | Total time (in milliseconds) that the snapshot took to complete. | - -### Index objects - -| Property | Type | Description | -:--- | :--- | :--- | -| shards_stats | Object | See [Shard stats](#shard-stats). | -| stats | Object | See [Snapshot file stats](#snapshot-file-stats). | -| shards | List of objects | Contains information about the shards included in the snapshot. OpenSearch returns the following properties about the shard:

**stage**: The current state of shards in the snapshot. Shard states are:

* DONE: The number of shards in the snapshot that were successfully stored in the repository.

* FAILURE: The number of shards in the snapshot that were not successfully stored in the repository.

* FINALIZE: The number of shards in the snapshot that are in the finalizing stage of being stored in the repository.

* INIT: The number of shards in the snapshot that are in the initializing stage of being stored in the repository.

* STARTED: The number of shards in the snapshot that are in the started stage of being stored in the repository.

**stats**: See [Snapshot file stats](#snapshot-file-stats).

**total**: The total number and sizes of files referenced by the snapshot.

**start_time_in_millis**: The time (in milliseconds) when snapshot creation began.

**time_in_millis**: The total amount of time (in milliseconds) that the snapshot took to complete. | +The response body is a JSON object with the following fields: + +| Property | Required | Data type | Description | +| :--- | :--- | :--- | :--- | +| `snapshots` | **Required** | Array of Objects | Array of snapshot status objects. | + +Each snapshot object in the `snapshots` array contains the following information: + +| Property | Data type | Description | +| :--- | :--- | :--- | +| `snapshot` | String | The name of the snapshot. | +| `repository` | String | The name of the repository containing the snapshot. | +| `uuid` | String | The universally unique identifier for the snapshot. | +| `state` | String | The current state of the snapshot. Possible values include `IN_PROGRESS`, `SUCCESS`, `FAILED`, and `PARTIAL`. | +| `include_global_state` | Boolean | Whether the snapshot includes the cluster state. | +| `shards_stats` | Object | Statistics about snapshot shards. | +| `stats` | Object | Detailed statistics about the snapshot. | +| `indices` | Object | Status of indexes included in the snapshot. | + +
+ + Shard stats fields + + {: .text-delta} + +The `shards_stats` object contains the following fields: + +| Property | Data type | Description | +| :--- | :--- | :--- | +| `initializing` | Integer | The number of shards in the initial stage of being stored in the repository. | +| `started` | Integer | The number of shards that have started but not completed storing data. | +| `finalizing` | Integer | The number of shards in the finalizing stage of being stored. | +| `done` | Integer | The number of shards successfully stored in the repository. | +| `failed` | Integer | The number of shards that failed to be stored in the repository. | +| `total` | Integer | The total number of shards in the snapshot. | + +
+ +
+ + Snapshot statistics fields + + {: .text-delta} + +The `stats` object contains the following fields: + +| Property | Data type | Description | +| :--- | :--- | :--- | +| `incremental` | Object | Statistics about incremental snapshot data, including `file_count` and `size_in_bytes`. | +| `total` | Object | Statistics about total snapshot data, including `file_count` and `size_in_bytes`. | +| `start_time_in_millis` | Integer | The time (in milliseconds) when the snapshot process began. | +| `time_in_millis` | Integer | Total time (in milliseconds) the snapshot process took. | + +
+ +
+ + Index details fields + + {: .text-delta} + +For each index in the `indices` object, the response includes: + +| Property | Data type | Description | +| :--- | :--- | :--- | +| `shards_stats` | Object | Statistics about index shards, including counts for various states. | +| `stats` | Object | Detailed statistics about the index snapshot. | +| `shards` | Object | Information about individual shards, including their stage and statistics. | + +
+ + + diff --git a/_api-reference/snapshots/get-snapshot.md b/_api-reference/snapshots/get-snapshot.md index c936cab6024..bd1824e8b65 100644 --- a/_api-reference/snapshots/get-snapshot.md +++ b/_api-reference/snapshots/get-snapshot.md @@ -5,31 +5,67 @@ parent: Snapshot APIs nav_order: 6 --- -# Get snapshot. +# Get snapshot **Introduced 1.0** {: .label .label-purple } -Retrieves information about a snapshot. +The Get Snapshot API retrieves information about one or more snapshots within a repository. This information includes details about snapshot creation, included indexes, and status. + +* For more information about snapshots, see [Snapshots]({{site.url}}{{site.baseurl}}/opensearch/snapshots/index/). +* To view a list of your repositories, see [Get Snapshot Repository]({{site.url}}{{site.baseurl}}/api-reference/snapshots/get-snapshot-repository/). -## Endpoints + +## Endpoints ```json -GET _snapshot/// +GET /_snapshot/{repository}/{snapshot} ``` + + + ## Path parameters +The following table lists the available path parameters. + +| Parameter | Required | Data type | Description | +| :--- | :--- | :--- | :--- | +| `repository` | **Required** | String | A comma-separated list of snapshot repository names used to limit the request. Wildcard (*) expressions are supported. | +| `snapshot` | **Required** | List or String | A comma-separated list of snapshot names to retrieve. Also accepts wildcard expressions. (`*`). - 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`. | + + + + +## Query parameters + +The following table lists the available query parameters. All query parameters are optional. + | Parameter | Data type | Description | | :--- | :--- | :--- | -| repository | String | The repository that contains the snapshot to retrieve. | -| snapshot | String | Snapshot to retrieve. +| `cluster_manager_timeout` | String | The amount of time to wait for a response from the cluster manager node. For more information about supported time units, see [Common parameters]({{site.url}}{{site.baseurl}}/api-reference/common-parameters/#time-units). | +| `ignore_unavailable` | Boolean | When `false`, the request returns an error for any snapshots that are unavailable. _(Default: `false`)_ | +| `verbose` | Boolean | When `true`, returns additional information about each snapshot such as the version of OpenSearch which took the snapshot, the start and end times of the snapshot, and the number of shards contained in the snapshot. | + + + + + + -## Query parameters -| Parameter | Data type | Description | -:--- | :--- | :--- -| verbose | Boolean | Whether to show all, or just basic snapshot information. If `true`, returns all information. If `false`, omits information like start/end times, failures, and shards. Optional, defaults to `true`.| -| ignore_unavailable | Boolean | How to handle snapshots that are unavailable (corrupted or otherwise temporarily can't be returned). If `true` and the snapshot is unavailable, the request does not return the snapshot. If `false` and the snapshot is unavailable, the request returns an error. Optional, defaults to `false`.| ## Example request @@ -42,59 +78,112 @@ GET _snapshot/my-opensearch-repo/my-first-snapshot ## Example response -Upon success, the response returns snapshot information: - -````json +```json { - "snapshots" : [ + "snapshots": [ { - "snapshot" : "my-first-snapshot", - "uuid" : "3P7Qa-M8RU6l16Od5n7Lxg", - "version_id" : 136217927, - "version" : "2.0.1", - "indices" : [ - ".opensearch-observability", - ".opendistro-reports-instances", - ".opensearch-notifications-config", - "shakespeare", - ".opendistro-reports-definitions", - "opensearch_dashboards_sample_data_flights", - ".kibana_1" + "snapshot": "my-snapshot", + "uuid": "XYZ4Zv7cSnuYev2JpLMJGw", + "version_id": 136217927, + "version": "2.0.1", + "indices": [ + "index-1", + "index-2", + ".opensearch-observability" ], - "data_streams" : [ ], - "include_global_state" : true, - "state" : "SUCCESS", - "start_time" : "2022-08-11T20:30:00.399Z", - "start_time_in_millis" : 1660249800399, - "end_time" : "2022-08-11T20:30:14.851Z", - "end_time_in_millis" : 1660249814851, - "duration_in_millis" : 14452, - "failures" : [ ], - "shards" : { - "total" : 7, - "failed" : 0, - "successful" : 7 + "data_streams": [], + "include_global_state": true, + "state": "SUCCESS", + "start_time": "2022-08-10T16:52:15.277Z", + "start_time_in_millis": 1660150335277, + "end_time": "2022-08-10T16:52:18.699Z", + "end_time_in_millis": 1660150338699, + "duration_in_millis": 3422, + "failures": [], + "shards": { + "total": 5, + "failed": 0, + "successful": 5 } } ] } -```` +``` + ## Response body fields -| Field | Data type | Description | -| :--- | :--- | :--- | -| snapshot | string | Snapshot name. | -| uuid | string | Snapshot's universally unique identifier (UUID). | -| version_id | int | Build ID of the Open Search version that created the snapshot. | -| version | float | Open Search version that created the snapshot. | -| indices | array | Indices in the snapshot. | -| data_streams | array | Data streams in the snapshot. | -| include_global_state | boolean | Whether the current cluster state is included in the snapshot. | -| start_time | string | Date/time when the snapshot creation process began. | -| start_time_in_millis | long | Time (in milliseconds) when the snapshot creation process began. | -| end_time | string | Date/time when the snapshot creation process ended. | -| end_time_in_millis | long | Time (in milliseconds) when the snapshot creation process ended. | -| duration_in_millis | long | Total time (in milliseconds) that the snapshot creation process lasted. | -| failures | array | Failures, if any, that occured during snapshot creation. | -| shards | object | Total number of shards created along with number of successful and failed shards. | -| state | string | Snapshot status. Possible values: `IN_PROGRESS`, `SUCCESS`, `FAILED`, `PARTIAL`. | \ No newline at end of file +The response body is a JSON object with the following fields: + +| Property | Required | Data type | Description | +| :--- | :--- | :--- | :--- | +| `snapshots` | **Required** | Array of Objects | Array of snapshot status objects. | + +Each snapshot object in the `snapshots` array contains the following information: + +| Property | Data type | Description | +| :--- | :--- | :--- | +| `snapshot` | String | The name of the snapshot. | +| `repository` | String | The name of the repository containing the snapshot. | +| `uuid` | String | The universally unique identifier for the snapshot. | +| `version_id` | Integer | The build ID of the OpenSearch version that created the snapshot. | +| `version` | String | The OpenSearch version that created the snapshot. | +| `indices` | Array of Strings | The list of indexes included in the snapshot. | +| `data_streams` | Array of Strings | The list of data streams included in the snapshot. | +| `state` | String | The current state of the snapshot. Possible values include `IN_PROGRESS`, `SUCCESS`, `FAILED`, and `PARTIAL`. | +| `include_global_state` | Boolean | Whether the snapshot includes the cluster state. | +| `start_time` | String | The date and time when the snapshot creation process began. | +| `start_time_in_millis` | Long | The time (in milliseconds) when the snapshot creation process began. | +| `end_time` | String | The date and time when the snapshot creation process ended. | +| `end_time_in_millis` | Long | The time (in milliseconds) when the snapshot creation process ended. | +| `duration_in_millis` | Long | The total time (in milliseconds) that the snapshot creation process lasted. | +| `failures` | Array of Objects | Any failures that occurred during snapshot creation. | +| `shards` | Object | Statistics about the shards included in the snapshot. | + +
+ + Shard stats fields + + {: .text-delta} + +The `shards` object contains the following fields: + +| Property | Data type | Description | +| :--- | :--- | :--- | +| `total` | Integer | The total number of shards included in the snapshot. | +| `failed` | Integer | The number of shards that failed to be stored in the repository. | +| `successful` | Integer | The number of shards successfully stored in the repository. | + +
+ +
+ + Snapshot statistics fields + + {: .text-delta} + +The `stats` object contains the following fields: + +| Property | Data type | Description | +| :--- | :--- | :--- | +| `incremental` | Object | Statistics about incremental snapshot data, including `file_count` and `size_in_bytes`. | +| `total` | Object | Statistics about total snapshot data, including `file_count` and `size_in_bytes`. | +| `start_time_in_millis` | Integer | The time (in milliseconds) when the snapshot process began. | +| `time_in_millis` | Integer | Total time (in milliseconds) the snapshot process took. | + +
+ +
+ + Index details fields + + {: .text-delta} + +For each index in the `indices` object, the response includes: + +| Property | Data type | Description | +| :--- | :--- | :--- | +| `shards_stats` | Object | Statistics about index shards, including counts for various states. | +| `stats` | Object | Detailed statistics about the index snapshot. | +| `shards` | Object | Information about individual shards, including their stage and statistics. | + +
diff --git a/_api-reference/snapshots/restore-snapshot.md b/_api-reference/snapshots/restore-snapshot.md index 6df1397cc69..07c8060f36a 100644 --- a/_api-reference/snapshots/restore-snapshot.md +++ b/_api-reference/snapshots/restore-snapshot.md @@ -12,117 +12,150 @@ nav_order: 9 Restores a snapshot of a cluster or specified data streams and indices. -* For information about indices and clusters, see [Introduction to OpenSearch]({{site.url}}{{site.baseurl}}/opensearch/index). +* For information about indexes and clusters, see [Introduction to OpenSearch]({{site.url}}{{site.baseurl}}/opensearch/index/). -* For information about data streams, see [Data streams]({{site.url}}{{site.baseurl}}/opensearch/data-streams). +* For information about data streams, see [Data streams]({{site.url}}{{site.baseurl}}/opensearch/data-streams/). -If open indexes with the same name that you want to restore already exist in the cluster, you must close, delete, or rename the indexes. See [Example request](#example-request) for information about renaming an index. See [Close index]({{site.url}}{{site.baseurl}}/api-reference/index-apis/close-index) for information about closing an index. +If open indexes with the same name that you want to restore already exist in the cluster, you must close, delete, or rename the indexes. See [Example request](#example-request) for information about renaming an index. See [Close index]({{site.url}}{{site.baseurl}}/api-reference/index-apis/close-index/) for information about closing an index. {: .note} + ## Endpoints - ```json -POST _snapshot///_restore +POST /_snapshot/{repository}/{snapshot}/_restore ``` + + + ## Path parameters -| Parameter | Data type | Description | -:--- | :--- | :--- -| repository | String | Repository containing the snapshot to restore. | -| snapshot | String | Snapshot to restore. | +The following table lists the available path parameters. -## Query parameters +| Parameter | Required | Data type | Description | +| :--- | :--- | :--- | :--- | +| `repository` | **Required** | String | The name of the repository containing the snapshot | +| `snapshot` | **Required** | String | The name of the snapshot to restore. | -Parameter | Data type | Description -:--- | :--- | :--- -wait_for_completion | Boolean | Whether to wait for snapshot restoration to complete before continuing. | + -## Request body fields + +## Query parameters -All request body parameters are optional. +The following table lists the available query parameters. All query parameters are optional. | Parameter | Data type | Description | -:--- | :--- | :--- -| ignore_unavailable | Boolean | How to handle data streams or indices that are missing or closed. If `false`, the request returns an error for any data stream or index that is missing or closed. If `true`, the request ignores data streams and indices in indices that are missing or closed. Defaults to `false`. | -| ignore_index_settings | Boolean | A comma-delimited list of index settings that you don't want to restore from a snapshot. | -| include_aliases | Boolean | How to handle index aliases from the original snapshot. If `true`, index aliases from the original snapshot are restored. If `false`, aliases along with associated indices are not restored. Defaults to `true`. | -| include_global_state | Boolean | Whether to restore the current cluster state1. If `false`, the cluster state is not restored. If true, the current cluster state is restored. Defaults to `false`.| -| index_settings | String | A comma-delimited list of settings to add or change in all restored indices. Use this parameter to override index settings during snapshot restoration. For data streams, these index settings are applied to the restored backing indices. | -| indices | String | A comma-delimited list of data streams and indices to restore from the snapshot. Multi-index syntax is supported. By default, a restore operation includes all data streams and indices in the snapshot. If this argument is provided, the restore operation only includes the data streams and indices that you specify. | -| partial | Boolean | How the restore operation will behave if indices in the snapshot do not have all primary shards available. If `false`, the entire restore operation fails if any indices in the snapshot do not have all primary shards available.

If `true`, allows the restoration of a partial snapshot of indices with unavailable shards. Only shards that were successfully included in the snapshot are restored. All missing shards are recreated as empty. By default, the entire restore operation fails if one or more indices included in the snapshot do not have all primary shards available. To change this behavior, set `partial` to `true`. Defaults to `false`. | -| rename_pattern | String | The pattern to apply to the restored data streams and indexes. Data streams and indexes matching the rename pattern will be renamed according to the `rename_replacement` setting.

The rename pattern is applied as defined by the regular expression that supports referencing the original text.

The request fails if two or more data streams or indexes are renamed to the same name. If you rename a restored data stream, its backing indexes are also renamed. For example, if you rename the logs data stream to `recovered-logs`, the backing index `.ds-logs-1` is renamed to `.ds-recovered-logs-1`.

If you rename a restored stream, ensure an index template matches the new stream name. If there are no matching index template names, the stream cannot roll over, and new backing indexes are not created.| -| rename_replacement | String | The rename replacement string.| -| rename_alias_pattern | String | The pattern to apply to the restored aliases. Aliases matching the rename pattern will be renamed according to the `rename_alias_replacement` setting.

The rename pattern is applied as defined by the regular expression that supports referencing the original text.

If two or more aliases are renamed to the same name, these aliases will be merged into one.| -| rename_alias_replacement | String | The rename replacement string for aliases.| -| source_remote_store_repository | String | The name of the remote store repository of the source index being restored. If not provided, the Snapshot Restore API will use the repository that was registered when the snapshot was created. -| wait_for_completion | Boolean | Whether to return a response after the restore operation has completed. If `false`, the request returns a response when the restore operation initializes. If `true`, the request returns a response when the restore operation completes. Defaults to `false`. | - -1The cluster state includes: -* Persistent cluster settings -* Index templates -* Legacy index templates -* Ingest pipelines -* Index lifecycle policies +| :--- | :--- | :--- | +| `cluster_manager_timeout` | String | The amount of time to wait for a response from the cluster manager node. For more information about supported time units, see [Common parameters]({{site.url}}{{site.baseurl}}/api-reference/common-parameters/#time-units). | +| `wait_for_completion` | Boolean | -\| Whether to return a response after the restore operation has completed. When `false`, the request returns a response when the restore operation initializes. When `true`, the request returns a response when the restore operation completes. _(Default: `false`)_ | +| `master_timeout`
_DEPRECATED_ | String | _(Deprecated since 2.0: To promote inclusive language, use `cluster_manager_timeout` instead.)_ Explicit operation timeout for connection to cluster-manager node | + + + +## Request body fields + +The request body is optional. It is a JSON object with the following fields. + +| Property | Data type | Description | Default | +| :--- | :--- | :--- | :--- | +| `indices` | String or Array of Strings | A comma-separated list of data streams, indexes, and aliases to restore from the snapshot. Supports wildcards (`*`). To restore all data streams and indexes, omit this parameter or use `*` or `_all`. | `_all` | +| `ignore_unavailable` | Boolean | When `true`, the request ignores any data streams and indexes that are missing or closed. When `false`, the request returns an error for any missing or closed data streams or indexes. | `false` | +| `include_global_state` | Boolean | When `true`, restores the cluster state from the snapshot. The cluster state includes persistent cluster settings, composable index templates, legacy index templates, ingest pipelines, and ILM policies. | `false` | +| `include_aliases` | Boolean | When `true`, restores index aliases from the original snapshot. When `false`, aliases along with associated indexes are not restored. | `true` | +| `partial` | Boolean | When `true`, allows the restoration of a partial snapshot from indexes with unavailable shards. Only shards that were successfully included in the snapshot will be restored. All missing shards will be recreated as empty. When `false`, the entire restore operation fails if any indexes in the snapshot do not have all primary shards available. | `false` | +| `index_settings` | Object | Index settings to add or change in all restored indexes. Use this parameter to override index settings during snapshot restoration. For data streams, these settings are applied to the restored backing indexes. | N/A | +| `ignore_index_settings` | Array of Strings | A comma-separated list of index settings that you don't want to restore from a snapshot. | N/A | +| `rename_pattern` | String | A pattern to apply to the restored data streams and indexes. Data streams and indexes matching the rename pattern will be renamed according to the `rename_replacement` setting. Uses regular expression syntax that supports referencing the original text. | N/A | +| `rename_replacement` | String | The replacement string used with `rename_pattern` to rename restored data streams and indexes. | N/A | +| `rename_alias_pattern` | String | A pattern to apply to the restored aliases. Aliases matching the pattern will be renamed according to the `rename_alias_replacement` setting. Uses regular expression syntax that supports referencing the original text. | N/A | +| `rename_alias_replacement` | String | The replacement string used with `rename_alias_pattern` to rename restored aliases. | N/A | +| `source_remote_store_repository` | String | The name of the remote store repository of the source index being restored. If not provided, the Snapshot Restore API will use the repository that was registered when the snapshot was created. | N/A | +| `storage_type` | String | Where the authoritative store of the restored indexes' data will be. A value of `local` indicates that all snapshot metadata and index data will be downloaded to local storage. A value of `remote_snapshot` indicates that snapshot metadata will be downloaded to the cluster, but the remote repository will remain the authoritative store of the index data, which will be downloaded and cached as needed. | `local` | ## Example request -The following request restores the `opendistro-reports-definitions` index from `my-first-snapshot`. The `rename_pattern` and `rename_replacement` combination causes the index to be renamed to `opendistro-reports-definitions_restored` because duplicate open index names in a cluster are not allowed. +The following request restores the `opendistro-reports-definitions` index from `my-first-snapshot`, renaming it to `opendistro-reports-definitions_restored` (because duplicate open index names in a cluster are not allowed): -````json +```json POST /_snapshot/my-opensearch-repo/my-first-snapshot/_restore { "indices": "opendistro-reports-definitions", "ignore_unavailable": true, - "include_global_state": false, + "include_global_state": false, "rename_pattern": "(.+)", "rename_replacement": "$1_restored", "include_aliases": false } -```` +``` +{% include copy-curl.html %} ## Example response Upon success, the response returns the following JSON object: -````json +```json { - "snapshot" : { - "snapshot" : "my-first-snapshot", - "indices" : [ ], - "shards" : { - "total" : 0, - "failed" : 0, - "successful" : 0 + "snapshot": { + "snapshot": "my-first-snapshot", + "indices": [], + "shards": { + "total": 0, + "failed": 0, + "successful": 0 } } } -```` -Except for the snapshot name, all properties are empty or `0`. This is because any changes made to the volume after the snapshot was generated are lost. However, if you invoke the [Get snapshot]({{site.url}}{{site.baseurl}}/api-reference/snapshots/get-snapshot) API to examine the snapshot, a fully populated snapshot object is returned. +``` + +If open indices in a snapshot already exist in a cluster, and you don't delete, close, or rename them, the API returns an error. +{: .note} ## Response body fields -| Field | Data type | Description | -| :--- | :--- | :--- | -| snapshot | string | Snapshot name. | -| indices | array | Indices in the snapshot. | -| shards | object | Total number of shards created along with number of successful and failed shards. | +The response body is a JSON object with the following fields. -If open indices in a snapshot already exist in a cluster, and you don't delete, close, or rename them, the API returns an error like the following: -{: .note} +| Property | Data type | Description | +| :--- | :--- | :--- | +| `accepted` | Boolean | Returns `true` if the restore was accepted. Present when the request had `wait_for_completion` set to `false`. | +| `snapshot` | Object | Information about the restored snapshot. | -````json -{ - "error" : { - "root_cause" : [ - { - "type" : "snapshot_restore_exception", - "reason" : "[my-opensearch-repo:my-first-snapshot/dCK4Qth-TymRQ7Tu7Iga0g] cannot restore index [.opendistro-reports-definitions] because an open index with same name already exists in the cluster. Either close or delete the existing index or restore the index under a different name by providing a rename pattern and replacement name" - } - ], - "type" : "snapshot_restore_exception", - "reason" : "[my-opensearch-repo:my-first-snapshot/dCK4Qth-TymRQ7Tu7Iga0g] cannot restore index [.opendistro-reports-definitions] because an open index with same name already exists in the cluster. Either close or delete the existing index or restore the index under a different name by providing a rename pattern and replacement name" - }, - "status" : 500 -} -```` +
+ + Response body fields: snapshot + + {: .text-delta} + +`snapshot` is a JSON object with the following fields. + +| Property | Data type | Description | +| :--- | :--- | :--- | +| `snapshot` | String | The name of the snapshot that was restored. | +| `indices` | Array of Strings | The list of indexes that were restored. | +| `shards` | Object | Statistics about the restored shards. | + +
+ +
+ + Response body fields: snapshot > shards + + {: .text-delta} + +`shards` is a JSON object with the following fields. + +| Property | Data type | Description | +| :--- | :--- | :--- | +| `total` | Integer | The total number of shards that were restored. | +| `successful` | Integer | The number of shards that were successfully restored. | +| `failed` | Integer | The number of shards that failed to be restored. | + +
\ No newline at end of file diff --git a/_api-reference/snapshots/verify-snapshot-repository.md b/_api-reference/snapshots/verify-snapshot-repository.md index 8827fee0c3f..ddd8f0df0b9 100644 --- a/_api-reference/snapshots/verify-snapshot-repository.md +++ b/_api-reference/snapshots/verify-snapshot-repository.md @@ -2,82 +2,116 @@ layout: default title: Verify Snaphot Repository parent: Snapshot APIs - nav_order: 4 --- -# Verify snapshot repository -**Introduced 1.0** -{: .label .label-purple } - -Verifies that a snapshot repository is functional. Verifies the repository on each node in a cluster. +The Verify Snapshot Repository API confirms that a snapshot repository is functional across all nodes in a cluster. This verification helps ensure that the repository is properly configured and accessible before you attempt to create or restore snapshots. -If verification is successful, the verify snapshot repository API returns a list of nodes connected to the snapshot repository. If verification failed, the API returns an error. +If verification is successful, the API returns a list of nodes connected to the snapshot repository. If verification fails, the API returns an error. If you use the Security plugin, you must have the `manage cluster` privilege. {: .note} + ## Endpoints - ```json -GET _snapshot// +POST /_snapshot/{repository}/_verify ``` + + + ## Path parameters -Path parameters are optional. +The following table lists the available path parameters. + +| Parameter | Required | Data type | Description | +| :--- | :--- | :--- | :--- | +| `repository` | **Required** | String | The name of the repository containing the snapshot. | -| Parameter | Data type | Description | -:--- | :--- | :--- -| repository | String | Name of repository to verify. | + + ## Query parameters -| Parameter | Data type | Description | -:--- | :--- | :--- -| cluster_manager_timeout | Time | Amount of time to wait for a connection to the cluster manager node. Optional, defaults to `30s`. | -| timeout | Time | The period of time to wait for a response. If a response is not received before the timeout value, the request fails and returns an error. Defaults to `30s`. | +The following table lists the available query parameters. All query parameters are optional. + +| Parameter | Data type | Description | +| :--- | :--- | :--- | +| `cluster_manager_timeout` | String | The amount of time to wait for a response from the cluster manager node. For more information about supported time units, see [Common parameters]({{site.url}}{{site.baseurl}}/api-reference/common-parameters/#time-units). | +| `timeout` | String | The amount of time to wait for a response. | + + ## Example request -The following request verifies that the my-opensearch-repo is functional: +The following request verifies that the `my-opensearch-repo` repository is functional with custom timeout settings: -````json +```json POST /_snapshot/my-opensearch-repo/_verify?timeout=0s&cluster_manager_timeout=50s -```` +``` +{% include copy-curl.html %} ## Example response -The example that follows corresponds to the request above in the [Example request](#example-request) section. +The response includes a list of all nodes that can access the repository: -The `POST /_snapshot/my-opensearch-repo/_verify?timeout=0s&cluster_manager_timeout=50s` request returns the following fields: - -````json +```json { - "nodes" : { - "by1kztwTRoeCyg4iGU5Y8A" : { - "name" : "opensearch-node1" + "nodes": { + "by1kztwTRoeCyg4iGU5Y8A": { + "name": "opensearch-node1" } } } -```` +``` -In the preceding sample, one node is connected to the snapshot repository. If more were connected, you would see them in the response. Example: +In this example, one node is connected to the snapshot repository. If multiple nodes can access the repository, they would all be listed in the response, as shown in this example: -````json +```json { - "nodes" : { - "lcfL6jv2jo6sMEtp4idMvg" : { - "name" : "node-1" + "nodes": { + "lcfL6jv2jo6sMEtp4idMvg": { + "name": "node-1" }, - "rEPtFT/B+cuuOHnQn0jy4s" : { - "name" : "node-2" + "rEPtFT/B+cuuOHnQn0jy4s": { + "name": "node-2" + } } } -```` +``` ## Response body fields -| Field | Data type | Description | -:--- | :--- | :--- -| nodes | Object | A list (not an array) of nodes connected to the snapshot repository. Each node itself is a property where the node ID is the key and the name has an ID (Object) and a name (String). | \ No newline at end of file +The response body is a JSON object with the following fields. + +| Property | Required | Data type | Description | +| :--- | :--- | :--- | :--- | +| `nodes` | **Required** | Object | A map of node IDs to node information for each node that can access the repository. | + +
+ + Response body fields: nodes + + {: .text-delta} + +For each node that can access the repository, the `nodes` object contains a key-value pair where: +- The key is the node ID (a string) +- The value is an object containing node information + +| Property | Data type | Description | +| :--- | :--- | :--- | +| `name` | String | The name of the node. | + +
+