IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.

« cat plugins API cat repositories API »

› › ›

cat recovery API

edit

cat recovery API

edit

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

Request

edit

GET /_cat/recovery/<index>

GET /_cat/recovery

Description

edit

The 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 to false.
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 to false.
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 to false.
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 to false.

Examples

edit

Example with no ongoing recoveries

edit

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 recovery

edit

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 recovery

edit

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%

« cat plugins API cat repositories API »