cat recovery APIedit

Returns information about ongoing and completed index shard recoveries, similar to the indices recovery API.

Requestedit

GET /_cat/recovery/<index>

Descriptionedit

The cat recovery API returns information about index shard recoveries, both ongoing and completed. It is a more compact view of the JSON indices recovery API.

A recovery event occurs anytime an index shard moves to a different node in the cluster. This can happen during a snapshot recovery, a change in replication level, node failure, or on node startup. This last type is called a local store recovery and is the normal way for shards to be loaded from disk when a node starts up.

Path parametersedit

<index>
(Optional, string) Comma-separated list or wildcard expression of index names used to limit the request.

Query parametersedit

bytes
(Optional, byte size units) Unit used to display byte values.
format
(Optional, string) Short version of the HTTP accept header. Valid values include JSON, YAML, etc.
h
(Optional, string) Comma-separated list of column names to display.
help
(Optional, boolean) If true, the response returns help information. Defaults to false.
local
(Optional, boolean) If true, the request retrieves information from the local node only. Defaults to false, which means information is retrieved from the master node.
master_timeout
(Optional, time units) Specifies the period of time 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. Defaults to 30s.
s
(Optional, string) Comma-separated list of column names or column aliases used to sort the response.
v
(Optional, boolean) If true, the response includes column headings. Defaults to false.

Examplesedit

Example with no ongoing recoveriesedit

GET _cat/recovery?v

The API returns the following response:

index   shard time type  stage source_host source_node target_host target_node repository snapshot files files_recovered files_percent files_total bytes bytes_recovered bytes_percent bytes_total translog_ops translog_ops_recovered translog_ops_percent
twitter 0     13ms store done  n/a         n/a         127.0.0.1   node-0      n/a        n/a      0     0               100%          13          0     0               100%          9928        0            0                      100.0%

In this example response, the source and target nodes are the same because the recovery type is store, meaning they were read from local storage on node start.

Example with a live shard recoveryedit

By increasing the replica count of an index and bringing another node online to host the replicas, you can retrieve information about an ongoing recovery.

GET _cat/recovery?v&h=i,s,t,ty,st,shost,thost,f,fp,b,bp

The API returns the following response:

i       s t      ty   st    shost       thost       f     fp      b bp
twitter 0 1252ms peer done  192.168.1.1 192.168.1.2 0     100.0%  0 100.0%

In this example response, the recovery type is peer, meaning the shard recovered from another node. The returned files and bytes are real-time measurements.

Example with a snapshot recoveryedit

You can restore backups of an index using the snapshot and restore API. You can use the cat recovery API retrieve information about a snapshot recovery.

GET _cat/recovery?v&h=i,s,t,ty,st,rep,snap,f,fp,b,bp

The API returns the following response with a recovery type of snapshot:

i       s t      ty       st    rep     snap   f  fp   b     bp
twitter 0 1978ms snapshot done  twitter snap_1 79 8.0% 12086 9.0%