elasticsearch/docs/reference/snapshot-restore/apis/restore-snapshot-api.asciidoc

[[restore-snapshot-api]]
=== Restore snapshot API
++++
<titleabbrev>Restore snapshot</titleabbrev>
++++

.New API reference
[sidebar]
--
For the most up-to-date API details, refer to {api-es}/group/endpoint-snapshot[Snapshot and restore APIs].
--

Restores a <<snapshot-restore,snapshot>> of a cluster or specified data streams and indices.

////
[source,console]
----
PUT /_snapshot/my_repository
{
  "type": "fs",
  "settings": {
    "location": "my_backup_location"
  }
}

PUT /_snapshot/my_repository/my_snapshot?wait_for_completion=true

PUT /index_1

PUT /index_2

PUT /index_3

PUT /index_4

PUT _snapshot/my_repository/snapshot_2?wait_for_completion=true
{
  "indices": "index_1,index_2",
  "ignore_unavailable": true,
  "include_global_state": false,
  "metadata": {
    "taken_by": "Elastic Machine",
    "taken_because": "backup testing"
  }
}

POST /index_1/_close

POST /index_2/_close

POST /index_3/_close

POST /index_4/_close

----
// TESTSETUP
////

[source,console]
----
POST /_snapshot/my_repository/my_snapshot/_restore
----
// TEST[s/_restore/_restore?wait_for_completion=true/]

[[restore-snapshot-api-request]]
==== {api-request-title}

`POST /_snapshot/<repository>/<snapshot>/_restore`

[[restore-snapshot-api-prereqs]]
==== {api-prereq-title}

* If you use {es} security features, you must have the `manage` or
`cluster:admin/snapshot/*` cluster privilege to use this API.

// tag::restore-prereqs[]
* You can only restore a snapshot to a running cluster with an elected
<<master-node,master node>>. The snapshot's repository must be
<<snapshots-register-repository,registered>> and available to the cluster.

* The snapshot and cluster versions must be compatible. See
<<snapshot-restore-version-compatibility>>.

* To restore a snapshot, the cluster's global metadata must be writable. Ensure
there aren't any <<cluster-read-only,cluster blocks>> that prevent writes. The
restore operation ignores <<index-modules-blocks,index blocks>>.

* Before you restore a data stream, ensure the cluster contains a
<<create-index-template,matching index template>> with data stream enabled. To
check, use {kib}'s <<manage-index-templates,**Index Management**>> feature or
the <<indices-get-template,get index template API>>:
+
[source,console]
----
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-index-template,create one>> or
<<restore-entire-cluster,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, ensure
you've restored the {enterprise-search-ref}/encryption-keys.html[Enterprise
Search encryption key] before restoring the snapshot.
// end::restore-prereqs[]

[[restore-snapshot-api-path-params]]
==== {api-path-parms-title}

`<repository>`::
(Required, string)
Name of the repository to restore a snapshot from.

`<snapshot>`::
(Required, string)
Name of the snapshot to restore.

[[restore-snapshot-api-query-params]]
==== {api-query-parms-title}

include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=master-timeout]

`wait_for_completion`::
(Optional, Boolean) If `true`, the request returns a response when the restore
operation completes. The operation is complete when it finishes all attempts to
<<monitor-restore,recover primary shards>> for restored indices.
This applies even if one or more of the recovery attempts fail.
+
If `false`, the request returns a response when the restore
operation initializes. Defaults to `false`.

[role="child_attributes"]
[[restore-snapshot-api-request-body]]
==== {api-request-body-title}

`ignore_unavailable`::
(Optional, Boolean) 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. Defaults to `false`.

`ignore_index_settings`::
(Optional, string or array of strings) Index settings to not restore from the snapshot. You can't use this option to ignore <<index-number-of-shards,`index.number_of_shards`>>.
+
For data streams, this option only applies to restored backing indices. New
backing indices are configured using the data stream's matching index template.

