Elasticsearch聚合必须设size: 0，否则默认返回文档干扰解析；terms聚合需字段为keyword类型；嵌套聚合需手动解包；全量分组应优先用composite聚合分页。
PHP用Elasticsearch做聚合时，size: 0不是可选，是必须加的
直接发聚合请求却拿到一堆文档？那大概率漏了 size: 0。Elasticsearch 默认会返回匹配的文档（hits），而聚合结果在 aggregations 里——但如果你没显式关掉文档返回，它既返回文档又算聚合，浪费带宽还干扰解析。尤其在纯统计场景（比如只想要各城市订单数），不设 size: 0 就等于白跑一次全文检索。
实操建议：
立即学习“PHP免费学习笔记（深入）”；
- 所有只关心聚合结果的请求，
body中必须包含"size": 0 - 用
elasticsearch/elasticsearch官方 PHP 客户端时，别把size放错层级——它得和aggs同级，不是嵌在aggs里面 - 如果误写成
"size": 10，且聚合桶数超 10，你可能发现top_hits类聚合结果被截断，但错误信息里不会提醒你 size 影响聚合
terms 聚合返回空数组？检查字段是否被映射为 keyword
PHP 里调用 terms 聚合，结果 buckets 是空的，但你知道数据里明明有值——八成是字段类型不对。Elasticsearch 对 text 字段默认会分词，而 terms 只能对未分词的 keyword 类型做精确分组。比如存了 "user_name": "zhang san"，若该字段是 text，聚合时实际拆成了 ["zhang", "san"]，根本无法按完整姓名分组。
实操建议：
立即学习“PHP免费学习笔记（深入）”；
- 查映射：用
GET /your_index/_mapping确认目标字段类型，如"user_name.keyword"存在才安全 - 聚合时写全路径：
"field": "user_name.keyword"，别只写"user_name" - 如果字段确实是
text且无法改映射，临时方案是用script强转，但性能差、无法缓存，仅限调试
PHP处理多层嵌套聚合（比如按日期+状态分组）要手动解包 aggregations
Elasticsearch 的嵌套聚合（如先 date_histogram 再套 terms）返回的是深层嵌套数组，PHP 不会自动扁平化。你看到的 $response['aggregations']['by_date']['buckets'][0]['by_status']['buckets'] 这种结构，容易因少写一层键名就报 Undefined index。
实操建议：
立即学习“PHP免费学习笔记（深入）”；
- 永远用
isset()或 null 合并操作符（??）访问嵌套键，例如：$buckets = $response['aggregations']['by_date']['buckets'] ?? []; - 避免硬编码索引，遍历用
foreach；date_histogram的key_as_string比key更可靠（后者可能是时间戳数字） - 如果聚合层级深、字段多，考虑封装一个递归提取函数，但别过度设计——多数业务场景两层足够
聚合结果超过 10 条？别急着改 size，先看是不是该用 composite 聚合
terms 聚合默认最多返回 10 个桶，设 "size": 100 能撑到 100，但内存和响应时间会明显上涨；设太大还可能触发 circuit_breaking_exception。真要查全部分组（比如导出所有省份销量），terms 不是正解。
实操建议：
立即学习“PHP免费学习笔记（深入）”；
- 需要全量分组且数据量大时，改用
composite聚合，它支持分页（after参数），内存友好 - PHP 请求里传
after要注意类型：上一页最后桶的key值需原样传入下一页，字符串就传字符串，对象就传对象，不能 JSON encode 后再 decode -
composite不支持子聚合嵌套太深，如果既要分页又要每组内算平均值，得在 PHP 层补计算，而不是全压给 ES
