> 2.1 里两件事一起发生：`scan` 这种 search type 被废弃，改成"按 `_doc` 排序的 scroll"；同时 `from + size` 超过 `index.max_result_window`（默认 10000）时直接报错，不再静默返回。前者是写法替换，后者是会让老代码失败的行为变更。

## **说明**

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

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

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

*图 1：官方文件 migrate_2_1.asciidoc（v2.4.6 标签）。来源：GitHub elastic/elasticsearch v2.4.6 migrate_2_1.asciidoc*


## 这两件事其实是同一件事

2.1 的这一节把"废弃 scan"和"给 from+size 加上限"放在一起，两件事针对的都是深度遍历数据。这是对迁移文档的归纳，文档本身没有这样写。

区别只在于方向：

* `scan` 的替代方案是"想全量遍历就用 scroll"，把这条路做顺、做到和 scan 一样的效率；
* `max_result_window` 是把"用 from/size 硬翻到底"这条路堵上，因为它会把节点堆内存吃光。

两条里会让老代码失败的是第二条。第一条只是写法过时（scan 还能用，只是废弃），第二条是行为变更：以前深分页请求会一直处理，2.1 起超过上限直接返回错误。"能跑"变成"直接失败"，业务方看到的是接口报错，所以排查时它排在前面。

所以我的建议是先看有没有深分页调用，再改 scan 的写法，后者在废弃阶段还能用。

