New

The executive guide to generative AI

Read more
About usPartnersSupport|Login
« Resolve index API Advantages of using this endpoint before a cross-cluster search »
Elastic Docs ›Elasticsearch Guide [8.18] ›REST APIs ›Index APIs

Resolve cluster API

edit
A newer version is available. Check out the latest documentation.

Resolve cluster API

edit

New API reference

For the most up-to-date API details, refer to Index APIs.

Resolves the specified index expressions to return information about each cluster, including the local "querying" cluster, if included. If no index expression is provided, this endpoint will return information about all the remote clusters that are configured on the querying cluster.

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 scope, information is returned about:

  1. 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.
  2. whether each remote cluster is configured with skip_unavailable as true or false
  3. whether there are any indices, aliases or data streams on that cluster that match the index expression (if one provided)
  4. 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)
  5. (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.

The ability to query without an index expression was added in 8.18, so when querying remote clusters older than that, the local cluster will send the index expression dummy* to those remote clusters. Thus, if an errors occur, you may see a reference to that index expression even though you didn’t request it. If it causes a problem, you can instead include an index expression like *:* to bypass the issue.

resp = client.indices.resolve_cluster()
print(resp)
GET /_resolve/cluster
Copy as curlTry in Elastic 

Returns information about all remote clusters configured on the local cluster without doing any index matching.

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-*
Copy as curlTry in Elastic 

Returns information about the local cluster and all remote 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

or

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>

(Optional, 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
timeout
(Optional, TimeValue) Specify a max wait time for remote clusters to respond. If a remote cluster does not respond within this timeout period, the API response will show the cluster as not connected and include an error message that the request timed out. The default timeout is unset and the query can take as long as the networking layer is configured to wait for remote clusters that are not responding (typically 30 seconds).
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.

The index options above are only allowed when specifying an index expression. You will get an error if you specify index options to the _resolve/cluster API that takes no index expression.

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 or GET _resolve/cluster/*:* ). The connected field in the response will indicate whether it was successful. 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 »
Was this helpful?
Feedback