文档反馈官招募中，报名立赚积分兑换代金券！> HOT
文档中心>Elasticsearch Service>实践教程>数据迁移和同步>ES 集群业务兼容性校验指南

ES 集群业务兼容性校验指南

最近更新时间：2025-08-08 10:38:32

我的收藏

本页目录：

腾讯云 ES 完全兼容开源社区的 ELK 生态，能够满足多样化的业务需求。而 ES 业务兼容性校验是保障数据迁移零风险的关键，通常情况下 ES 业务兼容性校验步骤会在割接前进行。当目标端 ES 完成数据同步后，将接入测试链路进行业务测试，包括读写成功率的验证和相关功能的确认，只有经过全面验证后，才能正式切流至目标集群。本文介绍了兼容性场景中的常见问题，建议用户结合实际业务场景进行测试，确保迁移顺利且系统稳定运行。

ES 客户端兼容性与访问方式

客户端兼容（非 API）

腾讯云 ES 支持多种客户端访问方式，满足不同版本和需求的集成。客户端访问方式包括：
Client
支持版本
Transport Client
0.9 ~ 7.17
Java Low Level Rest Client
5.6 ~ 7.15
Java High Level Rest Client
5.6 ~ 7.17
Java API Client
≥ 7.16
http request
完全兼容
spring-boot-starter-data-elasticsearch
兼容性有严格要求
SDK 版本建议：
对于 ES 版本 ≤ 7.x，建议使用 Java High Level Rest Client。
对于 ES 版本 ≥ 8.x，建议使用 ES Client。
其他语言例如 Python、PHP、Go 版本可参考 Elasticsearch Clients 进行选择。

端口兼容

腾讯云 ES 支持基于 HTTP 协议（公网访问基于 HTTPS 协议）的接口访问，统一使用 VIP 代理的 9200 端口，以确保不同访问方式下的稳定性和安全性。

不同版本的索引类型支持

ES 5.x ：单个索引可以包含多个 Type。
ES 6.x ：单个索引只能拥有一个 Type，默认为 doc，但可以为其指定其他 Type。在从 5.x 版本升级到 6.x 后，新增的多 Type 索引会报错，但原本在 5.x 版本创建的多 Type 索引不受影响，依然可以正常使用。
ES 7.x ：单个索引只能拥有一个 Type，默认 Type 为 _doc。
ES 8.x ：Type 已被废弃，不再支持。

冷热属性配置

冷热属性用于根据数据的访问频率将其分为热数据、暖数据和冷数据，从而实现更高效的资源管理。对于非冷热架构，冷热属性配置可以忽略。用户可通过以下命令查看索引冷热属性参数，如图所示该索引使用"index.routing.allocation.include._tier_preference"参数。
GET index_name/_settings

● ES 7.14 及以上版本
index.routing.allocation.include._tier_preference
● ES 7.14 以下版本
index.routing.allocation.require.temperature

字段类型与查询支持的变更

Bool 类型的变更

在 ES 5.3.0 及以后的版本中，bool 类型字段仅接受 true、"true"、false 和 "false" 四种真 bool 值，拒绝其他任何伪 bool 值。

match 查询不支持 type 关键字

在 ES 6.8 及以后的版本中，match 语句中不再支持使用 type 关键字。例如，下面的查询会报错：
GET index_name/_search
{
  "query": {
    "match": {
      "field_name": {
        "query": "测试",
        "type": "phrase"
      }
    }
  }
}
 
#如果使用，您会遇到以下错误
{
  "error": {
    "root_cause": [
      {
        "type": "parsing_exception",
        "reason": "[match] query does not support [type]",
        "line": 6,
        "col": 17
      }
    ],
    "type": "parsing_exception",
    "reason": "[match] query does not support [type]",
    "line": 6,
    "col": 17
  },
  "status": 400
}

term 聚合查询不支持 size=0

在 ES 5.6 及以后的版本中，term 聚合查询不再支持使用 size=0 的方式。例如，以下查询将不再有效：
GET index_name/_search
{
  "_source": "false",
  "aggs": {
    "my_terms_agg": {
      "terms": {
        "field": "name",
        "size": 1
      }
    }
  }
}

不支持关键字 fields

在 ES 5.6.4 及以后的版本中，fields 关键字已不再支持，需改用 stored_fields 关键字。
GET index_name/_search
{
  "stored_fields": ["description"]
}

索引属性不支持 string 类型

在 ES 5.0 及以后的版本中，索引字段类型不再支持使用 string 类型，改为使用 keyword 或 text 类型。
PUT my_index
{
  "mappings": {
    "my_type": {
      "properties": {
        "field1": { 
          "type":  "string"
        }
      }
    }
  }
}

SQL 查询与 JDBC 兼容性

开源 SQL 解析插件

腾讯云 ES 所有的开源版本均预装了开源社区提供的 SQL 解析插件，不同版本的 SQL 查询方式不同。
● 腾讯云 7.5.1 及以上版本
POST /_nlpcn/sql 
{
   "sql": "select * from test_index"
}
● 其他版本
POST /_sql 
{
   "sql": "select * from test_index"
}

原生 SQL 解析器

腾讯云 ES 6.8 及以上版本支持使用 ES 原生的 SQL 解析器。
POST /_xpack/sql?format=txt
{
    "query": "SELECT * FROM test_index"
}

Xpack-sql-jdbc 兼容性

通过 JDBC 连接 ES 时，Xpack-sql-jdbc 的兼容性版本如下。
ES 版本
兼容版本
8.0.0 及以上
相同版本，早期 8.x 版本，7.7.0 之后的 7.x 版本
7.7.1 - 7.17
相同版本，7.7.0 之后的 7.x 版本
7.7.0 及以下
相同版本

版本升级自检与功能变更

如果用户 ES 版本大于等于 6.6.0，那么可以通过 Kibana 的 Upgrade Assistant 功能初步检查。具体操作如下所示。
1. 打开 Kibana。
2. 单击 Management。

3. 单击 Upgrade Assistant。

4. 查看集群升级 7.x 中的不兼容 cluster settings。

5. 查看集群升级 7.x 中的不兼容 index settings。

6. 查看集群的弃用日志，查看那些正在使用但未来会被弃用的功能。


其他升级变化参考文档

腾讯云 ES 集群升级检查

详情请参见 ES 版本升级检查。

ES 集群升级变化

● 升级 ES 6.8 变化
● 升级 ES 7.10 变化
● 升级 ES 7.14 变化
● 升级 ES 8.13 变化
中国站
目录