Tbucket

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

Examples

TBUCKET can work in two modes: one in which the size of the bucket is computed based on a buckets count recommendation and a range, and another in which the bucket size is provided directly as a duration or period.

Using a target number of buckets, a start of a range, and an end of a range, TBUCKET picks an appropriate bucket size to generate the target number of buckets or fewer. For example, asking for at most 3 buckets over a 2 hour range results in hourly buckets {applies_to}stack: ga 9.4:

FROM sample_data
| STATS count = COUNT(*) BY bucket = TBUCKET(3, "2023-10-23T12:00:00Z", "2023-10-23T14:00:00Z")
| SORT bucket

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.

Asking for more buckets can result in a finer granularity. For example, asking for at most 20 buckets in the same range results in 10-minute buckets {applies_to}stack: ga 9.4:

FROM sample_data
| STATS count = COUNT(*) BY bucket = TBUCKET(20, "2023-10-23T12:00:00Z", "2023-10-23T14:00:00Z")
| SORT bucket

::::{note} TBUCKET 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 TBUCKET with WHERE to filter rows. ::::

If the desired bucket size is known in advance, simply provide it as the first argument, leaving the range out:

FROM sample_data
| STATS min = MIN(@timestamp), max = MAX(@timestamp) BY bucket = TBUCKET(1 hour)
| SORT min

::::{note} When providing the bucket size, it must be a time duration or date period. Also the reference is epoch, which starts at 0001-01-01T00:00:00Z. ::::

The bucket size can also be provided as a string:

FROM sample_data
| STATS min = MIN(@timestamp), max = MAX(@timestamp) BY bucket = TBUCKET("1 hour")
| SORT min