IMPORTANT: No additional bug fixes or documentation updates
will be released for this version. For the latest information, see the
current release documentation.
cat allocation API
editcat allocation API
editcat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications.
Provides a snapshot of the number of shards allocated to each data node and their disk space.
Prerequisites
edit-
If the Elasticsearch security features are enabled, you must have the
monitor
ormanage
cluster privilege to use this API.
Path parameters
edit-
<node_id>
- (Optional, string) Comma-separated list of node IDs or names used to limit returned information.
Query parameters
edit-
bytes
- (Optional, byte size units) Unit used to display byte values.
-
format
- (Optional, string) Short version of the HTTP accept header. Valid values include JSON, YAML, etc.
-
local
-
(Optional, Boolean) If
true
, the request retrieves information from the local node only. Defaults tofalse
, which means information is retrieved from the master node. -
master_timeout
-
(Optional, time units)
Period to wait for a connection to the master node. If no response is received
before the timeout expires, the request fails and returns an error. Defaults to
30s
. -
h
- (Optional, string) Comma-separated list of column names to display.
-
help
-
(Optional, Boolean) If
true
, the response includes help information. Defaults tofalse
. -
s
- (Optional, string) Comma-separated list of column names or column aliases used to sort the response.
-
v
-
(Optional, Boolean) If
true
, the response includes column headings. Defaults tofalse
.
Response body
edit-
shards
- Number of primary and replica shards assigned to the node.
-
disk.indices
-
Disk space used by the node’s shards. Does not include disk space for the translog or unassigned shards.
-
disk.used
-
Total disk space in use. Elasticsearch retrieves this metric from the node’s operating system (OS). The metric includes disk space for:
- Elasticsearch, including the translog and unassigned shards
- The node’s OS
- Any other applications or files on the node
Unlike
disk.indices
, this metric does not double-count disk space for hard-linked files. -
disk.avail
- Free disk space available to Elasticsearch. Elasticsearch retrieves this metric from the node’s OS. Disk-based shard allocation uses this metric to assign shards to nodes based on available disk space.
-
disk.total
- Total disk space for the node, including in-use and available space.
-
disk.percent
-
Total percentage of disk space in use. Calculated as
disk.used
/disk.total
. -
host
-
Network host for the node. Set using
network.host
. -
ip
- IP address and port for the node.
-
node
-
Name for the node. Set using
node.name
.
Examples
editresponse = client.cat.allocation( v: true ) puts response
GET /_cat/allocation?v=true
The API returns the following response:
shards disk.indices disk.used disk.avail disk.total disk.percent host ip node 1 260b 47.3gb 43.4gb 100.7gb 46 127.0.0.1 127.0.0.1 CSUXak2
This response shows a single shard is allocated to the one node available.