Create a snapshot Generally available; Added in 0.0.0

POST /_snapshot/{repository}/{snapshot}
Api key auth Basic auth Bearer auth

All methods and paths for this operation:

PUT /_snapshot/{repository}/{snapshot}

POST /_snapshot/{repository}/{snapshot}

Take a snapshot of a cluster or of data streams and indices.

Required authorization

  • Cluster privileges: create_snapshot
External documentation

Path parameters

  • repository string Required

    The name of the repository for the snapshot.

  • snapshot string Required

    The name of the snapshot. It supportes date math. It must be unique in the repository.

Query parameters

  • master_timeout string

    The period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.

    External documentation
  • wait_for_completion boolean

    If true, the request returns a response when the snapshot is complete. If false, the request returns a response when the snapshot initializes.

application/json

Body

  • expand_wildcards string | array[string]

    Determines how wildcard patterns in the indices parameter match data streams and indices. It supports comma-separated values such as open,hidden.

    Supported values include:

    • all: Match any data stream or index, including hidden ones.
    • open: Match open, non-hidden indices. Also matches any non-hidden data stream.
    • closed: Match closed, non-hidden indices. Also matches any non-hidden data stream. Data streams cannot be closed.
    • hidden: Match hidden data streams and hidden indices. Must be combined with open, closed, or both.
    • none: Wildcard expressions are not accepted.
  • feature_states array[string]

    The feature states to include in the snapshot. Each feature state includes one or more system indices containing related data. You can view a list of eligible features using the get features API.

    If include_global_state is true, all current feature states are included by default. If include_global_state is false, no feature states are included 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"]).

  • ignore_unavailable boolean

    If true, the request ignores data streams and indices in indices that are missing or closed. If false, the request returns an error for any data stream or index that is missing or closed.

    Default value is false.

  • include_global_state boolean

    If true, the current cluster state is included in the snapshot. The cluster state includes persistent cluster settings, composable index templates, legacy index templates, ingest pipelines, and ILM policies. It also includes data stored in system indices, such as Watches and task records (configurable via feature_states).

    Default value is true.

  • indices string | array[string]

    A comma-separated list of data streams and indices to include in the snapshot. It supports a multi-target syntax. The default is 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 system indices or system data streams from a snapshot. Use feature_states instead.

  • metadata object

    Arbitrary metadata to the snapshot, such as a record of who took the snapshot, why it was taken, or any other useful data. It can have any contents but it must be less than 1024 bytes. This information is not automatically generated by Elasticsearch.

    Hide metadata attribute Show metadata attribute object
    • * object Additional properties
  • partial boolean

    If true, allows the snapshot to proceed even if some of the target shards are unavailable. In this case, the resulting snapshot will not contain snapshots of the unavailable target shards, and will report its state as PARTIAL. Additionally, if true, allows index metadata operations such as deletions while the snapshot is in progress. This is almost always preferable to failing the snapshot completely when a single shard is unavailable, and blocking index metadata operations.

    If false, the entire restore operation will fail if one or more indices included in the snapshot do not have all primary shards available, and index metadata operations such as deletions will be forbidden until the snapshot completes.

    Default value is false.

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • accepted boolean Generally available; Added in 7.15.0

      Equals true if the snapshot was accepted. Present when the request had wait_for_completion set to false

    • snapshot object

      Snapshot information. Present when the request had wait_for_completion set to true

      Hide snapshot attributes Show snapshot attributes object
      • data_streams array[string] Required
      • duration string

        A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.

        External documentation
      • duration_in_millis number

        Time unit for milliseconds

      • end_time string | number

        One of:
        string-1 string UnitMillis number

        Time unit for milliseconds

      • end_time_in_millis number

        Time unit for milliseconds

      • failures array[object]
        Hide failures attributes Show failures attributes object
        • index string Required
        • node_id string
        • reason string Required
        • shard_id number Required
        • index_uuid string Required
        • status string Required
      • include_global_state boolean
      • indices array[string]
      • index_details object Generally available; Added in 7.13.0
        Hide index_details attribute Show index_details attribute object
        • * object Additional properties
          Hide * attributes Show * attributes object
          • shard_count number Required
          • size
          • size_in_bytes number Required
          • max_segments_per_shard number Required
      • metadata object
        Hide metadata attribute Show metadata attribute object
        • * object Additional properties
      • reason string
      • repository string Generally available; Added in 7.14.0
      • snapshot string Required
      • shards object
        Hide shards attributes Show shards attributes object
        • failed number Required

          The number of shards the operation or search attempted to run on but failed.

        • successful number Required

          The number of shards the operation or search succeeded on.

        • total number Required

          The number of shards the operation or search will run on overall.

        • failures array[object]
        • skipped number

      • start_time string | number

        One of:
        string-1 string UnitMillis number

        Time unit for milliseconds

      • start_time_in_millis number

        Time unit for milliseconds

      • state string
      • uuid string Required
      • version string
      • version_id number
      • feature_states array[object]
        Hide feature_states attributes Show feature_states attributes object
        • feature_name string Required
        • indices string | array[string] Required
