From e8b7c46d7c1dcd6c79fcc66c15e380b9d378debc Mon Sep 17 00:00:00 2001 From: Andreas Wahlen Date: Mon, 7 Oct 2024 13:57:41 +0200 Subject: [PATCH 1/4] Add note to prev expression return type for locf() --- api/_hyperfunctions/time_bucket_gapfill/locf.md | 1 + 1 file changed, 1 insertion(+) diff --git a/api/_hyperfunctions/time_bucket_gapfill/locf.md b/api/_hyperfunctions/time_bucket_gapfill/locf.md index ba5515a21d..49751195a1 100644 --- a/api/_hyperfunctions/time_bucket_gapfill/locf.md +++ b/api/_hyperfunctions/time_bucket_gapfill/locf.md @@ -35,6 +35,7 @@ api_details: description: > If no previous value is available for gapfilling, use the `prev` lookup expression to get a previous value. For example, you can use `prev` to fill in the first bucket in a queried time range. + The expression must return just a value (not a tuple as expected by the [`interpolate`](#interpolate) function) with the same type as the `value` parameter. - name: treat_null_as_missing type: BOOLEAN description: When `true`, `NULL` values are ignored, and only non-`NULL` values are carried forward. From b4b83c409a5a2ff9cba4586516eb3baf5afa2abb Mon Sep 17 00:00:00 2001 From: Andreas Wahlen Date: Sat, 12 Oct 2024 17:54:31 +0200 Subject: [PATCH 2/4] Add examples for prev and next args of interpolate and locf --- .../time_bucket_gapfill/examples.md | 91 +++++++++++++++++++ 1 file changed, 91 insertions(+) diff --git a/api/_hyperfunctions/time_bucket_gapfill/examples.md b/api/_hyperfunctions/time_bucket_gapfill/examples.md index e6de6de708..2386c1f9c5 100644 --- a/api/_hyperfunctions/time_bucket_gapfill/examples.md +++ b/api/_hyperfunctions/time_bucket_gapfill/examples.md @@ -67,6 +67,48 @@ day | value ``` +### Use `time_bucket_gapfill` and carry last value forward with `prev` expression + +Get the daily average metric value. Use the optional `prev` argument of `locf` +to fill any gaps at the beginning of the queried time range. Note that the +`prev` expression returns just a value without a time reference. + +```sql +SELECT time_bucket_gapfill('1 day', time) AS day, + locf( + avg(value), + ( + SELECT value + FROM metrics + WHERE time > '2021-12-31 00:00:00+00'::timestamptz + ORDER BY time ASC + LIMIT 1 + ) + ) as value + FROM metrics + WHERE time > '2021-12-31 00:00:00+00'::timestamptz + AND time < '2022-01-10 00:00:00-00'::timestamptz + GROUP BY day + ORDER BY day desc; +``` + +```text +day | value +-----------------------+-------------------- +2022-01-09 00:00:00+00 | 48.61293155993108 +2022-01-08 00:00:00+00 | 48.61293155993108 +2022-01-07 00:00:00+00 | 54.388267525986485 +2022-01-06 00:00:00+00 | 58.257520634785266 +2022-01-05 00:00:00+00 | 58.257520634785266 +2022-01-04 00:00:00+00 | 46.09172424261765 +2022-01-03 00:00:00+00 | 42.53498707820027 +2022-01-02 00:00:00+00 | 47.84420001415975 +2022-01-01 00:00:00+00 | 47.84420001415975 +2021-12-31 00:00:00+00 | 47.84420001415975 +(10 rows) + +``` + ### Use `time_bucket_gapfill` and use linear interpolation Get the daily average metric value. Use `interpolate` to linearly interpolate @@ -98,6 +140,55 @@ day | value (10 rows) ``` +### Use `time_bucket_gapfill` and use linear interpolation with `prev` and `next` expression + +Get the daily average metric value. Use the optional `prev` and `next` +arguments of `interpolate` to extrapolate, i.e. to fill the gaps at the +beginning and end of the queried time range. Note that the `prev` and +`next` expressions each return a tuple with time and value. + +```sql +SELECT time_bucket_gapfill('1 day', time) AS day, + interpolate( + avg(value), + ( + SELECT (time, value) + FROM metrics + WHERE time > '2021-12-31 00:00:00+00'::timestamptz + ORDER BY time ASC + LIMIT 1 + ), + ( + SELECT (time, value) + FROM metrics + WHERE time < '2021-12-10 00:00:00-00'::timestamptz + ORDER BY time DESC + LIMIT 1 + ) + ) as value + FROM metrics + WHERE time > '2021-12-31 00:00:00+00'::timestamptz + AND time < '2022-01-10 00:00:00-00'::timestamptz + GROUP BY day + ORDER BY day desc; +``` + +```text +day | value +-----------------------+-------------------- +2022-01-09 00:00:00+00 | 48.61293155993108 +2022-01-08 00:00:00+00 | 48.61293155993108 +2022-01-07 00:00:00+00 | 54.388267525986485 +2022-01-06 00:00:00+00 | 56.32289408038588 +2022-01-05 00:00:00+00 | 58.257520634785266 +2022-01-04 00:00:00+00 | 46.09172424261765 +2022-01-03 00:00:00+00 | 42.53498707820027 +2022-01-02 00:00:00+00 | 45.189593546180014 +2022-01-01 00:00:00+00 | 47.84420001415975 +2021-12-31 00:00:00+00 | 47.84420001415975 +(10 rows) + ``` + ### Use `time_bucket_gapfill` with a timezone argument Get the daily average metric value, using `Europe/Berlin` as the timezone. Note From 00b2005fc744cc13a984004f4922cbcb8e1a12c5 Mon Sep 17 00:00:00 2001 From: cracksalad Date: Mon, 14 Oct 2024 22:41:20 +0200 Subject: [PATCH 3/4] Rephrase locf with prev expression description Co-authored-by: Mats Kindahl Signed-off-by: cracksalad --- api/_hyperfunctions/time_bucket_gapfill/examples.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/api/_hyperfunctions/time_bucket_gapfill/examples.md b/api/_hyperfunctions/time_bucket_gapfill/examples.md index 2386c1f9c5..b919b72e4b 100644 --- a/api/_hyperfunctions/time_bucket_gapfill/examples.md +++ b/api/_hyperfunctions/time_bucket_gapfill/examples.md @@ -69,9 +69,9 @@ day | value ### Use `time_bucket_gapfill` and carry last value forward with `prev` expression -Get the daily average metric value. Use the optional `prev` argument of `locf` -to fill any gaps at the beginning of the queried time range. Note that the -`prev` expression returns just a value without a time reference. +Get the daily average metric value. Use the optional `prev` argument to `locf` +to fill gaps at the beginning of the queried time range. Note that the +`prev` expression returns just a value to fill the gap with. This is sufficient since the value is just carried forward and not further processed. ```sql SELECT time_bucket_gapfill('1 day', time) AS day, From 629c8ab0d2ab16149710df72d1ab210243136f70 Mon Sep 17 00:00:00 2001 From: cracksalad Date: Mon, 14 Oct 2024 22:42:52 +0200 Subject: [PATCH 4/4] Rephrase interpolate next/prev expression description Co-authored-by: Mats Kindahl Signed-off-by: cracksalad --- api/_hyperfunctions/time_bucket_gapfill/examples.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/api/_hyperfunctions/time_bucket_gapfill/examples.md b/api/_hyperfunctions/time_bucket_gapfill/examples.md index b919b72e4b..570c316687 100644 --- a/api/_hyperfunctions/time_bucket_gapfill/examples.md +++ b/api/_hyperfunctions/time_bucket_gapfill/examples.md @@ -143,9 +143,8 @@ day | value ### Use `time_bucket_gapfill` and use linear interpolation with `prev` and `next` expression Get the daily average metric value. Use the optional `prev` and `next` -arguments of `interpolate` to extrapolate, i.e. to fill the gaps at the -beginning and end of the queried time range. Note that the `prev` and -`next` expressions each return a tuple with time and value. +arguments to `interpolate` to extrapolate the missing values starting and ending the queried time range. Note that the `prev` and +`next` expressions each return a tuple with time and value. The time is necessary to compute the missing values correctly. ```sql SELECT time_bucket_gapfill('1 day', time) AS day,