terms aggregation
即词项分桶聚合。它是 Elasticsearch 最常用的聚合，类同于关系型数据库依据关键字段做 group。
-
size：返回的词项分桶数量，默认 10。阈值 65535。默认情况下，协调节点向每个分片请求 top size 数量的词项桶，并且在所有分片都响应后，将结果进行缩减并返回给客户端。如果实际词项桶的数量大于 size，则返回的词项桶可能会存在偏差并且不准确。
-
shard_size：每个分片返回的词项分桶数量，默认为 size * 1.5 + 10。shard_size 越大，结果越准确，但是最终计算结果的成本也越高（每个分片上的优先级队列会更大，并且节点与客户端之间的数据传输量也更大）。shard_size 不能比 size 小，否则 Elasticsearch 会覆盖该属性值，将其设置为和 size 一样的值。
-
min_doc_count：限制返回的词项分桶中对应文档的命中数量必须满足的最小值，默认 1。
-
shard_min_doc_count：限制每个分片返回的词项分桶中对应文档的命中数量必须满足的最小值，默认 0。必须小于 min_doc_count。建议为 min_doc_count / 分片数。
-
show_term_doc_count_error：显示词项分桶统计数据的错误信息，默认 false。用来显示聚合返回的每个词项的错误值，错误值表示文档计数在最差情况下的错误。这个错误值在决定 shard_size 参数值时非常有用。
-
order：指定排序规则。默认按照 doc_count 逆序排序。
-
missing：指定字段的值不存在时，给予文档的缺省值。默认会忽略。
修改返回的词项分桶的数量的阈值。
PUT _cluster/settings
{
"transient": {
"search.max_buckets": 10
}
}
查询航班目的地最多的 Top 10 国家。
GET kibana_sample_data_flights/_search
{
"size": 0,
"aggs": {
"DestCountry": {
"terms": {
"field": "DestCountry",
"size": 10
}
}
}
}
结果输出如下：
{
"took" : 38,
"timed_out" : false,
"_shards" : {
"total" : 1,
"successful" : 1,
"skipped" : 0,
"failed" : 0
},
"hits" : {
"total" : {
"value" : 10000,
"relation" : "gte"
},
"max_score" : null,
"hits" : [ ]
},
"aggregations" : {
"DestCountry" : {
"doc_count_error_upper_bound" : 0,
"sum_other_doc_count" : 3187,
"buckets" : [
{
"key" : "IT",
"doc_count" : 2371
},
{
"key" : "US",
"doc_count" : 1987
},
{
"key" : "CN",
"doc_count" : 1096
},
{
"key" : "CA",
"doc_count" : 944
},
{
"key" : "JP",
"doc_count" : 774
},
{
"key" : "RU",
"doc_count" : 739
},
{
"key" : "CH",
"doc_count" : 691
},
{
"key" : "GB",
"doc_count" : 449
},
{
"key" : "AU",
"doc_count" : 416
},
{
"key" : "PL",
"doc_count" : 405
}
]
}
}
}
词项分桶聚合返回的 doc_count 值是近似的。可以使用参考如下两个指标来判断 doc_count 值是否是准确的。
-
sum_other_doc_count：查询结果中没有出现的所有词项的文档总数。
-
doc_count_error_upper_bound：查询结果中没有出现的词项的最大可能文档数。它的值是所有分片返回的最后一个词项的文档数量的和。当
show_term_doc_count_error参数设置为 true，可以查看每个词项对应的文档数量的误差。这些误差只有当聚合结果按照文档数降序排序时才会被统计。此外，如果按照词项值本身排序、按照文档数升序或者按照子聚合结果排序都无法统计误差，doc_count_error_upper_bound 会返回 -1。
GET kibana_sample_data_flights/_search
{
"size": 0,
"aggs": {
"DestCountry": {
"terms": {
"field": "DestCountry",
"size": 10,
"show_term_doc_count_error": true
}
}
}
}
结果输出如下：
{
"took" : 5,
"timed_out" : false,
"_shards" : {
"total" : 1,
"successful" : 1,
"skipped" : 0,
"failed" : 0
},
"hits" : {
"total" : {
"value" : 10000,
"relation" : "gte"
},
"max_score" : null,
"hits" : [ ]
},
"aggregations" : {
"DestCountry" : {
"doc_count_error_upper_bound" : 0,
"sum_other_doc_count" : 3187,
"buckets" : [
{
"key" : "IT",
"doc_count" : 2371,
"doc_count_error_upper_bound" : 0
},
{
"key" : "US",
"doc_count" : 1987,
"doc_count_error_upper_bound" : 0
},
{
"key" : "CN",
"doc_count" : 1096,
"doc_count_error_upper_bound" : 0
},
{
"key" : "CA",
"doc_count" : 944,
"doc_count_error_upper_bound" : 0
},
{
"key" : "JP",
"doc_count" : 774,
"doc_count_error_upper_bound" : 0
},
{
"key" : "RU",
"doc_count" : 739,
"doc_count_error_upper_bound" : 0
},
{
"key" : "CH",
"doc_count" : 691,
"doc_count_error_upper_bound" : 0
},
{
"key" : "GB",
"doc_count" : 449,
"doc_count_error_upper_bound" : 0
},
{
"key" : "AU",
"doc_count" : 416,
"doc_count_error_upper_bound" : 0
},
{
"key" : "PL",
"doc_count" : 405,
"doc_count_error_upper_bound" : 0
}
]
}
}
}
排序
默认按照 doc_count 逆序排序。不推荐按照 doc_count 升序排序或者在子聚合中排序，这会增加统计文档数量的错误。但是如果在单一分片或者聚合使用的字段在索引时用做路由键，这两种情况下却是准确的。
_count：按照数量排序，默认的排序方式。
_key：按照词项排序。
_term： 按照词项排序。
按照文档数量的升序排序。
GET kibana_sample_data_flights/_search
{
"size": 0,
"aggs": {
"DestCountry": {
"terms": {
"field": "DestCountry",
"size": 10,
"show_term_doc_count_error": true,
"order": {
"_count": "asc"
}
}
}
}
}
按照 key 的字母顺序升序排序。
GET kibana_sample_data_flights/_search
{
"size": 0,
"aggs": {
"DestCountry": {
"terms": {
"field": "DestCountry",
"size": 10,
"show_term_doc_count_error": true,
"order": {
"_key": "asc"
}
}
}
}
}
查询航班飞行最短的 Top 10 国家。
GET kibana_sample_data_flights/_search
{
"size": 0,
"aggs": {
"DestCountry": {
"terms": {
"field": "DestCountry",
"size": 10,
"order": {
"min_FlightTimeMin": "desc"
}
},
"aggs": {
"min_FlightTimeMin": {
"min": {
"field": "FlightTimeMin"
}
}
}
}
}
}
GET kibana_sample_data_flights/_search
{
"size": 0,
"aggs": {
"DestCountry": {
"terms": {
"field": "DestCountry",
"size": 10,
"order": {
"stats_FlightTimeMin.max": "desc"
}
},
"aggs": {
"stats_FlightTimeMin": {
"stats": {
"field": "FlightTimeMin"
}
}
}
}
}
}
词项嵌套分桶
嵌套深度建议不要超过三层。
GET kibana_sample_data_flights/_search
{
"size": 0,
"aggs": {
"DestCountry": {
"terms": {
"field": "DestCountry",
"size": 10,
"show_term_doc_count_error": true
},
"aggs": {
"OriginCountry": {
"terms": {
"field": "OriginCountry",
"size": 10
}
}
}
}
}
}
脚本方式
GET kibana_sample_data_flights/_search
{
"size": 0,
"aggs": {
"DestCountry": {
"terms": {
"script": {
"source": """
doc['DestCountry'].value + "-DEMO";
""",
"lang": "painless"
},
"size": 10
}
}
}
}
结果输出如下：
{
"took" : 56,
"timed_out" : false,
"_shards" : {
"total" : 1,
"successful" : 1,
"skipped" : 0,
"failed" : 0
},
"hits" : {
"total" : {
"value" : 10000,
"relation" : "gte"
},
"max_score" : null,
"hits" : [ ]
},
"aggregations" : {
"DestCountry" : {
"doc_count_error_upper_bound" : 0,
"sum_other_doc_count" : 3187,
"buckets" : [
{
"key" : "IT-DEMO",
"doc_count" : 2371
},
{
"key" : "US-DEMO",
"doc_count" : 1987
},
{
"key" : "CN-DEMO",
"doc_count" : 1096
},
{
"key" : "CA-DEMO",
"doc_count" : 944
},
{
"key" : "JP-DEMO",
"doc_count" : 774
},
{
"key" : "RU-DEMO",
"doc_count" : 739
},
{
"key" : "CH-DEMO",
"doc_count" : 691
},
{
"key" : "GB-DEMO",
"doc_count" : 449
},
{
"key" : "AU-DEMO",
"doc_count" : 416
},
{
"key" : "PL-DEMO",
"doc_count" : 405
}
]
}
}
}
词项分桶键值过滤
支持精确键值过滤与模糊匹配方式（通过正则表达式）过滤。个人发现 Elasticsearch 7.14 版本模糊匹配方式实际操作中不生效。
- include：包括指定的词项分桶值。
- exclude：不包括指定的词项分桶值。
GET kibana_sample_data_flights/_search
{
"size": 0,
"aggs": {
"DestCountry": {
"terms": {
"field": "DestCountry",
"size": 10,
"show_term_doc_count_error": true,
"include": ["US", "IT", "CN"]
}
}
}
}
结果输出如下：
{
"took" : 2,
"timed_out" : false,
"_shards" : {
"total" : 1,
"successful" : 1,
"skipped" : 0,
"failed" : 0
},
"hits" : {
"total" : {
"value" : 10000,
"relation" : "gte"
},
"max_score" : null,
"hits" : [ ]
},
"aggregations" : {
"DestCountry" : {
"doc_count_error_upper_bound" : 0,
"sum_other_doc_count" : 0,
"buckets" : [
{
"key" : "IT",
"doc_count" : 2371,
"doc_count_error_upper_bound" : 0
},
{
"key" : "US",
"doc_count" : 1987,
"doc_count_error_upper_bound" : 0
},
{
"key" : "CN",
"doc_count" : 1096,
"doc_count_error_upper_bound" : 0
}
]
}
}
}
词项分桶分区聚合
很多时候需要统计的分桶数量太多，导致一次运行很慢。可以借助分区机制，在客户端进行合并。对所有可能的分桶进行分区。
partition：分区编号。从 0 开始。
num_partitions：分区数量。
GET kibana_sample_data_flights/_search
{
"size": 0,
"aggs": {
"DestCountry": {
"terms": {
"field": "DestCountry",
"size": 10,
"show_term_doc_count_error": true,
"include": {
"partition": 2,
"num_partitions": 5
}
}
}
}
}
个人在实际操作中，发现每次调整 partition的值，返回的桶的数量可能会不同。比如partition设置为2，结果返回8个桶；parition设置为1，结果返回6个桶，
词项分桶统计收集模型
- collect_mode：词项分桶统计收集模型。
- depth_first：（默认值）深度优先。适用于分桶数据量小的，分桶比较固定的，建议 10000 以内。
- breadth_first：广度优先。适用于分桶数据量大的。
GET kibana_sample_data_flights/_search
{
"size": 0,
"aggs": {
"DestCountry": {
"terms": {
"field": "DestCountry",
"size": 10,
"show_term_doc_count_error": true,
"collect_mode": "depth_first"
}
}
}
}
词项分桶存储选择
- execution_hint：词项分桶临时存储设置。
- map：使用 map 结构。适用于少量分桶的聚合统计。
- global_ordinals：（默认值）使用全局序号结构。适用于大量分桶的聚合统计。
GET kibana_sample_data_flights/_search
{
"size": 0,
"aggs": {
"DestCountry": {
"terms": {
"field": "DestCountry",
"size": 10,
"show_term_doc_count_error": true,
"execution_hint": "map"
}
}
}
}
提前加载全局序号
Elasticsearch 在使用全局序号时，第一次需要从 doc_values 读取所有值来构建全局序号。可以设置提前加载到内存中，避免查询响应慢。
- eager_global_ordinals：设置 true，提前加载并构建全局序号。
PUT my-index-000001/_mapping
{
"properties": {
"tags": {
"type": "keyword",
"eager_global_ordinals": true
}
}
}
指标聚合进行子聚合
stats 指标聚合作为子聚合。
GET kibana_sample_data_ecommerce/_search
{
"size": 0,
"aggs": {
"city_name": {
"terms": {
"field": "geoip.city_name",
"size": 10
},
"aggs": {
"taxful_total_price": {
"stats": {
"field": "taxful_total_price"
}
}
}
}
}
}
top_hits 指标聚合作为子聚合。
GET kibana_sample_data_ecommerce/_search
{
"size": 0,
"aggs": {
"aggs_customer_id": {
"terms": {
"field": "customer_id",
"size": 10
},
"aggs": {
"top_hits": {
"top_hits": {
"size": 2,
"_source": {
"includes": ["customer_id", "order_date", "products"]
},
"sort": [
{
"order_date": {
"order": "desc"
}
}
]
}
}
}
}
}
}
top_metrics 指标聚合作为子聚合。
GET kibana_sample_data_ecommerce/_search
{
"size": 0,
"aggs": {
"aggs_customer_id": {
"terms": {
"field": "customer_id",
"size": 2
},
"aggs": {
"top_metrics_total_price": {
"top_metrics": {
"metrics": {
"field": "taxful_total_price"
},
"sort": {
"order_date": "desc"
},
"size": 1
}
}
}
}
}
}
默认情况下，text 类型不支持 terms 词项分桶的，会直接报错。但是可以修改 text 类型的 fielddata 属性值（默认 false）。
fielddata 默认使用内存，需要消耗很大内存资源。建议能不用则不用，建议改变业务形式使用 keyword 类型。
GET kibana_sample_data_flights_3shard/_search
{
"size": 0,
"aggs": {
"Dest": {
"terms": {
"field": "Dest",
"size": 10
}
}
}
}
输出结果会报 illegal_argument_exception 异常。
为了解决这个问题。我们创建一个新的索引。
PUT kibana_sample_data_flights_fielddata
{
"mappings": {
"properties": {
"Dest": {
"type": "text",
"fielddata": true,
"fields": {
"keyword": {
"type": "keyword",
"ignore_above": 256
}
}
}
}
}
}
POST _reindex
{
"source": {
"index": "kibana_sample_data_flights"
},
"dest": {
"index": "kibana_sample_data_flights_fielddata"
}
}
现在再来执行一下上面的查询。
GET kibana_sample_data_flights_fielddata/_search
{
"size": 0,
"aggs": {
"Dest": {
"terms": {
"field": "Dest",
"size": 10
}
}
}
}
输出结果如下：
{
"took" : 799,
"timed_out" : false,
"_shards" : {
"total" : 1,
"successful" : 1,
"skipped" : 0,
"failed" : 0
},
"hits" : {
"total" : {
"value" : 10000,
"relation" : "gte"
},
"max_score" : null,
"hits" : [ ]
},
"aggregations" : {
"Dest" : {
"doc_count_error_upper_bound" : 0,
"sum_other_doc_count" : 22047,
"buckets" : [
{
"key" : "airport",
"doc_count" : 12527
},
{
"key" : "international",
"doc_count" : 7954
},
{
"key" : "zurich",
"doc_count" : 691
},
{
"key" : "xi'an",
"doc_count" : 526
},
{
"key" : "xianyang",
"doc_count" : 526
},
{
"key" : "air",
"doc_count" : 490
},
{
"key" : "base",
"doc_count" : 490
},
{
"key" : "armstrong",
"doc_count" : 486
},
{
"key" : "shanghai",
"doc_count" : 479
},
{
"key" : "james",
"doc_count" : 460
}
]
}
}
}
rare_terms aggregation
即稀有词项分桶聚合。对于词项分桶聚合按照 _count 顺序排序的方式会存在没有上限的错误，对此可以使用稀有词项分桶聚合。
稀有词项分桶聚合使用的是广度优先（breadth_first）模式，因为一旦文档数量达到阈值时，需要删除词项。这也意味着，稀有词项分桶聚合不能兼容深度优先（depth_first）模式的聚合，比如它作为 nested 聚合的子聚合时，运行结果就会抛出异常。
- field：（必须）聚合的字段。
- max_doc_count：每组的最大文档数量。默认 1。最大值为 100。
- precision：布谷鸟过滤器的精度。值越小，精度越高，内存占用也越高。不能小于 0.00001。默认 0.01。
- include：聚合结果中需要包括的值。可以指定多个，并且支持正则表达式。
- exclude：聚合结果中需要排除的值。可以指定多个，并且支持正则表达式。如果 include、exclude 同时指定，则 exclude 优先（即先使用 include 参数，再使用 exclude 参数）。
- missing：如果文档没有用于聚合的字段时，给予指定缺省值。
GET kibana_sample_data_flights/_search
{
"track_total_hits": true,
"size": 0,
"aggs": {
"DestCityName": {
"rare_terms": {
"field": "DestCityName",
"max_doc_count": 3,
"precision": 0.001,
"include": "(A.*|B.*)",
"exclude": ["Albuquerque", "Baltimore"]
}
}
}
}
输出结果如下：
{
"took" : 25,
"timed_out" : false,
"_shards" : {
"total" : 1,
"successful" : 1,
"skipped" : 0,
"failed" : 0
},
"hits" : {
"total" : {
"value" : 13059,
"relation" : "eq"
},
"max_score" : null,
"hits" : [ ]
},
"aggregations" : {
"DestCityName" : {
"buckets" : [
{
"key" : "Adelaide",
"doc_count" : 1
},
{
"key" : "Buffalo",
"doc_count" : 1
},
{
"key" : "Abu Dhabi",
"doc_count" : 2
},
{
"key" : "Billings",
"doc_count" : 2
},
{
"key" : "Amsterdam",
"doc_count" : 3
},
{
"key" : "Birmingham",
"doc_count" : 3
}
]
}
}
}
如果使用稀有词项分桶聚合得到的分桶数过多，可以修改 search.max_buckets 参数值进行限制。默认 65535。
# 临时修改
PUT _cluster/settings
{
"transient": {
"search.max_buckets": 100
}
}
# 永久修改
PUT _cluster/settings
{
"persistent": {
"search.max_buckets": 100
}
}
multi_terms aggregation
即多词项分桶聚合。
可以使用的参数与 terms 词项分桶聚合相同，这里不一一列出了。
GET kibana_sample_data_flights/_search
{
"track_total_hits": true,
"size": 0,
"aggs": {
"DestCountry_OriginCountry": {
"multi_terms": {
"terms": [
{
"field": "DestCountry"
},
{
"field": "OriginCountry"
}
]
}
}
}
}
输出结果如下：
{
"took" : 71,
"timed_out" : false,
"_shards" : {
"total" : 1,
"successful" : 1,
"skipped" : 0,
"failed" : 0
},
"hits" : {
"total" : {
"value" : 13059,
"relation" : "eq"
},
"max_score" : null,
"hits" : [ ]
},
"aggregations" : {
"DestCountry_OriginCountry" : {
"doc_count_error_upper_bound" : 0,
"sum_other_doc_count" : 10516,
"buckets" : [
{
"key" : [
"IT",
"IT"
],
"key_as_string" : "IT|IT",
"doc_count" : 459
},
{
"key" : [
"IT",
"US"
],
"key_as_string" : "IT|US",
"doc_count" : 379
},
{
"key" : [
"US",
"IT"
],
"key_as_string" : "US|IT",
"doc_count" : 328
},
{
"key" : [
"US",
"US"
],
"key_as_string" : "US|US",
"doc_count" : 322
},
{
"key" : [
"CN",
"IT"
],
"key_as_string" : "CN|IT",
"doc_count" : 195
},
{
"key" : [
"CA",
"IT"
],
"key_as_string" : "CA|IT",
"doc_count" : 192
},
{
"key" : [
"IT",
"JP"
],
"key_as_string" : "IT|JP",
"doc_count" : 192
},
{
"key" : [
"CN",
"US"
],
"key_as_string" : "CN|US",
"doc_count" : 185
},
{
"key" : [
"CA",
"US"
],
"key_as_string" : "CA|US",
"doc_count" : 147
},
{
"key" : [
"CH",
"CH"
],
"key_as_string" : "CH|CH",
"doc_count" : 144
}
]
}
}
}