A histogram aggregation groups documents into consecutive numeric buckets. For example, it can classify books by Amazon rating or countries by critical-patient counts. Each bucket reports a key and its document count. section 2.6.2 section 13.3.1
Listing 13.10 A histogram aggregation for books
GET books/_search
{
"size": 0,
"aggs": {
"ratings_histogram": { #1
"histogram": { #2
"field": "amazon_rating", #3
"interval": 1 #4
}
}
}
}
This query returns rating buckets without individual search hits: size 0 suppresses hits, field selects the numeric value, and interval 1 creates one-point buckets. section 13.3.1
Reading the bucket response
A bucket with key 2500 represents the interval beginning at 2,500; its doc_count gives the number of matching documents. Empty buckets can also appear, such as a bucket with key 5000 and doc_count 0. section 2.6.2
Choose the related aggregation according to the grouping requirement:
- Use a histogram when equal, system-defined numeric intervals are appropriate. section 13.3.3
- Use a range aggregation for custom boundaries, such as ratings from 1 to 4 and from 4 to 5; from is inclusive and to is exclusive. section 13.3.3
- Combine or nest aggregations to calculate metrics such as sales totals or minimum and maximum values inside each bucket. section 13.1.3
- Use date_histogram for date fields, choosing calendar intervals such as years or fixed intervals such as 730 days. section 13.3.1
- Send the aggregation results to a client such as Kibana when a bar-chart visualization is needed. section 13.3.1
