Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[DOCS] Adding get snapshot API docs #59098

Merged
240 changes: 240 additions & 0 deletions docs/reference/snapshot-restore/apis/get-snapshot-api.asciidoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,240 @@
[[get-snapshot-api]]
=== Get snapshot API
++++
<titleabbrev>Get snapshot</titleabbrev>
++++

Retrieves information about one or more snapshots.

////
[source,console]
----
PUT /_snapshot/my_repository
{
"type": "fs",
"settings": {
"location": "my_backup_location"
}
}

PUT /_snapshot/my_repository/my_snapshot?wait_for_completion=true

PUT /_snapshot/my_repository/snapshot_2?wait_for_completion=true
----
// TESTSETUP
////

[source,console]
----
GET /_snapshot/my_repository/my_snapshot
----

[[get-snapshot-api-request]]
==== {api-request-title}

`GET /_snapshot/<repository>/<snapshot>`

[[get-snapshot-api-desc]]
==== {api-description-title}

Use the get snapshot API to return information about one or more snapshots, including:

* Value start and end time
* Version of {es} that created the snapshot
* List of included indices
* Current state of the snapshot
* List of failures that occurred during the snapshot

[[get-snapshot-api-path-params]]
==== {api-path-parms-title}

`<repository>`::
(Required, string)
Comma-separated list of snapshot repository names used to limit the request.
Wildcard (`*`) expressions are supported.
+
To get information about all snapshot repositories registered in the
cluster, omit this parameter or use `*` or `_all`.

`<snapshot>`::
(Required, string)
Comma-separated list of snapshot names to retrieve. Also accepts wildcards (`*`).
+
* To get information about all snapshots in a registered repository, use a wildcard (`*`) or `_all`.
* To get information about any snapshots that are currently running, use `_current`.
+
NOTE: Using `_all` in a request fails if any snapshots are unavailable.
Set <<get-snapshot-api-ignore-unavailable,`ignore_unavailable`>> to `true` to return only available snapshots.

[role="child_attributes"]
[[get-snapshot-api-request-body]]
==== {api-request-body-title}

[[get-snapshot-api-ignore-unavailable]]
`ignore_unavailable`::
(Optional, boolean)
If `false`, the request returns an error for any snapshots that are unavailable. Defaults to `false`.
+
If `true`, the request ignores snapshots that are unavailable, such as those that are corrupted or temporarily cannot be returned.

`verbose`::
(Optional, boolean)
If `true`, returns all available information about a snapshot. Defaults to `true`.
+
If `false`, omits additional information about the snapshot, such as version information, start and end times, and the number of snapshotted shards.

[role="child_attributes"]
[[get-snapshot-api-response-body]]
==== {api-response-body-title}

`snapshot`::
lockewritesdocs marked this conversation as resolved.
Show resolved Hide resolved
(string)
Name of the snapshot.

`uuid`::
(string)
Universally unique identifier (UUID) of the snapshot.

`version_id`::
(int)
Build ID of the {es} version used to create the snapshot.

`version`::
(float)
{es} version used to create the snapshot.

`indices`::
(array)
List of indices included in the snapshot.

`data_streams`::
(array)
List of <<data-streams,data streams>> included in the snapshot.

`include_global_state`::
(boolean)
Indicates whether the current cluster state is included in the snapshot.

lockewritesdocs marked this conversation as resolved.
Show resolved Hide resolved
`start_time`::
(string)
Date timestamp of when the snapshot creation process started.

`start_time_in_millis`::
(long)
The time, in milliseconds, when the snapshot creation process started.

`end_time`::
(string)
Date timestamp of when the snapshot creation process ended.

`end_time_in_millis`::
(long)
The time, in milliseconds, when the snapshot creation process ended.

`duration_in_millis`::
(long)
How long, in milliseconds, it took to create the snapshot.

[[get-snapshot-api-response-failures]]
`failures`::
(array)
Lists any failures that occurred when creating the snapshot.

