Skip to content

Commit ca79dac

Browse files
committed
[DOCS] Add links and example
1 parent 7cf0f70 commit ca79dac

File tree

1 file changed

+31
-2
lines changed

1 file changed

+31
-2
lines changed

docs/reference/elasticsearch/rest-apis/api-conventions.md

Lines changed: 31 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -383,7 +383,7 @@ When overwriting current cluster state, system indices should be restored as par
383383
### Node specification [cluster-nodes]
384384

385385
Some cluster-level APIs may operate on a subset of the nodes which can be specified with node filters.
386-
For example, task management, node stats, and node info APIs can all report results from a filtered set of nodes rather than from all nodes.
386+
For example, [task management]({{es-apis}}group/endpoint-tasks), [node stats]({{es-apis}}operation/operation-nodes-stats), and [node info]({{es-apis}}operation/operation-nodes-info-1) APIs can all report results from a filtered set of nodes rather than from all nodes.
387387

388388
Node filters are written as a comma-separated list of individual filters, each of which adds or removes nodes from the chosen subset.
389389
Each filter can be one of the following:
@@ -396,7 +396,7 @@ Each filter can be one of the following:
396396
* a pattern, using `*` wildcards, which adds all nodes to the subset whose name, address, or hostname matches the pattern.
397397
* `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.
398398
* `master:false`, `data:false`, `ingest:false`, `voting_only:false`, `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.
399-
* 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`.
399+
* a pair of patterns, using `*` wildcards, of the form `attrname:attrvalue`, which adds to the subset all nodes with a [custom node attribute](/reference/elasticsearch/configuration-reference/node-settings#custom-node-attributes) 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`.
400400

401401
Node filters run in the order in which they are given, which is important if using filters that remove nodes from the set.
402402
For example, `_all,master:false` means all the nodes except the master-eligible ones.
@@ -407,6 +407,35 @@ If any filters are specified, they run starting with an empty chosen subset.
407407
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.
408408
When used on its own, `master:false` selects no nodes.
409409

410+
Here are some examples of the use of node filters with some [cluster APIs]({{es-apis}}group/endpoint-cluster):
411+
412+
```sh
413+
# If no filters are given, the default is to select all nodes
414+
GET /_nodes
415+
# Explicitly select all nodes
416+
GET /_nodes/_all
417+
# Select just the local node
418+
GET /_nodes/_local
419+
# Select the elected master node
420+
GET /_nodes/_master
421+
# Select nodes by name, which can include wildcards
422+
GET /_nodes/node_name_goes_here
423+
GET /_nodes/node_name_goes_*
424+
# Select nodes by address, which can include wildcards
425+
GET /_nodes/10.0.0.3,10.0.0.4
426+
GET /_nodes/10.0.0.*
427+
# Select nodes by role
428+
GET /_nodes/_all,master:false
429+
GET /_nodes/data:true,ingest:true
430+
GET /_nodes/coordinating_only:true
431+
GET /_nodes/master:true,voting_only:false
432+
# Select nodes by custom attribute
433+
# (for example, with something like `node.attr.rack: 2` in the configuration file)
434+
GET /_nodes/rack:2
435+
GET /_nodes/ra*:2
436+
GET /_nodes/ra*:2*
437+
```
438+
410439
## Parameters [api-conventions-parameters]
411440

412441
Rest parameters (when using HTTP, map to HTTP URL parameters) follow the convention of using underscore casing.

0 commit comments

Comments
 (0)