AUTO_BUCKET

Syntax
AUTO_BUCKET(field, buckets, from, to)
Parameters
field
Numeric or date column from which to derive buckets.
buckets
Target number of buckets.
from
Start of the range. Can be a number or a date expressed as a string.
to
End of the range. Can be a number or a date expressed as a string.
DescriptionCreates human-friendly buckets and returns a value for each row that corresponds
to the resulting bucket the row falls into.Using a target number of buckets, a start of a range, and an end of a range,
AUTO_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:
```esql
FROM employees
| WHERE hire_date >= "1985-01-01T00:00:00Z" AND hire_date < "1986-01-01T00:00:00Z"
| EVAL month = AUTO_BUCKET(hire_date, 20, "1985-01-01T00:00:00Z", "1986-01-01T00:00:00Z")
| KEEP hire_date, month
| SORT hire_date
```

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 AUTO_BUCKET with
STATS ... BY to create a histogram:
```esql
FROM employees
| WHERE hire_date >= "1985-01-01T00:00:00Z" AND hire_date < "1986-01-01T00:00:00Z"
| EVAL month = AUTO_BUCKET(hire_date, 20, "1985-01-01T00:00:00Z", "1986-01-01T00:00:00Z")
| STATS hires_per_month = COUNT(*) BY month
| SORT month
```

AUTO_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:
```esql
FROM employees
| WHERE hire_date >= "1985-01-01T00:00:00Z" AND hire_date < "1986-01-01T00:00:00Z"
| EVAL week = AUTO_BUCKET(hire_date, 100, "1985-01-01T00:00:00Z", "1986-01-01T00:00:00Z")
| STATS hires_per_week = COUNT(*) BY week
| SORT week
```

AUTO_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
AUTO_BUCKET with WHERE to filter rows.
AUTO_BUCKET can also operate on numeric fields. For example, to create a
salary histogram:
```esql
FROM employees
| EVAL bs = AUTO_BUCKET(salary, 20, 25324, 74999)
| STATS COUNT(*) by bs
| SORT bs
```

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. ES|QL doesn’t yet have an easy way to do that automatically.ExamplesCreate hourly buckets for the last 24 hours, and calculate the number of events
per hour:
```esql
FROM sample_data
| WHERE @timestamp >= NOW() - 1 day and @timestamp < NOW()
| EVAL bucket = AUTO_BUCKET(@timestamp, 25, DATE_FORMAT(NOW() - 1 day), DATE_FORMAT(NOW()))
| STATS COUNT(*) BY bucket
```

Create monthly buckets for the year 1985, and calculate the average salary by
hiring month:
```esql
FROM employees
| WHERE hire_date >= "1985-01-01T00:00:00Z" AND hire_date < "1986-01-01T00:00:00Z"
| EVAL bucket = AUTO_BUCKET(hire_date, 20, "1985-01-01T00:00:00Z", "1986-01-01T00:00:00Z")
| STATS AVG(salary) BY bucket
| SORT bucket
```
