› › ›

直方图聚合

一种基于多桶值来源的聚合，可以应用于从文档中提取的数值或数值范围值。它会在值上动态构建固定大小（又称区间）的桶。例如，如果文档中有一个字段保存价格（数值），我们可以将此聚合配置为动态构建区间为 5 的桶（如果价格代表美元，则可能代表 5 美元）。当聚合执行时，将评估每个文档的价格字段，并将其向下舍入到最接近的桶 - 例如，如果价格为 32 且桶大小为 5，则舍入结果为 30，因此文档将“落入”与键 30 关联的桶中。为了更正式地说明，以下是使用的舍入函数：

bucket_key = Math.floor((value - offset) / interval) * interval + offset

对于范围值，一个文档可以落入多个桶中。第一个桶的计算方式与单个值的桶相同，都是从范围的下限计算。最后一个桶的计算方式也与单个值的桶相同，都是从范围的上限计算，并且该范围会被计入这两个桶之间（包括这两个桶）的所有桶中。

interval 必须是正小数，而 offset 必须是 [0, interval)（大于或等于 0 且小于 interval 的小数）范围内的十进制数。

以下代码片段根据产品的 price（价格）按 50 的区间进行“分桶”

resp = client.search(
    index="sales",
    size="0",
    aggs={
        "prices": {
            "histogram": {
                "field": "price",
                "interval": 50
            }
        }
    },
)
print(resp)

response = client.search(
  index: 'sales',
  size: 0,
  body: {
    aggregations: {
      prices: {
        histogram: {
          field: 'price',
          interval: 50
        }
      }
    }
  }
)
puts response

const response = await client.search({
  index: "sales",
  size: 0,
  aggs: {
    prices: {
      histogram: {
        field: "price",
        interval: 50,
      },
    },
  },
});
console.log(response);

POST /sales/_search?size=0
{
  "aggs": {
    "prices": {
      "histogram": {
        "field": "price",
        "interval": 50
      }
    }
  }
}

响应可能如下所示：

{
  ...
  "aggregations": {
    "prices": {
      "buckets": [
        {
          "key": 0.0,
          "doc_count": 1
        },
        {
          "key": 50.0,
          "doc_count": 1
        },
        {
          "key": 100.0,
          "doc_count": 0
        },
        {
          "key": 150.0,
          "doc_count": 2
        },
        {
          "key": 200.0,
          "doc_count": 3
        }
      ]
    }
  }
}

最小文档计数

编辑

上面的响应显示没有文档的价格落在 [100, 150) 范围内。默认情况下，响应会用空桶填充直方图中的空隙。可以使用 min_doc_count 设置来更改此设置并请求最小计数更高的桶。

resp = client.search(
    index="sales",
    size="0",
    aggs={
        "prices": {
            "histogram": {
                "field": "price",
                "interval": 50,
                "min_doc_count": 1
            }
        }
    },
)
print(resp)

response = client.search(
  index: 'sales',
  size: 0,
  body: {
    aggregations: {
      prices: {
        histogram: {
          field: 'price',
          interval: 50,
          min_doc_count: 1
        }
      }
    }
  }
)
puts response

const response = await client.search({
  index: "sales",
  size: 0,
  aggs: {
    prices: {
      histogram: {
        field: "price",
        interval: 50,
        min_doc_count: 1,
      },
    },
  },
});
console.log(response);

POST /sales/_search?size=0
{
  "aggs": {
    "prices": {
      "histogram": {
        "field": "price",
        "interval": 50,
        "min_doc_count": 1
      }
    }
  }
}

响应

{
  ...
  "aggregations": {
    "prices": {
      "buckets": [
        {
          "key": 0.0,
          "doc_count": 1
        },
        {
          "key": 50.0,
          "doc_count": 1
        },
        {
          "key": 150.0,
          "doc_count": 2
        },
        {
          "key": 200.0,
          "doc_count": 3
        }
      ]
    }
  }
}

默认情况下，histogram 返回数据本身范围内的所有桶，也就是说，具有最小值（直方图作用的）的文档将确定最小桶（键最小的桶），而具有最大值的文档将确定最大桶（键最大的桶）。通常，在请求空桶时，这会导致混淆，尤其是在数据也经过过滤的情况下。

为了理解原因，让我们来看一个例子。

