6.1 聚合框架与指标聚合

6.1 聚合框架与指标聚合

本节摘要：聚合（aggregations）与 query 平级共存：查询圈定文档集，聚合回答这个集合的数字特征。本节讲聚合请求的骨架与执行模型，再把指标聚合一族过一遍——均值、极值、基数、百分位——每个配上业务读法与响应结构。统计视角从这里开眼。

换个视角看数据

骨架：一个请求，两种答案

聚合写在 aggs 字段里，与 query 平级。圈定条件与统计目标同在一个请求里送达：

GET tickets/_search
{
  "size": 0,
  "query": {
    "range": { "created_at": { "gte": "2026-08-01", "lt": "2026-09-01" } }
  },
  "aggs": {
    "avg_reply": { "avg": { "field": "first_reply_minutes" } }
  }
}
​

{
  "hits": { "total": { "value": 4213 }, "hits": [] },
  "aggregations": {
    "avg_reply": { "value": 37.6 }
  }
}
​

两个细节立住规范：size 设零——不要文档只要统计，省下阶段二的取回；hits.total 顺便告诉你统计样本量，报表注脚直接可用。执行模型沿用 5.1 的两阶段：聚合在阶段一随查询下发到每个分片，各自在本地文档集上算出部分结果（均值变"部分和加计数"的中间态），协调节点归并部分结果得出全局值——不搬运文档本体，只搬运中间量，这就是聚合能扛大集合的原因。数据来源是第 3 章埋的 doc_values 列式存储：字段值按列落盘，聚合扫列不扫行。

指标聚合一族

GET tickets/_search
{
  "size": 0,
  "aggs": {
    "max_priority":   { "max":  { "field": "priority" } },
    "min_priority":   { "min":  { "field": "priority" } },
    "distinct_tags":  { "cardinality": { "field": "tags", "precision_threshold": 40000 } },
    "reply_dist":     { "percentiles": { "field": "first_reply_minutes", "percents": [50, 95, 99] } }
  }
}
​

{
  "aggregations": {
    "max_priority":  { "value": 1 },
    "min_priority":  { "value": 5 },
    "distinct_tags": { "value": 1863 },
    "reply_dist":    { "values": { "50": 12.0, "95": 168.5, "99": 421.0 } }
  ]
}
​

四个指标四种性格。max 与 min 是精确的，代价只是扫一遍列。cardinality（基数、去重计数）是近似算法——用固定内存的概率结构换超大集合的可扩展性，precision_threshold 参数在四万以内基本精确，超过后开始有小的相对误差；报表上"标签去重数"对不上细账，先想到这里。percentiles（百分位）同样是近似，但它回答的是平均值给不了的问题：均值 37 分钟看着达标，九十五分位却是 168 分钟——每二十个用户就有一个等了近三小时，长尾才暴露真相。

指标面板速览

stats 是懒人五件套：count、min、max、avg、sum 一次拿全，看板首屏最常用。

一次报表数字的核对过程

背景：运营看板"八月去重标签数"显示 1863，细心的运营手工抽查三天数据算出 1871，来问哪个对。操作：先确认查询圈定范围一致（都是八月）；再看 cardinality 的 precision_threshold 设的是四万、八月去重数远小于阈值，按文档承诺应基本精确；用高阈值复跑一次，结果稳定在 1863；手工侧改用导出去重脚本重算，发现导出脚本把一个含逗号的多值标签拆成了两个。结果：聚合侧 1863 正确，差异来自手工方法。解读：近似算法有边界，但四万阈值内的 cardinality 可以放心当精确值用；对不上数时，先核对两边的口径（范围、字段、分词形态），再怀疑算法。变式：基数超过阈值又要精度时，改用较高的阈值档（内存换精度），或把 tags 拆到独立索引用精确计数——量级与精度的经典交换。

⚠️ 常见坑：对 text 字段直接做聚合，报错找不到聚合字段——聚合吃的是 keyword 与数值的 doc_values，text 没有列存。挂子字段（3.1 的 raw）再聚，是标准解。

💡 关键直觉：均值是广告，百分位是合同。给业务汇报响应时间，永远带九十五分位——被均值掩盖的长尾正是用户抱怨的来源。

考核与自测

考核知识点清单

易错点补充

• 混用事件时间与统计时间：直方图用的字段应是业务时间，错用进站时间会歪曲高峰位置。
• 对分位数做二次运算：它是估算值，报表展示分位曲线即可，别拿它加减乘除当精确数。
• 空字段拉低均值：缺字段文档被均值忽略而计入计数，先确认口径再解释数字，别急着汇报"平均变好了"。
• 聚合响应不校验字段缺失：返回里值为空的桶往往意味着字段映射错了或数据没写入，看见空桶先查数据再查语法。

开眼之后

• 聚合与 query 平级，size 设零只取统计；两阶段只传中间量，扛得住大集合。
• 精确与近似各就各位：极值精确，基数与百分位近似，阈值内近似可当精确用。
• stats 五件套适合看板首屏，percentiles 是长尾照妖镜。
• 聚合字段须有 doc_values：keyword 与数值天然具备，text 要靠子字段。

数字有了，下一节把它们分进格子：桶聚合与嵌套，报表的骨架拼装开始。