词项聚合

terms 聚合为字段的每个唯一词项动态创建一个桶。

以下示例使用 terms 聚合查找 Web 日志数据中每个响应码对应的文档数量：

GET opensearch_dashboards_sample_data_logs/_search
{
  "size": 0,
  "aggs": {
    "response_codes": {
      "terms": {
        "field": "response.keyword",
        "size": 10
      }
    }
  }
}

示例响应

...
"aggregations" : {
  "response_codes" : {
    "doc_count_error_upper_bound" : 0,
    "sum_other_doc_count" : 0,
    "buckets" : [
      {
        "key" : "200",
        "doc_count" : 12832
      },
      {
        "key" : "404",
        "doc_count" : 801
      },
      {
        "key" : "503",
        "doc_count" : 441
      }
    ]
  }
 }
}

返回值带有键 key。 doc_count 指定每个桶中的文档数量。默认情况下，桶按 doc_count 降序排序。

size 和 shard_size 参数

terms 聚合返回的桶数量由 size 参数控制，默认值为 10。

此外，负责聚合的协调节点将提示每个分片提供其顶部的唯一词项。每个分片返回的桶数量由 shard_size 参数控制。此参数与 size 参数不同，它是作为一种提高桶文档计数准确性的机制而存在的。

例如，设想一个场景，其中 size 和 shard_size 参数的值均为 3。terms 聚合会提示每个分片提供其前三个唯一词项。协调节点汇总结果以计算最终结果。如果某个分片包含一个未包含在前三个中的对象，则该对象不会出现在响应中。但是，为此请求增加 shard_size 值将允许每个分片返回更多数量的唯一词项，从而增加协调节点接收所有相关结果的可能性。

默认情况下，shard_size 参数设置为 size * 1.5 + 10。

当使用并发段搜索时，shard_size 参数也会应用于每个段切片。

shard_size 参数是一种平衡 terms 聚合性能和文档计数准确性的方式。较高的 shard_size 值将确保更高的文档计数准确性，但会导致更高的内存和计算使用量。较低的 shard_size 值将具有更高的性能，但会导致较低的文档计数准确性。

文档计数误差

响应还包含两个键，名为 doc_count_error_upper_bound 和 sum_other_doc_count。

terms 聚合返回顶部的唯一词项。因此，如果数据包含许多唯一词项，则其中一些可能不会出现在结果中。sum_other_doc_count 字段表示从响应中排除的文档的总和。在这种情况下，该数字为 0，因为所有唯一值都出现在响应中。

doc_count_error_upper_bound 字段表示可能被排除在最终结果之外的唯一值的最大可能计数。使用此字段来估计计数的误差范围。

doc_count_error_upper_bound 值和准确性的概念仅适用于使用默认排序顺序（按文档计数降序）的聚合。这是因为当您按降序文档计数排序时，任何未返回的词项保证包含的文档数等于或少于已返回的词项。基于此，您可以计算出 doc_count_error_upper_bound。

如果 show_term_doc_count_error 参数设置为 true，则 terms 聚合除了显示总体值外，还将显示为每个唯一桶计算的 doc_count_error_upper_bound。

`min_doc_count` 和 `shard_min_doc_count` 参数

您可以使用 min_doc_count 参数过滤掉结果数少于 min_doc_count 的任何唯一词项。min_doc_count 阈值仅在合并从所有分片检索到的结果后应用。每个分片不知道给定词项的全局文档计数。如果全局频繁词项的顶部 shard_size 与分片本地的顶部词项之间存在显著差异，则在使用 min_doc_count 参数时可能会收到意外结果。

另外，shard_min_doc_count 参数用于过滤掉分片返回给协调器的唯一词项中结果数少于 shard_min_doc_count 的那些词项。

当使用并发段搜索时，shard_min_doc_count 参数不会应用于每个段切片。

收集模式

有两种可用的收集模式：depth_first 和 breadth_first。depth_first 收集模式以深度优先的方式展开聚合树的所有分支，并且仅在展开完成后执行修剪。

然而，当使用嵌套的 terms 聚合时，返回的桶数量的基数会乘以每个嵌套级别字段的基数，这使得在嵌套聚合时很容易看到桶数量的组合爆炸。

您可以使用 breadth_first 收集模式来解决此问题。在这种情况下，修剪将在聚合树的第一级展开到下一级之前应用于第一级，从而可能大大减少计算的桶数量。

此外，执行 breadth_first 收集存在相关的内存开销，这与匹配文档的数量成线性关系。这是因为 breadth_first 收集通过缓存和重放来自父级的已修剪桶集来工作。

处理预聚合数据

虽然 doc_count 字段提供了聚合到桶中的单个文档数量的表示，但 doc_count 本身无法正确递增存储预聚合数据的文档。为了处理预聚合数据并准确计算桶中的文档数量，您可以使用 _doc_count 字段在单个摘要字段中添加文档数量。当文档包含 _doc_count 字段时，所有桶聚合都会识别其值并累积增加桶的 doc_count。使用 _doc_count 字段时，请记住以下几点：

该字段不支持嵌套数组；只能使用正整数。
如果文档不包含 _doc_count 字段，聚合会将该文档计为增加计数 1。

依赖于准确文档计数的 UDB-SX 功能说明了使用 _doc_count 字段的重要性。

示例请求

PUT /my_index/_doc/1
{
  "response_code": 404,
  "date":"2022-08-05",
  "_doc_count": 20
}

PUT /my_index/_doc/2
{
  "response_code": 404,
  "date":"2022-08-06",
  "_doc_count": 10
}

PUT /my_index/_doc/3
{
  "response_code": 200,
  "date":"2022-08-06",
  "_doc_count": 300
}

GET /my_index/_search
{
  "size": 0,
  "aggs": {
    "response_codes": {
      "terms": {
        "field" : "response_code"
      }
    }
  }
}

示例响应

{
  "took" : 20,
  "timed_out" : false,
  "_shards" : {
    "total" : 1,
    "successful" : 1,
    "skipped" : 0,
    "failed" : 0
  },
  "hits" : {
    "total" : {
      "value" : 3,
      "relation" : "eq"
    },
    "max_score" : null,
    "hits" : [ ]
  },
  "aggregations" : {
    "response_codes" : {
      "doc_count_error_upper_bound" : 0,
      "sum_other_doc_count" : 0,
      "buckets" : [
        {
          "key" : 200,
          "doc_count" : 300
        },
        {
          "key" : 404,
          "doc_count" : 30
        }
      ]
    }
  }
}

词项聚合

示例响应

size 和 shard_size 参数

文档计数误差

min_doc_count 和 shard_min_doc_count 参数

收集模式

处理预聚合数据

示例请求

示例响应

`min_doc_count` 和 `shard_min_doc_count` 参数