Yii2中ElasticSearch的terms聚合需绕过ActiveRecord，通过search()手动构造DSL，将aggs置于body顶层、字段加.keyword后缀、设size控制桶数量，并手动解析aggregations结果。
Yii2里怎么写ElasticSearch的terms聚合？
ElasticSearch原生聚合在Yii2里不能直接当ActiveRecord用，得绕过Query Builder手动拼DSL。Yii2的ElasticSearch扩展（比如yiisoft/yii2-elasticsearch）只封装了基础CRUD和简单filter，聚合必须走search()底层API。
常见错误是硬套ActiveDataProvider，结果返回空或报"Unknown key for a START_OBJECT in [aggs]"——因为没把聚合结构塞进body顶层，而是混进了query里。
使用场景主要是统计分类数量、热门标签、地域分布这类分组计数。别指望count()或groupBy()能生效，它们对ES无效。
- 聚合必须放在
body的aggs字段下，和query同级 -
terms聚合默认只返回前10个桶，要统计全部得加"size": 0（注意：这是ES参数，不是Yii配置） - 字段名要带
.keyword后缀（如果该字段是text类型且没开fielddata），否则会报"Fielddata is disabled on text fields"
$response = $client->search([
'index' => 'article',
'body' => [
'query' => ['match_all' => new \stdClass()],
'aggs' => [
'category_count' => [
'terms' => [
'field' => 'category.keyword',
'size' => 50
]
]
]
]
]);
怎么把ES聚合结果转成Yii2能用的数组？
$response['aggregations']是原始数组，但直接遍历容易漏掉嵌套层级或空桶。Yii2没提供聚合结果的模型映射，得自己扁平化。
常见错误是用ArrayHelper::map()直接套['buckets']，结果遇到missing或other桶就崩，或者字段名含点号（如user.name.keyword）导致PHP变量解析失败。
- 先检查
$response['aggregations']['your_agg_name']['buckets']是否存在且为数组 - 桶里的
key可能是字符串或数字，统一用(string)强转再作为键名 - 如果需要关联到ActiveRecord模型（比如查出“分类ID→分类名”），别在聚合里join，先取
key列表，再用find()->where(['id' => $keys])查一次MySQL
$buckets = $response['aggregations']['category_count']['buckets'] ?? [];
$result = [];
foreach ($buckets as $bucket) {
$result[(string)$bucket['key']] = $bucket['doc_count'];
}
date_histogram聚合怎么避免时区错乱？
ES默认用UTC，但Yii2应用常设'timeZone' => 'Asia/Shanghai'，直接用date_histogram会发现每天凌晨8点才切分——其实是UTC零点对应北京时间8点。
错误做法是前端用JS算偏移再传时间戳，或者在ES里硬写"time_zone": "+08:00"，但不同ES版本对time_zone支持不一（6.x支持，7.x开始推荐用fixed_interval+offset）。
- 优先用
fixed_interval（如"1d"）代替interval，再配"offset": "-8h"，兼容性更好 - 时间字段必须是
date类型，且mapping里明确指定了格式（比如"format": "strict_date_optional_time||epoch_millis"），否则聚合可能全归到一个桶 - 别信Kibana里显示的时间，用
_source里原始@timestamp值校验，ES返回的key_as_string才是真实分组时间
'date_histogram' => [
'field' => '@timestamp',
'fixed_interval' => '1d',
'offset' => '-8h',
'min_doc_count' => 1
]
聚合性能差、超时怎么办？
ES聚合默认扫描所有匹配文档，数据量一过百万，terms或date_histogram就容易触发"search_phase_execution_exception"或"timeout"。
根本原因不是Yii2慢，而是没加约束：没query过滤、没限制size、没关track_total_hits。
- 必须加
query缩小范围，哪怕只是range按时间过滤最近30天 -
terms聚合的size别设太大，500已经是临界值；真要全量统计，改用composite聚合分页拉取 - 在
body里显式关掉"track_total_hits": false，省掉全局计数开销
'body' => [
'track_total_hits' => false,
'query' => [
'range' => [
'created_at' => ['gte' => 'now-30d/d']
]
],
'aggs' => [/* ... */]
]
聚合本身不难，难在ES和Yii2之间那层DSL转换没人替你兜底。字段类型、时区、size限制、错误处理——每个点都得亲手试一遍，光抄示例代码基本跑不通。
