Cluster APIs

Node specification

Some cluster-level APIs may operate on a subset of the nodes which can be specified with node filters. For example, the Task Management, Nodes Stats, and Nodes Info APIs can all report results from a filtered set of nodes rather than from all nodes.

Node filters are written as a comma-separated list of individual filters, each of which adds or removes nodes from the chosen subset. Each filter can be one of the following:

  • _all, to add all nodes to the subset.
  • _local, to add the local node to the subset.
  • _master, to add the currently-elected master node to the subset.
  • a node id or name, to add this node to the subset.
  • an IP address or hostname, to add all matching nodes to the subset.
  • a pattern, using * wildcards, which adds all nodes to the subset whose name, address or hostname matches the pattern.
  • master:true, data:true, ingest:true, voting_only:true, ml:true, or coordinating_only:true, which respectively add to the subset all master-eligible nodes, all data nodes, all ingest nodes, all voting-only nodes, all machine learning nodes, and all coordinating-only nodes.
  • master:false, data:false, ingest:false, voting_only:true, ml:false, or coordinating_only:false, which respectively remove from the subset all master-eligible nodes, all data nodes, all ingest nodes, all voting-only nodes, all machine learning nodes, and all coordinating-only nodes.
  • a pair of patterns, using * wildcards, of the form attrname:attrvalue, which adds to the subset all nodes with a custom node attribute whose name and value match the respective patterns. Custom node attributes are configured by setting properties in the configuration file of the form node.attr.attrname: attrvalue.

node filters run in the order in which they are given, which is important if using filters that remove nodes from the set. For example _all,master:false means all the nodes except the master-eligible ones, but master:false,_all means the same as _all because the _all filter runs after the master:false filter.

if no filters are given, the default is to select all nodes. However, if any filters are given then they run starting with an empty chosen subset. This means that filters such as master:false which remove nodes from the chosen subset are only useful if they come after some other filters. When used on its own, master:false selects no nodes.

The voting_only role requires the default distribution of Elasticsearch and is not supported in the OSS-only distribution.

Here are some examples of the use of node filters with the Nodes Info APIs.

  1. # If no filters are given, the default is to select all nodes
  2. GET /_nodes
  3. # Explicitly select all nodes
  4. GET /_nodes/_all
  5. # Select just the local node
  6. GET /_nodes/_local
  7. # Select the elected master node
  8. GET /_nodes/_master
  9. # Select nodes by name, which can include wildcards
  10. GET /_nodes/node_name_goes_here
  11. GET /_nodes/node_name_goes_*
  12. # Select nodes by address, which can include wildcards
  13. GET /_nodes/10.0.0.3,10.0.0.4
  14. GET /_nodes/10.0.0.*
  15. # Select nodes by role
  16. GET /_nodes/_all,master:false
  17. GET /_nodes/data:true,ingest:true
  18. GET /_nodes/coordinating_only:true
  19. GET /_nodes/master:true,voting_only:false
  20. # Select nodes by custom attribute (e.g. with something like `node.attr.rack: 2` in the configuration file)
  21. GET /_nodes/rack:2
  22. GET /_nodes/ra*:2
  23. GET /_nodes/ra*:2*