Imported Upstream version 1.0.3upstream/1.0.3

1 files changed, 90 insertions, 0 deletions

diff --git a/docs/reference/cat/shards.asciidoc b/docs/reference/cat/shards.asciidoc
new file mode 100644
index 0000000..bb91027
--- /dev/null
+++ b/docs/reference/cat/shards.asciidoc
@@ -0,0 +1,90 @@
+[[cat-shards]]
+== 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 three primary shards and no replicas:
+
+[source,shell]
+--------------------------------------------------
+% 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]]
+=== 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,shell]
+--------------------------------------------------
+% 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]]
+=== Relocation
+
+Let's say you've checked your health and you see two relocating
+shards.  Where are they from and where are they going?
+
+[source,shell]
+--------------------------------------------------
+% 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
+--------------------------------------------------
+
+[[states]]
+=== Shard states
+
+Before a shard can be used, it goes through an `INITIALIZING` state.
+`shards` can show you which ones.
+
+[source,shell]
+--------------------------------------------------
+% 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, they will
+remain `UNASSIGNED`.
+
+[source,shell]
+--------------------------------------------------
+% 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
+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
+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
+--------------------------------------------------