POST /_snapshot/{repository}/{snapshot} 
PUT /_snapshot/my_repository/snapshot_2?wait_for_completion=true
{
  "partial": true,
  "indices": "index_1,index_2",
  "ignore_unavailable": true,
  "include_global_state": false,
  "metadata": {
    "taken_by": "user123",
    "taken_because": "backup before upgrading"
  }
}
resp = client.snapshot.create(
    repository="my_repository",
    snapshot="snapshot_2",
    wait_for_completion=True,
    partial=True,
    indices="index_1,index_2",
    ignore_unavailable=True,
    include_global_state=False,
    metadata={
        "taken_by": "user123",
        "taken_because": "backup before upgrading"
    },
)
const response = await client.snapshot.create({
  repository: "my_repository",
  snapshot: "snapshot_2",
  wait_for_completion: "true",
  partial: true,
  indices: "index_1,index_2",
  ignore_unavailable: true,
  include_global_state: false,
  metadata: {
    taken_by: "user123",
    taken_because: "backup before upgrading",
  },
});
response = client.snapshot.create(
  repository: "my_repository",
  snapshot: "snapshot_2",
  wait_for_completion: "true",
  body: {
    "partial": true,
    "indices": "index_1,index_2",
    "ignore_unavailable": true,
    "include_global_state": false,
    "metadata": {
      "taken_by": "user123",
      "taken_because": "backup before upgrading"
    }
  }
)
$resp = $client->snapshot()->create([
    "repository" => "my_repository",
    "snapshot" => "snapshot_2",
    "wait_for_completion" => "true",
    "body" => [
        "partial" => true,
        "indices" => "index_1,index_2",
        "ignore_unavailable" => true,
        "include_global_state" => false,
        "metadata" => [
            "taken_by" => "user123",
            "taken_because" => "backup before upgrading",
        ],
    ],
]);
curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"partial":true,"indices":"index_1,index_2","ignore_unavailable":true,"include_global_state":false,"metadata":{"taken_by":"user123","taken_because":"backup before upgrading"}}' "$ELASTICSEARCH_URL/_snapshot/my_repository/snapshot_2?wait_for_completion=true"
client.snapshot().create(c -> c
    .ignoreUnavailable(true)
    .includeGlobalState(false)
    .indices("index_1,index_2")
    .metadata(Map.of("taken_by", JsonData.fromJson("\"user123\""),"taken_because", JsonData.fromJson("\"backup before upgrading\"")))
    .repository("my_repository")
    .snapshot("snapshot_2")
    .waitForCompletion(true)
);
Request example
Run `PUT /_snapshot/my_repository/snapshot_2?wait_for_completion=true` to take a snapshot of `index_1` and `index_2`. 
{
  "partial": true,
  "indices": "index_1,index_2",
  "ignore_unavailable": true,
  "include_global_state": false,
  "metadata": {
    "taken_by": "user123",
    "taken_because": "backup before upgrading"
  }
}
Response examples (200)
A successful response from `PUT /_snapshot/my_repository/snapshot_2?wait_for_completion=true`. 
{
  "snapshot": {
    "snapshot": "snapshot_2",
    "uuid": "vdRctLCxSketdKb54xw67g",
    "repository": "my_repository",
    "version_id": <version_id>,
    "version": <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
    }
  }
}