From 85b59c72eb82ab6eb917ebbd5eba5916a519e7f3 Mon Sep 17 00:00:00 2001 From: Aleksander Alekseev Date: Mon, 13 Sep 2021 14:02:40 +0300 Subject: [PATCH] Document the differences between time_bucket() and time_bucket_ng() (#354) Document the differences between time_bucket() and time_bucket_ng() Co-authored-by: Lana Brindley --- api/time_bucket_ng.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/api/time_bucket_ng.md b/api/time_bucket_ng.md index 076c40ca7509..5c83f6d25c4b 100644 --- a/api/time_bucket_ng.md +++ b/api/time_bucket_ng.md @@ -11,6 +11,26 @@ and could be removed in future releases. Use these features at your own risk, an do not use any experimental features in production. +Functionality | time_bucket() | time_bucket_ng() +--------------|---------------|----------------- +Buckets by seconds, minutes, hours, days and weeks | YES | YES +Buckets by months and years | NO | YES +Buckets by timezones | NO | (Coming soon) + + +The `time_bucket()` and `time_bucket_ng()` functions are similar, but not +completely compatible. There are two main differences. + +Firstly, `time_bucket_ng()` doesn't work with timestamps prior to `origin`, +while `time_bucket()` does. + +Secondly, the default `origin` values differ. `time_bucket()` uses an origin +date of 3 Jan 2000, because that date is a Monday. This works better with +weekly buckets. `time_bucket_ng()` uses an origin date of 1 Jan 2000, because +it is the first day of the month and the year. This works better with monthly +or annual aggregates. + + In this example, `time_bucket_ng()` is used to create bucket data in three month intervals: