引言
在使用 Elasticsearch 进行数据分析时，我们经常需要查询海量数据。当数据量达到百万甚至千万级别时，传统的分页查询方式会遇到严重的性能问题。这时，游标查询（Scroll API） 就成了我们的救星。
本文将结合实际案例，详细介绍 Elasticsearch 游标查询的使用方法和最佳实践。
什么是游标查询？
游标查询是 Elasticsearch 提供的一种批量检索机制。与传统的 from/size 分页不同，游标查询会创建一个快照（snapshot），并在内存中维护这个查询上下文，允许我们分批获取所有匹配的数据，而不会受到深度分页性能问题的困扰。
为什么需要游标查询？
- 性能优势：避免深度分页带来的性能损耗
- 内存友好：不会一次性加载所有数据到内存
- 适合场景：数据导出、批量处理、数据分析等
实战操作指南
第一步：初始化游标查询
首先，我们需要发起一个游标查询请求，并设置游标的存活时间：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
| GET /yk_callinfo_v2/_search?scroll=5m
{
"_source": false,
"fields": ["_id","userId","planCustomerId"],
"size": 50000,
"query": {
"bool": {
"must": [
{
"range": {
"createdTime": {
"gte": "2026-04-01T00:00:00.000Z",
"lt": "2026-04-02T00:00:00.000Z"
}
}
},
{ "term": { "ai": 1 } },
{ "exists": { "field": "planCustomerId" } }
]
}
}
}
|
参数说明：
| 参数 | 说明 |
|---|
scroll=5m | 游标存活时间为 5 分钟，超时后会自动释放 |
size: 50000 | 每批次返回 50000 条数据 |
_source: false | 不返回完整的 _source 字段，节省带宽 |
fields | 只返回指定的字段 |
注意：scroll_id 是游标的唯一标识符，每次查询都会返回一个新的 scroll_id，下次查询时需要使用这个 ID。
第二步：继续查询下一批数据
使用上一步返回的 scroll_id，继续获取下一批数据：
1
2
3
4
5
| POST /_search/scroll
{
"scroll": "5m",
"scroll_id": "FGluY2x1ZGVfY29udGV4dF91dWlkDnF1ZXJ5VGhlbkZldGNoBRZTSm9hS0lWa1JMMjlVZWdnQTVDamt3AAAAAACboVkWQ0NIOF9CQk9UclNERHVSLTduNk1MdxY3cDRpY1lDeFFVcVZXR2VQYVJ6NFRRAAAAAACfpmIWNFVqVVAxUGtTS2VkWDVUcGRfWXRDQRZTSm9hS0lWa1JMMjlVZWdnQTVDamt3AAAAAACboVgWQ0NIOF9CQk9UclNERHVSLTduNk1MdxZrZU9xREtpWFQ0YUdJaHd3a3Q0WERRAAAAAACnZz4WRmdvem1WS0RUdTZ6eDA1M1NMdGh2dxZrZU9xREtpWFQ0YUdJaHd3a3Q0WFFRAAAAAACnZz0WRmdvem1WS0RUdTZ6eDA1M1NMdGh2dw=="
}
|
关键点：
- 每次执行后都会返回一个新的
scroll_id - 需要持续使用最新的
scroll_id 进行下一次查询 - 如果返回的结果为空，说明已经查询完所有数据
第三步：释放游标资源
查询完成后，记得手动删除游标，释放服务器资源：
1
2
3
4
| DELETE /_search/scroll
{
"scroll_id": "FGluY2x1ZGVfY29udGV4dF91dWlkDnF1ZXJ5VGhlbkZldGNoBRZrZU9xREtpWFQ0YUdJaHd3a3Q0WFFRAAAAAACqwqwWRmdvem1WS0RUdTZ6eDA1M1NMdGh2dxZTSm9hS0lWa1JMMjlVZWdnQTVDamt3AAAAAACe0BQWQ0NIOF9CQk9UclNERHVSLTduNk1MdxZTSm9hS0lWa1JMMjlVZWdnQTVDamt3AAAAAACe0BMWQ0NIOF9CQk9UclNERHVSLTduNk1MdxY3cDRpY1lDeFFVcVZXR2VQYVJ6NFRRAAAAAACi23wWNFVqVVAxUGtTS2VkWDVUcGRfWXRDQRZrZU9xREtpWFQ0YUdJaHd3a3Q0WFFRAAAAAACqwq0WRmdvem1WS0RUdTZ6eDA1M1NMdGh2dw=="
}
|
也可以一次性删除多个游标：
1
2
3
4
5
6
7
8
| DELETE /_search/scroll
{
"scroll_id": [
"scroll_id_1",
"scroll_id_2",
"scroll_id_3"
]
}
|
使用场景
1. 数据导出
当需要将 Elasticsearch 中的数据导出到外部系统（如 MySQL、CSV 文件）时，游标查询是最佳选择：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
| from elasticsearch import Elasticsearch
es = Elasticsearch("http://localhost:9200")
# 初始化游标
response = es.search(
index="yk_callinfo_v2",
scroll="5m",
size=50000,
body={
"query": {
"range": {
"createdTime": {
"gte": "2026-04-01T00:00:00.000Z",
"lt": "2026-04-02T00:00:00.000Z"
}
}
}
}
)
scroll_id = response['_scroll_id']
total_records = 0
# 循环获取数据
while True:
hits = response['hits']['hits']
if not hits:
break
# 处理数据
for hit in hits:
# 写入数据库或文件
process_record(hit)
total_records += len(hits)
# 获取下一批数据
response = es.scroll(scroll_id=scroll_id, scroll="5m")
# 释放游标
es.clear_scroll(scroll_id=scroll_id)
print(f"总共处理了 {total_records} 条记录")
|
2. 批量数据分析
对大量数据进行统计分析时，可以分批处理，避免内存溢出。
3. 数据迁移
在不同 Elasticsearch 集群之间迁移数据时，使用游标查询可以高效地批量读取数据。
最佳实践
1. 合理设置存活时间
- 游标存活时间不宜过长，避免占用过多内存
- 一般设置为 1-5 分钟即可
- 如果处理速度慢，可以每次查询时重置存活时间
2. 控制批次大小
size 参数建议设置为 5000-50000- 太大会导致单次查询过慢
- 太小会增加网络开销
3. 及时释放资源
- 查询完成后务必删除游标
- 即使超时自动释放，手动删除更安全
- 可以设置定时任务清理残留游标
4. 使用 search_after 替代方案
对于实时搜索场景，推荐使用 search_after 参数，它不会创建快照，资源消耗更低。
注意事项
- 游标查询不是实时的：它基于查询时刻的索引快照，后续的数据变更不会反映在结果中
- 内存消耗：每个游标都会占用一定的内存，并发游标过多会影响集群性能
- 不适用于用户请求：游标查询适合后台任务，不适合实时用户请求
- 排序限制：使用游标查询时，建议使用
_doc 排序以获得最佳性能
总结
Elasticsearch 游标查询是处理海量数据的利器，通过合理使用可以高效地完成数据导出、批量分析等任务。记住关键点：
- 设置合适的游标存活时间
- 控制每批次的数据量
- 及时释放游标资源
- 根据场景选择游标查询或 search_after
希望本文能帮助你在实际工作中更好地使用 Elasticsearch 游标查询！
参考资料：