60_restore.asciidoc

Restoring from a snapshot

Once you’ve backed up some data, restoring it is very easy: simply add _restore to the ID of the snapshot you wish to restore into your cluster:

POST _snapshot/my_backup/snapshot_1/_restore

The default behavior is to restore all indices that exist in that snapshot. If snapshot_1 contains five different indices, all five will be restored into our cluster. Like the Snapshot API, it is possible to select which indices we want to restore.

There are also additional options for renaming indices. This allows you to match index names with a pattern, then provide a new name during the restore process. This is useful if you want to restore old data to verify it’s contents, or perform some other processing, without replacing existing data. Let’s restore a single index from the snapshot and provide a replacement name:

POST /_snapshot/my_backup/snapshot_1/_restore
{
    "indices": "index_1", (1)
    "rename_pattern": "index_(.+)", (2)
    "rename_replacement": "restored_index_$1" (3)
}

1. Only restore the index_1 index, ignoring the rest that are present in the snapshot

2. Find any indices being restored which match the provided pattern…​

3. …​ then rename them with the replacement pattern

This will restore index_1 into your cluster, but rename it to restored_index_1.

Tip

Blocking for completion Similar to snapshotting, the restore command will return immediately and the restoration process will happen in the background. If you would prefer your HTTP call to block until the restore is finished, simply add the wait_for_completion flag: POST _snapshot/my_backup/snapshot_1/_restore?wait_for_completion=true

Monitoring Restore operations

The restoration of data from a repository piggybacks on the existing recovery mechanisms already in place in Elasticsearch. Internally, recovering shards from a repository is identical to recovering from another node.

If you wish to monitor the progress of a restore, you can use the Recovery API. This is a general purpose API which shows status of shards moving around your cluster.

The API can be invoked for the specific indices that you are recovering:

GET /_recovery/restored_index_3

Or for all indices in your cluster, which may include other shards moving around, unrelated to your restore process:

GET /_recovery/

The output will look similar to this (and note, it can become very verbose depending on the activity of your clsuter!):

{
  "restored_index_3" : {
    "shards" : [ {
      "id" : 0,
      "type" : "snapshot", (1)
      "stage" : "index",
      "primary" : true,
      "start_time" : "2014-02-24T12:15:59.716",
      "stop_time" : 0,
      "total_time_in_millis" : 175576,
      "source" : { (2)
        "repository" : "my_backup",
        "snapshot" : "snapshot_3",
        "index" : "restored_index_3"
      },
      "target" : {
        "id" : "ryqJ5lO5S4-lSFbGntkEkg",
        "hostname" : "my.fqdn",
        "ip" : "10.0.1.7",
        "name" : "my_es_node"
      },
      "index" : {
        "files" : {
          "total" : 73,
          "reused" : 0,
          "recovered" : 69,
          "percent" : "94.5%" (3)
        },
        "bytes" : {
          "total" : 79063092,
          "reused" : 0,
          "recovered" : 68891939,
          "percent" : "87.1%"
        },
        "total_time_in_millis" : 0
      },
      "translog" : {
        "recovered" : 0,
        "total_time_in_millis" : 0
      },
      "start" : {
        "check_index_time" : 0,
        "total_time_in_millis" : 0
      }
    } ]
  }
}

1. The type field will tell you the nature of the recovery — this shard is being recovered from a snapshot

2. The source hash will describe the particular snapshot and repository that is being recovered from

3. And the percent field will give you an idea about the status of the recovery. This particular shard has recovered 94% of the files so far…​it is almost complete

The output will list all indices currently undergoing a recovery, and then a list of all shards in each of those indices. Each of these shards will have stats about start/stop time, duration, recover percentage, bytes transferred, etc.

Canceling a Restore

To cancel a restore, you need to delete the indices being restored. Because a restore process is really just shard recovery, issuing a Delete Index API alters the cluster state, which will in turn halt recovery. For example:

DELETE /restored_index_3

If restored_index_3 was actively being restored, this delete command would halt the restoration as well as deleting any data that had already been restored into the cluster.