New

The executive guide to generative AI

Read more
About usPartnersSupport|Login

WARNING: Version 2.2 of Elasticsearch has passed its EOL date.

This documentation is no longer being maintained and may be removed. If you are running this version, we strongly advise you to upgrade. For the latest information, see the current release documentation.

« cat thread pool cat segments »
Elastic Docs ›Elasticsearch Guide [2.2] ›cat APIs

cat shards

edit

cat shards

edit

The shards command is the detailed view of what nodes contain which shards. It will tell you if it’s a primary or replica, the number of docs, the bytes it takes on disk, and the node where it’s located.

Here we see a single index, with three primary shards and no replicas:

% curl 192.168.56.20:9200/_cat/shards
wiki1 0 p STARTED 3014 31.1mb 192.168.56.10 Stiletto
wiki1 1 p STARTED 3013 29.6mb 192.168.56.30 Frankie Raye
wiki1 2 p STARTED 3973 38.1mb 192.168.56.20 Commander Kraken

Index pattern

edit

If you have many shards, you may wish to limit which indices show up in the output. You can always do this with grep, but you can save some bandwidth by supplying an index pattern to the end.

% curl 192.168.56.20:9200/_cat/shards/wiki2
wiki2 0 p STARTED 197 3.2mb 192.168.56.10 Stiletto
wiki2 1 p STARTED 205 5.9mb 192.168.56.30 Frankie Raye
wiki2 2 p STARTED 275 7.8mb 192.168.56.20 Commander Kraken

Relocation

edit

Let’s say you’ve checked your health and you see two relocating shards. Where are they from and where are they going?

% curl 192.168.56.10:9200/_cat/health
1384315316 20:01:56 foo green 3 3 12 6 2 0 0
% curl 192.168.56.10:9200/_cat/shards | fgrep RELO
wiki1 0 r RELOCATING 3014 31.1mb 192.168.56.20 Commander Kraken -> 192.168.56.30 Frankie Raye
wiki1 1 r RELOCATING 3013 29.6mb 192.168.56.10 Stiletto -> 192.168.56.30 Frankie Raye

Shard states

edit

Before a shard can be used, it goes through an INITIALIZING state. shards can show you which ones.

% curl -XPUT 192.168.56.20:9200/_settings -d'{"number_of_replicas":1}'
{"acknowledged":true}
% curl 192.168.56.20:9200/_cat/shards
wiki1 0 p STARTED      3014 31.1mb 192.168.56.10 Stiletto
wiki1 0 r INITIALIZING    0 14.3mb 192.168.56.30 Frankie Raye
wiki1 1 p STARTED      3013 29.6mb 192.168.56.30 Frankie Raye
wiki1 1 r INITIALIZING    0 13.1mb 192.168.56.20 Commander Kraken
wiki1 2 r INITIALIZING    0   14mb 192.168.56.10 Stiletto
wiki1 2 p STARTED      3973 38.1mb 192.168.56.20 Commander Kraken

If a shard cannot be assigned, for example you’ve overallocated the number of replicas for the number of nodes in the cluster, the shard will remain UNASSIGNED with the reason code ALLOCATION_FAILED.

% curl -XPUT 192.168.56.20:9200/_settings -d'{"number_of_replicas":3}'
% curl 192.168.56.20:9200/_cat/health
1384316325 20:18:45 foo yellow 3 3 9 3 0 0 3
% curl 192.168.56.20:9200/_cat/shards
wiki1 0 p STARTED    3014 31.1mb 192.168.56.10 Stiletto
wiki1 0 r STARTED    3014 31.1mb 192.168.56.30 Frankie Raye
wiki1 0 r STARTED    3014 31.1mb 192.168.56.20 Commander Kraken
wiki1 0 r UNASSIGNED ALLOCATION_FAILED
wiki1 1 r STARTED    3013 29.6mb 192.168.56.10 Stiletto
wiki1 1 p STARTED    3013 29.6mb 192.168.56.30 Frankie Raye
wiki1 1 r STARTED    3013 29.6mb 192.168.56.20 Commander Kraken
wiki1 1 r UNASSIGNED ALLOCATION_FAILED
wiki1 2 r STARTED    3973 38.1mb 192.168.56.10 Stiletto
wiki1 2 r STARTED    3973 38.1mb 192.168.56.30 Frankie Raye
wiki1 2 p STARTED    3973 38.1mb 192.168.56.20 Commander Kraken
wiki1 2 r UNASSIGNED ALLOCATION_FAILED

Reasons for unassigned shard

edit

These are the possible reasons for a shard be in a unassigned state:

INDEX_CREATED

Unassigned as a result of an API creation of an index.

CLUSTER_RECOVERED

Unassigned as a result of a full cluster recovery.

INDEX_REOPENED

Unassigned as a result of opening a closed index.

DANGLING_INDEX_IMPORTED

Unassigned as a result of importing a dangling index.

NEW_INDEX_RESTORED

Unassigned as a result of restoring into a new index.

EXISTING_INDEX_RESTORED

Unassigned as a result of restoring into a closed index.

REPLICA_ADDED

Unassigned as a result of explicit addition of a replica.

ALLOCATION_FAILED

Unassigned as a result of a failed allocation of the shard.

NODE_LEFT

Unassigned as a result of the node hosting it leaving the cluster.

REROUTE_CANCELLED

Unassigned as a result of explicit cancel reroute command.

REINITIALIZED

When a shard moves from started back to initializing, for example, with shadow replicas.

REALLOCATED_REPLICA

A better replica location is identified and causes the existing replica allocation to be cancelled.

« cat thread pool cat segments »

On this page

Was this helpful?
Feedback