Add note to prev expression return type for locf()

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

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.