|
|
@@ -1,9 +1,5 @@
|
|
|
[[snapshots-take-snapshot]]
|
|
|
-== Take a snapshot of one or more indices
|
|
|
-
|
|
|
-++++
|
|
|
-<titleabbrev>Take a snapshot</titleabbrev>
|
|
|
-++++
|
|
|
+== 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
|
|
|
@@ -33,14 +29,14 @@ initialization (default) or wait for snapshot completion. During snapshot initia
|
|
|
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.
|
|
|
+By default a snapshot backs up all data streams and open indices in the cluster. This behavior can be changed by
|
|
|
+specifying the list of data streams and 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",
|
|
|
+ "indices": "data_stream_1,index_1,index_2",
|
|
|
"ignore_unavailable": true,
|
|
|
"include_global_state": false,
|
|
|
"metadata": {
|
|
|
@@ -51,13 +47,31 @@ PUT /_snapshot/my_backup/snapshot_2?wait_for_completion=true
|
|
|
-----------------------------------
|
|
|
// 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
|
|
|
+The list of data streams and indices that should be included into the snapshot can be specified using the `indices` parameter that
|
|
|
supports <<multi-index,multi-target syntax>>, although the options which control the behavior of multi index syntax
|
|
|
-must be supplied in the body of the request, rather than as request parameters. 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.
|
|
|
+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 <<data-streams-generation,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.
|
|
|
+
|
|
|
+The snapshot request also 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 don't have
|
|
|
+the snapshot.
|
|
|
+
|
|
|
+IMPORTANT: The global cluster state includes the cluster's index
|
|
|
+templates, such as those <<create-a-data-stream-template,matching a data
|
|
|
+streams>>. 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 don't have
|
|
|
all primary shards available. This behaviour can be changed 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`.
|
|
|
|
|
|
@@ -65,7 +79,7 @@ The `metadata` field can be used to attach arbitrary metadata to the snapshot. T
|
|
|
why it was taken, or any other data that might be useful.
|
|
|
|
|
|
Snapshot names can be automatically derived using <<date-math-index-names,date math expressions>>, similarly as when creating
|
|
|
-new indices. Note that special characters need to be URI encoded.
|
|
|
+new data streams or 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:
|
|
|
@@ -78,18 +92,18 @@ 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
|
|
|
+The snapshot process is incremental. In the process of making the snapshot, {es} 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. 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
|
|
|
+executed 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 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
|
|
|
+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.
|
|
|
|
|
|
@@ -107,7 +121,7 @@ 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
|
|
|
+Elasticsearch that created the snapshot, the list of included data streams and indices, the current state of the
|
|
|
snapshot and the list of failures that occurred during the snapshot. The snapshot `state` can be
|
|
|
|
|
|
[horizontal]
|
|
|
@@ -150,7 +164,7 @@ 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 snapshot names/uuids in the repository and the data streams and 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
|
James Rodewig