Restore Snapshot
Introduced 1.0
Restores a snapshot of a cluster or specified data streams and indices.
-
For information about indices and clusters, see Introduction to OpenSearch.
-
For information about data streams, see 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 for information about renaming an index. See Close index for information about closing an index.
Path parameters
| Parameter | Data type | Description |
|---|---|---|
| repository | String | Repository containing the snapshot to restore. |
| snapshot | String | Snapshot to restore. |
Query parameters
| Parameter | Data type | Description |
|---|---|---|
| wait_for_completion | Boolean | Whether to wait for snapshot restoration to complete before continuing. |
Request fields
All request body 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 restored data streams and indices. Data streams and indices matching the rename pattern will be renamed according to rename_replacement. The rename pattern is applied as defined by the regular expression that supports referencing the original text. The request fails if two or more data streams or indices are renamed into the same name. If you rename a restored data stream, its backing indices 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 indices are not created. |
| rename_replacement | String | The rename replacement string. See rename_pattern for more information. |
| 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
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.
POST /_snapshot/my-opensearch-repo/my-first-snapshot/_restore
{
"indices": "opendistro-reports-definitions",
"ignore_unavailable": true,
"include_global_state": false,
"rename_pattern": "(.+)",
"rename_replacement": "$1_restored",
"include_aliases": false
}
Example response
Upon success, the response returns the following JSON object:
{
"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 API to examine the snapshot, a fully populated snapshot object is returned.
Response 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. |
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:
{
"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
}