假设您正在过滤请求以获取所有值介于 0 和 500 之间的文档，此外，您还希望使用区间为 50 的直方图按价格切片数据。您还指定了 "min_doc_count" : 0，因为您希望获取所有桶，即使是空桶也是如此。如果碰巧所有产品（文档）的价格都高于 100，那么您将获得的第一个桶的键将为 100。这令人困惑，因为很多时候，您也希望获得 0-100 之间的那些桶。

使用 extended_bounds 设置，您现在可以“强制”直方图聚合从特定 min 值开始构建桶，并且还可以继续构建桶直到 max 值（即使不再有文档）。只有当 min_doc_count 为 0 时，使用 extended_bounds 才有意义（如果 min_doc_count 大于 0，则永远不会返回空桶）。

请注意（顾名思义），extended_bounds 不会过滤桶。这意味着，如果 extended_bounds.min 高于从文档中提取的值，则文档仍然会决定第一个桶是什么（extended_bounds.max 和最后一个桶也是如此）。要过滤桶，应该将直方图聚合嵌套在具有适当 from/to 设置的范围 filter 聚合之下。

示例

resp = client.search(
    index="sales",
    size="0",
    query={
        "constant_score": {
            "filter": {
                "range": {
                    "price": {
                        "lte": "500"
                    }
                }
            }
        }
    },
    aggs={
        "prices": {
            "histogram": {
                "field": "price",
                "interval": 50,
                "extended_bounds": {
                    "min": 0,
                    "max": 500
                }
            }
        }
    },
)
print(resp)

const response = await client.search({
  index: "sales",
  size: 0,
  query: {
    constant_score: {
      filter: {
        range: {
          price: {
            lte: "500",
          },
        },
      },
    },
  },
  aggs: {
    prices: {
      histogram: {
        field: "price",
        interval: 50,
        extended_bounds: {
          min: 0,
          max: 500,
        },
      },
    },
  },
});
console.log(response);

POST /sales/_search?size=0
{
  "query": {
    "constant_score": { "filter": { "range": { "price": { "lte": "500" } } } }
  },
  "aggs": {
    "prices": {
      "histogram": {
        "field": "price",
        "interval": 50,
        "extended_bounds": {
          "min": 0,
          "max": 500
        }
      }
    }
  }
}

聚合范围时，桶基于返回文档的值。这意味着响应可能包含查询范围之外的桶。例如，如果您的查询查找大于 100 的值，并且您有一个覆盖 50 到 150 的范围，以及 50 的区间，则该文档将落入 3 个桶中 - 50、100 和 150。一般来说，最好将查询和聚合步骤视为独立的 - 查询选择一组文档，然后聚合对这些文档进行分桶，而不考虑它们是如何被选择的。有关更多信息和示例，请参见关于范围字段分桶的说明。

hard_bounds 是 extended_bounds 的对应部分，可以限制直方图中桶的范围。对于可能导致大量桶的开放数据范围，它特别有用。

示例

resp = client.search(
    index="sales",
    size="0",
    query={
        "constant_score": {
            "filter": {
                "range": {
                    "price": {
                        "lte": "500"
                    }
                }
            }
        }
    },
    aggs={
        "prices": {
            "histogram": {
                "field": "price",
                "interval": 50,
                "hard_bounds": {
                    "min": 100,
                    "max": 200
                }
            }
        }
    },
)
print(resp)

const response = await client.search({
  index: "sales",
  size: 0,
  query: {
    constant_score: {
      filter: {
        range: {
          price: {
            lte: "500",
          },
        },
      },
    },
  },
  aggs: {
    prices: {
      histogram: {
        field: "price",
        interval: 50,
        hard_bounds: {
          min: 100,
          max: 200,
        },
      },
    },
  },
});
console.log(response);

POST /sales/_search?size=0
{
  "query": {
    "constant_score": { "filter": { "range": { "price": { "lte": "500" } } } }
  },
  "aggs": {
    "prices": {
      "histogram": {
        "field": "price",
        "interval": 50,
        "hard_bounds": {
          "min": 100,
          "max": 200
        }
      }
    }
  }
}

在这个例子中，即使查询中指定的范围高达 500，直方图也只有从 100 和 150 开始的 2 个桶。即使结果中存在应该进入这些桶的文档，所有其他桶也会被省略。

顺序

编辑

默认情况下，返回的桶按其 key 升序排序，但可以使用 order 设置来控制顺序行为。支持与术语聚合相同的 order 功能。

偏移量

编辑

