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

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

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_3,index_4",
  "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
{
  "indices": "*,-.*",
  "feature_states": [ "geoip" ]
}
----
// TEST[s/_restore/_restore?wait_for_completion=true/]
// TEST[s/",/"/]
// TEST[s/"feature_states": \[ "geoip" \]//]

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

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

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

// tag::restore-prereqs[]
* If you use the {es} security features, you must have the `manage` or
`cluster:admin/snapshot/*` cluster privilege to restore a snapshot.

* 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>>.

* If you restore a data stream, ensure the cluster contains a
<<create-index-template,matching index template>> with data stream enabled.
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-repo-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>>
* For snapshots taken after 7.12.0, data stored in system indices, such as
  Watches and task records.
// 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.

You can use the `feature_states` parameter to configure how system indices
are restored from the cluster state.
--

[[restore-snapshot-api-feature-states]]
`feature_states`::
(Optional, array of strings)
A comma-separated list of feature states you wish to restore. Each feature state contains one or more system indices. The list of feature states
available in a given snapshot are returned by the <<get-snapshot-api-feature-states, Get Snapshot API>>. Note that feature
states restored this way will completely replace any existing configuration, rather than returning an error if the system index already exists.
Providing an empty array will restore no feature states, regardless of the value of `include_global_state`.
+
By default, all available feature states will be restored if `include_global_state` is `true`, and no feature states will be restored if
`include_global_state` is `false`.

[[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 indices and data streams in the snapshot, including system indices.

[[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}

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.