2.0 迁移文档的 Search changes 一节,单条看都不大,但升级后容易造成结果结构不一致:partial fields 被删除改用 source filtering;
search_type=count废弃,改用size=0;count API 内部变成 search API,失败时从"返回 count=0"变成抛异常;stored 元字段默认返回且移到顶层;另外require_field_match默认值改变会让高亮静默消失。
来源和边界先交代:本文的依据出自 v2.4.6 标签下的官方文件(search.asciidoc),文中引用的原文均来自这些文件。示例取自官方示例;文末「在 7.17.29 上跑一遍」里的命令与响应取自本机实测。哪些是文档写明、哪些是我的推断,正文里逐处标注。
实测环境:本地另起一个 Elasticsearch 7.17.29 单节点实例(官方 tar 包,端口 9200,独立 path.data);本机没有 0.90 / 1.x / 2.x 二进制,所以这里验的是这些旧写法在较新版本上的当前行为,不是当年的执行过程。文末「在 7.17.29 上跑一遍」里的命令与响应均取自该实例。
图 1:官方文件 search.asciidoc(v2.4.6 标签)。来源:GitHub elastic/elasticsearch v2.4.6 search.asciidoc
2.0 的定位是"清理版本":把 1.x 攒下的兼容包袱一次清掉——查询和过滤器合并(query 与 filter 合并)、facets 和 rivers 移除(2.0 的删除清单)、mapping 收紧(2.0 的 mapping 冲突检查)都在那一批里。Search changes 这一节属于其中"小而密"的部分:单独拆出来,哪一条都不足以单独发一个 breaking 公告,但加在一起,你升级后会发现响应结构、失败行为、参数名全对不上。
判断是:这类"小而密"的改动最容易被漏掉,因为每一条都不触发报错。会报错的改动(参数删了、字段没了)第一次调用就能发现;不报错但语义变了的(count 失败改抛异常、元字段挪位置、script field 少包一层数组),要等数据不对了才回头查,那时排查方向往往已经跑偏:先怀疑查询条件、数据、分片,最后才想到是版本行为变了。
所以大版本升级前,我建议把迁移文档里"没有报错但改了行为"的条目单独摘出来,一条条对照代码找;有报错的那批可以等运行时暴露。下面的检查顺序把 count API 的行为变化排在最前面,理由也在这里。
这一节看着都是小改动,但风险不同。下面的等级是按"是否报错、是否只在失败时出现"排的:
require_field_match 默认值(高):请求不报错,只是高亮片段消失,容易被当成数据问题。hit.fields.X 变成 hit.X。search_type=count 与 partial fields(低):这两个是显式的参数或字段移除,要么报错,要么结果不对,马上就能发现。所以升级 2.0 时,检查顺序建议倒过来:先排查所有 count API 的调用点,再看高亮和响应解析,最后才是那两个会显式报错的。
图 2:官方页面 removals.asciidoc(v2.4.6 标签)。来源:GitHub elastic/elasticsearch v2.4.6 docs/reference/migration/migrate_2_0/removals.asciidoc
2.0 移除了 partial fields,改用 source filtering(migrate_2_0/search.asciidoc @ v2.4.6):
Partial fields have been removed in favor of source filtering.
1.x 的 partial fields 靠 partial_fields 参数配合 include/exclude 的通配匹配抽取字段片段。2.0 统一到 _source 过滤:
GET my_index/_search
{
"_source": { "includes": [ "obj1.*", "obj2.*" ], "excludes": [ "*.description" ] },
"query": { "match_all": {} }
}迁移文档只说了"改用 source filtering",没有给逐项对照。我的默认做法是改写后拿新旧两种请求各跑一遍,比较返回的字段是否一致。
search_type=count 废弃count 这种 search type 被废弃。它带来的好处现在用默认的 query_then_fetch 加 size: 0 就能拿到:
GET my_index/_search
{
"size": 0,
"query": { "term": { "status": "published" } }
}聚合场景尤其常见这个组合:只想要聚合结果,不要命中文档。
图 3:官方页面 query_dsl.asciidoc(v2.4.6 标签)。来源:GitHub elastic/elasticsearch v2.4.6 docs/reference/migration/migrate_2_0/query_dsl.asciidoc
count API 在 2.0 里变成了 search API(size=0)的快捷方式。由此带来一个容易被忽略的差异:
As a result, a total failure will result in an exception being returned rather than a normal response with
countset to0and shard failures.
1.x 里请求彻底失败时,count API 可能返回一个正常响应,只是 count 为 0 并带上 shard failures;2.0 会直接抛异常。这对调用方的错误处理是破坏性的——原来"只看 count 数字、不检查 shard failures"的代码,在 2.0 会收到 HTTP 错误码,如果该分支没做异常处理就会崩。
正确的适配是:显式捕获异常,或者像搜索一样检查 _shards.failed。
这条改动平时看不出来,需要主动造一次"所有分片都失败"的请求。文档没有给复现办法,下面是构造的思路:用一个无法解析的查询,让每个分片都失败。本文没有在 1.x 和 2.0 上跑过,预期来自文档那句"total failure 会返回异常",实际响应要以环境为准。
curl -i -XGET 'localhost:9200/my_index/_count' -d '{
"query": { "no_such_query_type": {} }
}'按文档,1.x 对整体失败可能回一个正常响应,count 为 0 并带 shard failures;2.0 起会返回异常。不存在的索引不适合当复现用例:它是否在两个版本都直接报错,文档没有说,本文没有验证。把这个差异写进集成测试,比读文档可靠。
适配时同时处理两条路径:捕获异常,也检查分片失败。
GET my_index/_count
{
"query": { "term": { "status": "published" } }
}拿到响应后检查 _shards.failed > 0,同时代码里包一层异常处理,1.x 和 2.0 的行为差异就被抹平了。
如果代码里有"count 为 0 就当作没有数据"这类逻辑,2.0 之后必须重看。"请求失败"和"确实没有数据"在 1.x 里表现相同(count=0),2.0 才把它们分开,旧代码往往正是靠这个混淆过得去的。
1.x 里 _routing、_timestamp 这类元字段只有用 fields 参数显式请求时才会出现在结果里。2.0 起,所有有 stored 值的元字段默认返回,而且位置从 fields 元素里挪到了顶层(和 _index、_type、_id 并列)。
例如这个请求:
GET /my_index/_search?fields=foo返回结果里 _timestamp 会在 top level:
{
"hits": {
"total": 1,
"max_score": 1,
"hits": [
{
"_index": "my_index",
"_type": "my_type",
"_id": "1",
"_score": 1,
"_timestamp": 10000000,
"fields": {
"foo": [ "bar" ]
}
}
]
}
}升级后解析响应的代码要改:原来去 hit.fields._timestamp 取值的地方改成 hit._timestamp。响应体也会变大:凡是有 stored 值的元字段都会带出来。批量 scroll 拉取的场景,升级后要重新看一遍超时和带宽。
1.x 里 script field 永远返回单个值:即使脚本返回的是列表,也会被包成一个"数组里的数组"。2.0 起不再有这层多余包裹,脚本返回列表就直接返回列表。取值代码里如果写了 fields[0][0] 这种解包,升级后要改成 fields[0]。
这一节原文共 8 条,前面讲了 5 条。剩下三条同样不一定报错(原文):
time_zone 格式变严。date 字段的查询或聚合里,time_zone 参数必须是 ISO 8601 的 UTC 偏移量或时区 ID,+1:00 要写成 +01:00。代码里拼时区字符串的地方要检查补零。
高亮默认只管被查询的字段。require_field_match 的默认值从 false 改为 true,高亮器默认只处理被查询到的字段。文档特别点明:查询 _all 字段时,对 _all 以外的字段做高亮,不会产生任何高亮片段。解决办法是查询需要高亮的同一批字段,或者把 require_field_match 设回 false,这样高亮时完全不看字段名。postings highlighter 不再支持这个选项,只高亮被查询的字段。这条是上面排第二的原因:请求不报错,只是高亮消失。
postings highlighter 不支持 match_phrase_prefix。match 查询的类型设为 phrase_prefix(或 match_phrase_prefix 查询)时,postings highlighter 不返回高亮片段。
按上面的风险排序,不按文档顺序:
第一步,先找 count API 的调用点(最安静、最容易漏):
# 代码里所有 /_count 的调用
grep -rn "_count" --include=*.java --include=*.py --include=*.go --include=*.js . | head -30找到之后逐个确认:调用方有没有异常处理?有没有把 count == 0 当成"无数据"?这两处是重灾区。
第二步,查响应解析里的 fields 路径:
grep -rn "fields\[\|_source.*fields\|hit.*fields" --include=*.py --include=*.java . | head -20确认元字段(_routing、_timestamp 等)的取值路径是不是还写在 fields 里,是的话改到顶层。
第三步,再查那两个会显式报错的:
grep -rn "partial_fields" . | head -20
grep -rn "search_type.*count\|searchType.*count" . | head -20partial_fields → 改成 _source 过滤,并确认字段是否 store: true;search_type=count → 改成 size: 0;fields[0][0] → fields[0]);require_field_match 设回 false。partial_fields 与 search_type=count 两条,和替代写法放一起对照。
图 4:7.17.29 单节点实例的实测输出。partial_fields 报 Unknown key for a START_OBJECT in [partial_fields],_source 过滤返回 ["v"];search_type=count 报 No search type for [count],size=0 返回 total=4 且 hits=0。
curl -s -X POST 'http://localhost:9200/old-idx/_search' -H 'Content-Type: application/json' -d '{"query":{"match_all":{}},"partial_fields":{"x":{"include":"v"}}}' \
| jq -r '.error.root_cause[0].reason'
# Unknown key for a START_OBJECT in [partial_fields].
curl -s -X POST 'http://localhost:9200/old-idx/_search' -H 'Content-Type: application/json' -d '{"query":{"match_all":{}},"_source":{"includes":["v"]}}' \
| jq -c '.hits.hits[0]._source | keys'
# ["v"]
curl -s -X POST 'http://localhost:9200/old-idx/_search?search_type=count' -H 'Content-Type: application/json' \
-d '{"query":{"match_all":{}}}' | jq -r '.error.root_cause[0].reason'
# No search type for [count]
curl -s -X POST 'http://localhost:9200/old-idx/_search' -H 'Content-Type: application/json' -d '{"query":{"match_all":{}},"size":0}' \
| jq -c '{total:.hits.total.value, hits:(.hits.hits|length)}'
# {"total":4,"hits":0}图 4 把正文列的两条替换关系做成了可复现的对照:旧参数在解析阶段被拒,新写法照常工作。正文提到「所有分片都失败时 _count 从返回 0 改成抛异常」,本机没有造出该场景,仍是文档依据。
边界:
require_field_match 默认值变化与高亮静默消失未测;
_count 在分片全失败时的响应未复现。
这一节的改动都不难改,但都改得隐蔽。迁移文档里 Search changes 只有寥寥几条,真正的工作量在"代码里有多少处依赖旧行为",这只能靠上面的 grep 一条条找,读文档读不出来。
建议升级前先在测试环境把三步 grep 跑一遍,把命中点列成表再逐个改。2.0 之后看到的症状往往是"数据不对"或"高亮没了",而不是报错,事后排查的方向很容易跑偏。
本文对照 Elasticsearch
v2.4.6标签的官方文档核对,引文逐字取自原文。「在 7.17.29 上跑一遍」里已实际对照:partial_fields与search_type=count分别报Unknown key for a START_OBJECT与No search type for [count],_source过滤返回["v"]、size=0返回total=4且hits=0。本机无 2.x 二进制;_count在分片全失败时的响应、require_field_match默认值变化未实测。