terms 聚合是什么
terms 聚合按字段值分桶计数，是最常用的分组统计：字段必须是 keyword 或数值类型，text 字段因 fielddata 默认关闭会直接报错。size 控制返回的桶数量，排序默认按文档数降序，也可以按子聚合的指标排序。结果中的误差提示字段反映被裁掉的桶，多个分片时前 N 名并不保证精确。
基本信息
| 用法 | "aggs": { "名称": { "terms": { "field": "字段", "size": 10 } } } |
|---|---|
| 排序 | order 可指定 _count、_key 或子聚合指标 |
| 误差字段 | doc_count_error_upper_bound 与 sum_other_doc_count |
| 常用参数 | size、shard_size、missing、min_doc_count、include/exclude |
| 结构 | search 的 size 设为 0 可只取聚合结果 |
| 适用版本 | Elasticsearch 7.x / 8.x |
典型使用场景
- 按状态、渠道、地区统计订单分布
- 按用户统计下单次数，做 TOP 榜
- 桶内再挂指标聚合，算每组的平均金额
- 嵌套时间直方图，观察分组随时间的变化
- 统计日志中错误类型的占比，定位主要问题
- 统计热门搜索词，为运营提供依据
示例
示例
GET /orders/_search
{
"size": 0, # 不返回命中文档，只要聚合
"aggs": {
"by_status": {
"terms": {
"field": "status",
"size": 10,
"missing": "unknown", # 缺失字段归到一个桶
"order": { "total_amount": "desc" } # 按子聚合指标排序
},
"aggs": { "total_amount": { "sum": { "field": "amount" } } }
}
}
}关键参数读法
| 参数 | 作用 | 注意点 |
|---|---|---|
| size | 返回桶数量 | 过大会增加协调开销 |
| shard_size | 每个分片预取的桶数 | 提高可提升结果精度 |
| missing | 字段缺失时的归类值 | 避免 null 桶难以理解 |
| min_doc_count | 桶的最小文档数 | 过滤长尾小桶 |
| include/exclude | 按正则或前缀筛选桶 | 只影响返回不影响统计 |
| order | 桶排序方式 | 可指定子聚合指标 |
聚合实践要点
- 对 text 字段聚合前先确认有 keyword 子字段
- 排序字段用完整字段名，聚合指标排序要写成嵌套路径
- 桶数量按需收敛，几百个以上的桶会让响应明显变大
- 需要精确排名时提高 shard_size，或先把数据落到单分片索引
- 分页取全部桶用 composite 聚合，它能稳定续取且内存友好
- 组合统计时注意桶数与子聚合相乘，容易触发桶上限
结果判读要点
- doc_count 是桶内文档数，_key 是分组值
- sum_other_doc_count 不为零说明还有桶没返回
- doc_count_error_upper_bound 大于 0 说明排名可能存在误差
- 桶内子聚合的 value 为 null 时通常是没有匹配的数值文档
- 对空值桶要结合 missing 参数判断是否符合业务预期
- 落库前先确认桶统计口径与业务口径是否一致
search 体里把 size 设为 0 可以跳过 hits 返回，只取聚合结果，减少无用序列化；聚合分析场景几乎都该这么写。
返回桶数量受 size 与 shard_size 影响，多分片时前 N 名可能不精确，需要严格排名时要提高 shard_size 或改用 composite 聚合。
对 text 字段直接聚合会报 fielddata is disabled，改用 keyword 子字段或在映射里事先定义好合适的类型。
桶数量有上限（search.max_buckets，默认 10000），嵌套聚合会把桶数相乘，超限后聚合直接失败，粒度和 size 都要提前估算。
统计口径核对
- 先加 query 限定时间与状态范围，再看聚合结果
- 核对 doc_count 与业务系统的口径是否一致
- sum 的 value 为 null 表示桶内没有数值文档，不等于 0
- 排名误差用 doc_count_error_upper_bound 判断
- 需要精确全量排名时提高 shard_size 或先改用 composite 聚合
- 关键聚合结果与明细抽样比对，避免口径漂移
聚合只统计匹配 query 的文档：忘记加范围条件会把全量历史数据一起算进来，报表数字会明显偏大。
桶默认按文档数降序排序；按 _key 排序适合输出按名称排列的清单，按子聚合指标排序时要写完整的指标路径。