[[snapshots-take-snapshot]] == Take a snapshot of one or more indices ++++ Take a snapshot ++++ A repository can contain multiple snapshots of the same cluster. Snapshots are identified by unique names within the cluster. A snapshot with the name `snapshot_1` in the repository `my_backup` can be created by executing the following command: //// [source,console] ----------------------------------- PUT /_snapshot/my_backup { "type": "fs", "settings": { "location": "my_backup_location" } } ----------------------------------- // TESTSETUP //// [source,console] ----------------------------------- 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 the memory, which means that in large repositories it may take several seconds (or even minutes) for this command to return even if the `wait_for_completion` parameter is set to `false`. By default a snapshot of all open and started indices in the cluster is created. This behavior can be changed by specifying the list of indices in the body of the snapshot request. [source,console] ----------------------------------- PUT /_snapshot/my_backup/snapshot_2?wait_for_completion=true { "indices": "index_1,index_2", "ignore_unavailable": true, "include_global_state": false, "metadata": { "taken_by": "kimchy", "taken_because": "backup before upgrading" } } ----------------------------------- // TEST[skip:cannot complete subsequent snapshot] The list of indices that should be included into the snapshot can be specified using the `indices` parameter that supports <>. The snapshot request also supports the `ignore_unavailable` option. Setting it to `true` will cause indices that do not exist to be ignored during snapshot creation. By default, when `ignore_unavailable` option is not set and an 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 don't have all primary shards available. This behaviour can be changed by setting `partial` to `true`. The `metadata` field can be used to attach arbitrary metadata to the snapshot. This may be a record of who took the snapshot, why it was taken, or any other data that might be useful. Snapshot names can be automatically derived using <>, similarly as when creating new indices. Note that special characters need to be URI encoded. For example, creating a snapshot with the current day in the name, like `snapshot-2018.05.11`, can be achieved with the following command: [source,console] ----------------------------------- # PUT /_snapshot/my_backup/ PUT /_snapshot/my_backup/%3Csnapshot-%7Bnow%2Fd%7D%3E ----------------------------------- // TEST[continued] The index snapshot process is incremental. In the process of making the index snapshot Elasticsearch analyses the list of the index files that are already stored in the repository and copies only files that were created or changed since the last snapshot. That allows multiple snapshots to be preserved in the repository in a compact form. Snapshotting process is executed in non-blocking fashion. All indexing and searching operation can continue to be executed against the index that is being snapshotted. However, a snapshot represents the point-in-time view of the index at the moment when snapshot was created, so no records that were added to the index after the snapshot process was started will be present in the snapshot. The snapshot process starts immediately for the primary shards that has been started and are not relocating at the moment. Before version 1.2.0, the snapshot operation fails if the cluster has any relocating or initializing primaries of indices participating in the snapshot. Starting with version 1.2.0, Elasticsearch waits for relocation or initialization of shards to complete before snapshotting them. Besides creating a copy of each 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. Only one snapshot process can be executed in the cluster at any time. While snapshot of a particular shard is being created this shard cannot be moved to another node, which can interfere with rebalancing process and allocation filtering. Elasticsearch will only be able to move a shard to another node (according to the current allocation filtering settings and rebalancing algorithm) once the snapshot is finished. Once a snapshot is created information about this snapshot can be obtained using the following command: [source,console] ----------------------------------- GET /_snapshot/my_backup/snapshot_1 ----------------------------------- // TEST[continued] This command returns basic information about the snapshot including start and end time, version of Elasticsearch that created the snapshot, the list of included indices, the current state of the snapshot and the list of failures that occurred during the snapshot. The snapshot `state` can be [horizontal] `IN_PROGRESS`:: The snapshot is currently running. `SUCCESS`:: The snapshot finished and all shards were stored successfully. `FAILED`:: The snapshot finished with an error and failed to store any data. `PARTIAL`:: The global cluster state was stored, but data of at least one shard wasn't stored successfully. The `failure` section in this case should contain more detailed information about shards that were not processed correctly. `INCOMPATIBLE`:: The snapshot was created with an old version of Elasticsearch and therefore is incompatible with the current version of the cluster. Similar as for repositories, information about multiple snapshots can be queried in one go, supporting wildcards as well: [source,console] ----------------------------------- GET /_snapshot/my_backup/snapshot_*,some_other_snapshot ----------------------------------- // TEST[continued] All snapshots currently stored in the repository can be listed using the following command: [source,console] ----------------------------------- GET /_snapshot/my_backup/_all ----------------------------------- // TEST[continued] The command fails if some of the snapshots are unavailable. The boolean parameter `ignore_unavailable` can be used to return all snapshots that are currently available. Getting all snapshots in the repository can be costly on cloud-based repositories, both from a cost and performance perspective. If the only information required is the snapshot names/uuids in the repository and the indices in each snapshot, then the optional boolean parameter `verbose` can be set to `false` to execute a more performant and cost-effective retrieval of the snapshots in the repository. Note that setting `verbose` to `false` will omit all other information about the snapshot such as status information, the number of snapshotted shards, etc. The default value of the `verbose` parameter is `true`. It is also possible to retrieve snapshots from multiple repositories in one go, for example: [source,console] ----------------------------------- GET /_snapshot/_all GET /_snapshot/my_backup,my_fs_backup GET /_snapshot/my*/snap* ----------------------------------- // TEST[skip:no my_fs_backup] A currently running snapshot can be retrieved using the following command: [source,console] ----------------------------------- GET /_snapshot/my_backup/_current ----------------------------------- // TEST[continued] A snapshot can be deleted from the repository using the following command: [source,console] ----------------------------------- DELETE /_snapshot/my_backup/snapshot_2 ----------------------------------- // TEST[continued] When a snapshot is deleted from a repository, Elasticsearch deletes all files that are associated with the deleted snapshot and not used by any other snapshots. If the deleted snapshot operation is executed while the snapshot is being created the snapshotting process will be aborted and all files created as part of the snapshotting process will be cleaned. Therefore, the delete snapshot operation can be used to cancel long running snapshot operations that were started by mistake. A repository can be unregistered using the following command: [source,console] ----------------------------------- DELETE /_snapshot/my_backup ----------------------------------- // TEST[continued] When a repository is unregistered, Elasticsearch only removes the reference to the location where the repository is storing the snapshots. The snapshots themselves are left untouched and in place.