OpenSearch/docs/reference/indices/recovery.asciidoc

[[indices-recovery]]
=== Index recovery API
++++
<titleabbrev>Index recovery</titleabbrev>
++++


Returns 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.

[source,console]
----
GET /twitter/_recovery
----
// TEST[setup:twitter]


[[index-recovery-api-request]]
==== {api-request-title}

`GET /<target>/_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::{es-repo-dir}/glossary.asciidoc[tag=recovery-triggers]

// end::shard-recovery-desc[]

[[index-recovery-api-path-params]]
==== {api-path-parms-title}

`<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 `*`.


[[index-recovery-api-query-params]]
==== {api-query-parms-title}

include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=active-only]

include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=detailed]

include::{es-repo-dir}/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 <<snapshots-restore-snapshot,snapshot restoration>>.

`REPLICA`::
The recovery is related to
a <<glossary-replica-shard,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.


[[index-recovery-api-example]]
==== {api-examples-title}


[[index-recovery-api-multi-ex]]
===== Get recovery information for several data streams and 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 data streams and indices in a cluster

//////////////////////////
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`.