Create a snapshot

A repository can contain multiple snapshots of the same cluster. Snapshots are identified by unique names within the cluster.

Use the put snapshot repository API to register or update a snapshot repository, and then use the create snapshot API to create a snapshot in a repository.

The following request creates a snapshot with the name snapshot_1 in the repository my_backup:

PUT /_snapshot/my_backup/snapshot_1?wait_for_completion=true

The wait_for_completion parameter specifies whether or not the request should return immediately after snapshot initialization (default) or wait for snapshot completion. During snapshot initialization, information about all previous snapshots is loaded into memory, which means that in large repositories it may take several seconds (or even minutes) for this request to return even if the wait_for_completion parameter is set to false.

By default, a snapshot backs up all data streams and open indices in the cluster. You can change this behavior by specifying the list of data streams and indices in the body of the snapshot request:

PUT /_snapshot/my_backup/snapshot_2?wait_for_completion=true
{
  "indices": "data_stream_1,index_1,index_2",
  "ignore_unavailable": true,
  "include_global_state": false,
  "metadata": {
    "taken_by": "kimchy",
    "taken_because": "backup before upgrading"
  }
}

Use the indices parameter to list the data streams and indices that should be included in the snapshot. This parameter supports multi-target syntax, although the options that control the behavior of multi-index syntax must be supplied in the body of the request, rather than as request parameters.

Data stream backups include the stream’s backing indices and metadata, such as the current generation and timestamp field.

You can also choose to include only specific backing indices in a snapshot. However, these backups do not include the associated data stream’s metadata or its other backing indices.

Snapshot process details

The snapshot process is incremental. In the process of making the snapshot, Elasticsearch analyses the list of the data stream and index files that are already stored in the repository and copies only files that were created or changed since the last snapshot. This process allows multiple snapshots to be preserved in the repository in a compact form.

The snapshot process is executed in non-blocking fashion. All indexing and searching operations can continue to run against the data stream or index that is being snapshotted. However, a snapshot represents a point-in-time view at the moment when snapshot was created, so no records that were added to the data stream or index after the snapshot process was started will be included in the snapshot.

The snapshot process starts immediately for the primary shards that have been started and are not relocating at the moment. Elasticsearch waits for relocation or initialization of shards to complete before snapshotting them.

Besides creating a copy of each data stream and index, the snapshot process can also store global cluster metadata, which includes persistent cluster settings and templates. The transient settings and registered snapshot repositories are not stored as part of the snapshot.

While a snapshot of a particular shard is being created, this shard cannot be moved to another node, which can interfere with rebalancing and allocation filtering. Elasticsearch can only move a shard to another node (according to the current allocation filtering settings and rebalancing algorithm) after the snapshot process is finished.

After a snapshot is created, use the Get snapshot API to retrieve information about a snapshot. See Monitor snapshot and restore progress to learn more about retrieving snapshot status.

Options for creating a snapshot

The create snapshot request supports the ignore_unavailable option. Setting it to true will cause data streams and indices that do not exist to be ignored during snapshot creation. By default, when the ignore_unavailable option is not set and a data stream or index is missing, the snapshot request will fail.

By setting include_global_state to false it’s possible to prevent the cluster global state to be stored as part of the snapshot.

The global cluster state includes the cluster’s index templates, such as those matching a data stream. If your snapshot includes data streams, we recommend storing the cluster state as part of the snapshot. This lets you later restored any templates required for a data stream.

By default, the entire snapshot will fail if one or more indices participating in the snapshot do not have all primary shards available. You can change this behaviour by setting partial to true. The expand_wildcards option can be used to control whether hidden and closed indices will be included in the snapshot, and defaults to all.

Use the metadata field to attach arbitrary metadata to the snapshot, such as who took the snapshot, why it was taken, or any other data that might be useful.

Snapshot names can be automatically derived using date math expressions, similarly as when creating new indices. Special characters must be URI encoded.

For example, use the create snapshot API to create a snapshot with the current day in the name, such as snapshot-2020.07.11:

PUT /_snapshot/my_backup/<snapshot-{now/d}>
PUT /_snapshot/my_backup/%3Csnapshot-%7Bnow%2Fd%7D%3E