Node filters are undocumented

[DaveCTurner]

The introduction to the cluster APIs reference documentation indicates that it's possible to filter the target nodes and gives some examples of how to do so, but there seems to be no comprehensive description of all the possibilities here. In particular, the special filters {data,master,ingest}:{true,false} are not documented. The code in question is:

elasticsearch/server/src/main/java/org/elasticsearch/cluster/node/DiscoveryNodes.java

Lines 303 to 368 in 27ddb4f

	public String[] resolveNodes(String... nodes) {
	if (nodes == null || nodes.length == 0) {
	return StreamSupport.stream(this.spliterator(), false).map(DiscoveryNode::getId).toArray(String[]::new);
	} else {
	ObjectHashSet<String> resolvedNodesIds = new ObjectHashSet<>(nodes.length);
	for (String nodeId : nodes) {
	if (nodeId.equals("_local")) {
	String localNodeId = getLocalNodeId();
	if (localNodeId != null) {
	resolvedNodesIds.add(localNodeId);
	}
	} else if (nodeId.equals("_master")) {
	String masterNodeId = getMasterNodeId();
	if (masterNodeId != null) {
	resolvedNodesIds.add(masterNodeId);
	}
	} else if (nodeExists(nodeId)) {
	resolvedNodesIds.add(nodeId);
	} else {
	for (DiscoveryNode node : this) {
	if ("_all".equals(nodeId)
	|| Regex.simpleMatch(nodeId, node.getName())
	|| Regex.simpleMatch(nodeId, node.getHostAddress())
	|| Regex.simpleMatch(nodeId, node.getHostName())) {
	resolvedNodesIds.add(node.getId());
	}
	}
	int index = nodeId.indexOf(':');
	if (index != -1) {
	String matchAttrName = nodeId.substring(0, index);
	String matchAttrValue = nodeId.substring(index + 1);
	if (DiscoveryNode.Role.DATA.getRoleName().equals(matchAttrName)) {
	if (Booleans.parseBoolean(matchAttrValue, true)) {
	resolvedNodesIds.addAll(dataNodes.keys());
	} else {
	resolvedNodesIds.removeAll(dataNodes.keys());
	}
	} else if (DiscoveryNode.Role.MASTER.getRoleName().equals(matchAttrName)) {
	if (Booleans.parseBoolean(matchAttrValue, true)) {
	resolvedNodesIds.addAll(masterNodes.keys());
	} else {
	resolvedNodesIds.removeAll(masterNodes.keys());
	}
	} else if (DiscoveryNode.Role.INGEST.getRoleName().equals(matchAttrName)) {
	if (Booleans.parseBoolean(matchAttrValue, true)) {
	resolvedNodesIds.addAll(ingestNodes.keys());
	} else {
	resolvedNodesIds.removeAll(ingestNodes.keys());
	}
	} else {
	for (DiscoveryNode node : this) {
	for (Map.Entry<String, String> entry : node.getAttributes().entrySet()) {
	String attrName = entry.getKey();
	String attrValue = entry.getValue();
	if (Regex.simpleMatch(matchAttrName, attrName) && Regex.simpleMatch(matchAttrValue, attrValue)) {
	resolvedNodesIds.add(node.getId());
	}
	}
	}
	}
	}
	}
	}
	return resolvedNodesIds.toArray(String.class);
	}
	}

Noticed in the context of #30313 which changes this method but there's apparently no corresponding docs to change.

[elasticmachine]

Pinging @elastic/es-core-infra

[debadair]

[doc-issue-triage]

Closed as fixed by #30468