Type to search.

Explain the shard allocations

  • POST also GET /_cluster/allocation/explain
Auth The Elastic Stack includes Elastic's core products such as Elasticsearch, Kibana, Logstash, and Beats. Availability Generally available since 5.0 This functionality is generally available and ready for production usage. Unless stated otherwise on the page, this functionality is available when your Elastic Stack is deployed on Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed environments. This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes.

Get explanations for shard allocations in the cluster. For unassigned shards, it provides an explanation for why the shard is unassigned. For assigned shards, it provides an explanation for why the shard is remaining on its current node 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.

Query parameters

include_disk_info boolean · default: false

If true, returns information about disk usage and shard sizes.

include_yes_decisions boolean · default: false

If true, returns YES decisions in explanation.

master_timeout union oneOf · default: 30s

Period to wait for a connection to the master node.

Values: -1 0

Request body

current_node string

Specifies the node ID or the name of the node to only explain a shard that is currently located on the specified node.

index string

Specifies the name of the index that you would like an explanation for.

primary boolean

If true, returns explanation for the primary shard for the given shard ID.

shard number

Specifies the ID of the shard that you would like an explanation for.

Response

application/json
allocate_explanation string
allocation_delay union oneOf
Values: -1 0
allocation_delay_in_millis number
can_allocate enum
Values: yes no worse_balance throttled awaiting_info allocation_delayed no_valid_shard_copy no_attempt
can_move_to_other_node enum
Values: yes no worse_balance throttled awaiting_info allocation_delayed no_valid_shard_copy no_attempt
can_rebalance_cluster enum
Values: yes no worse_balance throttled awaiting_info allocation_delayed no_valid_shard_copy no_attempt
can_rebalance_to_other_node enum
Values: yes no worse_balance throttled awaiting_info allocation_delayed no_valid_shard_copy no_attempt
can_remain_on_current_node enum
Values: yes no worse_balance throttled awaiting_info allocation_delayed no_valid_shard_copy no_attempt
configured_delay union oneOf
Values: -1 0
configured_delay_in_millis number
current_state string required
index string required
move_explanation string
primary boolean required
rebalance_explanation string
remaining_delay union oneOf
Values: -1 0
remaining_delay_in_millis number
shard number required
note string The Elastic Stack includes Elastic's core products such as Elasticsearch, Kibana, Logstash, and Beats. Availability Generally available since 7.14 This functionality is generally available and ready for production usage. Unless stated otherwise on the page, this functionality is available when your Elastic Stack is deployed on Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed environments. This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes.