cat recovery API
editcat recovery API
editReturns information about ongoing and completed shard recoveries, similar to the index recovery API.
Description
editThe cat recovery API returns information about shard recoveries, both ongoing and completed. It is a more compact view of the JSON index recovery API.
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-
<index>
- (Optional, string) Comma-separated list or wildcard expression of index names used to limit the request.
Query parameters
edit-
active_only
-
(Optional, boolean)
If
true
, the response only includes ongoing shard recoveries. Defaults tofalse
. -
bytes
- (Optional, byte size units) Unit used to display byte values.
-
detailed
-
(Optional, boolean)
If
true
, the response includes detailed information about shard recoveries. Defaults tofalse
. -
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 includes help information. Defaults tofalse
. -
index
- (Optional, string) Comma-separated list or wildcard expression of index names used to limit the request.
-
s
- (Optional, string) Comma-separated list of column names or column aliases used to sort the response.
-
time
- (Optional, time units) Unit used to display time values.
-
v
-
(Optional, boolean) If
true
, the response includes column headings. Defaults tofalse
.
Examples
editExample with no ongoing recoveries
editGET _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 recovery
editBy 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 recovery
editYou 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%