![02-DefaultSearchContext](https://developer.qcloudimg.com/http-save/yehe-7348459/57fab26d050117eceb2cb1912b21aced.png)

*图 2：官方文件 DefaultSearchContext.java（v2.4.6 标签）。来源：GitHub elastic/elasticsearch v2.4.6 DefaultSearchContext.java*


## `search_type=scan` 废弃

2.1 迁移文档（[migrate_2_1.asciidoc @ v2.4.6](https://github.com/elastic/elasticsearch/blob/v2.4.6/docs/reference/migration/migrate_2_1.asciidoc)）的说明：

> The `scan` search type has been deprecated. All benefits from this search type can now be achieved by doing a scroll request that sorts documents in `_doc` order.

替代写法：

```sh
GET /my_index/_search?scroll=2m
{
  "sort": [
    "_doc"
  ]
}
```

官方补了一句性能上的保证：

> Scroll requests sorted by `_doc` have been optimized to more efficiently resume from where the previous request stopped, so this will have the same performance characteristics as the former `scan` search type.

也就是说，替代方案的性能特征与 scan 相同，不是用 scroll 将就。

`scan` 是一种特殊的 search type，请求要带 `search_type=scan&scroll=...`。按 scan 的设计，首个响应只返回 `_scroll_id`，需要再发 scroll 请求才拿得到数据，这是本文的理解，没有在 2.x 上实跑核对。若如此，改成 `_doc` 排序的 scroll 后，首个响应就是正常的搜索响应，客户端不用再处理"第一个响应没有数据"这个分支，迁移时可以删掉。

同一节里 `search_type=count` 也再次被标记废弃（2.0 已经说过一次），替代写法是 `size: 0`：

```sh
GET my_index/_search
{
  "aggs": {...},
  "size": 0
}
```


## `from + size` 的上限

这是 2.1 里会让老代码失败的行为变更：

> Elasticsearch will now return an error message if a query's `from` + `size` is more than the `index.max_result_window` parameter. This parameter defaults to 10,000 which is safe for almost all clusters.

在此之前，深分页请求不受这个限制。2.1 起超过阈值直接返回错误，默认值 10000，见 [DefaultSearchContext 第 95 行](https://github.com/elastic/elasticsearch/blob/v2.4.6/core/src/main/java/org/elasticsearch/search/internal/DefaultSearchContext.java#L95)。

为什么要限制：文档说，超过这个值会在每次搜索、每个分片上占用大量堆内存。机制上，每个分片都要先取出并排序 `from + size` 条，协调节点再合并这些结果，所以分页越深，单次请求占的内存越多，并发一多就会给节点造成压力。

文档给的建议很明确：

> It's safest to leave this value as it is and use the scroll api for any deep scrolling but this setting is dynamic so it can raised or lowered as needed.

`index.max_result_window` 是动态设置，可以调，但官方建议别调，深翻页改用 scroll。

![03-api-conventions.asciidoc](https://developer.qcloudimg.com/http-save/yehe-7348459/66c724c37b97ac36215886ce002288dc.png)

*图 3：官方页面 api-conventions.asciidoc（v2.4.6 标签）。来源：GitHub elastic/elasticsearch v2.4.6 docs/reference/api-conventions.asciidoc*


## 遇到这个错误怎么办

错误信息见 [DefaultSearchContext 第 213–217 行](https://github.com/elastic/elasticsearch/blob/v2.4.6/core/src/main/java/org/elasticsearch/search/internal/DefaultSearchContext.java#L213-L217)，开头是 `Result window is too large, from + size must be less than or equal to: [10000]`，后面还提示去看 scroll API，以及这个限制由索引级参数 `index.max_result_window` 设置。处理路径按场景分：

导出或遍历全量数据：不建议用 `from/size` 翻页，用按 `_doc` 排序的 scroll，也就是上面替代 `scan` 的写法。

产品上的"跳到第 N 页"：先确认真有这个需求。如果访问日志里深页请求来自爬虫或循环写错，可以在应用层限制最大页码。确实要支持，2.x 里没有 `search_after`：在 v2.4.6 源码里搜过，它在 2.x 不存在，要到后续版本才引入。2.x 上要么限制页码，要么用 scroll 配合应用层缓存，要么调大 `index.max_result_window` 并接受相应的堆内存代价。

确实需要放宽阈值：动态调大 `index.max_result_window`：

```json
PUT my_index/_settings
{
  "index.max_result_window": 50000
}
```

调之前先估算代价：窗口越大，每个分片的排序缓冲和协调节点的合并缓冲越大，一个深分页请求占的堆内存也越多。调完要观察节点堆使用和 GC。


## 这笔内存账怎么算

文档只说深分页会占堆内存，没给量级。下面按它的机制给一个估算方法，用来判断自己的集群能不能承受：协调节点要合并的结果约为 `分片数 × (from + size)` 条。假设索引有 5 个分片，请求是 `from=9990, size=10`：

```text
5 个分片 × (9990 + 10) = 50000 条
```

为了返回 10 条数据，协调节点要合并约 5 万条的排序信息，这还只是一个请求；10 个并发就是 50 万条。每个分片本地还要各自排出前 1 万条，开销也按这个量级。

判断方法是把 `分片数 × (from + size)` 乘以并发数，看数量级能不能接受。这个公式来自机制推导，没有实测，每条结果实际占多少内存取决于排序字段和文档大小。

压垮集群的通常是循环写错的客户端，正常业务分页很少到这个量级：`for (page=0; ; page++)` 没有终止条件的话，`from` 会一路增大。有了 10000 的硬上限，这类请求第一次越界就会报错。我的建议是这个默认值不要动。


## 一份能跑通的全量遍历示例

文档只说"改用按 `_doc` 排序的 scroll"，没给完整流程。下面补一个三段式的版本，没有在 2.x 上实跑，请先在测试环境验证：

```sh
# 1) 初始化：拿到第一批和 _scroll_id
curl -s -XGET 'localhost:9200/my_index/_search?scroll=5m&size=1000' -d '{
  "sort": ["_doc"],
  "query": { "match_all": {} }
}' > /tmp/p1.json

# 2) 续读：取下一批，直到 hits 为空；每次响应都会返回新的 _scroll_id，下一次要用最新的
SCROLL_ID=$(python3 -c "import json;print(json.load(open('/tmp/p1.json'))['_scroll_id'])")
curl -s -XGET "localhost:9200/_search/scroll?scroll=5m&scroll_id=$SCROLL_ID" > /tmp/p2.json

# 3) 用完清理：scroll 上下文占资源，不清理要等超时
curl -s -XDELETE "localhost:9200/_search/scroll" -d "{\"scroll_id\":[\"$SCROLL_ID\"]}"
```

第 2 步里，scroll 文档的说明是每次请求都会返回新的 `_scroll_id`，只有最新的那个有效，所以循环里要更新变量，不能一直用第一次拿到的 id。第 3 步要强调的是：scroll 上下文是服务端资源，不清理就要等超时才释放。遍历结束后立刻清理，用 try/finally 包住，异常路径也要清。


## 迁移检查（附排查命令）

```sh
# 找 scan 用法
grep -rn "search_type.*scan\|searchType.*scan" . | head -20

# 找深分页：from 大于几千的都要逐个看
grep -rn "\"from\"\|from=\|\.from(" --include=*.py --include=*.java --include=*.js . | head -30
```

* 搜 `search_type=scan`，改成 `sort: ["_doc"]` 的 scroll，并去掉"第一个响应为空"的客户端分支；
* 搜分页逻辑，算一下最大 `from + size` 会不会超过 10000；
* 检查有没有依赖"深分页不会报错"的批量任务，这类任务升级 2.1 后会直接失败，而不是慢一点。


## 写在最后

全量遍历用 scroll（`_doc` 排序），不要用 `from/size` 翻到底。`index.max_result_window` 能调，但它是保护阈值，调大只是把出问题的时间往后推，深分页的需求本身应该换个做法。文档说默认值对"几乎所有集群"是安全的，同意这个判断，需要超过 10000 的分页多半是用法问题。

`index.max_result_window` 是索引级设置。要改的话，想清楚是只改当前索引，还是用索引模板批量改，只改当前索引的话，新建的索引仍是 10000。

文中命令按 2.x 的接口写的，跨版本使用前请用实际版本的手册核对一次。


## 参考

- [migrate_2_1.asciidoc @ v2.4.6](https://github.com/elastic/elasticsearch/blob/v2.4.6/docs/reference/migration/migrate_2_1.asciidoc)

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


2.1 里两件事一起发生：scan 这种 search type 被废弃，改成"按 _doc 排序的 scroll"；同时 from + size 超过 index.max_result_window（默认 10000）时直接报错，不再静默返回。前者是写法替换，后者是会让老代码失败的行为变更。

考古｜深分页翻过一万条就被拦下，ES 2.1 起 scan 交给了 scroll

2.1 里两件事一起发生：scan 这种 search type 被废弃，改成"按 doc 排序的 scroll"；

官方产研

云计算

后端

大数据

Elasticsearch 2.1中scan搜索类型废弃，改用按_doc排序的scroll实现全量遍历；同时from+size超过index.max_result_window（默认10000）将直接报错。本文详解迁移方案、错误处理及scroll优化写法，适用于腾讯云ES服务。

Elasticsearch Service

Elasticsearch 

代码解释

GitHub

JSON

Java

让每一个 Agent，都跑在云上

bigdata-class

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

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

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

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

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

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

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

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

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

社区新版编辑器体验调研

考古｜深分页翻过一万条就被拦下，ES 2.1 起 scan 交给了 scroll-腾讯云开发者社区-腾讯云

考古｜深分页翻过一万条就被拦下，ES 2.1 起 scan 交给了 scroll

考古｜深分页翻过一万条就被拦下，ES 2.1 起 scan 交给了 scroll

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