默认情况下，桶键从 0 开始，然后以 interval 的均匀间隔递增，例如，如果区间为 10，则前三个桶（假设其中包含数据）将为 [0, 10)、[10, 20)、[20, 30)。可以使用 offset 选项来移动桶边界。

这可以用一个例子最好地说明。如果有 10 个文档的值范围为 5 到 14，使用区间 10 将产生两个桶，每个桶包含 5 个文档。如果使用附加的偏移量 5，则将只有一个桶 [5, 15) 包含所有 10 个文档。

响应格式

编辑

默认情况下，桶作为有序数组返回。也可以请求将响应作为哈希返回，并按桶键进行键控。

resp = client.search(
    index="sales",
    size="0",
    aggs={
        "prices": {
            "histogram": {
                "field": "price",
                "interval": 50,
                "keyed": True
            }
        }
    },
)
print(resp)

response = client.search(
  index: 'sales',
  size: 0,
  body: {
    aggregations: {
      prices: {
        histogram: {
          field: 'price',
          interval: 50,
          keyed: true
        }
      }
    }
  }
)
puts response

const response = await client.search({
  index: "sales",
  size: 0,
  aggs: {
    prices: {
      histogram: {
        field: "price",
        interval: 50,
        keyed: true,
      },
    },
  },
});
console.log(response);

POST /sales/_search?size=0
{
  "aggs": {
    "prices": {
      "histogram": {
        "field": "price",
        "interval": 50,
        "keyed": true
      }
    }
  }
}

响应

{
  ...
  "aggregations": {
    "prices": {
      "buckets": {
        "0.0": {
          "key": 0.0,
          "doc_count": 1
        },
        "50.0": {
          "key": 50.0,
          "doc_count": 1
        },
        "100.0": {
          "key": 100.0,
          "doc_count": 0
        },
        "150.0": {
          "key": 150.0,
          "doc_count": 2
        },
        "200.0": {
          "key": 200.0,
          "doc_count": 3
        }
      }
    }
  }
}

缺失值

编辑

missing 参数定义如何处理缺少值的文档。默认情况下，它们将被忽略，但也可以将其视为具有值。

resp = client.search(
    index="sales",
    size="0",
    aggs={
        "quantity": {
            "histogram": {
                "field": "quantity",
                "interval": 10,
                "missing": 0
            }
        }
    },
)
print(resp)

response = client.search(
  index: 'sales',
  size: 0,
  body: {
    aggregations: {
      quantity: {
        histogram: {
          field: 'quantity',
          interval: 10,
          missing: 0
        }
      }
    }
  }
)
puts response

const response = await client.search({
  index: "sales",
  size: 0,
  aggs: {
    quantity: {
      histogram: {
        field: "quantity",
        interval: 10,
        missing: 0,
      },
    },
  },
});
console.log(response);

POST /sales/_search?size=0
{
  "aggs": {
    "quantity": {
      "histogram": {
        "field": "quantity",
        "interval": 10,
        "missing": 0 
      }
    }
  }
}

在 quantity 字段中没有值的文档将落入与值为 0 的文档相同的桶中。

直方图字段

编辑

在直方图字段上运行直方图聚合会计算每个区间的总计数。

例如，针对以下索引执行直方图聚合，该索引存储不同网络的延迟指标（以毫秒为单位）的预聚合直方图：

resp = client.indices.create(
    index="metrics_index",
    mappings={
        "properties": {
            "network": {
                "properties": {
                    "name": {
                        "type": "keyword"
                    }
                }
            },
            "latency_histo": {
                "type": "histogram"
            }
        }
    },
)
print(resp)

resp1 = client.index(
    index="metrics_index",
    id="1",
    refresh=True,
    document={
        "network.name": "net-1",
        "latency_histo": {
            "values": [
                1,
                3,
                8,
                12,
                15
            ],
            "counts": [
                3,
                7,
                23,
                12,
                6
            ]
        }
    },
)
print(resp1)

resp2 = client.index(
    index="metrics_index",
    id="2",
    refresh=True,
    document={
        "network.name": "net-2",
        "latency_histo": {
            "values": [
                1,
                6,
                8,
                12,
                14
            ],
            "counts": [
                8,
                17,
                8,
                7,
                6
            ]
        }
    },
)
print(resp2)

resp3 = client.search(
    index="metrics_index",
    size="0",
    aggs={
        "latency_buckets": {
            "histogram": {
                "field": "latency_histo",
                "interval": 5
            }
        }
    },
)
print(resp3)