`include_aliases`::
(Optional, Boolean)
If `true`, the request restores aliases for any restored data streams and
indices. If `false`, the request doesn't restore aliases. Defaults to `true`.

[[restore-snapshot-api-include-global-state]]
`include_global_state`::
+
--
(Optional, Boolean)
If `true`, restore the cluster state. Defaults to `false`.

The cluster state includes:

// tag::cluster-state-contents[]
* <<cluster-setting-types,Persistent cluster settings>>
* <<index-templates,Index templates>>
* <<indices-templates-v1,Legacy index templates>>
* <<ingest,Ingest pipelines>>
* <<index-lifecycle-management,{ilm-init} policies>>
* <<script-stored-scripts,Stored scripts>>
* For snapshots taken after 7.12.0, <<feature-state,feature states>>
// end::cluster-state-contents[]

If `include_global_state` is `true` then 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-init} 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.
--

[[restore-snapshot-api-feature-states]]
`feature_states`::
(Optional, array of strings)
<<feature-state,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"]`).

[[restore-snapshot-api-index-settings]]
`index_settings`::
(Optional, object) Index settings to add or change in restored indices,
including backing indices. You can't use this option to change
<<index-number-of-shards,`index.number_of_shards`>>.
+
For data streams, this option only applies to restored backing indices. New
backing indices are configured using the data stream's matching index template.

`indices`::
(Optional, string or array of strings) Comma-separated list of indices and data
streams to restore. Supports <<api-multi-index,multi-target syntax>>. Defaults
to all regular indices and regular data streams in the snapshot.
+
You can't use this parameter to restore <<system-indices,system indices or
system data streams>>. Use
<<restore-snapshot-api-feature-states,`feature_states`>> instead.

[[restore-snapshot-api-partial]]
`partial`::
(Optional, Boolean)
If `false`, the entire restore operation will fail if one or more indices included in the snapshot do not have all primary shards available. Defaults to `false`.
+
If `true`, allows restoring a partial snapshot of indices with unavailable shards. Only shards that were successfully included in the snapshot
will be restored. All missing shards will be recreated as empty.

[[restore-snapshot-api-rename-pattern]]
`rename_pattern`::
(Optional, string)
Defines a rename pattern to apply to restored data streams and indices. Data streams and indices matching the rename pattern will be renamed according to
<<restore-snapshot-api-rename-replacement,`rename_replacement`>>.
+
The rename pattern is applied as defined by the regular expression that
supports referencing the original text, according to the https://docs.oracle.com/javase/8/docs/api/java/util/regex/Matcher.html#appendReplacement-java.lang.StringBuffer-java.lang.String-[`appendReplacement`] logic.

[[restore-snapshot-api-rename-replacement]]
`rename_replacement`::
(Optional, string)
Defines the rename replacement string. See <<restore-snapshot-api-rename-pattern,`rename_pattern`>> for more information.

[[restore-snapshot-api-example]]
==== {api-examples-title}

[[restore-snapshot-api-example-rename]]
===== Restore renamed

The following request 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` when restored.

For example, `index_1` will be renamed to `restored_index_1`. `index_2` will be renamed to `restored_index_2`.

[source,console]
----
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
}
----

The API returns an acknowledgement if the request succeeds. If the request encounters errors, the response indicates any issues found, such as
open indices that are blocking the restore operation from completing.

[[restore-snapshot-api-example-inplace]]
===== Restore in-place

You may want to restore an index in-place, for example when no alternative
options surface after the <<cluster-allocation-explain>> API reports
`no_valid_shard_copy`.

The following request <<indices-close,closes>> `index_1` and then restores it
in-place from the `snapshot_2` snapshot in the `my_repository` repository.

[source,console]
----
POST index_1/_close

POST /_snapshot/my_repository/snapshot_2/_restore?wait_for_completion=true
{
  "indices": "index_1"
}
----