Time Bucketizer

Time Bucketizer

A time bucketizer in AQL specifies how to bucketize a time dimension according to the query timezone before grouping by. A time column must be bucketized, raw timestamps should not be used directly as group by conditions.

There are two types of bucketizers:

• Time series bucketizers that partition the timeline into non-overlapping and non-recurring buckets. A bucket corresponds to a single range of time in the timeline aligned to calendar unit boundaries using the specified timezone. The name of the bucket is formatted using the start of the bucket. This was also known as precision truncation based: precision of the timestamp is truncated to the desired level. Examples:

Bucketizer	Example Bucket Name	Comment
minute / m	2016-01-06 14:37	beginning of the minute
{2,3,4,5,6,10,12,15,20,30} minutes/m)	2016-01-06 14:30	beginning of the hour-aligned N minute
quarter-hour	2016-01-06 14:00	beginning of a quarter hour, same as 15m
hour	2016-01-06 14:00	beginning of the hour
{2,3,4,6,8,12} hours	2016-01-06 12:00	beginning of the day-aligned N hour
day	2016-01-06	beginning of the day (midnight)
week	2016-01-04	beginning of the ISO week (Monday)
month	2016-01	beginning of the month
quarter	2016-Q1	beginning of the quarter
year	2016	beginning of the year

• Recurring unit bucketizers. The timeline is partitioned into non-overlapping ranges; the ranges are then mapped into recurring buckets. This was also known as component based: the buckets represent recurring time concepts, and are no longer single points/periods in the timeline. Here are some examples:

Bucketizer	Example Bucket Name
time of day	14:37
{2,3,4,5,6,10,15,20,30} minutes of day	14:30
hour of day	14:00
hour of week	Wednesday 14:00
day of week	Wednesday
day of month	6
day of year	January 6
month of year	January
quarter of year	Q1

Note this is different from the time series model in the Artemis query language, where start and end are first (optionally) snapped to calendar, and then each bucket/step/interval generated is aligned to either start or end using a specified size. In Apollo Query Language, time buckets are independent from the time range (time filter), and the buckets are always aligned to calendar unit boundaries. This significantly reduces the query space and made caching more effective.

Time Unit

By default the bucket names are reported as strings as shown in the above examples. You can specify a timeUnit to report the bucket name as a number in the amount of specified unit instead. For time series bucketizers, the number is the amount of specified unit since Unix Epoch time until the start of the bucket; for recurring unit bucketizers, the number is the amount of the unit since the beginning of day, week, month, year, until the start of the bucket. Time unit can be any of millisecond, second, minute, hour, day. Examples:

Example timeBucketizer	Default Bucket Name	Example timeUnit To Use With The Bucketizer	Resulting Bucket Name
day	2016-01-06	millisecond	1452067200000
day	2016-01-06	second	1452067200
time of day	14:37	minute	877
day of week	Wednesday	day	2
day of year	January 6	day	5