Restore Snapshot API

Introduced 1.0

Restores a snapshot of a cluster or specified data streams and indexes.

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. You can restore over a closed index only if it has the same number of shards as the index in the snapshot; the restore operation reopens the index. For information about renaming an index, see Example requests. For information about closing an index, see Close index. To restore a snapshot to a different cluster, see Restoring to a different cluster. For more information about avoiding conflicts, see Conflicts and compatibility.

Endpoints

POST _snapshot/{repository}/{snapshot}/_restore

Path parameters

The following table lists the available path parameters.

Query parameters

The following table lists the available query parameters. All query parameters are optional.

Request body fields

The following table lists the available request body fields. All request body fields are optional.

¹The cluster state includes the following items. When you restore the cluster state, these items replace existing items with the same names in the cluster:

• Persistent cluster settings
• Index templates
• Legacy index templates
• Ingest pipelines

Index State Management (ISM) policies are stored in an index, not in the cluster state, so they are not restored with the cluster state.

Example requests

The following examples demonstrate different snapshot restore scenarios.

Basic restore

The following request restores the restore-test index from my-first-snapshot. The rename_pattern and rename_replacement combination causes the index to be renamed to restore-test_restored because duplicate open index names in a cluster are not allowed.

POST /_snapshot/my-opensearch-repo/my-first-snapshot/_restore
{
  "indices": "restore-test",
  "ignore_unavailable": true,
  "include_global_state": false,
  "rename_pattern": "(.+)",
  "rename_replacement": "$1_restored",
  "include_aliases": false
}

response = client.snapshot.restore(
  repository = "my-opensearch-repo",
  snapshot = "my-first-snapshot",
  body =   {
    "indices": "restore-test",
    "ignore_unavailable": true,
    "include_global_state": false,
    "rename_pattern": "(.+)",
    "rename_replacement": "$1_restored",
    "include_aliases": false
  }
)

Change index settings during restore

The following request restores the restore-test index under the name restore-test-settings, sets the number of replicas to 0, and resets the index.refresh_interval setting to its default value. Reducing the number of replicas is useful when you restore a snapshot to a smaller cluster:

POST /_snapshot/my-opensearch-repo/my-first-snapshot/_restore?wait_for_completion=true
{
  "indices": "restore-test",
  "rename_pattern": "(.+)",
  "rename_replacement": "$1-settings",
  "index_settings": {
    "index.number_of_replicas": 0
  },
  "ignore_index_settings": [
    "index.refresh_interval"
  ]
}

Cross-cluster restore with remote-backed storage

Remote-backed storage is a feature where OpenSearch automatically backs up segments and translogs to remote repositories. When restoring snapshots between clusters that both use remote-backed storage with different remote store repositories, use both the source_remote_store_repository and source_remote_translog_repository parameters.

The following example restores an index from a snapshot taken on a source cluster to a target cluster. In this example, source-cluster-snapshots is the snapshot repository containing the snapshot from the source cluster, snapshot-1 is the snapshot name, my-remote-index is the index to restore, source-remote-segment-repo is the remote segment repository from the source cluster (must be registered as read-only on the target cluster), and source-remote-translog-repo is the remote translog repository from the source cluster (must be registered as read-only on the target cluster):

POST /_snapshot/source-cluster-snapshots/snapshot-1/_restore
{
  "indices": "my-remote-index",
  "source_remote_store_repository": "source-remote-segment-repo",
  "source_remote_translog_repository": "source-remote-translog-repo"
}

response = client.snapshot.restore(
  repository = "source-cluster-snapshots",
  snapshot = "snapshot-1",
  body =   {
    "indices": "my-remote-index",
    "source_remote_store_repository": "source-remote-segment-repo",
    "source_remote_translog_repository": "source-remote-translog-repo"
  }
)

The target cluster will restore the index and configure it to read remote segments and translogs from the source cluster’s remote store repositories.

For the complete step-by-step procedure, see Restoring snapshots across remote-backed clusters.

Attach a restored backing index to a data stream

Introduced 3.8

This is an experimental feature and is not recommended for use in a production environment. For updates on the progress of the feature or if you want to leave feedback, see the associated GitHub issue.

To attach a restored backing index to a pre-existing data stream with the same name, set attach_to_data_stream to true. The restored index name must match the .ds-<data_stream>-NNNNNN backing index convention, and the index must map the stream’s timestamp field as a date. The following request restores the .ds-logs-foo-000001 backing index and attaches it to the existing logs-foo data stream, advancing the stream generation as needed:

POST /_snapshot/my-opensearch-repo/my-first-snapshot/_restore
{
  "indices": ".ds-logs-foo-000001",
  "attach_to_data_stream": true
}

To add or remove backing indexes of a data stream without restoring an index from a snapshot, use the Modify Data Stream API.

Example response

By default, the request returns the following response when the restore operation starts:

{
  "accepted": true
}

If you set wait_for_completion to true, the request returns a response after the restore operation completes. The following response is returned for the Change index settings during restore example:

{
  "snapshot": {
    "snapshot": "my-first-snapshot",
    "indices": [
      "restore-test-settings"
    ],
    "shards": {
      "total": 1,
      "failed": 0,
      "successful": 1
    }
  }
}

To view the full snapshot details, such as all of the indexes it contains, use the Get Snapshot API.

To monitor the progress of a restore operation, use the CAT Recovery API. Shards being restored from a snapshot have the recovery type snapshot:

GET _cat/recovery/restore-test-settings?v&h=index,shard,type,stage,snapshot,repository,files_percent,bytes_percent

The response shows the snapshot and repository from which each shard is restored and the percentage of files and bytes restored so far:

index                 shard type     stage snapshot          repository         files_percent bytes_percent
restore-test-settings 0     snapshot done  my-first-snapshot my-opensearch-repo 100.0%        100.0%

Response body fields

The following table lists all response body fields.

If open indexes in a snapshot already exist in a cluster, and you don’t delete, close, or rename them, the API returns an error similar to the following:

{
  "error" : {
    "root_cause" : [
      {
        "type" : "snapshot_restore_exception",
        "reason" : "[my-opensearch-repo:my-first-snapshot/DdQp-ksUQ66Vd4H9S2fyKw] cannot restore index [restore-test] 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/DdQp-ksUQ66Vd4H9S2fyKw] cannot restore index [restore-test] 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
}

Required permissions

If you use the Security plugin, make sure you have the appropriate permissions: cluster:admin/snapshot/restore.