Elasticsearch直方图聚合需在aggs下定义，field必须为number/date类型，interval设正数，min_doc_count:0保留空桶；PHP中key为float需round处理；filter应置于bool.query.filter中以确保统计准确。
elasticsearch histogram 聚合在 Laravel 中怎么写
直方图聚合（histogram）不是用 range 手动切分，而是让 ES 自动按固定间隔（interval）对数值字段做桶划分，适合价格、评分、销量等连续型数据的分布统计。Laravel 里直接调用原生客户端即可，Scout 的抽象层不暴露聚合 DSL，写不了。
常见错误是把 histogram 写进 query 下（它属于 aggs），或漏掉 field 类型必须是 number 或 date——如果 mapping 里字段是 text，会直接报错 "Fielddata is disabled on text fields"。
- 确保目标字段（如
price）在 index mapping 中类型为float、integer或date，不能是keyword或text - 聚合必须放在请求 body 的
aggs键下，和query同级，不是嵌套在must里 -
interval值需为正整数或浮点数，比如价格按 50 元一档："interval": 50；时间按天："interval": "1d" - 可加
min_doc_count: 0保留空桶（否则 ES 默认只返回 doc_count > 0 的桶）
$params = [
'index' => 'products',
'body' => [
'size' => 0,
'aggs' => [
'price_histogram' => [
'histogram' => [
'field' => 'price',
'interval' => 50,
'min_doc_count' => 0,
],
],
],
],
];
$result = app('es')->search($params);
// 结果在 $result['aggregations']['price_histogram']['buckets'] 里
为什么 histogram 返回的 key 是 double 类型而不是整数
ES 的 histogram 桶 key 默认是起始值的原始类型，price 是 float 字段时，key 就是 0.0、50.0、100.0 —— 这不是 bug，是设计行为。PHP json_decode 会把它转成 float，导致后续用 array_key_exists(100, $buckets) 失败。
解决办法只有两个：
- 用
round($bucket['key'], 2)统一转成两位小数再比较（推荐，兼容所有 interval） - 改用
extended_stats+percentiles配合前端分段，绕开 histogram 的 key 类型问题
别试图用 script 强制转整数——性能差、不可缓存、还可能触发 sandbox 限制。
如何把 histogram 和搜索条件一起用
直方图是聚合，不是过滤，它始终基于整个查询上下文统计。想“只统计上架商品的价格分布”，就得把过滤条件写进 query 的 filter 分支，再在同个请求里声明 aggs：
-
filter放确定性条件（如['term' => ['status' => true]]），不影响评分且可被缓存 - 不要把
filter写进must，否则会影响相关度计算，还可能让 histogram 结果变少（因为 must 影响 query context） - 如果同时要查商品列表 + 直方图，
size设为0可省去 hits 开销；要带结果就设成实际需要的数量（如 20），但注意 deep pagination 限制
$params['body']['query'] = [
'bool' => [
'filter' => [
['term' => ['status' => true]],
['range' => ['price' => ['gte' => 0]]],
],
],
];
$params['body']['aggs'] = [/* histogram 定义 */];
区间分段不准？检查 offset 和 min_doc_count
默认 histogram 从字段最小值向下取整开始分桶，比如 price 最小值是 12，interval=50，第一个桶就是 0.0 → 50.0，中间会有空档。用户常误以为“12–62 应该是第一档”，但 ES 不这么算。
要对齐业务口径（比如“0–49、50–99…”），得用 offset 手动校准：
- 加
"offset": -0.01可让 0–49.99 落进第一个桶（适用于整数字段） - 更稳妥的是用
range聚合替代histogram，显式定义ranges数组，完全可控 -
min_doc_count: 0必须带上，否则你看到的桶全是非空的，根本不知道哪些区间没数据
真正难调试的点不在代码怎么写，而在 mapping 是否正确、数据是否已刷新、以及聚合是否被 query 的 filter 条件意外截断——这三个地方出问题，histogram 返回永远比预期少桶。
