[[indices-recovery]] === Index recovery API ++++ Index recovery ++++ Returns information about ongoing and completed shard recoveries. [source,console] ---- GET /twitter/_recovery ---- // TEST[setup:twitter] [[index-recovery-api-request]] ==== {api-request-title} `GET //_recovery` `GET /_recovery` [[index-recovery-api-desc]] ==== {api-description-title} Use the index recovery API to get information about ongoing and completed shard recoveries. // tag::shard-recovery-desc[] Shard recovery is the process of syncing a replica shard from a primary shard. Upon completion, the replica shard is available for search. include::{docdir}/glossary.asciidoc[tag=recovery-triggers] // end::shard-recovery-desc[] [[index-recovery-api-path-params]] ==== {api-path-parms-title} include::{docdir}/rest-api/common-parms.asciidoc[tag=index] + Use a value of `_all` to retrieve information for all indices in the cluster. [[index-recovery-api-query-params]] ==== {api-query-parms-title} include::{docdir}/rest-api/common-parms.asciidoc[tag=active-only] include::{docdir}/rest-api/common-parms.asciidoc[tag=detailed] include::{docdir}/rest-api/common-parms.asciidoc[tag=index-query-parm] [[index-recovery-api-response-body]] ==== {api-response-body-title} `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 <>. `REPLICA`:: The recovery is related to a <>. `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. [[index-recovery-api-example]] ==== {api-examples-title} [[index-recovery-api-multi-ex]] ===== Get recovery information for several indices [source,console] -------------------------------------------------- GET index1,index2/_recovery?human -------------------------------------------------- // TEST[s/^/PUT index1\nPUT index2\n/] [[index-recovery-api-all-ex]] ===== Get segment information for all indices ////////////////////////// Here we create a repository and snapshot index1 in order to restore it right after and prints out the index recovery result. [source,console] -------------------------------------------------- # create the index PUT index1 {"settings": {"index.number_of_shards": 1}} # create the repository PUT /_snapshot/my_repository {"type": "fs","settings": {"location": "recovery_asciidoc" }} # snapshot the index PUT /_snapshot/my_repository/snap_1?wait_for_completion=true {"indices": "index1"} # delete the index DELETE index1 # and restore the snapshot POST /_snapshot/my_repository/snap_1/_restore?wait_for_completion=true -------------------------------------------------- [source,console-result] -------------------------------------------------- { "snapshot": { "snapshot": "snap_1", "indices": [ "index1" ], "shards": { "total": 1, "failed": 0, "successful": 1 } } } -------------------------------------------------- ////////////////////////// [source,console] -------------------------------------------------- GET /_recovery?human -------------------------------------------------- // TEST[continued] The API returns the following response: [source,console-result] -------------------------------------------------- { "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 } } ] } } -------------------------------------------------- // TESTRESPONSE[s/: (\-)?[0-9]+/: $body.$_path/] // TESTRESPONSE[s/: "[^"]*"/: $body.$_path/] //// The TESTRESPONSE above replace all the fields values by the expected ones in the test, because we don't really care about the field values but we want to check the fields names. //// 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. [[index-recovery-api-detailed-ex]] ===== Get detailed recovery information To get a list of physical files in recovery, set the `detailed` query parameter to `true`. [source,console] -------------------------------------------------- GET _recovery?human&detailed=true -------------------------------------------------- // TEST[s/^/PUT index1\n{"settings": {"index.number_of_shards": 1}}\n/] The API returns the following response: [source,console-result] -------------------------------------------------- { "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 } } ] } } -------------------------------------------------- // TESTRESPONSE[s/"source" : \{[^}]*\}/"source" : $body.$_path/] // TESTRESPONSE[s/"details" : \[[^\]]*\]/"details" : $body.$_path/] // TESTRESPONSE[s/: (\-)?[0-9]+/: $body.$_path/] // TESTRESPONSE[s/: "[^"]*"/: $body.$_path/] //// The TESTRESPONSE above replace all the fields values by the expected ones in the test, because we don't really care about the field values but we want to check the fields names. It also removes the "details" part which is important in this doc but really hard to test. //// 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`.