<commit_before>[[cluster-allocation-explain]]
== Cluster Allocation Explain API

The purpose of the cluster allocation explain API is to provide
explanations for shard allocations in the cluster.  For unassigned shards,
the explain API provides an explanation for why the shard is unassigned.
For assigned shards, the explain API provides an explanation for why the
shard is remaining on its current moved and has not moved or rebalanced to
another node.  This API can be very useful when attempting to diagnose why
a shard is unassigned or why a shard continues to remain on its current node
when you might expect otherwise.

=== Explain API Request

To explain the allocation of a shard, issue a request:

[source,js]
--------------------------------------------------
$ curl -XGET 'http://localhost:9200/_cluster/allocation/explain' -d '{
  "index": "myindex",
  "shard": 0,
  "primary": true
}'
--------------------------------------------------

Specify the `index` and `shard` id of the shard you would like an explanation
for, as well as the `primary` flag to indicate whether to explain the primary
shard for the given shard id or one of its replica shards.  These three request
parameters are required.

You may also specify an optional `current_node` request parameter to only explain
a shard that is currently located on `current_node`.  The `current_node` can be
specified as either the node id or node name.

[source,js]
--------------------------------------------------
$ curl -XGET 'http://localhost:9200/_cluster/allocation/explain' -d '{
  "index": "myindex",
  "shard": 0,
  "primary": false,
  "current_node": "nodeA"                         <1>
}'
--------------------------------------------------
<1> The node where shard 0 currently has a replica on

You can also have Elasticsearch explain the allocation of the first unassigned
shard that it finds by sending an empty body for the request:

[source,js]
--------------------------------------------------
$ curl -XGET 'http://localhost:9200/_cluster/allocation/explain'
--------------------------------------------------

=== Explain API Response

This section includes examples of the cluster allocation explain API response output
under various scenarios.

The API response for an unassigned shard:

[source,js]
--------------------------------------------------
{
  "index" : "idx",
  "shard" : 0,
  "primary" : true,
  "current_state" : "unassigned",                 <1>
  "unassigned_info" : {
    "reason" : "INDEX_CREATED",                   <2>
    "at" : "2017-01-04T18:08:16.600Z",
    "last_allocation_status" : "no"
  },
  "can_allocate" : "no",                          <3>
  "allocate_explanation" : "cannot allocate because allocation is not permitted to any of the nodes",
  "node_allocation_decisions" : [
    {
      "node_id" : "8qt2rY-pT6KNZB3-hGfLnw",
      "node_name" : "node_t1",
      "transport_address" : "127.0.0.1:9401",
      "node_decision" : "no",                     <4>
      "weight_ranking" : 1,<commit_msg>Docs: Cluster allocation explain should be on one page<commit_after>[[cluster-allocation-explain]]
== Cluster Allocation Explain API

The purpose of the cluster allocation explain API is to provide
explanations for shard allocations in the cluster.  For unassigned shards,
the explain API provides an explanation for why the shard is unassigned.
For assigned shards, the explain API provides an explanation for why the
shard is remaining on its current moved and has not moved or rebalanced to
another node.  This API can be very useful when attempting to diagnose why
a shard is unassigned or why a shard continues to remain on its current node
when you might expect otherwise.

[float]
=== Explain API Request

To explain the allocation of a shard, issue a request:

[source,js]
--------------------------------------------------
$ curl -XGET 'http://localhost:9200/_cluster/allocation/explain' -d '{
  "index": "myindex",
  "shard": 0,
  "primary": true
}'
--------------------------------------------------

Specify the `index` and `shard` id of the shard you would like an explanation
for, as well as the `primary` flag to indicate whether to explain the primary
shard for the given shard id or one of its replica shards.  These three request
parameters are required.

You may also specify an optional `current_node` request parameter to only explain
a shard that is currently located on `current_node`.  The `current_node` can be
specified as either the node id or node name.

[source,js]
--------------------------------------------------
$ curl -XGET 'http://localhost:9200/_cluster/allocation/explain' -d '{
  "index": "myindex",
  "shard": 0,
  "primary": false,
  "current_node": "nodeA"                         <1>
}'
--------------------------------------------------
<1> The node where shard 0 currently has a replica on

You can also have Elasticsearch explain the allocation of the first unassigned
shard that it finds by sending an empty body for the request:

[source,js]
--------------------------------------------------
$ curl -XGET 'http://localhost:9200/_cluster/allocation/explain'
--------------------------------------------------

[float]
=== Explain API Response

This section includes examples of the cluster allocation explain API response output
under various scenarios.

The API response for an unassigned shard:

[source,js]
--------------------------------------------------
{
  "index" : "idx",
  "shard" : 0,
  "primary" : true,
  "current_state" : "unassigned",                 <1>
  "unassigned_info" : {
    "reason" : "INDEX_CREATED",                   <2>
    "at" : "2017-01-04T18:08:16.600Z",
    "last_allocation_status" : "no"
  },
  "can_allocate" : "no",                          <3>
  "allocate_explanation" : "cannot allocate because allocation is not permitted to any of the nodes",
  "node_allocation_decisions" : [
    {
      "node_id" : "8qt2rY-pT6KNZB3-hGfLnw",
      "node_name" : "node_t1",
      "transport_address" : "127.0.0.1:9401",
      "node_decision" : "no",                     <4>
      "weight_ranking" : 1,
{'fraction_non_alphanumeric': 0.19579845724602002, 'fraction_numerical': 0.018053504021007714, 'mean_word_length': 2.1955951756685894, 'pattern_counts': {'":': 14, '<': 15, '<?xml version=': 0, '>': 15, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 2, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4326630', 'n_tokens_mistral': 1730, 'n_tokens_neox': 1646, 'n_words': 659}