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 的折腾。

posted @ 2026-11-12 08:40  新*  阅读(15)  评论(0)    收藏  举报