Resolve cluster API
editResolve cluster API
editResolves the specified index expressions to return information about each cluster, including the local 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 is currently connected to each remote cluster in the index expression scope
-
whether each remote cluster is configured with
skip_unavailable
astrue
orfalse
- 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 the cross-cluster search (including any authorization errors if your user does not have permission to query the index)
- cluster version information, including the Elasticsearch server version
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
editGET /_resolve/cluster/<index_expression>
Prerequisites
edit-
If the Elasticsearch security features are enabled, you must have the
view_index_metadata
,read
, ormanage
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 tofalse
.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 targetingfoo*,bar*
returns an error if an index starts withfoo
but no index starts withbar
.Defaults to
true
. -
ignore_throttled
-
(Optional, Boolean) If
true
, concrete, expanded or aliased indices are ignored when frozen. Defaults tofalse
.[7.16.0] Deprecated in 7.16.0.
Advantages of using this endpoint before a cross-cluster search
editYou may want to exclude a cluster or index from a search when:
-
A remote cluster is not currently connected and is configured with
skip_unavailable
=false
. Executing a cross-cluster search under those conditions will cause the entire search to fail. -
A cluster has no matching indices, aliases or data streams for the index expression
(or your user does not have permissions to search them). For example, suppose your
index expression is
logs*,remote1:logs*
and theremote1
cluster has no indices, aliases or data streams that matchlogs*
. In that case, that cluster will return no results from that cluster if you include it in a cross-cluster search. -
The index expression (combined with any query parameters you specify) will likely cause an exception
to be thrown when you do the search. In these cases, the "error" field in the
_resolve/cluster
response will be present. (This is also where security/permission errors will be shown.) - A remote cluster is an older version that does not support the feature you want to use in your search.
Examples
editGET /_resolve/cluster/my-index*,clust*:my-index*
The API returns the following response:
{ "(local)": { "connected": true, "skip_unavailable": false, "matching_indices": true, "version": { "number": "8.13.0", "build_flavor": "default", "minimum_wire_compatibility_version": "7.17.0", "minimum_index_compatibility_version": "7.0.0" } }, "cluster_one": { "connected": true, "skip_unavailable": true, "matching_indices": true, "version": { "number": "8.13.0", "build_flavor": "default", "minimum_wire_compatibility_version": "7.17.0", "minimum_index_compatibility_version": "7.0.0" } }, "cluster_two": { "connected": true, "skip_unavailable": false, "matching_indices": true, "version": { "number": "8.13.0", "build_flavor": "default", "minimum_wire_compatibility_version": "7.17.0", "minimum_index_compatibility_version": "7.0.0" } } }
Each cluster has its own response section. The cluster you sent the request to is labelled as "(local)". |
|
The querying cluster attempts to make a request to each remote cluster. If successful, |
|
The |
|
Indicates whether any index, alias or data stream matches the index expression specified for that cluster. |
|
The Elasticsearch server version. |
Identifying potential problems with your cross-cluster search
editThe following request shows several examples of how modifying your query can prevent search failures.
GET /_resolve/cluster/not-present,clust*:my-index*,oldcluster:*?ignore_unavailable=false
{ "(local)": { "connected": true, "skip_unavailable": false, "error": "no such index [not_present]" }, "cluster_one": { "connected": true, "skip_unavailable": true, "matching_indices": false, "version": { "number": "8.13.0", "build_flavor": "default", "minimum_wire_compatibility_version": "7.17.0", "minimum_index_compatibility_version": "7.0.0" } }, "cluster_two": { "connected": false, "skip_unavailable": false, "matching_indices": true, "version": { "number": "8.13.0", "build_flavor": "default", "minimum_wire_compatibility_version": "7.17.0", "minimum_index_compatibility_version": "7.0.0" } }, "oldcluster": { "connected": true, "skip_unavailable": false, "matching_indices": true } }
The local cluster has no index called |
|
The |
|
The |
|
The |