Resolve cluster API

Resolves the specified index expressions to return information about each cluster, including the local "querying" cluster, if included.

This endpoint is useful before doing a cross-cluster search in order to determine which remote clusters should be included in a search.

You use the same index expression with this endpoint as you would for cross-cluster search. Index and cluster exclusions are also supported with this endpoint.

For each cluster in the index expression, information is returned about:

whether the querying ("local") cluster was able to connect to each remote cluster specified in the index expression. Note that this endpoint actively attempts to contact the remote clusters, unlike the remote/info endpoint.
whether each remote cluster is configured with skip_unavailable as true or false
whether there are any indices, aliases or data streams on that cluster that match the index expression
whether the search is likely to have errors returned when you do a cross-cluster search (including any authorization errors if your user does not have permission to query a remote cluster or the indices on that cluster)
(in some cases) cluster version information, including the Elasticsearch server version

Whenever a security exception is returned for a remote cluster, that remote will always be marked as connected=false in the response, since your user does not have permissions to access that cluster (or perhaps the remote index) you are querying. Once the proper security permissions are obtained, then you can rely on the connected field in the response to determine whether the remote cluster is available and ready for querying.

resp = client.indices.resolve_cluster(
    name="my-index-*,cluster*:my-index-*",
)
print(resp)

response = client.indices.resolve_cluster(
  name: 'my-index-*,cluster*:my-index-*'
)
puts response

const response = await client.indices.resolveCluster({
  name: "my-index-*,cluster*:my-index-*",
});
console.log(response);

GET /_resolve/cluster/my-index-*,cluster*:my-index-*

This will return information about the local cluster and all remotely configured clusters that start with the alias cluster*. Each cluster will return information about whether it has any indices, aliases or data streams that match my-index-*.

Request

edit

GET /_resolve/cluster/<index_expression>

Prerequisites

edit

If the Elasticsearch security features are enabled, you must have the view_index_metadata, read, or manage index privilege for the target data stream, index, or alias.

Path parameters

edit

<index_expression>: (Required, string) Comma-separated name(s) or index pattern(s) of the indices, aliases, and data streams to resolve, using Multi-target syntax. Resources on remote clusters can be specified using the <cluster>:<name> syntax.

Query parameters

edit

expand_wildcards

(Optional, string) Type of index that wildcard patterns can match. If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams. Supports comma-separated values, such as open,hidden. Valid values are:

all: Match any data stream or index, including hidden ones.
open: Match open, non-hidden indices. Also matches any non-hidden data stream.
closed: Match closed, non-hidden indices. Also matches any non-hidden data stream. Data streams cannot be closed.
hidden: Match hidden data streams and hidden indices. Must be combined with open, closed, or both.
none: Wildcard patterns are not accepted.

Defaults to open.

ignore_unavailable

(Optional, Boolean) If false, the request returns an error if it targets a missing or closed index. Defaults to false.

Defaults to false.

allow_no_indices

(Optional, Boolean) If false, the request returns an error if any wildcard expression, index alias, or _all value targets only missing or closed indices. This behavior applies even if the request targets other open indices. For example, a request targeting foo*,bar* returns an error if an index starts with foo but no index starts with bar.

Defaults to true.

ignore_throttled

(Optional, Boolean) If true, concrete, expanded or aliased indices are ignored when frozen. Defaults to false.

[7.16.0] Deprecated in 7.16.0.

Test availability of remote clusters

edit

The remote/info endpoint is commonly used to test whether the "local" cluster (the cluster being queried) is connected to its remote clusters, but it does not necessarily reflect whether the remote cluster is available or not. The remote cluster may be available, while the local cluster is not currently connected to it.

You can use the resolve-cluster API to attempt to reconnect to remote clusters (for example with GET _resolve/cluster/*:*) and the connected field in the response will indicate whether it was successful or not. If a connection was (re-)established, this will also cause the remote/info endpoint to now indicate a connected status.

« Resolve index API Advantages of using this endpoint before a cross-cluster search »