Search across clusters
editSearch across clusters
editCross-cluster search lets you run a single search request against one or more remote clusters. For example, you can use a cross-cluster search to filter and analyze log data stored on clusters in different data centers.
Supported APIs
editThe following APIs support cross-cluster search:
- Search
- Async search
- Multi search
- Search template
- Multi search template
- Field capabilities
- [preview] This functionality is in technical preview and may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features. EQL search
- [preview] This functionality is in technical preview and may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features. SQL search
- [preview] This functionality is in technical preview and may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features. Vector tile search
Prerequisites
edit-
Cross-cluster search requires remote clusters. To set up remote clusters on Elasticsearch Service, see configure remote clusters on Elasticsearch Service. If you run Elasticsearch on your own hardware, see Remote clusters.
To ensure your remote cluster configuration supports cross-cluster search, see Supported cross-cluster search configurations.
- For full cross-cluster search capabilities, the local and remote cluster must be on the same subscription level.
-
The local coordinating node must have the
remote_cluster_client
node role.
-
If you use sniff mode, the local coordinating node must be able to connect to seed and gateway nodes on the remote cluster.
We recommend using gateway nodes capable of serving as coordinating nodes. The seed nodes can be a subset of these gateway nodes.
-
If you use proxy mode, the local coordinating node must be able
to connect to the configured
proxy_address
. The proxy at this address must be able to route connections to gateway and coordinating nodes on the remote cluster. - Cross-cluster search requires different security privileges on the local cluster and remote cluster. See Configure privileges for cross-cluster search and Configure privileges for cross-cluster search and Kibana.
Cross-cluster search examples
editRemote cluster setup
editThe following cluster update settings API request
adds three remote clusters: cluster_one
, cluster_two
, and cluster_three
.
PUT _cluster/settings { "persistent": { "cluster": { "remote": { "cluster_one": { "seeds": [ "127.0.0.1:9300" ] }, "cluster_two": { "seeds": [ "127.0.0.1:9301" ] }, "cluster_three": { "seeds": [ "127.0.0.1:9302" ] } } } } }
Search a single remote cluster
editIn the search request, you specify data streams and indices on a remote cluster
as <remote_cluster_name>:<target>
.
The following search API request searches the
my-index-000001
index on a single remote cluster, cluster_one
.
response = client.search( index: 'cluster_one:my-index-000001', body: { query: { match: { "user.id": 'kimchy' } }, _source: [ 'user.id', 'message', 'http.response.status_code' ] } ) puts response
GET /cluster_one:my-index-000001/_search { "query": { "match": { "user.id": "kimchy" } }, "_source": ["user.id", "message", "http.response.status_code"] }
The API returns the following response:
{ "took": 150, "timed_out": false, "_shards": { "total": 1, "successful": 1, "failed": 0, "skipped": 0 }, "_clusters": { "total": 1, "successful": 1, "skipped": 0 }, "hits": { "total" : { "value": 1, "relation": "eq" }, "max_score": 1, "hits": [ { "_index": "cluster_one:my-index-000001", "_id": "0", "_score": 1, "_source": { "user": { "id": "kimchy" }, "message": "GET /search HTTP/1.1 200 1070000", "http": { "response": { "status_code": 200 } } } } ] } }
Search multiple remote clusters
editThe following search API request searches the my-index-000001
index on
three clusters:
- Your local cluster
-
Two remote clusters,
cluster_one
andcluster_two
response = client.search( index: 'my-index-000001,cluster_one:my-index-000001,cluster_two:my-index-000001', body: { query: { match: { "user.id": 'kimchy' } }, _source: [ 'user.id', 'message', 'http.response.status_code' ] } ) puts response
GET /my-index-000001,cluster_one:my-index-000001,cluster_two:my-index-000001/_search { "query": { "match": { "user.id": "kimchy" } }, "_source": ["user.id", "message", "http.response.status_code"] }
The API returns the following response:
{ "took": 150, "timed_out": false, "num_reduce_phases": 4, "_shards": { "total": 3, "successful": 3, "failed": 0, "skipped": 0 }, "_clusters": { "total": 3, "successful": 3, "skipped": 0 }, "hits": { "total" : { "value": 3, "relation": "eq" }, "max_score": 1, "hits": [ { "_index": "my-index-000001", "_id": "0", "_score": 2, "_source": { "user": { "id": "kimchy" }, "message": "GET /search HTTP/1.1 200 1070000", "http": { "response": { "status_code": 200 } } } }, { "_index": "cluster_one:my-index-000001", "_id": "0", "_score": 1, "_source": { "user": { "id": "kimchy" }, "message": "GET /search HTTP/1.1 200 1070000", "http": { "response": { "status_code": 200 } } } }, { "_index": "cluster_two:my-index-000001", "_id": "0", "_score": 1, "_source": { "user": { "id": "kimchy" }, "message": "GET /search HTTP/1.1 200 1070000", "http": { "response": { "status_code": 200 } } } } ] } }
This document’s |
|
This document came from |
|
This document came from |
Optional remote clusters
editBy default, a cross-cluster search fails if a remote cluster in the request returns an
error or is unavailable. Use the skip_unavailable
cluster
setting to mark a specific remote cluster as optional for cross-cluster search.
If skip_unavailable
is true
, a cross-cluster search:
-
Skips the remote cluster if its nodes are unavailable during the search. The
response’s
_cluster.skipped
value contains a count of any skipped clusters. -
Ignores errors returned by the remote cluster, such as errors related to
unavailable shards or indices. This can include errors related to search
parameters such as
allow_no_indices
andignore_unavailable
. -
Ignores the
allow_partial_search_results
parameter and the relatedsearch.default_allow_partial_results
cluster setting when searching the remote cluster. This means searches on the remote cluster may return partial results.
The following cluster update settings
API request changes cluster_two
's skip_unavailable
setting to true
.
PUT _cluster/settings { "persistent": { "cluster.remote.cluster_two.skip_unavailable": true } }
If cluster_two
is disconnected or unavailable during a cross-cluster search, Elasticsearch won’t
include matching documents from that cluster in the final results.
How cross-cluster search handles network delays
editBecause cross-cluster search involves sending requests to remote clusters, any network delays can impact search speed. To avoid slow searches, cross-cluster search offers two options for handling network delays:
- Minimize network roundtrips
-
By default, Elasticsearch reduces the number of network roundtrips between remote clusters. This reduces the impact of network delays on search speed. However, Elasticsearch can’t reduce network roundtrips for large search requests, such as those including a scroll or inner hits.
See Minimize network roundtrips to learn how this option works.
- Don’t minimize network roundtrips
-
For search requests that include a scroll or inner hits, Elasticsearch sends multiple outgoing and ingoing requests to each remote cluster. You can also choose this option by setting the
ccs_minimize_roundtrips
parameter tofalse
. While typically slower, this approach may work well for networks with low latency.See Don’t minimize network roundtrips to learn how this option works.
The vector tile search API always minimizes
network roundtrips and doesn’t include the ccs_minimize_roundtrips
parameter.
Minimize network roundtrips
editHere’s how cross-cluster search works when you minimize network roundtrips.
-
You send a cross-cluster search request to your local cluster. A coordinating node in that cluster receives and parses the request.
-
The coordinating node sends a single search request to each cluster, including the local cluster. Each cluster performs the search request independently, applying its own cluster-level settings to the request.
-
Each remote cluster sends its search results back to the coordinating node.
-
After collecting results from each cluster, the coordinating node returns the final results in the cross-cluster search response.
Don’t minimize network roundtrips
editHere’s how cross-cluster search works when you don’t minimize network roundtrips.
-
You send a cross-cluster search request to your local cluster. A coordinating node in that cluster receives and parses the request.
-
The coordinating node sends a search shards API request to each remote cluster.
-
Each remote cluster sends its response back to the coordinating node. This response contains information about the indices and shards the cross-cluster search request will be executed on.
-
The coordinating node sends a search request to each shard, including those in its own cluster. Each shard performs the search request independently.
When network roundtrips aren’t minimized, the search is executed as if all data were in the coordinating node’s cluster. We recommend updating cluster-level settings that limit searches, such as
action.search.shard_count.limit
,pre_filter_shard_size
, andmax_concurrent_shard_requests
, to account for this. If these limits are too low, the search may be rejected. -
Each shard sends its search results back to the coordinating node.
-
After collecting results from each cluster, the coordinating node returns the final results in the cross-cluster search response.
Supported cross-cluster search configurations
editIn 8.0+, Elastic supports searches from a local cluster to a remote cluster running:
- The previous minor version.
- The same version.
- A newer minor version in the same major version.
Elastic also supports searches from a local cluster running the last minor version of a major version to a remote cluster running any minor version in the following major version. For example, a local 7.17 cluster can search any remote 8.x cluster.
Remote cluster version |
||||||||||||
Local cluster version |
6.8 |
7.1–7.16 |
7.17 |
8.0 |
8.1 |
8.2 |
8.3 |
8.4 |
8.5 |
8.6 |
8.7 |
8.8 |
6.8 |
||||||||||||
7.1–7.16 |
||||||||||||
7.17 |
||||||||||||
8.0 |
||||||||||||
8.1 |
||||||||||||
8.2 |
||||||||||||
8.3 |
||||||||||||
8.4 |
||||||||||||
8.5 |
||||||||||||
8.6 |
||||||||||||
8.7 |
||||||||||||
8.8 |
For the EQL search API, the local and remote clusters must use the same Elasticsearch version if they have versions prior to 7.17.7 (included) or prior to 8.5.1 (included).
For example, a local 8.0 cluster can search a remote 7.17 or any remote 8.x cluster. However, a search from a local 8.0 cluster to a remote 7.16 or 6.8 cluster is not supported.
Only features that exist across all searched clusters are supported. Using a feature with a remote cluster where the feature is not supported will result in undefined behavior.
A cross-cluster search using an unsupported configuration may still work. However, such searches aren’t tested by Elastic, and their behavior isn’t guaranteed.
Ensure cross-cluster search support
editThe simplest way to ensure your clusters support cross-cluster search is to keep each cluster on the same version of Elasticsearch. If you need to maintain clusters with different versions, you can:
- Maintain a dedicated cluster for cross-cluster search. Keep this cluster on the earliest version needed to search the other clusters. For example, if you have 7.17 and 8.x clusters, you can maintain a dedicated 7.17 cluster to use as the local cluster for cross-cluster search.
- Keep each cluster no more than one minor version apart. This lets you use any cluster as the local cluster when running a cross-cluster search.
Cross-cluster search during an upgrade
editYou can still search a remote cluster while performing a rolling upgrade on the local cluster. However, the local coordinating node’s "upgrade from" and "upgrade to" version must be compatible with the remote cluster’s gateway node.
Running multiple versions of Elasticsearch in the same cluster beyond the duration of an upgrade is not supported.
For more information about upgrades, see Upgrading Elasticsearch.