« 全局聚合 IP 前缀聚合 »
Elastic 文档 ›Elasticsearch 指南 [8.17] ›聚合 ›桶聚合

直方图聚合

编辑

直方图聚合

编辑

一种基于多桶值源的聚合，可以应用于从文档中提取的数值或数值范围值。它动态地在值上构建固定大小（又称间隔）的桶。例如，如果文档有一个字段保存价格（数值），我们可以配置此聚合以动态构建间隔为 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，直方图也只会包含 2 个桶，分别从 100 和 150 开始。所有其他桶都将被省略，即使应该进入这些桶的文档存在于结果中。

排序

编辑

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

偏移量

编辑

默认情况下，桶键从 0 开始，然后以 interval 的等间隔步长继续，例如，如果间隔是 10，则前三个桶（假设其中有数据）将是 [0, 10)、[10, 20)、[20, 30)。可以使用 offset 选项移动桶边界。

通过一个例子可以最好地说明这一点。如果有 10 个文档，其值范围从 5 到 14，使用间隔 10 将导致两个桶，每个桶有 5 个文档。如果使用额外的偏移量 5，则只会有一个包含所有 10 个文档的单个桶 [5, 15)。

响应格式

编辑

默认情况下，桶将作为有序数组返回。也可以请求将响应作为哈希返回，哈希的键是桶的键

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 前缀聚合 »