Cross-Cluster Search: Federated Queries Across Multiple Elasticsearch Clusters

1. What cross-cluster search is and what it's for

Cross-cluster search, CCS for short, lets a coordinating cluster run a search request not only against its own, local indices but simultaneously against indices on one or more clusters registered as remote. From the requesting client's point of view, the result looks like a single, merged response, even though the underlying data physically lives on completely separate cluster installations, each managing its own master elections, shard distribution, and version upgrades independently.

The central use case is federated search across organizationally or geographically separate data sets, without having to consolidate them into one single, shared cluster. That matters most when regulatory requirements demand physical data separation by region, while a company-wide overview is still desired at the same time.

2. Remote cluster configuration: sniff and proxy mode

A remote cluster gets registered via the cluster settings API or directly in elasticsearch.yml, with two connection modes to choose from. In sniff mode, the coordinating cluster first connects to one or more specified seed nodes and automatically discovers additional nodes in the remote cluster that are suitable for cross-cluster requests.

In proxy mode, on the other hand, all communication runs through a single, configured address, typically a load balancer or reverse proxy sitting in front of the remote cluster, which removes the need for direct network visibility into individual node addresses of the remote cluster. For setups with strict network segmentation between regions, proxy mode is usually the more practical choice.

PUT _cluster/settings
{
  "persistent": {
    "cluster.remote": {
      "us_cluster": {
        "mode": "proxy",
        "proxy_address": "us-es-proxy.internal:9443"
      },
      "eu_cluster": {
        "mode": "sniff",
        "seeds": [ "eu-es-node-01.internal:9300" ]
      }
    }
  }
}

3. Executing a cross-cluster query: structure and syntax

A cross-cluster request barely differs syntactically from an ordinary search request, the index name simply gets extended with the cluster alias and a colon, for instance eu_cluster:products or us_cluster:products. Multiple clusters and local indices can be combined in the same request, so a single search call searches both local and remote data at once.

Internally, the coordinating cluster splits the request into sub-requests per cluster, sends them in parallel to the respective remote clusters, and then merges the returning partial results into one combined, relevance-sorted result list, exactly like merging shard results within a single cluster.

GET eu_cluster:products,us_cluster:products,products/_search
{
  "query": {
    "match": { "name": "hiking boots" }
  },
  "size": 20
}

4. Latency trade-offs of distributed queries

Every cross-cluster request is fundamentally as slow as the slowest remote cluster involved, since the coordinating cluster has to wait for responses from every queried cluster before it can return the combined result. Between geographically distant clusters, for instance between Europe and the US, sheer network round-trip time alone adds noticeably to the actual search time.

The minimize roundtrips parameter reduces the number of network round trips by letting more processing happen on the remote clusters themselves, but it only reduces latency to a limited extent between far-apart clusters. For latency-critical, company-wide search requests, it's realistic to expect a noticeably higher response time than with a purely local search.

5. Consistency limits: no global read consistency model

Cross-cluster search offers no global, cross-cluster consistency guarantee. Every involved cluster returns its result based on its own local state at the time of the request, with no cross-cluster synchronization happening between them. If a document changes in a remote cluster exactly while a cross-cluster request is running, that can result in an inconsistent snapshot.

For most search use cases, this behavior is uncritical, since search rarely requires transactional consistency anyway. For use cases that depend on exact, immediately consistent numbers, for instance real-time stock queries, cross-cluster search should not serve as the sole data source.

6. Security: cross-cluster API keys and permissions

For production setups, a cross-cluster API key is preferable to the classic certificate-based remote cluster connection, since it can be scoped precisely to individual indices and permissions on the remote cluster. That way, the coordinating cluster only gets access to exactly the indices meant to be exposed for federated search, not to the entire remote cluster.

This granular permission model matters especially when separate teams operate the involved clusters independently, for instance different regional Magento instances with their own operational owners. A tightly scoped API key prevents a central search integration from accidentally gaining access to indices that were never meant to be part of the company-wide search.

POST /_security/cross_cluster/api_key
{
  "name": "central-search-eu-cluster",
  "access": {
    "search": [
      { "names": [ "products*" ], "allow_restricted_indices": false }
    ]
  }
}

7. Practical use case: regionally separate store clusters with central search

A retailer runs a separate, independent Elasticsearch cluster for each of its Magento instances in Germany, France, and the US, partly for latency reasons but also because of regulatory requirements around data residency. For an internal team that needs a company-wide view of product availability and search trends, fully consolidating the data into one shared cluster would be disproportionately expensive and would undercut the existing regional separation.

Cross-cluster search solves exactly this problem: a central, internal analytics tool registers all three regional clusters as remote clusters and can run a combined search across all three product catalogs through them, while each regional Magento instance itself keeps searching exclusively against its own local cluster, unaffected by the extra cross-cluster load.

8. Skip unavailable and error handling for unreachable clusters

If a registered remote cluster is unreachable at the time of a request, the skip_unavailable setting decides, per cluster, how the overall request behaves. If it's set to true, the request still returns a result built from the reachable clusters, supplemented with a note about the skipped cluster, instead of failing outright.

If skip_unavailable is set to false, the default, the entire request fails as soon as even a single involved cluster is unreachable. For a company-wide search where a single, temporarily unreachable regional cluster shouldn't take down the whole feature, setting it to true is the more robust choice in most cases.

9. Limits, and when cross-cluster search isn't worth it

Cross-cluster search is no substitute for data consolidation when a genuinely shared, consistent data basis with uniform relevance scoring across all regions is required, for instance because different clusters use slightly different mapping or analyzer configurations, which makes scores not directly comparable.

For very latency-critical, frequently repeated requests, for instance live search directly in the storefront, cross-cluster search is rarely the right choice either, because the extra network round-trip time between clusters becomes noticeable. For internal, less frequently run, company-wide evaluations and reports, the approach is well suited, without giving up the operational separation of the regional clusters.

10. Summary

11. FAQ: Cross-Cluster Search: The Essentials at a Glance