Elasticsearch 查询添加分组与排序的完整踩坑记录:从 No mapping found 到 text 字段不能排序
AI 生成声明:本文内容由 AI 生成或经 AI 辅助完成,请注意甄别。
起点:一个很朴素的需求
手上有一个 ES 查询,只想按文件名模糊匹配一批文档:
GET my_docs/_search
{
"query": {
"bool": {
"must": [
{ "wildcard": { "file_name": { "value": "*report_2026*.pdf*" } } }
]
}
}
}
需求变成:既要分组统计,又要按时间排序。看起来就是在原有 query 后面追加几行的事,实际一路踩了三个坑,每个坑的报错信息都指向不同的根因。这篇把整个过程整理下来。
一、分组和排序,本质是三个不同的东西
刚上手时容易把"排序"和"分组排序"混成一件事。先分清:
| 要做什么 | 用哪个关键字 | 作用范围 |
|---|---|---|
| 按某字段把所有结果分成若干组,统计每组数量 | aggs + terms |
聚合结果 |
| 让分组(桶)之间按某个规则排列 | terms.order |
聚合结果内部 |
| 让返回的文档本身按某字段排列 | 顶层 sort |
命中的文档 |
三者互不干扰,可以同时出现在一个 DSL 里。
1. 分组
GET my_docs/_search
{
"size": 0,
"query": {
"bool": {
"must": [
{ "wildcard": { "file_name": { "value": "*report_2026*.pdf*" } } }
]
}
},
"aggs": {
"by_category": {
"terms": {
"field": "category",
"size": 10
}
}
}
}
size: 0:只返回聚合结果,不返回命中文档(避免无谓传输)by_category:聚合别名,随便起terms.size:最多返回多少个桶
2. 分组内部排序
terms 聚合默认按桶内文档数 doc_count 降序。想改规则就加 order:
| 排序方式 | 写法 |
|---|---|
| 按文档数升序 | { "_count": "asc" } |
| 按分组键排序 | { "_key": "asc" } |
| 按子聚合指标排序 | 先定义 metric 子聚合,再引用其名称 |
按子聚合排序的例子:
{
"aggs": {
"by_category": {
"terms": {
"field": "category",
"size": 10,
"order": { "max_score": "desc" }
},
"aggs": {
"max_score": { "max": { "field": "score" } }
}
}
}
}
3. 文档本身排序
{
"sort": [
{ "created_at": { "order": "desc" } },
{ "_score": "desc" }
]
}
数组里顺序即优先级:前一个字段值相同,才用后一个比较。
二、坑一:No mapping found for [xxx] in order to sort on
把示例里的 created_at 直接套到自己索引上,报错:
{
"type": "query_shard_exception",
"reason": "No mapping found for [created_at] in order to sort on"
}
原因:ES 排序、聚合要求字段必须存在于 mapping 里。示例字段名是假设的,自己索引里不叫这个。
解决:先查真实 mapping。
GET my_docs/_mapping
重点找两类字段:
- 时间语义的:可能是
create_time、update_time、upload_time、timestamp、publish_date…… - 可排序的
keyword类型字段
这里有个容易忽略的点:_mapping 返回的是全量字段,别只凭记忆猜字段名。实际项目里同义字段经常并存,比如同时有 create_time 和 created_at,只有一个真正有数据。
三、坑二:Text fields are not optimised for operations that require per-document field data
找到时间字段了,一排序又报:
{
"type": "illegal_argument_exception",
"reason": "Text fields are not optimised for operations that require per-document field data like aggregations and sorting, so these operations are disabled by default. Please use a keyword field instead. Alternatively, set fielddata=true on [update_time] ..."
}
为什么 text 不能排序
ES 的 text 类型会被分词器切成一个个词条存进倒排索引。倒排索引是"词 → 文档"的方向,而排序需要的是"文档 → 原始值"的方向。要对 text 排序,ES 必须在查询时反向重建正排(fielddata),代价极高,所以默认关掉。
keyword 类型不做分词,整个值原样索引,天然支持排序和聚合。
检查有没有 keyword 子字段
GET my_docs/_mapping/field/update_time
典型返回形态有两种:
有子字段(推荐直接使用):
{
"my_docs": {
"mappings": {
"update_time": {
"full_name": "update_time",
"mapping": {
"update_time": {
"type": "text",
"fields": {
"keyword": { "type": "keyword", "ignore_above": 256 }
}
}
}
}
}
}
}
这种最简单,排序把字段名改成 update_time.keyword 就行:
"sort": [
{ "update_time.keyword": { "order": "desc" } }
]
没有任何子字段(纯 text):
"update_time": { "type": "text" }
这就麻烦了,得走下面三条路之一。
四、纯 text 字段的三种解法
方案 A:给已有字段补一个 keyword 子字段
ES 7+ 支持给已存在字段追加多字段:
PUT my_docs/_mapping
{
"properties": {
"update_time": {
"type": "text",
"fields": {
"keyword": { "type": "keyword", "ignore_above": 256 }
}
}
}
}
关键限制:mapping 变更只对新写入的文档生效。已有文档的 update_time.keyword 是空的,排序时会被当成缺失值——于是你会看到"排序没生效"或"旧文档全排最后"。要全量生效必须 reindex。
方案 B:开 fielddata(应急)
PUT my_docs/_mapping
{
"properties": {
"update_time": {
"type": "text",
"fielddata": true
}
}
}
优点:即时生效,不需要 reindex,查询时实时从倒排索引反解加载。
代价:占用大量堆内存。字段基数大或文档多时,很容易把节点压垮。生产环境不建议长期开,只适合临时救火。
方案 C:reindex 成 date 类型(根本解法)
如果字段语义就是时间,那 text 本身就用错了。
先想一个问题:text 按字典序排序,结果真的是时间序吗?
- 格式统一成 ISO 风格
2026-10-08 14:50:34时,字典序恰好等于时间序,看起来能用 - 但只要出现
2026/10/8、2026-1-5(月日不补零)这类格式,字典序就会排错——10排在2前面
正确做法是重建索引,把字段定义成 date:
PUT my_docs_v2
{
"mappings": {
"properties": {
"update_time": {
"type": "date",
"format": "yyyy-MM-dd HH:mm:ss||yyyy-MM-dd||epoch_millis"
}
}
}
}
POST _reindex
{
"source": { "index": "my_docs" },
"dest": { "index": "my_docs_v2" }
}
format 支持用 || 并列多种格式,这样历史脏数据也能被正确解析。reindex 完成后把业务查询切到新索引,之后:
- 排序直接写
update_time,无需.keyword - 可以用
date_histogram按月/按天分组 - 可以用
range查询做时间范围过滤
GET my_docs_v2/_search
{
"query": {
"bool": {
"must": [
{ "wildcard": { "file_name": { "value": "*report_2026*.pdf*" } } }
]
}
},
"sort": [
{ "update_time": { "order": "desc" } }
],
"aggs": {
"by_month": {
"date_histogram": {
"field": "update_time",
"calendar_interval": "month"
}
}
}
}
五、一个完整的 query + sort + aggs DSL
把三种能力拼在一起的样子(字段名按实际 mapping 替换):
GET my_docs/_search
{
"size": 20,
"query": {
"bool": {
"must": [
{ "wildcard": { "file_name": { "value": "*report_2026*.pdf*" } } },
{ "term": { "file_type": "pdf" } }
],
"filter": [
{ "range": { "file_size": { "gte": 1024, "lte": 104857600 } } },
{ "term": { "category.keyword": "公告" } }
],
"should": [
{ "match": { "title": "2026" } }
],
"minimum_should_match": 1
}
},
"sort": [
{ "create_time.keyword": { "order": "desc" } },
{ "file_size": { "order": "desc" } },
{ "rank": { "order": "asc" } }
],
"aggs": {
"by_category": {
"terms": {
"field": "category.keyword",
"size": 10,
"order": { "_count": "desc" }
},
"aggs": {
"avg_budget": { "avg": { "field": "budget_amt" } },
"max_rank": { "max": { "field": "rank" } }
}
},
"by_area": {
"terms": {
"field": "area_name.keyword",
"size": 10,
"order": { "_key": "asc" }
}
},
"budget_stats": {
"stats": { "field": "budget_amt" }
}
}
}
拆开看:
query 层
must:必须满足,参与打分(wildcard模糊、term精确)filter:只过滤不计分,结果可被缓存,性能更好——范围过滤、精确过滤都该放这里should+minimum_should_match:加分项,控制"至少命中几个"
sort 层
数组顺序即优先级。keyword 字段直接写名字,text 字段必须写 .keyword 子字段,数值类型直接写。
aggs 层
by_category:按分类分组,桶内再挂avg/max两个指标子聚合by_area:按地区分组,用_key按分组键升序budget_stats:一次算 count/min/max/avg/sum
六、字段类型 → 用法速查表
踩完坑整理出来的对照表,值得贴在显示器边上:
| 字段类型 | 分组(terms) | 排序(sort) | 模糊查询(wildcard) |
|---|---|---|---|
keyword |
直接写字段名 | 直接写字段名 | 直接写字段名 |
text + keyword 子字段 |
字段名.keyword |
字段名.keyword |
用主字段或子字段均可 |
text(无子字段) |
不可用 | 不可用(除非开 fielddata) | 可用(注意分词) |
long / integer / float |
直接用 | 直接用 | 不适用 |
date |
用 date_histogram |
直接用 | 不适用 |
七、几条踩出来的经验
先查 mapping,再写 DSL。 不要凭感觉套示例字段名,GET index/_mapping 是所有 ES 排障的第一步。
text 字段参与聚合/排序时统一加 .keyword。 记住这条,能避掉大半报错。
ignore_above: 256 是个隐形门槛。 超过 256 字符的值不会进 keyword 索引,聚合和排序时会被当缺失值。长文本字段(content、summary 之类)不要指望用它的 .keyword 做分组。
mapping 变更不回溯历史数据。 补子字段、加 fielddata 都只对新写入生效或需要运行时重建。要全量生效只有 reindex 一条路。
时间字段就该用 date 类型。 用 text 存时间,排序靠字符串巧合、聚合做不了 date_histogram、范围查询也容易出边界问题,长期是技术债。
分组数量大要分页时用 composite 聚合。 terms 聚合的 size 只是"取前 N 个桶",无法稳定翻页遍历全部桶;composite 支持 after 游标,适合做全量遍历。
只想要聚合结果就把顶层 size 设为 0。 否则 ES 还要额外取文档,白花开销。
小结
一个"给查询加个分组和排序"的需求,最终牵出的是 ES 类型系统的基本约束:倒排索引擅长检索,不擅长排序;text 为检索而生,keyword 为精确匹配和排序而生。 理解这一层,那些看似莫名其妙的报错就都有了统一的解释。
真要在时间维度上做文章,最省事的做法不是绕过限制,而是把时间字段老老实实定义成 date——建索引时多写一行 mapping,能省掉日后无数次 fielddata 和 reindex 的折腾。

浙公网安备 33010602011771号