› › ›

Advantages of using this endpoint before a cross-cluster search

You may want to exclude a cluster or index from a search when:

A remote cluster could not be connected to 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 the remote1 cluster has no indices, aliases or data streams that match logs*. 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

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

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

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

GET /_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, `connected`=`true`.
	The `skip_unavailable` setting for each remote cluster, as configured on the local cluster.
	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

edit

The following request shows several examples of how modifying your query can prevent search failures.

response = client.indices.resolve_cluster(
  name: 'not-present,clust*:my-index*,oldcluster:*',
  ignore_unavailable: false
)
puts response

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
  },
  "oldcluster": {         
    "connected": true,
    "skip_unavailable": false,
    "matching_indices": true
  }
}

	The local cluster has no index called `not_present`. Searching against it using the specified `ignore_unavailable=false` param will return a "no such index" error. Other types of errors can show up here as well, such as security permission errors when the user does not have authorization to search the specified index.
	The `cluster_one` remote cluster has no indices that match the pattern `my-index*`. There may be no indices that match the pattern or the index could be closed. (You can check this by using the resolve index API.)
	The `cluster_two` remote cluster is not connected (the attempt to connect failed). Since this cluster is marked as `skip_unavailable=false`, you should probably exclude this cluster from the search by adding `-cluster_two:*` to the search index expression.
	The `oldcluster` remote cluster shows that it has matching indices, but no version information is included. This indicates that the cluster version predates the introduction of the `_resolve/cluster` API in 8.13.0., so you may want to exclude it from your cross-cluster search. (Note: the endpoint was able to tell there were matching indices because it fell back to using the resolve index API.)

« Resolve cluster API Rollover API »