Skip to content

Commit

Permalink
Small line edits to time_bucket_ng API (github#314)
Browse files Browse the repository at this point in the history
* Small line edits

* slight edit
  • Loading branch information
Loquacity authored Sep 3, 2021
1 parent a4b44f3 commit cc117b8
Showing 1 changed file with 15 additions and 18 deletions.
33 changes: 15 additions & 18 deletions api/time_bucket_ng.md
Original file line number Diff line number Diff line change
@@ -1,9 +1,9 @@
## timescaledb_experimental.time_bucket_ng() <tag type="experimental">Experimental</tag>

The `time_bucket_ng()` (next generation) experimental function is
similar to [`time_bucket()`][time_bucket], but works with years and
months. It is expected that the feature will also support timezones
in a future release.
The `time_bucket_ng()` (next generation) experimental function is an updated
version of the original [`time_bucket()`][time_bucket] function. While
`time_bucket` works with small units of time, the `time_bucket_ng()` function
uses years and months. The `time_bucket_ng()` function does not, at this stage,
support timezones.

<highlight type="warning">
Experimental features could have bugs! They might not be backwards compatible,
Expand Down Expand Up @@ -32,24 +32,21 @@ SELECT timescaledb_experimental.time_bucket_ng('1 year', date '2021-08-01');
(1 row)
```

To split time into buckets we use a starting point in time called `origin`. The
default origin is '2000-01-01'. `time_bucket_ng` can't work with timestamps
earlier than `origin`:
To split time into buckets, `time_bucket_ng()` uses a starting point in time
called `origin`. The default origin is `2000-01-01`. `time_bucket_ng` cannot use
timestamps earlier than `origin`:

```
SELECT timescaledb_experimental.time_bucket_ng('100 years', timestamp '1988-05-08');
ERROR: origin must be before the given date
```

Going back in time from `origin` isn't possible in general case, especially
when you consider time zones and DST. We could partially support it
depending on the arguments, but it seems to be a bad user experience.

Note also that there is no reasonable way to split time in
variable-sized buckets (e.g. months) from an arbitrary `origin`. For this
reason the default `origin` is the first day of the month.
Going back in time from `origin` isn't usually possible, especially when you
consider timezones and daylight savings time (DST). Note also that there is no
reasonable way to split time in variable-sized buckets (such as months) from an
arbitrary `origin`, so `origin` defaults to the first day of the month.

To bypass named limitations it's possible to override the default `origin`:
To bypass named limitations, you can override the default `origin`:

```
-- working with timestamps before 2000-01-01
Expand All @@ -65,8 +62,8 @@ SELECT timescaledb_experimental.time_bucket_ng('1 week', timestamp '2021-08-26',
2021-08-23 00:00:00
```

You can use `time_bucket_ng()` with continuous aggregates.
This example tracks the temperature in Moscow over seven day intervals:
You can use `time_bucket_ng()` with continuous aggregates. This example tracks
the temperature in Moscow over seven day intervals:

```
CREATE TABLE conditions(
Expand Down

0 comments on commit cc117b8

Please sign in to comment.