OpenSearch/docs/reference/cat/shards.asciidoc

[[cat-shards]]
== cat shards

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 one primary shard and no replicas:

[source,js]
---------------------------------------------------------------------------
GET _cat/shards
---------------------------------------------------------------------------
// CONSOLE
// TEST[setup:twitter]

This will return

[source,js]
---------------------------------------------------------------------------
twitter 0 p STARTED 3014 31.1mb 192.168.56.10 H5dfFeA
---------------------------------------------------------------------------
// TESTRESPONSE[s/3014/\\d+/]
// TESTRESPONSE[s/31.1mb/\\d+(\.\\d+)?[kmg]?b/]
// TESTRESPONSE[s/192.168.56.10/.*/]
// TESTRESPONSE[s/H5dfFeA/node-0/ _cat]

[float]
[[index-pattern]]
=== Index pattern

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.

[source,js]
---------------------------------------------------------------------------
GET _cat/shards/twitt*
---------------------------------------------------------------------------
// CONSOLE
// TEST[setup:twitter]

Which will return the following

[source,js]
---------------------------------------------------------------------------
twitter 0 p STARTED 3014 31.1mb 192.168.56.10 H5dfFeA
---------------------------------------------------------------------------
// TESTRESPONSE[s/3014/\\d+/]
// TESTRESPONSE[s/31.1mb/\\d+(\.\\d+)?[kmg]?b/]
// TESTRESPONSE[s/192.168.56.10/.*/]
// TESTRESPONSE[s/H5dfFeA/node-0/ _cat]


[float]
[[relocation]]
=== Relocation

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

[source,js]
---------------------------------------------------------------------------
GET _cat/shards
---------------------------------------------------------------------------
// CONSOLE
// TEST[skip:for now, relocation cannot be recreated]

A relocating shard will be shown as follows

[source,js]
---------------------------------------------------------------------------
twitter 0 p RELOCATING 3014 31.1mb 192.168.56.10 H5dfFeA -> -> 192.168.56.30 bGG90GE
---------------------------------------------------------------------------
// TESTRESPONSE[_cat]

[float]
[[states]]
=== Shard states

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

[source,js]
---------------------------------------------------------------------------
GET _cat/shards
---------------------------------------------------------------------------
// CONSOLE
// TEST[skip:there is no guarantee to test for shards in initializing state]

You can the the initializing state in the response like this

[source,js]
---------------------------------------------------------------------------
twitter 0 p STARTED      3014 31.1mb 192.168.56.10 H5dfFeA
twitter 0 r INITIALIZING    0 14.3mb 192.168.56.30 bGG90GE
---------------------------------------------------------------------------
// TESTRESPONSE[_cat]

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-unassigned,reason code>> `ALLOCATION_FAILED`.

You can use the shards API to find out that reason.

[source,js]
---------------------------------------------------------------------------
GET _cat/shards?h=index,shard,prirep,state,unassigned.reason
---------------------------------------------------------------------------
// CONSOLE
// TEST[skip:for now]

The reason for an unassigned shard will be listed as the last field

[source,js]
---------------------------------------------------------------------------
twitter 0 p STARTED    3014 31.1mb 192.168.56.10 H5dfFeA
twitter 0 r STARTED    3014 31.1mb 192.168.56.30 bGG90GE
twitter 0 r STARTED    3014 31.1mb 192.168.56.20 I8hydUG
twitter 0 r UNASSIGNED ALLOCATION_FAILED
---------------------------------------------------------------------------
// TESTRESPONSE[_cat]

[float]
[[reason-unassigned]]
=== Reasons for unassigned shard

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

[horizontal]
`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.