Elasticsearch 跨集群检索（CCS）完整版实战指南

1 什么是 CCS？

CCS（Cross-Cluster Search）允许在一条请求中同时查询本地及多个远端 Elasticsearch 集群，常见用例：

2 支持的 API

• Search / MSearch / Async Search
• Search Template / MSearch Template
• Field Capabilities / Resolve Index
• Painless Execute
• Vector Tile Search
• ES|QL（9.x preview）
• SQL / EQL（preview）

3 部署前提

1. 远端集群已配置 remote_cluster

2. 本地协调节点具备 remote_cluster_client 角色

3. 本地 & 远端 订阅级别一致 才能用全部功能

4. 网络互通

   • sniff mode：协调节点可连 seed & gateway :9300
   • proxy mode：协调节点连 proxy_address，由代理转发

4 配置 Remote Cluster

PUT _cluster/settings
{
  "persistent": {
    "cluster.remote": {
      "cluster_one": {
        "seeds": ["10.0.1.2:9300"],
        "skip_unavailable": true      // 8.15+ 默认 true
      },
      "cluster_two": {
        "seeds": ["10.0.2.2:9300"],
        "skip_unavailable": false
      },
      "cluster_three": {
        "seeds": ["10.0.3.2:9300"]
      }
    }
  }
}

• skip_unavailable=true：远端故障→跳过，HTTP 200；
• skip_unavailable=false：远端故障→整体失败，HTTP 5xx。

5 查询语法与示例

5.1 查询单远端集群

GET cluster_one:logs-2024.05/_search
{
  "query": { "match": { "user.id": "kimchy" } },
  "_source": ["user.id","message"]
}

返回体新增 _clusters 区块，展示远端耗时与 shard 状态。

5.2 本地 + 多集群联合查询

GET logs-2024.05,cluster_one:logs-*,cluster_two:logs-* /_search

• 本地索引前缀可省略 cluster。
• _index 字段带 cluster_name: 即表示远端来源。

5.3 Async Search + ccs_minimize_roundtrips

POST logs-*,cluster*:logs-* /_async_search?ccs_minimize_roundtrips=true

• true（同步默认值）：一次往返，按 cluster 级别返回增量；
• false（异步默认）：多步交互，可在 shard 级别返回增量聚合。

查询进度：GET _async_search/<id>

• is_partial true → 结果尚未合并完；
• _clusters.running 逐渐减到 0。

5.4 排除（-）集群/索引写法

# 排除整条 cluster_three
GET cluster*:logs-*,-cluster_three:*/_search

# 仅排除 cluster_three 下的指定索引
GET cluster*:logs-*,cluster_three:-logs-2024.05/_search

排除集群时索引位置必须使用 *。

6 skip_unavailable 可用性策略

8.15 以前默认 false，升级需留意。

7 失败与部分结果

• _shards.failed > 0 → 远端或局部 shard 失败

• _clusters.details.<name>.status：

  • successful / running / skipped / partial / failed

• 如果存在 failed cluster，会有最外层 error 并返回 5xx。

示例：远端 cluster_two 某个 shard 失败

"_clusters": {
  "total":3,"successful":2,"partial":1,"failed":0,
  "details": {
     "cluster_two": {
        "status":"partial",
        "_shards":{"total":6,"successful":5,"failed":1},
        "failures":[{...}]
     }
  }
}

8 性能策略：Minimize VS Non-minimize Roundtrips

Vector Tile Search 始终 true；Approx kNN 始终 false。

9 版本兼容矩阵

• 同 minor + 前一 minor 可互查
• 8.19 ➟ 查询所有 9.x
• 8.18 ➟ 查询 9.0
• 查询不支持向下 major（9.x 查询 8.17 ⇥ 不保证）

升级期间（rolling）本地节点旧 ↔ 新混跑可临时查询，升级完成后需统一版本。

10 常见问题与优化

结语

通过合理配置 Remote Cluster、网络拓扑与 skip_unavailable 策略，跨集群检索可以在多数据中心、大规模归档场景下提供几乎与本地一致的查询体验。结合 Async Search 及 ccs_minimize_roundtrips，不仅能在长距离网络里获得最佳性能，还可在前端实时展示增量结果。祝你的多集群数据洞察之旅一切顺利！