Restore Snapshot API

edit

The Restore Snapshot API allows to restore a snapshot.

Restore Snapshot Request

edit

A RestoreSnapshotRequest:

RestoreSnapshotRequest request = new RestoreSnapshotRequest(repositoryName, snapshotName);

Limiting Indices to Restore

edit

By default all indices are restored. With the indices property you can provide a list of indices that should be restored:

request.indices("test_index"); 

Request that Elasticsearch only restores "test_index".

Renaming Indices

edit

You can rename indices using regular expressions when restoring a snapshot:

request.renamePattern("test_(.+)"); 
request.renameReplacement("restored_$1"); 

A regular expression matching the indices that should be renamed.

A replacement pattern that references the group from the regular expression as $1. "test_index" from the snapshot is restored as "restored_index" in this example.

Index Settings and Options

edit

You can also customize index settings and options when restoring:

request.indexSettings(  
    Settings.builder()
    .put("index.number_of_replicas", 0)
        .build());

request.ignoreIndexSettings("index.refresh_interval", "index.search.idle.after"); 
request.indicesOptions(new IndicesOptions( 
    EnumSet.of(IndicesOptions.Option.IGNORE_UNAVAILABLE),
    EnumSet.of(IndicesOptions.WildcardStates.OPEN)));

Use #indexSettings() to set any specific index setting for the indices that are restored.

Use #ignoreIndexSettings() to provide index settings that should be ignored from the original indices.

Set IndicesOptions.Option.IGNORE_UNAVAILABLE in #indicesOptions() to have the restore succeed even if indices are missing in the snapshot.

Further Arguments

edit

The following arguments can optionally be provided:

request.masterNodeTimeout(TimeValue.timeValueMinutes(1)); 
request.masterNodeTimeout("1m"); 

Timeout to connect to the master node as a TimeValue

Timeout to connect to the master node as a String

request.waitForCompletion(true); 

Boolean indicating whether to wait until the snapshot has been restored.

request.partial(false); 

Boolean indicating whether the entire snapshot should succeed although one or more indices participating in the snapshot don’t have all primary shards available.

request.includeGlobalState(false); 

Boolean indicating whether restored templates that don’t currently exist in the cluster are added and existing templates with the same name are replaced by the restored templates. The restored persistent settings are added to the existing persistent settings.

request.includeAliases(false); 

Boolean to control whether aliases should be restored. Set to false to prevent aliases from being restored together with associated indices.

Synchronous Execution

edit
RestoreSnapshotResponse response = client.snapshot().restore(request, RequestOptions.DEFAULT);

Asynchronous Execution

edit

The asynchronous execution of a restore snapshot request requires both the RestoreSnapshotRequest instance and an ActionListener instance to be passed to the asynchronous method:

client.snapshot().restoreAsync(request, RequestOptions.DEFAULT, listener); 

The RestoreSnapshotRequest to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed.

A typical listener for RestoreSnapshotResponse looks like:

ActionListener<RestoreSnapshotResponse> listener =
    new ActionListener<RestoreSnapshotResponse>() {
        @Override
        public void onResponse(RestoreSnapshotResponse restoreSnapshotResponse) {
            
        }

        @Override
        public void onFailure(Exception e) {
            
        }
    };

Called when the execution is successfully completed. The response is provided as an argument.

Called in case of a failure. The raised exception is provided as an argument.

Restore Snapshot Response

edit

The returned RestoreSnapshotResponse allows to retrieve information about the executed operation as follows:

RestoreInfo restoreInfo = response.getRestoreInfo();
List<String> indices = restoreInfo.indices(); 

The RestoreInfo contains details about the restored snapshot like the indices or the number of successfully restored and failed shards.