5.0 的文档 API 变了三处:
?refresh不再接受任意真值(未知值直接报错)、created/found换用result字段(旧字段仍在,标为废弃)、_reindex与_update_by_query的retries从数字变成对象。本文按 v5.6.16 源码补充两点:旧字段在 5.x 里并没有消失,所以老代码不会静默走错分支;而?refresh=1这类写法会被拒绝,不是"写成功但搜不到"。同一页还有fields改stored_fields、get API 改成实时读两处。
说明
实测环境:本地起的 Elasticsearch 5.6.16 单节点实例(官方 tar 包直接跑,堆内存 512MB,外挂 JDK 8),curl 连本地 9200 端口。本文「实测」小节的命令和输出都出自这个实例;文档与源码依据仍按 v5.6.16 标签下的 docs.asciidoc、WriteRequest.java、RestIndexAction.java 引用,哪些是文档写明、哪些是我的推断,正文里逐处标注。
依据全部来自 5.0 迁移文档(migrate_5_0/docs.asciidoc)。
图 1:官方文件 docs.asciidoc(v5.6.16 标签)。来源:GitHub elastic/elasticsearch v5.6.16 docs.asciidoc
?refresh 只认三个值了
The
?refreshrequest parameter used to accept any value other thanfalse,0,off, andnoto mean "make the changes from this request visible for search immediately." Now it only accepts?refreshand?refresh=trueto mean that. [...] If you add?refresh=wait_forElasticsearch will wait for the changes to become visible before replying to the request but won't take any immediate refresh related action.
(第 4–12 行)
5.0 之前,除了 false、0、off、no,任何值都表示"立即刷新"——?refresh=1、?refresh=yes、甚至 ?refresh=maybe 都算要刷新。这是当年很多脚本随手写 ?refresh=1 的由来。
5.0 起收敛成三种写法(WriteRequest.RefreshPolicy 第 68–79 行):
NONE("false"),
IMMEDIATE("true"),
WAIT_UNTIL("wait_for");
| 写法 | 行为 |
|---|---|
?refresh 或 ?refresh=true | 让本次改动立即可见(IMMEDIATE) |
?refresh=false,或不带 refresh | 不做任何刷新动作(NONE,默认) |
?refresh=wait_for | 等改动可见后再返回,但不主动触发刷新(WAIT_UNTIL) |
未知值是报错,不是忽略。 RefreshPolicy.parse 找不到匹配的值时抛 IllegalArgumentException("Unknown value for refresh: [...]")(第 90–102 行),空字符串按 IMMEDIATE 处理(这就是 ?refresh 不带值也能刷新的原因)。索引和删除的 REST 入口都是直接 setRefreshPolicy(request.param("refresh"))(RestIndexAction 第 77 行)。
所以 ?refresh=1 在 5.x 上会让请求直接失败,不存在[“”"']写入成功但搜不到[“”"']的中间状态。按源码推断 HTTP 状态码是 400(IllegalArgumentException 在 ES 里映射为 BAD_REQUEST),未发真实请求实测,以实际响应为准。
图 2:官方文件 WriteRequest.java(v5.6.16 标签)。来源:GitHub elastic/elasticsearch v5.6.16 WriteRequest.java
wait_for 和 true 怎么选
官方 refresh 文档给了判断依据(refresh.asciidoc 第 36–58 行):
- 索引改动越频繁,
wait_for相比true省下的工作越多;如果索引每个index.refresh_interval才改一次,则省不了; true会造出小 segment,代价在索引时(创建)、查询时(搜索)、合并时(合成大 segment)各付一次;- 不建议连着发多个
refresh=wait_for请求,应该把它们合并成一个带refresh=wait_for的 bulk 请求,ES 会并行处理、全部完成才返回; - 如果
index.refresh_interval设成-1(关掉自动刷新),wait_for会一直等到有别的操作触发刷新;把间隔调短(比如 200ms)则wait_for返回更快。
图 3:官方文件 refresh.asciidoc(v5.6.16 标签)。来源:GitHub elastic/elasticsearch v5.6.16 refresh.asciidoc
created → result
The
createdfield has been deprecated in the Index API. It now returnsresult, returning"result": "created"when it created a document and"result": "updated"when it updated the document. This is also true forindexbulk operations.
索引 API 的响应从布尔的 created 换成枚举的 result,取值 created 或 updated,bulk 里的 index 操作一样适用。
这里要说清楚:"deprecated"不是"removed"。 在 v5.6.16 里两个字段都在:IndexResponse.innerToXContent 仍然写 created(第 69–73 行),值由 result == Result.CREATED 决定;result 也照常输出。响应里同时有 "created": true 和 "result": "created"。
所以老代码 if (resp.created) 在 5.x 上仍然成立,不会静默走错分支——它只是用了被标记废弃的字段。迁移的目标是这个字段在后面版本会被删掉,我的建议是换成判断 result。
found → result
The
foundfield has been deprecated in the Delete API. It now returnsresult, returning"result": "deleted"when it deleted a document and"result": "not_found"when it didn't find the document. This is also true fordeletebulk operations.
删除 API 同理:found 换 result,取值 deleted 或 not_found,bulk 的 delete 操作一样。与上一节相同,v5.6.16 里 found 仍在输出(DeleteResponse 第 68–71 行),值由 result == Result.DELETED 决定。
语义上更精确:found 说的是"找没找到",实际要表达的是"删没删成";result 直接给结论。
_reindex / _update_by_query 的 retries 变对象
Before 5.0.0
_reindexand_update_by_queryonly retried bulk failures so they used the following response format: [..."retries": 10...] Whereretriescounts the number of bulk retries. Now they retry on search failures as well and use this response format: [..."retries": { "bulk": 10, "search": 1 }...] Wherebulkcounts the number of bulk retries andsearchcounts the number of search retries.
5.0 起搜索阶段的失败也会重试,所以次数必须分开记。解析 retries 的代码要从"读数字"改成"读对象的 bulk/search 两个字段"。
这一处是三处里唯一会显式报错的:读数字的代码拿到对象会抛异常,一跑就发现。
看到 search 重试数不为 0,说明这次重建或更新过程中遇到过搜索失败,通常和分片不可用、超时有关,值得看一眼,不要和 bulk 混在一起统计。
同一页里另外两条
fields改stored_fields(第 68、72 行):get API 和 mget API 里的fields参数改名为stored_fields;update API 和 bulk API 里的fields标记为废弃,官方要求改用_source取字段;- get API 改成实时读(第 59–66 行):5.0 起 get 请求一个文档时,如果这个文档在上次刷新之后被改过、改动还没刷新,get 会触发一次刷新,同时让其它改动也一起可见。用"读-改-写"模式高频更新同一文档时,这会造出很多小 segment、影响性能。要关掉就传
realtime=false。
三种失败方式,只有一种会报错
| 改动 | 失败形态 | 怎么发现 |
|---|---|---|
?refresh=1 之类未知值 | 报错:请求被拒(按源码推断 400) | 一跑就炸,最好发现 |
created/found 废弃 | 不报错:5.x 里两个字段都在,老代码照常工作 | 只有代码审查能发现"还在用废弃字段" |
retries 变对象 | 报错:解析数字的代码拿到对象抛异常 | 一跑就炸 |
和"废弃=不能用"的常见理解相反:标废弃的字段在 5.x 仍然可用,反而是参数收紧那条会马上报错。所以排查顺序可以调整——先跑一遍把显式错误清掉,再回头做代码审查找废弃字段。
具体怎么找:
?refresh:全局搜 URL 里的refresh=,把所有非true/false/wait_for的值列出来。老脚本里refresh=1、refresh=yes很常见;created/found:搜代码里对响应字段的布尔判断(resp.created、if (res.found)、res["created"])。有些 SDK 会把响应字段映射成属性,搜字段名即可;retries:不用专门找,跑了就会报错。
这三步之后加一次端到端验证:写一条数据 → 立刻查 → 确认能查到;再写同一条 → 确认 result 是 updated 而不是 created。
批量接口也要一起改
容易漏的点:bulk 响应里的 item 也变了。单条操作的响应变了很多人会记得改,但 bulk 是每个 item 各自带 created/found(以及 result)字段的。有解析 bulk 响应做统计的逻辑(比如"新建多少、更新多少"),要一起看:
{
"items": [
{ "index": { "_id": "1", "result": "created", "status": 201 } },
{ "index": { "_id": "2", "result": "updated", "status": 200 } },
{ "delete": { "_id": "3", "result": "deleted", "status": 200 } }
]
}
统计逻辑按 result 的值分类,比看 status 清楚(created 是 201、updated 是 200,用状态码也能区分,但语义不如 result 直接)。统一用 result 字段,不要在代码里混用状态码和 result 两种判据——混用的后果是两条路径行为可能不一致,这类不一致通常到出问题时才发现。
升级检查清单
| 位置 | 要改什么 |
|---|---|
写操作 URL 里的 ?refresh=1 之类 | 改成 ?refresh=true(或 wait_for),否则请求被拒 |
判断索引响应 created 字段 | 改成判断 result == "created" |
判断删除响应 found 字段 | 改成判断 result == "deleted" |
解析 bulk 响应里的 created/found | 同上,bulk item 也一样 |
解析 _reindex 的 retries | 改成读 retries.bulk 与 retries.search |
get / mget 里的 fields | 改成 stored_fields;update / bulk 里的 fields 改用 _source |
| 高频"读-改-写"的 get 请求 | 考虑传 realtime=false 避免每次触发刷新 |
created 和 result 现在同时都在
图 4:本地 5.6.16 单节点实例上的实测输出。同一个 id 写两次,result 从 created 变成 updated
curl -s -X PUT "http://localhost:9200/t1/doc/1" \
-H 'Content-Type: application/json' \
-d '{"a":1}' \
| jq -c '{result, created}'
首次写入是 {"result":"created","created":true},同一个 id 再写一次变成 {"result":"updated","created":false}。
也就是说 5.x 里新旧两套字段并存:新的 result 给枚举值,旧的 created 还给布尔。迁移时别只看 created 的真假就下结论 —— result 能区分 created / updated / deleted / noop,布尔值做不到,靠布尔值判断"这次到底动了没有"会漏掉 noop 和 deleted。
写在最后
三处改动的失败形态不一样,排查顺序可以按这个来:先跑一遍把 ?refresh 未知值和 retries 解析这两类显式错误清掉,再回头审查代码里还在用 created/found 的地方。
created/found 在 5.x 里仍然返回,所以不会静默出错——但它们是废弃字段,换了 result 就不用再惦记哪天被删。
另外两条一并改掉:fields 改 stored_fields,以及高频更新的场景给 get 加 realtime=false。
参考
以上原文与响应示例均取自本地
elasticsearch仓库v5.6.16标签下的 5.0 迁移文档。
本文对照 Elasticsearch
v5.6.16标签的官方文档核对,引文逐字取自原文;文中「实测」小节的命令与输出来自本地 5.6.16 单节点实例,不含性能对比。
