Elasticsearch聚合在Python中需手写严格符合DSL规范的字典传入aggs参数，elasticsearch-py仅序列化不解析；必须用小写"aggs"键、正确嵌套层级（如terms下用"aggs"包裹子聚合）、字段名拼写准确（如"field"非"filed"），且注意text字段须用".keyword"子字段。
直接上结论：Elasticsearch 的聚合（aggregation）在 Python 中不是靠 elasticsearch-py 自动“翻译”成对象来实现的，而是你手写符合 DSL 规范的字典结构，再传给 search() 的 aggs 参数——写错字段名、嵌套层级或漏掉 aggs 键，90% 的“聚合没结果”问题就出在这儿。
为什么用 body 字典而不是链式调用？
elasticsearch-py 官方客户端不提供高级聚合构造器（比如 .terms("field").sub_aggs(...)），它只负责把 Python 字典序列化为 JSON 并发请求。所有聚合逻辑都由 Elasticsearch 服务端解析执行，Python 层只是“传参工具人”。这意味着：
- 你写的字典必须严格遵循 Elasticsearch 的聚合 DSL 语法，比如
"terms"必须是小写，"field"下不能拼错成"filed" - 嵌套聚合必须显式用
"aggs"键包裹下级聚合，不能靠缩进或方法链隐含关系 - 常见错误：
Response hits=100, aggregations={}—— 很可能因为顶层没写"aggs"，或者拼成了"agg"或"aggregations"
多层嵌套聚合怎么写才不出错？
比如“按城市分组 → 每个城市内按价格区间统计平均评分”，必须两层嵌套，且第二层必须挂在第一层的 "aggs" 下。容易漏掉中间的 "aggs" 键，导致第二层聚合被忽略：
{
"size": 0,
"aggs": {
"by_city": {
"terms": { "field": "city.keyword" },
"aggs": { // ← 这个 "aggs" 是关键，不是可选
"avg_rating": { "avg": { "field": "rating" } },
"price_ranges": {
"range": {
"field": "price",
"ranges": [{ "to": 100 }, { "from": 100 }]
}
}
}
}
}
}Python 中对应写法（注意引号和层级）：
立即学习“Python免费学习笔记（深入）”；
es.search(
index="hotels",
body={
"size": 0,
"aggs": {
"by_city": {
"terms": {"field": "city.keyword"},
"aggs": { # ← 必须有
"avg_rating": {"avg": {"field": "rating"}},
"price_ranges": {
"range": {
"field": "price",
"ranges": [{"to": 100}, {"from": 100}]
}
}
}
}
}
}
)聚合结果怎么安全取值？别硬写 response["aggregations"]["by_city"]["buckets"]
ES 返回的聚合结构深度取决于你的 DSL，但 response["aggregations"] 可能为 None（比如 query 报错但 HTTP 状态码仍是 200），或 key 不存在（比如聚合名写错）。直接链式取值会抛 KeyError 或 TypeError：
- 用
.get()链式防御：resp.get("aggregations", {}).get("by_city", {}).get("buckets", []) - 对每个 bucket，检查
"key"和子聚合是否存在，比如bucket.get("avg_rating", {}).get("value") - 如果聚合用了
"missing"或"include"参数，返回结构可能含额外字段，不要假设字段一定存在
聚合性能和 mapping 不匹配的坑
聚合快慢和字段类型强相关。最常见踩坑点：
- 对
text类型字段做terms聚合 → 返回空或报错，必须用.keyword子字段（如"title.keyword"） - 日期字段没设
"format"，导致date_histogram解析失败，返回空桶 - 聚合大量唯一值（比如用户 ID）时，
size默认只返回前 10 个，要加"size": 1000（但注意内存压力） - 使用
script聚合时，需确保集群开启了script.allowed_types: inline，否则报script_exception
复杂聚合真正难的不是写法，而是理解 DSL 结构与数据 mapping 的耦合关系——一个字段类型不对，整个聚合链就静默失效，连 error 都不报。
