Restore a snapshot

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

Restore a snapshot of a cluster or data streams and indices.

You can restore a snapshot only to a running cluster with an elected master node. The snapshot repository must be registered and available to the cluster. The snapshot and cluster versions must be compatible.

To restore a snapshot, the cluster's global metadata must be writable. Ensure there are't any cluster blocks that prevent writes. The restore operation ignores index blocks.

Before you restore a data stream, ensure the cluster contains a matching index template with data streams enabled. To check, use the index management feature in Kibana or the get index template API:

		GET _index_template/*?filter_path=index_templates.name,index_templates.index_template.index_patterns,index_templates.index_template.data_stream
		
	

If no such template exists, you can create one or restore a cluster state that contains one. Without a matching index template, a data stream can't roll over or create backing indices.

If your snapshot contains data from App Search or Workplace Search, you must restore the Enterprise Search encryption key before you restore the snapshot.

Required authorization

Cluster privileges: manage

Read the reference documentation

Path Parameters

Query Parameters

Request

feature_states [] string

The feature states to restore. If include_global_state is true, the request restores all feature states in the snapshot by default. If include_global_state is false, the request restores no feature states by default. Note that specifying an empty array will result in the default behavior. To restore no feature states, regardless of the include_global_state value, specify an array containing only the value none (["none"]).

Reference

ignore_index_settings [] string

The index settings to not restore from the snapshot. You can't use this option to ignore index.number_of_shards.

For data streams, this option applies only to restored backing indices. New backing indices are configured using the data stream's matching index template.

ignore_unavailable boolean · default: false

If true, the request ignores any index or data stream in indices that's missing from the snapshot. If false, the request returns an error for any missing index or data stream.

include_aliases boolean · default: true

If true, the request restores aliases for any restored data streams and indices. If false, the request doesn’t restore aliases.

include_global_state boolean · default: false

If true, restore the cluster state. The cluster state includes:

Persistent cluster settings
Index templates
Legacy index templates
Ingest pipelines
Index lifecycle management (ILM) policies
Stored scripts
For snapshots taken after 7.12.0, feature states

If include_global_state is true, the restore operation merges the legacy index templates in your cluster with the templates contained in the snapshot, replacing any existing ones whose name matches one in the snapshot. It completely removes all persistent settings, non-legacy index templates, ingest pipelines, and ILM lifecycle policies that exist in your cluster and replaces them with the corresponding items from the snapshot.

Use the feature_states parameter to configure how feature states are restored.

If include_global_state is true and a snapshot was created without a global state then the restore request will fail.

index_settings IndexSettings

Index settings to add or change in restored indices, including backing indices. You can't use this option to change index.number_of_shards.

For data streams, this option applies only to restored backing indices. New backing indices are configured using the data stream's matching index template.

indices string Indices

A comma-separated list of indices and data streams to restore. It supports a multi-target syntax. The default behavior is all regular indices and regular data streams in the snapshot.

You can't use this parameter to restore system indices or system data streams. Use feature_states instead.

partial boolean · default: false

If false, the entire restore operation will fail if one or more indices included in the snapshot do not have all primary shards available.

If true, it allows restoring a partial snapshot of indices with unavailable shards. Only shards that were successfully included in the snapshot will be restored. All missing shards will be recreated as empty.

rename_pattern string

A rename pattern to apply to restored data streams and indices. Data streams and indices matching the rename pattern will be renamed according to rename_replacement.

The rename pattern is applied as defined by the regular expression that supports referencing the original text, according to the appendReplacement logic.

External docs

rename_replacement string

The rename replacement string that is used with the rename_pattern.

Response

application/json

Examples

Run POST /_snapshot/my_repository/snapshot_2/_restore?wait_for_completion=true. It restores index_1 and index_2 from snapshot_2. The rename_pattern and rename_replacement parameters indicate any index matching the regular expression index_(.+) will be renamed using the pattern restored_index_$1. For example, index_1 will be renamed to restored_index_1.

Request Console 1 / 8 languages

Console Kibana Dev Tools

POST /_snapshot/my_repository/snapshot_2/_restore?wait_for_completion=true
{
  "indices": "index_1,index_2",
  "ignore_unavailable": true,
  "include_global_state": false,
  "rename_pattern": "index_(.+)",
  "rename_replacement": "restored_index_$1",
  "include_aliases": false
}

JavaScript Elasticsearch JavaScript Client

const response = await client.snapshot.restore({
  repository: "my_repository",
  snapshot: "snapshot_2",
  wait_for_completion: "true",
  indices: "index_1,index_2",
  ignore_unavailable: true,
  include_global_state: false,
  rename_pattern: "index_(.+)",
  rename_replacement: "restored_index_$1",
  include_aliases: false,
});

Python Elasticsearch Python Client

resp = client.snapshot.restore(
    repository="my_repository",
    snapshot="snapshot_2",
    wait_for_completion=True,
    indices="index_1,index_2",
    ignore_unavailable=True,
    include_global_state=False,
    rename_pattern="index_(.+)",
    rename_replacement="restored_index_$1",
    include_aliases=False,
)

curl Shell

curl -X POST "$ELASTICSEARCH_URL/_snapshot/my_repository/snapshot_2/_restore?wait_for_completion=true" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "indices": "index_1,index_2",
    "ignore_unavailable": true,
    "include_global_state": false,
    "rename_pattern": "index_(.\u002B)",
    "rename_replacement": "restored_index_$1",
    "include_aliases": false
  }'

Java Elasticsearch Java Client

client.snapshot().restore(r -> r
    .ignoreUnavailable(true)
    .includeAliases(false)
    .includeGlobalState(false)
    .indices("index_1,index_2")
    .renamePattern("index_(.+)")
    .renameReplacement("restored_index_$1")
    .repository("my_repository")
    .snapshot("snapshot_2")
    .waitForCompletion(true)
);

C# Elasticsearch .NET Client

var response = await client.Snapshot
    .RestoreAsync(repository: "my_repository", snapshot: "snapshot_2", d1 => d1
        .WaitForCompletion(true)
        .IgnoreUnavailable(true)
        .IncludeAliases(false)
        .IncludeGlobalState(false)
        .Indices(new[] { "index_1,index_2" })
        .RenamePattern("index_(.+)")
        .RenameReplacement("restored_index_$1")
    );

PHP Elasticsearch PHP Client

$resp = $client->snapshot()->restore([
    "repository" => "my_repository",
    "snapshot" => "snapshot_2",
    "wait_for_completion" => "true",
    "body" => [
        "indices" => "index_1,index_2",
        "ignore_unavailable" => true,
        "include_global_state" => false,
        "rename_pattern" => "index_(.+)",
        "rename_replacement" => "restored_index_$1",
        "include_aliases" => false,
    ],
]);

Ruby Elasticsearch Ruby Client

response = client.snapshot.restore(
  repository: "my_repository",
  snapshot: "snapshot_2",
  wait_for_completion: "true",
  body: {
    "indices": "index_1,index_2",
    "ignore_unavailable": true,
    "include_global_state": false,
    "rename_pattern": "index_(.+)",
    "rename_replacement": "restored_index_$1",
    "include_aliases": false
  }
)

Response

No example

Close index_1 then run POST /_snapshot/my_repository/snapshot_2/_restore?wait_for_completion=true to restore an index in-place. For example, you might want to perform this type of restore operation when no alternative options surface after the cluster allocation explain API reports no_valid_shard_copy.

Request Console 1 / 2 languages

Console Kibana Dev Tools

POST /_snapshot/{repository}/{snapshot}/_restore
{
  "indices": "index_1"
}

curl Shell

curl -X POST "$ELASTICSEARCH_URL/_snapshot/{repository}/{snapshot}/_restore" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "indices": "index_1"
}'

Response

No example

Required authorization

Path Parameters { repository , snapshot , }

Query Parameters { master_timeout , wait_for_completion , }

Request { feature_states , ignore_index_settings , ignore_unavailable , include_aliases , include_global_state , index_settings , indices , partial , rename_pattern , rename_replacement , }

Response

Path Parameters

Query Parameters

Request