Index recovery API
editIndex recovery API
editReturns information about ongoing and completed shard recoveries for one or more indices. For data streams, the API returns information for the stream’s backing indices.
GET /my-index-000001/_recovery
Description
editUse the index recovery API to get information about ongoing and completed shard recoveries.
Shard recovery is the process of syncing a replica shard from a primary shard. Upon completion, the replica shard is available for search.
Recovery automatically occurs during the following processes:
- Node startup or failure. This type of recovery is called a local store recovery.
- Primary shard replication.
- Relocation of a shard to a different node in the same cluster.
- Snapshot restoration.
Path parameters
edit-
<target>
-
(Optional, string) Comma-separated list of data streams, indices, and index aliases used to limit the request. Wildcard expressions (
*
) are supported.To target all data streams and indices in a cluster, omit this parameter or use
_all
or*
.
Query parameters
edit-
active_only
-
(Optional, Boolean)
If
true
, the response only includes ongoing shard recoveries. Defaults tofalse
. -
detailed
-
(Optional, Boolean)
If
true
, the response includes detailed information about shard recoveries. Defaults tofalse
. -
index
- (Optional, string) Comma-separated list or wildcard expression of index names used to limit the request.
Response body
edit-
id
- (Integer) ID of the shard.
-
type
-
(String) Recovery type. Returned values include:
-
STORE
- The recovery is related to a node startup or failure. This type of recovery is called a local store recovery.
-
SNAPSHOT
- The recovery is related to a snapshot restoration.
-
REPLICA
- The recovery is related to a primary shard replication.
-
RELOCATING
- The recovery is related to the relocation of a shard to a different node in the same cluster.
-
-
STAGE
-
(String) Recovery stage. Returned values include:
-
DONE
- Complete.
-
FINALIZE
- Cleanup.
-
INDEX
- Reading index metadata and copying bytes from source to destination.
-
INIT
- Recovery has not started.
-
START
- Starting the recovery process; opening the index for use.
-
TRANSLOG
- Replaying transaction log .
-
-
primary
-
(Boolean)
If
true
, the shard is a primary shard. -
start_time
- (String) Timestamp of recovery start.
-
stop_time
- (String) Timestamp of recovery finish.
-
total_time_in_millis
- (String) Total time to recover shard in milliseconds.
-
source
-
(Object) Recovery source. This can include:
- A repository description if recovery is from a snapshot
- A description of source node
-
target
- (Object) Destination node.
-
index
- (Object) Statistics about physical index recovery.
-
translog
- (Object) Statistics about translog recovery.
-
start
- (Object) Statistics about time to open and start the index.
Examples
editGet recovery information for several data streams and indices
editGET index1,index2/_recovery?human
Get segment information for all data streams and indices in a cluster
editGET /_recovery?human
The API returns the following response:
{ "index1" : { "shards" : [ { "id" : 0, "type" : "SNAPSHOT", "stage" : "INDEX", "primary" : true, "start_time" : "2014-02-24T12:15:59.716", "start_time_in_millis": 1393244159716, "stop_time" : "0s", "stop_time_in_millis" : 0, "total_time" : "2.9m", "total_time_in_millis" : 175576, "source" : { "repository" : "my_repository", "snapshot" : "my_snapshot", "index" : "index1", "version" : "{version}", "restoreUUID": "PDh1ZAOaRbiGIVtCvZOMww" }, "target" : { "id" : "ryqJ5lO5S4-lSFbGntkEkg", "host" : "my.fqdn", "transport_address" : "my.fqdn", "ip" : "10.0.1.7", "name" : "my_es_node" }, "index" : { "size" : { "total" : "75.4mb", "total_in_bytes" : 79063092, "reused" : "0b", "reused_in_bytes" : 0, "recovered" : "65.7mb", "recovered_in_bytes" : 68891939, "percent" : "87.1%" }, "files" : { "total" : 73, "reused" : 0, "recovered" : 69, "percent" : "94.5%" }, "total_time" : "0s", "total_time_in_millis" : 0, "source_throttle_time" : "0s", "source_throttle_time_in_millis" : 0, "target_throttle_time" : "0s", "target_throttle_time_in_millis" : 0 }, "translog" : { "recovered" : 0, "total" : 0, "percent" : "100.0%", "total_on_start" : 0, "total_time" : "0s", "total_time_in_millis" : 0, }, "verify_index" : { "check_index_time" : "0s", "check_index_time_in_millis" : 0, "total_time" : "0s", "total_time_in_millis" : 0 } } ] } }
This response includes information
about a single index recovering a single shard.
The source of the recovery is a snapshot repository
and the target of the recovery is the my_es_node
node.
The response also includes the number and percentage of files and bytes recovered.
Get detailed recovery information
editTo get a list of physical files in recovery,
set the detailed
query parameter to true
.
GET _recovery?human&detailed=true
The API returns the following response:
{ "index1" : { "shards" : [ { "id" : 0, "type" : "STORE", "stage" : "DONE", "primary" : true, "start_time" : "2014-02-24T12:38:06.349", "start_time_in_millis" : "1393245486349", "stop_time" : "2014-02-24T12:38:08.464", "stop_time_in_millis" : "1393245488464", "total_time" : "2.1s", "total_time_in_millis" : 2115, "source" : { "id" : "RGMdRc-yQWWKIBM4DGvwqQ", "host" : "my.fqdn", "transport_address" : "my.fqdn", "ip" : "10.0.1.7", "name" : "my_es_node" }, "target" : { "id" : "RGMdRc-yQWWKIBM4DGvwqQ", "host" : "my.fqdn", "transport_address" : "my.fqdn", "ip" : "10.0.1.7", "name" : "my_es_node" }, "index" : { "size" : { "total" : "24.7mb", "total_in_bytes" : 26001617, "reused" : "24.7mb", "reused_in_bytes" : 26001617, "recovered" : "0b", "recovered_in_bytes" : 0, "percent" : "100.0%" }, "files" : { "total" : 26, "reused" : 26, "recovered" : 0, "percent" : "100.0%", "details" : [ { "name" : "segments.gen", "length" : 20, "recovered" : 20 }, { "name" : "_0.cfs", "length" : 135306, "recovered" : 135306 }, { "name" : "segments_2", "length" : 251, "recovered" : 251 } ] }, "total_time" : "2ms", "total_time_in_millis" : 2, "source_throttle_time" : "0s", "source_throttle_time_in_millis" : 0, "target_throttle_time" : "0s", "target_throttle_time_in_millis" : 0 }, "translog" : { "recovered" : 71, "total" : 0, "percent" : "100.0%", "total_on_start" : 0, "total_time" : "2.0s", "total_time_in_millis" : 2025 }, "verify_index" : { "check_index_time" : 0, "check_index_time_in_millis" : 0, "total_time" : "88ms", "total_time_in_millis" : 88 } } ] } }
The response includes a listing of any physical files recovered and their sizes.
The response also includes timings in milliseconds of the various stages of recovery:
- Index retrieval
- Translog replay
- Index start time
This response indicates the recovery is done
.
All recoveries,
whether ongoing or complete,
are kept in the cluster state
and may be reported on at any time.
To only return information about ongoing recoveries,
set the active_only
query parameter to true
.