response = client.indices.create(
  index: 'metrics_index',
  body: {
    mappings: {
      properties: {
        network: {
          properties: {
            name: {
              type: 'keyword'
            }
          }
        },
        latency_histo: {
          type: 'histogram'
        }
      }
    }
  }
)
puts response

response = client.index(
  index: 'metrics_index',
  id: 1,
  refresh: true,
  body: {
    'network.name' => 'net-1',
    latency_histo: {
      values: [
        1,
        3,
        8,
        12,
        15
      ],
      counts: [
        3,
        7,
        23,
        12,
        6
      ]
    }
  }
)
puts response

response = client.index(
  index: 'metrics_index',
  id: 2,
  refresh: true,
  body: {
    'network.name' => 'net-2',
    latency_histo: {
      values: [
        1,
        6,
        8,
        12,
        14
      ],
      counts: [
        8,
        17,
        8,
        7,
        6
      ]
    }
  }
)
puts response

response = client.search(
  index: 'metrics_index',
  size: 0,
  body: {
    aggregations: {
      latency_buckets: {
        histogram: {
          field: 'latency_histo',
          interval: 5
        }
      }
    }
  }
)
puts response

const response = await client.indices.create({
  index: "metrics_index",
  mappings: {
    properties: {
      network: {
        properties: {
          name: {
            type: "keyword",
          },
        },
      },
      latency_histo: {
        type: "histogram",
      },
    },
  },
});
console.log(response);

const response1 = await client.index({
  index: "metrics_index",
  id: 1,
  refresh: "true",
  document: {
    "network.name": "net-1",
    latency_histo: {
      values: [1, 3, 8, 12, 15],
      counts: [3, 7, 23, 12, 6],
    },
  },
});
console.log(response1);

const response2 = await client.index({
  index: "metrics_index",
  id: 2,
  refresh: "true",
  document: {
    "network.name": "net-2",
    latency_histo: {
      values: [1, 6, 8, 12, 14],
      counts: [8, 17, 8, 7, 6],
    },
  },
});
console.log(response2);

const response3 = await client.search({
  index: "metrics_index",
  size: 0,
  aggs: {
    latency_buckets: {
      histogram: {
        field: "latency_histo",
        interval: 5,
      },
    },
  },
});
console.log(response3);

PUT metrics_index
{
  "mappings": {
    "properties": {
      "network": {
        "properties": {
          "name": {
            "type": "keyword"
          }
        }
      },
      "latency_histo": {
         "type": "histogram"
      }
    }
  }
}

PUT metrics_index/_doc/1?refresh
{
  "network.name" : "net-1",
  "latency_histo" : {
      "values" : [1, 3, 8, 12, 15],
      "counts" : [3, 7, 23, 12, 6]
   }
}

PUT metrics_index/_doc/2?refresh
{
  "network.name" : "net-2",
  "latency_histo" : {
      "values" : [1, 6, 8, 12, 14],
      "counts" : [8, 17, 8, 7, 6]
   }
}

POST /metrics_index/_search?size=0
{
  "aggs": {
    "latency_buckets": {
      "histogram": {
        "field": "latency_histo",
        "interval": 5
      }
    }
  }
}

histogram 聚合将根据 values 计算的每个区间的计数进行求和，并返回以下输出：

{
  ...
  "aggregations": {
    "latency_buckets": {
      "buckets": [
        {
          "key": 0.0,
          "doc_count": 18
        },
        {
          "key": 5.0,
          "doc_count": 48
        },
        {
          "key": 10.0,
          "doc_count": 25
        },
        {
          "key": 15.0,
          "doc_count": 6
        }
      ]
    }
  }
}

直方图聚合是一种桶聚合，它将文档划分为桶，而不是像指标聚合那样计算字段上的指标。每个桶代表文档的集合，子聚合可以在其上运行。另一方面，直方图字段是一个预聚合字段，它在一个字段内表示多个值：数值数据的桶和每个桶的项目/文档计数。直方图聚合的预期输入（预期原始文档）和直方图字段（提供摘要信息）之间的这种不匹配限制了聚合的结果，使其仅包含每个桶的文档计数。

因此，在直方图字段上执行直方图聚合时，不允许使用子聚合。

此外，在直方图字段上运行直方图聚合时，不支持 missing 参数。

« 全局聚合 IP 前缀聚合 »