> 5.0 把数字字段的索引结构换成 BKD tree。迁移文档说磁盘占用预计更少、范围查询预计更快，代价是数字字段上的 `term` 查询不再有文档频率的贡献，一律返回常量分。读 v5.6.16 源码能补上文档没写的一条：这个变化只发生在 5.0.0-alpha2 及之后创建的索引上，老索引沿用旧结构，升级后分数不会变，要等重建索引才会变。

## **说明**

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

来源和边界先交代：本文的依据出自 v5.6.16 标签下的官方文件（`mapping.asciidoc`、`LegacyNumberFieldMapper.java`、`NumberFieldMapper.java`），文中引用的原文均来自这些文件。我没有启动集群、也没有跑测试，示例取自官方示例；哪些是文档写明、哪些是我的推断，正文里逐处标注。

![01-mapping](https://developer.qcloudimg.com/http-save/yehe-7348459/bc3fce06210c147eb73ef969fae98408.png)

*图 1：官方文件 mapping.asciidoc（v5.6.16 标签）。来源：GitHub elastic/elasticsearch v5.6.16 mapping.asciidoc*

## 官方说明

5.0 迁移文档（[migrate_5_0/mapping.asciidoc 第 39–77 行](https://github.com/elastic/elasticsearch/blob/v5.6.16/docs/reference/migration/migrate_5_0/mapping.asciidoc#L39-L77)）的原文：

> Numeric fields are now indexed with a completely different data-structure, called BKD tree, that is expected to require less disk space and be faster for range queries than the previous way that numerics were indexed.

> Term queries will return constant scores now, while they used to return higher scores for rare terms due to the contribution of the document frequency, which this new BKD structure does not record. If scoring is needed, then it is advised to map the numeric fields as `keyword`s too.

文档用的是 "expected to"，没有给磁盘占用或查询耗时的数字，本文也不编数字。同一节还有一句：`precision_step` 参数现在不再有意义，在 5.0 及以后创建的索引上会被拒绝。

![02-LegacyNumberFieldMapper](https://developer.qcloudimg.com/http-save/yehe-7348459/1ec7507589d02999ba08559d67c837c6.png)

*图 2：官方文件 LegacyNumberFieldMapper.java（v5.6.16 标签）。来源：GitHub elastic/elasticsearch v5.6.16 LegacyNumberFieldMapper.java*

## 换了什么

旧实现按 `precision_step` 把一个数值拆成多个不同精度的前缀词项写进倒排索引。默认的步长在 [LegacyNumberFieldMapper 第 51–54 行](https://github.com/elastic/elasticsearch/blob/v5.6.16/core/src/main/java/org/elasticsearch/index/mapper/LegacyNumberFieldMapper.java#L51-L54)：8 位类型是 `Integer.MAX_VALUE`，16 位和 32 位是 8，64 位是 16。所以数字的每个取值在倒排里都对应词项，有文档频率。

新实现在 [NumberFieldMapper](https://github.com/elastic/elasticsearch/blob/v5.6.16/core/src/main/java/org/elasticsearch/index/mapper/NumberFieldMapper.java) 里用 Lucene 的点（point）类型，例如 `IntPoint`、`LongPoint`、`DoublePoint`、`HalfFloatPoint`、`FloatPoint`。点不进倒排词典，没有词项，也就没有文档频率。

![03-function-score-query](https://developer.qcloudimg.com/http-save/yehe-7348459/1674060647dcb099dcae5ef6f49f1778.png)

*图 3：官方文件 function-score-query.asciidoc（v5.6.16 标签）。来源：GitHub elastic/elasticsearch v5.6.16 function-score-query.asciidoc*

## 看索引创建版本

源码里选用哪种实现取决于索引的创建版本。[NumberFieldMapper 第 136–140 行](https://github.com/elastic/elasticsearch/blob/v5.6.16/core/src/main/java/org/elasticsearch/index/mapper/NumberFieldMapper.java#L136-L140)的 `TypeParser.parse` 开头：

```java
if (parserContext.indexVersionCreated().before(Version.V_5_0_0_alpha2)) {
    switch (type) {
    case BYTE:
        return new LegacyByteFieldMapper.TypeParser().parse(name, node, parserContext);
    ...
```

创建版本早于 `5.0.0-alpha2` 的索引，数字字段仍然走 `Legacy*FieldMapper`，也就是旧的词项结构。所以这篇文章讲的变化有一个前提：

- 2.x 创建的索引升到 5.x，数字字段结构不变，`term` 查询的分数也不变；
- 在 5.0.0-alpha2 及之后新建的索引，数字字段才是 BKD 结构，`term` 查询才是常量分；
- 重建索引（reindex 到新索引）的时刻，才是分数变化真正发生的时刻。

这一点会影响排查顺序：升级当天结果排序没变化，不代表没有风险，风险推迟到了重建索引之后。同一个别名后面如果新老索引并存，同一个查询在两类索引上的分数会不一致，混排时尤其容易看出来。以上是读源码的推断，没有在集群上跑过。

## 打分上的影响

旧结构里数字的每个取值是一个词项，有文档频率，稀有值能拿到更高的 IDF 分。新结构不记录这个信息。看 [NumberFieldMapper 第 604–609 行](https://github.com/elastic/elasticsearch/blob/v5.6.16/core/src/main/java/org/elasticsearch/index/mapper/NumberFieldMapper.java#L604-L609)，`integer` 的 `termQuery` 返回的是 `IntPoint.newExactQuery(field, v)`；`long` 在第 741–746 行同理，返回 `LongPoint.newExactQuery`。点查询是 Lucene 的 constant score 查询，没有 TF-IDF 的贡献。字段上配置了 `boost` 时，[第 955–962 行](https://github.com/elastic/elasticsearch/blob/v5.6.16/core/src/main/java/org/elasticsearch/index/mapper/NumberFieldMapper.java#L955-L962)的 `termQuery` 会用 `BoostQuery` 包一层，所以 boost 仍然有效，只是乘在常量上。

后果是：如果结果排序依赖"稀有数字值排前面"这种隐式 IDF 行为，在新建索引上排序会变平，表现为最相关的结果不再靠前。

`match` 查询落在数字字段上也是同样的结果。[MatchQuery 第 290–292 行](https://github.com/elastic/elasticsearch/blob/v5.6.16/core/src/main/java/org/elasticsearch/index/search/MatchQuery.java#L290-L292)最终调用 `fieldType.termQuery`，数字字段的 `termQuery` 就是上面的点查询。这是读代码的推断，没有逐条验证。

## 官方给的解决方法

> If scoring is needed, then it is advised to map the numeric fields as `keyword`s too.

> Note that this `keyword` mapping do not need to replace the numeric mapping. For instance if you need both sorting and scoring on your numeric field, you could map it both as a number and a `keyword` using multi-fields.

用多字段同时映射成数字和 keyword：

```json
PUT my_index
{
  "mappings": {
    "my_type": {
      "properties": {
        "my_number": {
          "type": "long",
          "fields": {
            "keyword": { "type": "keyword" }
          }
        }
      }
    }
  }
}
```

这样 `my_number` 保留数字语义，范围查询、数值排序都用它；`my_number.keyword` 作为词项存在，需要按词项打分时查这个子字段。两者并存，不是二选一。

## 多数场景不用处理，要处理的是"靠 IDF 排序"的查询

数字字段上的查询大多是范围过滤（时间、价格、年龄区间）或精确匹配（`status: 1`、`type: 3`）。精确匹配本来不需要相关性，匹配就是匹配，固定分合理。范围查询在 filter context 里不计分，常量分和旧行为也没有差别。

真正会受影响的是少数用法：

- 靠数字 `term` 的 IDF 做"稀有值优先"；
- 多个数字 `term` 用 `should` 组合，以前各子句的分不同，现在都是常量，组合后的相对顺序会变；
- 数字字段参与 `match`，同样落到常量分。

遇到"重建索引后排序变平"，先问这个字段是不是本来就不该参与算分。如果答案是应该，就加 keyword 子字段；如果只是想表达"值大更重要"，用 `function_score` 显式写。

## 稀有值优先和 function_score 不是一回事

`function_score` 的 `field_value_factor` 用的是字段的数值本身（[文档](https://github.com/elastic/elasticsearch/blob/v5.6.16/docs/reference/query-dsl/function-score-query.asciidoc)里 `modifier` 有 `log1p`、`ln`、`sqrt` 等），表达的是"值大排前面"，不是"值稀有排前面"：

```json
{
  "query": {
    "function_score": {
      "query": { "match_all": {} },
      "field_value_factor": { "field": "price", "factor": 1.2, "modifier": "log1p" }
    }
  }
}
```

所以两种诉求要分开处理：想要"价格高的排前面"，用 `field_value_factor`，意图写在查询里；想要真正的"稀有值得分更高"，只能保留词项，也就是加 `keyword` 子字段，让它参与 TF-IDF。把后者改写成前者会改变语义。

## 怎么查、怎么改

第一步，找出哪些查询在数字字段上用 `term` 或 `match`。先拿到业务代码和保存的查询模板，按字段名人工筛选；字段名猜不准，最后要用 mapping 确认类型：

```sh
curl -s 'localhost:9200/my_index/_mapping?pretty' | grep -B1 -A1 -E '"type" : "(integer|long|short|byte|double|float|half_float|scaled_float)"'
```

第二步，确认索引的创建版本，判断它是不是 BKD 结构：

```sh
curl -s 'localhost:9200/my_index/_settings?pretty' | grep created
```

输出是数字形式的版本号，创建于 5.0.0-alpha2 之前的索引还是旧结构。

第三步，在新建索引上用 explain 对比数字字段和 keyword 子字段。预期是数字字段上的 `term` 分数不随值稀有程度变化，keyword 子字段上会不同，这是按源码推断的，请在测试集群上确认：

```sh
curl -s 'localhost:9200/my_index/_search?explain=true' -d '{
  "query": { "term": { "my_number": 3 } }
}'
curl -s 'localhost:9200/my_index/_search?explain=true' -d '{
  "query": { "term": { "my_number.keyword": "3" } }
}'
```

第四步，需要打分就按上面的多字段方式改 mapping。改 mapping 不会给老数据补上子字段，要重建索引。

## 升级前后怎么对比

挑一批有代表性的查询，升级前记录前 10 条的 `_id` 和 `_score`，重建索引后用同样的查询再跑一次做对比。分数对不上就查是不是数字字段参与了算分。这个对比成本低，能在业务方反馈之前发现排序变化。

收益侧可以对比同一批数据重建前后的磁盘占用和范围查询耗时：

```sh
curl -s 'localhost:9200/_cat/indices?v&bytes=b' | grep my_index
```

官方文档只说"预计"更省、更快，实际差异取决于数据，以你自己的对比为准。

## 写在最后

数字字段换成 BKD 之后，`term` 查询变成点查询，返回常量分。它只发生在 5.0.0-alpha2 及之后创建的索引上，老索引升级后不变，重建索引时才会变。

多数场景不需要处理。靠 IDF 排序的少数查询，要么给数字字段加 `keyword` 子字段，要么按真实意图改成 `function_score`；这两者表达的意思不同，不能互相替换。重建前后做一次 top N 的 id 和分数对比，是最便宜的验证。

## 参考

- [migrate_5_0/mapping.asciidoc @ v5.6.16](https://github.com/elastic/elasticsearch/blob/v5.6.16/docs/reference/migration/migrate_5_0/mapping.asciidoc)

> 本文对照 Elasticsearch `v5.6.16` 标签的官方文档核对，引文逐字取自原文。撰写时未启动集群、未运行测试。


5.0 把数字字段的索引结构换成 BKD tree。迁移文档说磁盘占用预计更少、范围查询预计更快，代价是数字字段上的 term 查询不再有文档频率的贡献，一律返回常量分。读 v5.6.16 源码能补上文档没写的一条：这个变化只发生在 5.0.0-alpha2 及之后创建的索引上，老索引沿用旧结构，升级后分数不会变，要等重建索引才会变。

考古｜ES 5.0 换了数字字段的词项结构，老索引却还按旧结构打分

5.0 把数字字段的索引结构换成 BKD tree。

官方产研

云计算

后端

大数据

Elasticsearch 5.0 起数字字段索引改为 BKD 树结构，term 查询返回常量分，不再计入文档频率。此变更仅影响 5.0.0-alpha2 后新建索引，旧索引升级后不变，需重建索引才生效。腾讯云 ES 同样适用。若需数字字段评分，建议添加 keyword 多字段。重建前对比 topN 分数可快速验证排序变化。

代码解释

Java

让每一个 Agent，都跑在云上

bigdata-class

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

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

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

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

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

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

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

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

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

社区新版编辑器体验调研

Elasticsearch 5.0 起数字字段索引改为 BKD 树结构，term 查询返回常量分，不再计入文档频率。此变更仅影响 5.0.0-alpha2 后新建索引，旧索引升级后不变，需重建索引才生效。腾讯云 ES 同样适用。若需数字字段评分，建议添加 keyword 多字段。重建前对比 topN 分数可快速验证排序...

考古｜ES 5.0 换了数字字段的词项结构，老索引却还按旧结构打分-腾讯云开发者社区-腾讯云

考古｜ES 5.0 换了数字字段的词项结构，老索引却还按旧结构打分

考古｜ES 5.0 换了数字字段的词项结构，老索引却还按旧结构打分

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