基数聚合

cardinality 聚合是一种单值指标聚合，用于统计字段中唯一值（不同值）的数量。

基数计数是近似值。更多信息请参阅控制精度。

参数

cardinality 聚合接受以下参数。

参数	必需/可选	数据类型	描述
`field`	必需	字符串	需要估计其基数的字段。
`precision_threshold`	可选	数值	低于此阈值时，计数预期接近精确。更多信息请参阅控制精度。
`execution_hint`	可选	字符串	如何运行聚合。有效值为 `ordinals` 和 `direct`。
`missing`	可选	与 `field` 类型相同	用于存储字段缺失实例的桶。如果未提供，缺失值将被忽略。

示例

以下示例请求查找 UDB-SX Dashboards 示例电子商务数据中唯一产品 ID 的数量：

GET opensearch_dashboards_sample_data_ecommerce/_search
{
  "size": 0,
  "aggs": {
    "unique_products": {
      "cardinality": {
        "field": "products.product_id"
      }
    }
  }
}

示例响应

如以下示例响应所示，聚合返回 unique_products 变量中的基数计数：

{
  "took": 176,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 4675,
      "relation": "eq"
    },
    "max_score": null,
    "hits": []
  },
  "aggregations": {
    "unique_products": {
      "value": 7033
    }
  }
}

控制精度

精确的基数计算需要将所有值加载到一个哈希集中并返回其大小。这种方法难以扩展；它可能占用大量内存并导致高延迟。

您可以通过使用 precision_threshold 设置来控制内存和准确性之间的权衡。此参数设置了一个阈值，低于该阈值时，计数预期接近精确。高于此值的计数可能不太准确。

precision_threshold 的默认值为 3,000。支持的最大值为 40,000。

基数聚合使用 HyperLogLog++ 算法。基数计数在精度阈值范围内通常非常准确，并且在大多数其他情况下，即使在阈值低至 100 的情况下，误差也在真实计数的 6% 以内。

预计算哈希值

对于高基数字符串字段，为索引字段存储哈希值并计算哈希的基数可以节省计算和内存资源。请谨慎使用此方法；它仅对于具有长字符串和/或高基数的集合更有效。数字字段和内存消耗较少的字符串集更适合直接处理。

示例：控制精度

将精度阈值设置为 10000 个唯一值：

GET opensearch_dashboards_sample_data_ecommerce/_search
{
  "size": 0,
  "aggs": {
    "unique_products": {
      "cardinality": {
        "field": "products.product_id",
        "precision_threshold": 10000
      }
    }
  }
}

响应与使用默认阈值的结果相似，但返回的值略有不同。改变 precision_threshold 参数以查看它如何影响基数估计。

配置聚合执行

您可以使用 execution_hint 设置来控制聚合的运行方式。此设置支持两个选项：

direct – 直接使用字段值。
ordinals – 使用字段的序号。

如果您不指定 execution_hint，UDB-SX 会自动为字段选择最佳选项。

在非序号字段上设置 ordinals 无效。同样，direct 对序号字段无效。 {: .note}

这是一个专家级设置。序号使用字节数组，其大小取决于字段的基数。高基数字段可能消耗大量堆内存，增加内存不足错误的风险。 {: .warning}

示例：控制执行

以下请求使用序号运行基数聚合：

GET opensearch_dashboards_sample_data_ecommerce/_search
{
  "size": 0,
  "aggs": {
    "unique_products": {
      "cardinality": {
        "field": "products.product_id",
        "execution_hint": "ordinals"
      }
    }
  }
}

缺失值

您可以为聚合字段的缺失实例分配一个值。更多信息请参阅缺失值聚合。

在基数聚合中替换缺失值会将替换值添加到唯一值列表中，使实际基数增加一。