Create a snapshot

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

Use the create or update 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.

Snapshots can also include a data stream but exclude specific backing indices. When you restore the data stream, it will contain only backing indices present in the snapshot. If the stream’s original write index is not in the snapshot, the most recent backing index from the snapshot becomes the stream’s write index.

The snapshot process works by taking a byte-for-byte copy of the files that make up each index or data stream and placing these copies in the repository. These files are mostly written by Lucene and contain a compact representation of all the data in each index or data stream in a form that is designed to be searched efficiently. This means that when you restore an index or data stream from a snapshot there is no need to rebuild these search-focused data structures. It also means that you can use Searchable snapshots to directly search the data in the repository.

The snapshot process is incremental: Elasticsearch compares the files that make up the index or data stream against the files that already exist in the repository and only copies files that were created or changed since the last snapshot. Snapshots are very space-efficient since they reuse any files copied to the repository by earlier snapshots.

Snapshotting does not interfere with ongoing indexing or searching operations. A snapshot captures a view of each shard at some point in time between the start and end of the snapshotting process. The snapshot may not include documents added to a data stream or index after the snapshot process starts.

You can start multiple snapshot operations at the same time. Concurrent snapshot operations are limited by the snapshot.max_concurrent_operations cluster setting, which defaults to 1000. This limit applies in total to all ongoing snapshot creation, cloning, and deletion operations. Elasticsearch will reject any operations that would exceed this limit.

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, templates, and data stored in system indices, such as Watches and task records, regardless of whether those system indices are named in the indices section of the request. You can also use the create snapshot API’s feature_states parameter to include only a subset of system indices in the snapshot. Snapshots do not store transient settings or registered snapshot repositories.

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

You can use the Get snapshot API to retrieve information about ongoing and completed snapshots. See Monitor snapshot and restore progress.

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.

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 open,hidden.

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