elasticsearch/docs/reference/esql/functions/examples/bucket.asciidoc

// This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.

*Examples*

Using a target number of buckets, a start of a range, and an end of a range,
`BUCKET` picks an appropriate bucket size to generate the target number of buckets or fewer.
For example, asking for at most 20 buckets over a year results in monthly buckets:
[source.merge.styled,esql]
----
include::{esql-specs}/bucket.csv-spec[tag=docsBucketMonth]
----
[%header.monospaced.styled,format=dsv,separator=|]
|===
include::{esql-specs}/bucket.csv-spec[tag=docsBucketMonth-result]
|===

The goal isn't to provide *exactly* the target number of buckets,
it's to pick a range that people are comfortable with that provides at most the target number of buckets.

Combine `BUCKET` with <<esql-stats-by>> to create a histogram:
[source.merge.styled,esql]
----
include::{esql-specs}/bucket.csv-spec[tag=docsBucketMonthlyHistogram]
----
[%header.monospaced.styled,format=dsv,separator=|]
|===
include::{esql-specs}/bucket.csv-spec[tag=docsBucketMonthlyHistogram-result]
|===

NOTE: `BUCKET` does not create buckets that don't match any documents.
+ "That's why this example is missing `1985-03-01` and other dates.

Asking for more buckets can result in a smaller range.
For example, asking for at most 100 buckets in a year results in weekly buckets:
[source.merge.styled,esql]
----
include::{esql-specs}/bucket.csv-spec[tag=docsBucketWeeklyHistogram]
----
[%header.monospaced.styled,format=dsv,separator=|]
|===
include::{esql-specs}/bucket.csv-spec[tag=docsBucketWeeklyHistogram-result]
|===

NOTE: `BUCKET` does not filter any rows. It only uses the provided range to pick a good bucket size.
For rows with a value outside of the range, it returns a bucket value that corresponds to a bucket outside the range.
Combine`BUCKET` with <<esql-where>> to filter rows.

`BUCKET` can also operate on numeric fields. For example, to create a salary histogram:
[source.merge.styled,esql]
----
include::{esql-specs}/bucket.csv-spec[tag=docsBucketNumeric]
----
[%header.monospaced.styled,format=dsv,separator=|]
|===
include::{esql-specs}/bucket.csv-spec[tag=docsBucketNumeric-result]
|===

Unlike the earlier example that intentionally filters on a date range, you rarely want to filter on a numeric range.
You have to find the `min` and `max` separately. {esql} doesn't yet have an easy way to do that automatically.

Create hourly buckets for the last 24 hours, and calculate the number of events per hour:
[source.merge.styled,esql]
----
include::{esql-specs}/bucket.csv-spec[tag=docsBucketLast24hr]
----
[%header.monospaced.styled,format=dsv,separator=|]
|===
include::{esql-specs}/bucket.csv-spec[tag=docsBucketLast24hr-result]
|===
Create monthly buckets for the year 1985, and calculate the average salary by hiring month
[source.merge.styled,esql]
----
include::{esql-specs}/bucket.csv-spec[tag=bucket_in_agg]
----
[%header.monospaced.styled,format=dsv,separator=|]
|===
include::{esql-specs}/bucket.csv-spec[tag=bucket_in_agg-result]
|===