Date Histogram Aggregation · Elasticsearch 5.4 中文文檔

# Date Histogram Aggregation 原文鏈接 : [https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-bucket-datehistogram-aggregation.html](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-bucket-datehistogram-aggregation.html) 譯文鏈接 : [http://www.apache.wiki/display/Elasticsearch](http://www.apache.wiki/display/Elasticsearch)（修改該鏈接為 **ApacheCN** 對應的譯文鏈接）貢獻者 : @于永超，[ApacheCN](/display/~apachecn)，[Apache中文網](/display/~apachechina) ## Date Histogram Aggregation 與直方圖類似的多bucket聚合，但只能應用于日期值. 由于日期在elastic search中以內部值表示,也可以在日期上使用正常的直方圖，盡管精度會受到影響(想想閏年和一個月的天數)。因此，我們需要對基于時間的數據進行特殊的支持。從功能的角度來看，該直方圖支持與正常[直方圖](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-bucket-histogram-aggregation.html)相同的特征，?主要區別是間隔可以通過日期/時間表達式指定。要求一個月的間隔時間的bucket： ``` POST /sales/_search?size=0 { "aggs" : { "sales_over_time" : { "date_histogram" : { "field" : "date", "interval" : "month" } } } } ``` ?對于時間間隔，有一下可用表達式：`year`,?`quarter`,?`month`,?`week`,?`day`,?`hour`,?`minute`,?`second` ?時間值也可以通過?[time units](https://www.elastic.co/guide/en/elasticsearch/reference/current/common-options.html#time-units "Time unitsedit")?parsing（時間單元解析）支持的縮寫來指定，這里要注意，不支持小數時間值，但是您可以通過轉換到另一個時間單位來解決這個問題（例如，1.5h可以被指定為90m） ``` POST /sales/_search?size=0 { "aggs" : { "sales_over_time" : { "date_histogram" : { "field" : "date", "interval" : "90m" } } } } ``` ### Keys 在內部，日期被表示為64位數，表示時間戳，以毫秒為單位。這些時間戳作為bucket的key（鍵）返回，key_as_string是使用**format**參數指定的格式轉換為格式化日期字符串的同一時間戳。如果沒有指定**format**，那么它將使用字段映射中指定的第一個日期格式。 ``` POST /sales/_search?size=0 { "aggs" : { "sales_over_time" : { "date_histogram" : { "field" : "date", "interval" : "1M", "format" : "yyyy-MM-dd" #1 } } } } ``` #1 ?支持表達式的日期[format pattern](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-bucket-daterange-aggregation.html#date-format-pattern "Date Format/Pattern")(格式模式) 返回結果： ``` { ... "aggregations": { "sales_over_time": { "buckets": [ { "key_as_string": "2015-01-01", "key": 1420070400000, "doc_count": 3 }, { "key_as_string": "2015-02-01", "key": 1422748800000, "doc_count": 2 }, { "key_as_string": "2015-03-01", "key": 1425168000000, "doc_count": 2 } ] } } } ``` ### Time Zone 日期時間以UTC為單位存儲在elastic search中, ?默認情況下，所有的bucketing (加權)?和?rounding(舍入)都是以UTC為單位，bucketing要使用不同的時區，可以使用**time_zone**參數來表示。時區可以指定為ISO 8601 UTC偏移量 (例如 +01：00或-08：00),?或者作為時區id，在TZ數據庫中使用的標識符，如America / Los_Angeles 請考慮以下示例: ``` PUT my_index/log/1?refresh { "date": "2015-10-01T00:30:00Z" } PUT my_index/log/2?refresh { "date": "2015-10-01T01:30:00Z" } GET my_index/_search?size=0 { "aggs": { "by_day": { "date_histogram": { "field": "date", "interval": "day" } } } } ``` 如果沒有指定時區，則使用UTC，這將導致這兩份文件都被放在同一天的bucket(桶)中，這將于2015年10月1日午夜開始。 ``` { ... "aggregations": { "by_day": { "buckets": [ { "key_as_string": "2015-10-01T00:00:00.000Z", "key": 1443657600000, "doc_count": 2 } ] } } } ``` 如果指定了-01：00的time_zone的時區，則午夜從UTC之前的一小時開始： ``` GET my_index/_search?size=0 { "aggs": { "by_day": { "date_histogram": { "field": "date", "interval": "day", "time_zone": "-01:00" } } } } ``` 現在，第一份文件落在2015年9月30日bucket(桶)中，而第二份文件則落在了2015年10月1日的bucket(桶)里: ``` { ... "aggregations": { "by_day": { "buckets": [ { "key_as_string": "2015-09-30T00:00:00.000-01:00", #1 "key": 1443574800000, "doc_count": 1 }, { "key_as_string": "2015-10-01T00:00:00.000-01:00", #2 "key": 1443661200000, "doc_count": 1 } ] } } } ``` #1 ??key_as_string值代表指定時區的每一天的午夜。 #2 當使用遵循DST（夏令時）的時區變化時,當這些變化發生的時候，bucket(桶)的大小與使用間隔時所期望的大小略有不同。例如，考慮在CET時區的DST開始：2016年3月27日凌晨2點，時鐘轉到1小時到當地時間3點。當使用日期作為間隔時，當天的bucket將只保存23小時的數據而不是其他桶的24小時，對于較短的時間間隔(例如，12h)也是如此。在3月27日上午，當DST轉移發生時，我們只有一個11小時的bucket(桶) ### Offset offset參數通過指定的正(+)或負偏移(-)持續時間來改變每個bucket的開始值，比如1h表示一小時，1d表示一天。有關更多可能的持續時間選項，請參閱“[Time units](https://www.elastic.co/guide/en/elasticsearch/reference/current/common-options.html#time-units)”一節例如，當使用一天的間隔時，每個桶從午夜持續到午夜。將偏移量設置為+ 6h，將會改變每個**bucket(**桶)的運行時間從早上6點到6點 ``` PUT my_index/log/1?refresh { "date": "2015-10-01T05:30:00Z" } PUT my_index/log/2?refresh { "date": "2015-10-01T06:30:00Z" } GET my_index/_search?size=0 { "aggs": { "by_day": { "date_histogram": { "field": "date", "interval": "day", "offset": "+6h" } } } } ``` 而不是從午夜開始的一個單獨的bucket(桶)，上面的請求將文件從早上6點開始放到bucket(桶)里: ``` { ... "aggregations": { "by_day": { "buckets": [ { "key_as_string": "2015-09-30T06:00:00.000Z", "key": 1443592800000, "doc_count": 1 }, { "key_as_string": "2015-10-01T06:00:00.000Z", "key": 1443679200000, "doc_count": 1 } ] } } } ``` 每個bucket(桶)的開始偏移量是在完成time_zone調整后計算的。 ### Keyed Response 將keyed標志設置為true會將一個惟一的字符串鍵與每個bucket關聯起來，并將范圍作為散列而不是數組返回: ``` POST /sales/_search?size=0 { "aggs" : { "sales_over_time" : { "date_histogram" : { "field" : "date", "interval" : "1M", "format" : "yyyy-MM-dd", "keyed": true } } } } ``` 響應結果： ``` { ... "aggregations": { "sales_over_time": { "buckets": { "2015-01-01": { "key_as_string": "2015-01-01", "key": 1420070400000, "doc_count": 3 }, "2015-02-01": { "key_as_string": "2015-02-01", "key": 1422748800000, "doc_count": 2 }, "2015-03-01": { "key_as_string": "2015-03-01", "key": 1425168000000, "doc_count": 2 } } } } } ``` ### Scripts 像正常的[直方圖](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-bucket-histogram-aggregation.html)一樣，支持文檔級腳本和值級腳本，還可以使用order設置來控制返回的bucket的順序，并根據min_doc_count設置對返回的bucket進行篩選(默認情況下，與文檔匹配的第一個存儲桶與最后一個之間的所有存儲桶都將被返回）,該直方圖還支持extended_bounds設置，這使得能夠將直方圖的范圍擴展到數據本身之外(想了解更多關于為什么要這么做的原因請參考[這里](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-bucket-histogram-aggregation.html#search-aggregations-bucket-histogram-aggregation-extended-bounds)的解釋) ### Missing value **missing**參數定義了如何處理缺少值的文檔。默認情況下，它們將被忽略，但也可以將它們視為具有值 ``` POST /sales/_search?size=0 { "aggs" : { "sale_date" : { "date_histogram" : { "field" : "date", "interval": "year", "missing": "2000/01/01" #1 } } } } ``` #1 ?在publish_date字段中沒有值的文檔將與具有值2000-01-01的文檔落在同一個存儲區中。