`shards`::
(object)
Contains a count of shards in the snapshot.
+
.Properties of `shards`
[%collapsible%open]
====
`total`::
(integer)
Total number of shards included in the snapshot.

`successful`::
(integer)
Number of shards that were successfully included in the snapshot.

`failed`::
(integer)
Number of shards that failed to be included in the snapshot.
====

`state`::
+
--
(string)
The snapshot `state` can be one of the following values:

.Values for `state`
[%collapsible%open]
====
`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 was not stored successfully.
The <<get-snapshot-api-response-failures,`failures`>> section of the response contains more detailed information about shards
that were not processed correctly.
====
--

[[get-snapshot-api-example]]
==== {api-examples-title}

The following request returns information for `snapshot_2` in the `my_repository` repository.

[source,console]
----
GET /_snapshot/my_repository/snapshot_2
----

The API returns the following response:

[source,console-result]
----
{
"responses": [
{
"repository": "my_repository",
"snapshots": [
{
"snapshot": "snapshot_2",
"uuid": "vdRctLCxSketdKb54xw67g",
"version_id": <version_id>,
"version": <version>,
"indices": [],
"data_streams": [],
"include_global_state": true,
"state": "SUCCESS",
"start_time": "2020-07-06T21:55:18.129Z",
"start_time_in_millis": 1593093628850,
"end_time": "2020-07-06T21:55:18.129Z",
"end_time_in_millis": 1593094752018,
"duration_in_millis": 0,
"failures": [],
"shards": {
"total": 0,
"failed": 0,
"successful": 0
}
}
]
}
]
}
----
// TESTRESPONSE[s/"uuid": "vdRctLCxSketdKb54xw67g"/"uuid": $body.responses.0.snapshots.0.uuid/]
// TESTRESPONSE[s/"version_id": <version_id>/"version_id": $body.responses.0.snapshots.0.version_id/]
// TESTRESPONSE[s/"version": <version>/"version": $body.responses.0.snapshots.0.version/]
// TESTRESPONSE[s/"start_time": "2020-07-06T21:55:18.129Z"/"start_time": $body.responses.0.snapshots.0.start_time/]
// TESTRESPONSE[s/"start_time_in_millis": 1593093628850/"start_time_in_millis": $body.responses.0.snapshots.0.start_time_in_millis/]
// TESTRESPONSE[s/"end_time": "2020-07-06T21:55:18.129Z"/"end_time": $body.responses.0.snapshots.0.end_time/]
// TESTRESPONSE[s/"end_time_in_millis": 1593094752018/"end_time_in_millis": $body.responses.0.snapshots.0.end_time_in_millis/]
// TESTRESPONSE[s/"duration_in_millis": 0/"duration_in_millis": $body.responses.0.snapshots.0.duration_in_millis/]
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,7 @@ content may not be included yet.
[[snapshot-management-apis]]
=== Snapshot management APIs
* <<create-snapshot-api,Create snapshot>>
* <<get-snapshot-api,Get snapshot>>
* <<delete-snapshot-api,Delete snapshot>>

include::put-repo-api.asciidoc[]
Expand All @@ -33,4 +34,5 @@ include::get-repo-api.asciidoc[]
include::delete-repo-api.asciidoc[]
include::clean-up-repo-api.asciidoc[]
include::create-snapshot-api.asciidoc[]
include::get-snapshot-api.asciidoc[]
include::delete-snapshot-api.asciidoc[]
14 changes: 4 additions & 10 deletions docs/reference/snapshot-restore/take-snapshot.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -112,30 +112,24 @@ snapshot and the list of failures that occurred during the snapshot. The snapsho

[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
The global cluster state was stored, but data of at least one shard was not stored successfully.
The `failures` section of the response contains 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 snapshot was created with an old version of {es} and 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:
Similar as for repositories, information about multiple snapshots can be queried in a single request, supporting wildcards as well:

[source,console]
-----------------------------------
Expand Down