可变宽度直方图聚合 #

variable_width_histogram 聚合与标准 histogram 聚合类似，但它会自动调整每个桶的宽度，使数据点在各桶之间尽可能均匀分布。该聚合使用聚类算法，根据数据的实际分布动态确定最优的桶边界，而不是使用固定间隔。

这在数据分布不均匀时特别有用 —— 例如，大部分值集中在某个范围内，但也有少量离群值。使用固定间隔的 histogram 可能导致大量空桶或单个桶内文档过多，而 variable_width_histogram 能自适应地解决这些问题。

参数说明 #

参数	必需/可选	数据类型	描述
`field`	必填	String	要聚合的数值字段。必须为数值类型。也可使用 `script` 替代。
`buckets`	可选	Integer	期望的桶数量。实际返回的桶数量可能小于或等于此值。默认 `10`。必须大于 0。
`shard_size`	可选	Integer	每个分片上用于聚类的文档数量。值越大结果越精确，但内存消耗越大。默认为 `buckets * 50`。必须大于 1。
`initial_buffer`	可选	Integer	初始缓冲区大小，用于收集初始数据点以启动聚类算法。默认为 `min(10 * shard_size, 50000)`。必须大于 0 且不小于 `buckets`。
`script`	可选	Object	使用脚本动态生成聚合值。
`missing`	可选	Numeric	缺少字段值的文档所使用的替代值。

基本用法 #

以下示例将商品价格分成 5 个自适应宽度的桶：

GET products/_search
{
  "size": 0,
  "aggs": {
    "price_distribution": {
      "variable_width_histogram": {
        "field": "price",
        "buckets": 5
      }
    }
  }
}

返回内容中，每个桶包含 min、max、key（桶的中心值）和 doc_count：

{
  ...
  "aggregations": {
    "price_distribution": {
      "buckets": [
        {
          "min": 5.0,
          "key": 15.3,
          "max": 25.0,
          "doc_count": 120
        },
        {
          "min": 25.0,
          "key": 42.7,
          "max": 60.0,
          "doc_count": 95
        },
        {
          "min": 60.0,
          "key": 85.2,
          "max": 110.0,
          "doc_count": 88
        },
        {
          "min": 110.0,
          "key": 150.0,
          "max": 200.0,
          "doc_count": 45
        },
        {
          "min": 200.0,
          "key": 350.5,
          "max": 500.0,
          "doc_count": 12
        }
      ]
    }
  }
}

注意与固定间隔 histogram 的区别 —— 每个桶的宽度不同，但文档数量更加均匀。

调整精度 #

通过增加 shard_size 可以提高聚类精度（但会消耗更多内存）：

GET products/_search
{
  "size": 0,
  "aggs": {
    "price_distribution": {
      "variable_width_histogram": {
        "field": "price",
        "buckets": 10,
        "shard_size": 1000,
        "initial_buffer": 5000
      }
    }
  }
}

histogram vs. variable_width_histogram #

特性	`histogram`	`variable_width_histogram`
桶宽度	固定（由 `interval` 决定）	可变（由数据分布决定）
桶边界	均匀分布	根据聚类算法自适应
文档分布	可能极不均匀	尽量均匀
参数	需指定 `interval`	需指定 `buckets` 数量
适用场景	数据分布均匀，需要固定区间	数据分布不均匀，需要自适应分桶

注意事项 #

variable_width_histogram 的结果是近似的，基于每个分片上的聚类算法。多分片环境下，结果可能因分片数据分布不同而有所差异。
initial_buffer 必须大于或等于 buckets，否则会报错。
shard_size 的 3/4 必须大于或等于 buckets，否则会报错。
该聚合不支持子聚合（如嵌套 avg 或 terms）。
仅支持数值类型字段。