> 1.0 的迁移说明记录了一批移除：`text` 查询、`field` 查询、`_boost` 文档级加权、`custom_score` 系列。本文按固定标签核对这些条目，说明替换写法、不等价的地方，以及一组可复现的验收数据。

## **说明**

本文描述问题及解决方法同样适用于 [腾讯云 Elasticsearch Service（ES）](https://cloud.tencent.com/document/product/845)。

本文讨论 1.0 的历史实现，不表示当前云服务支持这些旧接口。示例用于准备隔离的旧版本验证环境，不得在生产集群执行。本文没有启动历史集群，示例的预期行为来自文档与语义推导，不是实测结果。

## 迁移说明写了哪些移除

[v1.0.0 的迁移说明](https://github.com/elastic/elasticsearch/blob/v1.0.0/docs/reference/migration/migrate_1_0.asciidoc#L348-L364)在 Deprecations 一节列出以下条目：

> * The `text` query has been removed. Use the `match` query instead.
> * The `field` query has been removed. Use the `query_string` query instead.
> * Per-document boosting with the `_boost` field has been removed. You can use the `function_score` instead.
> * The `path` parameter in mappings has been deprecated. Use the `copy_to` parameter instead.
> * The `custom_score` and `custom_boost_score` is no longer supported. You can use `function_score` instead.

原稿引用的是这些原文。它们说明的是 1.0 迁移时要求的改写方向，不自动等于“该版本解析器一定拒绝旧写法的全部形式”。实际行为应按运行版本核实。

还有一个容易混淆的点：后续版本的发布说明里仍能看到与 `_boost`、`custom_score` 相关的移除条目。这说明清理可能分阶段进行，也可能只是移除兼容层。**不能因为后一份说明出现相同名字，就断定前一版没有移除。**排查时应以实际运行的版本与解析器为准。

因此本文的标题强调“验收”，而不是给一个统一的移除版本号。维护老系统时，先确认目标版本对每个旧名字的处理方式，再决定改哪些。

## `text` 与 `field` 是查询名被移除，不是能力新增

把 `text` 查询改写成 `match`，容易被理解成“1.0 才有 match”。这不准确。0.90 的文档里已经有 match 查询，并且包含 `operator`、`minimum_should_match`、`analyzer`、`zero_terms_query`，以及 `match_phrase`、`match_phrase_prefix` 等形态。

所以这次变化的核心是**查询名的收敛**：`text` 这个名字不再使用，统一到 `match`。排查老代码时应关注查询名是否仍被接受，而不是假设能力是新的。

同理，`field` 查询改为 `query_string`，也不代表之前没有字段限定的查询方式。改写时要比较的是语法与默认行为，不是“能不能查询某个字段”。

`query_string` 会解析查询语法，这一点需要单独评估。若原查询里的用户输入包含特殊字符，改写后可能出现解析错误或匹配范围变化。验收时应包含带特殊字符的输入。

## `_boost` 换成了什么

`_boost` 是文档级加权：mapping 里声明某个字段的值控制该文档的 boost 级别。1.0 的[boost 字段文档](https://github.com/elastic/elasticsearch/blob/v1.0.0/docs/reference/mapping/fields/boost-field.asciidoc#L4)标注 `deprecated[1.0.0.RC1]`，并给出替代做法。

替代示例是用 `function_score` 包住原查询，再用 `script_score` 返回该字段的值：

```json
{
    "function_score": {
        "query": { "match": { "title": "quick brown fox" } },
        "functions": [{
            "script_score": { "script": "doc['my_boost_field'].value" }
        }]
    }
}
```

文档对这个示例的说明是：脚本返回 `my_boost_field` 的值，再与查询的 `_score` 相乘，见[第 66–70 行](https://github.com/elastic/elasticsearch/blob/v1.0.0/docs/reference/mapping/fields/boost-field.asciidoc#L66-L70)。

这里有三点要留意。

第一，脚本返回的是字段值，最终仍会与查询得分相乘。若原脚本或原语义不希望这样，需要按版本确认对应的合并方式，例如设置 `boost_mode`，参见 [function_score 文档](https://github.com/elastic/elasticsearch/blob/v1.0.0/docs/reference/query-dsl/queries/function-score-query.asciidoc#L76-L84)。

第二，字段必须可取。若文档缺少该字段，脚本取值的行为需要按版本实测，不能假定为 1。

第三，**索引时加权与查询时相乘不等价**。旧 `_boost` 影响的是索引期的 boost；改成查询时脚本后，doc 的 norms、字段配置都可能不同。是否等价要实测，不能只比较公式。

另外，修改查询侧公式不等于修改已写入的数据。若旧索引里已经保存了加权效果，重建索引前后的排序可能不同，这一点应在迁移方案中说明。

## `path` 与 `copy_to` 不是等价替换

迁移说明写的是 `path` 参数废弃，改用 `copy_to`。但两者语义不同：`path` 描述对象字段的路径策略，`copy_to` 是把字段值复制到另一个字段。

因此不能把 `"path": "full"` 直接改写成 `"copy_to": "full"` 就认为等价。前者影响对象字段如何被引用，后者会生成一个目标字段。目标字段是否有自己的 mapping、用什么分析器，都要重新确认。

改写后应验证：目标字段是否真的包含复制过来的值、分析行为是否符合预期、以及旧查询里对该路径的引用是否还能命中。

## `custom_score` 系列的名字

迁移说明写的是 `custom_score` 与 `custom_boost_score` 不再支持。这里有一个名字需要注意：0.90 的查询文档里有 `custom_boost_factor`，而 1.0 迁移说明写的是 `custom_boost_score`。

本文不假定两者是同一个查询，也不把迁移说明里的名字改掉。核对时应分别查看对应版本的解析器和文档，确认实际存在过哪些名字。

替代方向是一致的：用 `function_score`。具体写法参见[0.90 打分查询那篇](./es0-03-when-scoring-had-three-queries.md)对迁移对照与脚本相乘问题的说明。

## 准备一组能暴露打分差异的数据

下面使用 1.0 时代的 REST 记法，供隔离的 `v1.0.0` 环境验证。旧版本没有现代 Dev Tools 配套，需要通过受控 HTTP 客户端发送；不要提交给当前生产版本。

索引显式声明字段类型，避免动态 mapping 的类型差异影响对照。1.0 的字符串字段使用 `string` 类型：

```console
PUT /boost_lab_100
{
  "settings": {
    "number_of_shards": 1,
    "number_of_replicas": 0
  },
  "mappings": {
    "item": {
      "properties": {
        "title": { "type": "string", "index": "analyzed" },
        "status": { "type": "string", "index": "not_analyzed" },
        "my_boost_field": { "type": "double" }
      }
    }
  }
}

PUT /boost_lab_100/item/a
{"title":"quick brown fox","status":"published","my_boost_field":3.0}

PUT /boost_lab_100/item/b
{"title":"quick brown fox","status":"published","my_boost_field":1.0}

PUT /boost_lab_100/item/c
{"title":"quick brown fox","status":"draft","my_boost_field":3.0}

POST /boost_lab_100/_refresh
```

写入后逐项确认成功。数据有意让 `a`、`b` 标题相同但权重不同，`c` 状态不同，这样可以分别观察加权与筛选的作用。

按文档给出的替代写法验证加权：

```console
GET /boost_lab_100/item/_search
{
  "size": 20,
  "query": {
    "function_score": {
      "query": { "match": { "title": "quick brown fox" } },
      "functions": [
        { "script_score": { "script": "doc['my_boost_field'].value" } }
      ]
    }
  }
}
```

预期检查是三条文档都命中，且 `a` 的得分高于 `b`。**本文没有运行这个查询，不给出假定的分数值。**

再做一次只改合并方式的对照：显式设置 `boost_mode` 后重新查询，比较得分与排序是否不同。这能把“加权是否按预期生效”从假设变成可观察的事实。

还要准备一条缺少 `my_boost_field` 的文档，观察脚本取不到值时的行为。这是迁移后最容易出问题的地方：老代码里可能允许该字段缺失，新写法下未必得到相同的分数。

## 同一份迁移说明里的响应格式变化

升级 1.0 不只影响查询。同一份迁移说明在 Return values 一节列出多项响应变化，见[第 303–324 行](https://github.com/elastic/elasticsearch/blob/v1.0.0/docs/reference/migration/migrate_1_0.asciidoc#L303-L324)。

首先是 `ok` 返回值：文档写明它已从所有响应体中移除，理由是它不提供有用信息。老代码里判断 `ok` 的地方都要改，参见[0.90 percolator 那篇](./es0-04-percolator-reverse-search-in-0-90.md)对这类写法的说明。

其次是 `found`、`not_found`、`exists` 被统一为 `found`。依赖具体返回值的分支逻辑要重新检查。

`fields` 参数的变化也需要留意：**返回的字段值一律是数组**，只有 `routing` 这类元数据仍为标量。文档还说明 `fields` 用于取已存储的字段，不再支持返回整个对象，也不再接受 `_source.fieldname` 这种形式，这类需求应改用 `_source` 过滤参数。

索引设置接口的返回结构也变了：设置以嵌套 JSON 对象返回，需要扁平格式时可以加 `?flat_settings`。解析响应时按扁平结构取值的代码需要调整。

最后是 `analyze` API 不再支持 text 响应格式，只支持 JSON 与 YAML。调试脚本若按文本解析输出，要改成解析 JSON。

这些变化与查询改写属于同一次升级，但容易被分别处理。建议把响应格式的检查放进同一份升级清单，避免只改查询而漏掉解析逻辑。

## 排查顺序与回退

升级后如果结果异常，建议按顺序排查：先确认旧查询名是否仍被接受；再确认替换后的查询语义是否一致；然后检查加权方式；最后检查 mapping 层面的改动。

每一步只改一类问题。同时修改查询名、加权与 mapping，出现异常时无法归因。

回退方案要分别考虑查询与数据。改回旧查询名只影响查询侧；若已经重建索引或改过 mapping，数据侧的恢复要单独安排。不能假定切回旧版本就能得到与升级前完全一致的结果。

保留旧查询模板与其适用版本，是回退的前提。只保留改写后的查询，回退时就只能凭记忆重建，风险不可控。

## 验收矩阵

| 测试组 | 必测边界 |
|---|---|
| `text` / `match` | 布尔、短语、短语前缀；显式分析器；全停用词；空输入 |
| `field` / `query_string` | 简写与对象写法；非法语法；特殊字符转义；显式字段前缀 |
| 脚本加权 | 原分数不为 1；脚本是否引用 `_score`；默认合并与 `replace`；缺失值；多值 |
| 多函数 | 多个过滤器同时命中；全部不命中；顺序变化；封顶位置 |
| `_boost` 迁移 | 原权重能否恢复；字段 norms 配置；旧索引与重建索引的差异 |
| `path` / `copy_to` | 同名字段；目标字段分析器；旧数据是否重新索引 |

矩阵里的每一项都应保留可解释的差异记录。若只比较“有没有报错”，很多语义差异会被漏掉。

业务数据也要参与验收。用真实文档的一个子集，分别在新旧写法下查询，比较命中集合与排序。完全一致的得分不现实，**若前几条大面积变化，应回到公式检查，而不是当作正常漂移**。

## 什么时候不该按默认替换

若旧查询依赖的是索引期 boost，且重建索引不可行，那么改成查询时脚本未必能复现原排序。这种情况下应先评估排序变化对业务的影响，再决定是否迁移。

若用户输入直接进入 `query_string`，语法解析会带来额外风险。更稳妥的做法是限定可查询字段，或对输入做转义，而不是把所有字段查询都改写成 `query_string`。

若 `custom_score` 场景里的脚本本身就依赖旧的行为（例如脚本结果直接作为最终分），迁移时必须明确合并方式。默认行为可能与旧行为不同，只比较“能否执行”是不够的。

## 两组查询名的对照写法

用前面的测试索引再验证两组替换。第一组是 `text` 到 `match`：

```console
GET /boost_lab_100/item/_search
{
  "size": 20,
  "query": {
    "match": {
      "title": {
        "query": "quick brown fox",
        "operator": "and"
      }
    }
  }
}
```

与旧的 `text` 查询比较时，要确认默认算子是否一致。旧写法默认的匹配要求需要按原版本文档核对，不能假定与 `match` 的默认行为相同。显式写出 `operator` 能减少这类差异。

第二组是 `field` 到 `query_string`：

```console
GET /boost_lab_100/item/_search
{
  "size": 20,
  "query": {
    "query_string": {
      "default_field": "title",
      "query": "quick AND fox"
    }
  }
}
```

这里显式指定 `default_field`，避免依赖默认字段配置。若原 `field` 查询的内容来自用户输入，还要测试特殊字符与非法语法，确认错误是否可接受。

两组替换都应准备同一批数据，分别执行并比较命中集合。**集合相同不代表排序相同，排序相同也不代表得分相同**，三者要分别记录。

## 为什么不能假设等价

替换文档给的是方向，不是等价证明。旧查询的默认值、分析行为、加权时机、以及响应格式都可能不同。把这些差异当成“正常漂移”，往往会在业务指标异常时才被发现。

正确的态度是把每次替换都当成一次需要验收的变更：固定输入、固定数据、逐项比较。差异出现时先定位到具体类别，再决定是调整写法还是接受变化。

这也解释了为什么本文不给出“改完就一定一样”的结论。没有实测，等价性就无法确认；而实测需要提供环境、数据与运行记录，本文两者都没有。

## 同一次升级里的 mapping 变化

查询之外，迁移说明还记录了 mapping 层面的改动。其中一项是 `multi_field` 类型被移除，改为让核心字段类型（除 `object` 与 `nested` 外）直接接受 `fields` 参数，见[第 223–227 行](https://github.com/elastic/elasticsearch/blob/v1.0.0/docs/reference/migration/migrate_1_0.asciidoc#L223-L227)。

这项改动与前文的 `path` 废弃同属 mapping 调整。它们的共同点是：改写方式相对明确，但目标字段是否有自己的 mapping、用什么分析器，都需要重新确认。

升级时把 mapping 改动与查询改动分开验证更省事：先确保索引结构与字段行为正确，再比较查询得分。否则字段行为异常会被误判成查询改写错误。

## 旧代码里怎么认出这一代写法

| 特征 | 说明 |
|---|---|
| 查询名是 `text` 或 `field` | 1.0 前需要改写为 `match` 或 `query_string` |
| mapping 里有 `_boost` | 文档级加权，需改为查询时加权 |
| mapping 里用 `path` | 已废弃，改用 `copy_to`，语义不同 |
| 查询名是 `custom_score`、`custom_boost_score` | 迁移说明写明不再支持 |
| 响应里判断 `ok` | 1.0 起该返回值已移除 |
| mapping 用 `multi_field` | 已移除，改用 `fields` |

认出之后按类别处理，不要一次性全局替换。每类改动都应有对应的验收数据，避免改完之后无法判断是哪一处引入了差异。

## 升级检查清单

1. 列出代码中所有旧查询名、`_boost`、`path`、`multi_field` 的使用位置。
2. 确认目标版本对每个名字的处理方式：拒绝、废弃警告还是仍可使用。
3. 改写查询名，保持数据与查询不变，比对命中集合与排序。
4. 处理加权方式，明确合并模式，并比较新旧得分。
5. 处理 mapping 改动，确认目标字段的 mapping 与分析行为。
6. 检查响应解析逻辑：`ok`、`found`、`fields`、设置结构、`analyze` 输出。
7. 保留旧查询模板与适用版本，作为回退依据。

清单的顺序遵循“先确认、再改写、后验收”。跳过第 2 步直接改写，最容易在后续排查中失去方向。

## 写在最后

1.0 迁移说明给出的是替换方向，不是等价保证。`text`、`field`、`_boost`、`path`、`custom_score` 系列各有不同的改写代价，其中 `_boost` 到查询时加权的差异最大。

迁移顺序可以按先改查询名、再改加权方式、最后处理 mapping 的路径走，每一步用固定数据比对集合与排序。这样即使出现差异，也能定位到具体是哪一类改动造成的。

## 参考

- [1.0 迁移说明（移除条目）@ v1.0.0](https://github.com/elastic/elasticsearch/blob/v1.0.0/docs/reference/migration/migrate_1_0.asciidoc#L348-L364)
- [`_boost` 字段与 function_score 替代 @ v1.0.0](https://github.com/elastic/elasticsearch/blob/v1.0.0/docs/reference/mapping/fields/boost-field.asciidoc)
- [function_score 合并模式 @ v1.0.0](https://github.com/elastic/elasticsearch/blob/v1.0.0/docs/reference/query-dsl/queries/function-score-query.asciidoc#L76-L84)
- [0.90 打分查询的合并](./es0-03-when-scoring-had-three-queries.md)

> 本文核对了固定标签的迁移说明、`_boost` 文档与 function_score 文档。请求为本文构造的历史验证方案，未启动集群、未运行历史测试；得分与等价性结论需按实际环境实测确认。


1.0 的迁移说明记录了一批移除：text 查询、field 查询、_boost 文档级加权、custom_score 系列。本文按固定标签核对这些条目，说明替换写法、不等价的地方，以及一组可复现的验收数据。

考古 | ES 1.0 旧查询和 _boost 要按什么顺序验收

1.0 的迁移说明记录了一批移除：text 查询、field 查询、boost 文档级加权、customscore 系列。

官方产研

云计算

后端

大数据

针对ES 1.0迁移，text/field查询改match/query_string，_boost用function_score替代，path改copy_to但语义不等价，custom_score系列统一改用function_score。需注意响应格式变化（ok移除、fields返回数组）。迁移后须用固定数据验证命中集合、排序及得分差异，尤其关注缺失字段、特殊字符输入等边界场景。

Elasticsearch Service

Elasticsearch 

代码解释

JSON

2026上云采购 | AI焕新·智启新局

bigdata-class

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

针对ES 1.0迁移，text/field查询改match/query_string，_boost用function_score替代，path改copy_to但语义不等价，custom_score系列统一改用function_score。需注意响应格式变化（ok移除、fields返回数组）。迁移后须用固定数据验证命中集...

考古 | ES 1.0 旧查询和 _boost 要按什么顺序验收-腾讯云开发者社区-腾讯云

考古 | ES 1.0 旧查询和 _boost 要按什么顺序验收

考古 | ES 1.0 旧查询和 _boost 要按什么顺序验收

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