[[create-snapshot-api]] === Create snapshot API ++++ Create snapshot ++++ <> of a cluster or specified data streams and indices. //// [source,console] ----------------------------------- PUT /_snapshot/my_repository { "type": "fs", "settings": { "location": "my_backup_location" } } ----------------------------------- // TESTSETUP //// [source,console] ----------------------------------- PUT /_snapshot/my_repository/my_snapshot ----------------------------------- // TEST[s/my_snapshot/my_snapshot?wait_for_completion=true/] [[create-snapshot-api-request]] ==== {api-request-title} `PUT /_snapshot//` `POST /_snapshot//` [[create-snapshot-api-prereqs]] ==== {api-prereq-title} * If the {es} {security-features} are enabled, you must have the `create_snapshot` or `manage` <> to use this API. [[create-snapshot-api-path-params]] ==== {api-path-parms-title} ``:: (Required, string) Name of the snapshot repository. ``:: (Required, string) Name of the snapshot. Supports <>. Must be unique within the snapshot repository. [[create-snapshot-api-query-params]] ==== {api-query-parms-title} include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=master-timeout] `wait_for_completion`:: (Optional, Boolean) If `true`, the request returns a response when the snapshot is complete. If `false`, the request returns a response when the snapshot initializes. Defaults to `false`. [role="child_attributes"] [[create-snapshot-api-request-body]] ==== {api-request-body-title} // Set an attribute so we can reuse these params with anchors :page-id: create-snapshot-api // tag::snapshot-config[] `expand_wildcards`:: + -- (Optional, string) Determines how wildcard patterns in the `indices` parameter match data streams and indices. Supports comma-separated values, such as `open,hidden`. Defaults to `all`. Valid values are: `all`::: Match any data stream or index, including closed and <> ones. `open`::: Match open indices and data streams. `closed`::: Match closed indices and data streams. `hidden`::: Match hidden data streams and indices. Must be combined with `open`, `closed`, or both. `none`::: Don't expand wildcard patterns. -- `ignore_unavailable`:: (Optional, Boolean) If `false`, the snapshot fails if any data stream or index in `indices` is missing. If `true`, the snapshot ignores missing data streams and indices. Defaults to `false`. `include_global_state`:: + -- (Optional, Boolean) If `true`, include the cluster state in the snapshot. Defaults to `true`. The cluster state includes: include::restore-snapshot-api.asciidoc[tag=cluster-state-contents] -- `indices`:: (Optional, string or array of strings) Comma-separated list of data streams and indices to include in the snapshot. Supports <>. Defaults to an empty array (`[]`), which includes all regular data streams and regular indices. To exclude all data streams and indices, use `-*`. + You can't use this parameter to include or exclude <> from a snapshot. Use <<{page-id}-feature-states,`feature_states`>> instead. [id="{page-id}-feature-states"] `feature_states`:: (Optional, array of strings) <> to include in the snapshot. To get a list of possible values and their descriptions, use the <>. + If `include_global_state` is `true`, the snapshot includes all feature states by default. If `include_global_state` is `false`, the snapshot includes no feature states by default. + Note that specifying an empty array will result in the default behavior. To exclude all feature states, regardless of the `include_global_state` value, specify an array with only the value `none` (`["none"]`). `metadata`:: (Optional, object) Attaches arbitrary metadata to the snapshot, such as a record of who took the snapshot, why it was taken, or any other useful data. Metadata must be less than 1024 bytes. [id="{page-id}-partial"] `partial`:: (Optional, Boolean) If `false`, the entire snapshot will fail if one or more indices included in the snapshot do not have all primary shards available. Defaults to `false`. + If `true`, allows taking a partial snapshot of indices with unavailable shards. // end::snapshot-config[] // Unset the attribute :!page-id: [[create-snapshot-api-example]] ==== {api-examples-title} The following request takes a snapshot of `index_1` and `index_2`. [source,console] ----------------------------------- PUT /_snapshot/my_repository/snapshot_2?wait_for_completion=true { "indices": "index_1,index_2", "ignore_unavailable": true, "include_global_state": false, "metadata": { "taken_by": "user123", "taken_because": "backup before upgrading" } } ----------------------------------- The API returns the following response: [source,console-result] ---- { "snapshot": { "snapshot": "snapshot_2", "uuid": "vdRctLCxSketdKb54xw67g", "repository": "my_repository", "version_id": , "version": , "indices": [], "data_streams": [], "feature_states": [], "include_global_state": false, "metadata": { "taken_by": "user123", "taken_because": "backup before upgrading" }, "state": "SUCCESS", "start_time": "2020-06-25T14:00:28.850Z", "start_time_in_millis": 1593093628850, "end_time": "2020-06-25T14:00:28.850Z", "end_time_in_millis": 1593094752018, "duration_in_millis": 0, "failures": [], "shards": { "total": 0, "failed": 0, "successful": 0 } } } ---- // TESTRESPONSE[s/"uuid": "vdRctLCxSketdKb54xw67g"/"uuid": $body.snapshot.uuid/] // TESTRESPONSE[s/"version_id": /"version_id": $body.snapshot.version_id/] // TESTRESPONSE[s/"version": /"version": $body.snapshot.version/] // TESTRESPONSE[s/"start_time": "2020-06-25T14:00:28.850Z"/"start_time": $body.snapshot.start_time/] // TESTRESPONSE[s/"start_time_in_millis": 1593093628850/"start_time_in_millis": $body.snapshot.start_time_in_millis/] // TESTRESPONSE[s/"end_time": "2020-06-25T14:00:28.850Z"/"end_time": $body.snapshot.end_time/] // TESTRESPONSE[s/"end_time_in_millis": 1593094752018/"end_time_in_millis": $body.snapshot.end_time_in_millis/] // TESTRESPONSE[s/"duration_in_millis": 0/"duration_in_millis": $body.snapshot.duration_in_millis/]