interpolated_state_timeline()

Returns the interpolated timeline of states in a timeline aggregate.

Unlike state_timeline, you can use this function across multiple state aggregates that cover different time buckets. Any missing values at the time bucket boundaries are interpolated from adjacent TimelineAggs.


interpolated_state_timeline(
    tws [StateAgg | TimelineAgg],
    start TIMESTAMPTZ,
    interval INTERVAL,
    prev [StateAgg | TimelineAgg],
    next [StateAgg | TimelineAgg]
) RETURNS (TIMESTAMPTZ, TIMESTAMPTZ)

warning

Experimental features could have bugs. They might not be backwards compatible, and could be removed in future releases. Use these features at your own risk, and do not use any experimental features in production.

Required arguments

Name	Type	Description
`aggregate`	`TimelineAgg`	Previously created state_agg aggregate
`start`	`TIMESTAMPTZ`	The start of the interval which this function should cover (if there is a preceeding point)
`interval`	`INTERVAL`	The length of the interval

Optional arguments

Name	Type	Description
`prev`	`TimelineAgg`	The `TimelineAgg` from the prior interval, used to interpolate the value at `start`. If `NULL`, the first timestamp in `aggregate` is used as the start of the interval.
`next`	`TimelineAgg`	The `TimelineAgg` from the following interval, used to interpolate the value at `start` + `interval`. If `NULL`, the last timestamp in `aggregate` is used as the end of the interval.

Returns

Column	Type	Description
`state`	`TEXT` or `BIGINT`	A state found in the `TimelineAgg`
`start_time`	`TIMESTAMPTZ`	The time the state started at (inclusive)
`end_time`	`TIMESTAMPTZ`	The time the state ended at (exclusive)

Sample usage

Getting the interpolated history of states in a timeline aggregate:


SELECT
    bucket,
    (toolkit_experimental.interpolated_state_timeline(
        summary,
        bucket,
        '15 min',
        LAG(summary) OVER (ORDER by bucket),
        LEAD(summary) OVER (ORDER by bucket)
    )).*
FROM (
    SELECT
        time_bucket('1 min'::interval, ts) AS bucket,
        toolkit_experimental.timeline_agg(ts, state) AS summary
    FROM states_test
    GROUP BY time_bucket('1 min'::interval, ts)
) t;

Example output:


bucket         | state |       start_time       |        end_time
------------------------+-------+------------------------+------------------------
 2020-01-01 00:00:00+00 | START | 2020-01-01 00:00:00+00 | 2020-01-01 00:00:11+00
 2020-01-01 00:00:00+00 | OK    | 2020-01-01 00:00:11+00 | 2020-01-01 00:15:00+00
 2020-01-01 00:01:00+00 | ERROR | 2020-01-01 00:01:00+00 | 2020-01-01 00:01:03+00
 2020-01-01 00:01:00+00 | OK    | 2020-01-01 00:01:03+00 | 2020-01-01 00:16:00+00
 2020-01-01 00:02:00+00 | STOP  | 2020-01-01 00:02:00+00 | 2020-01-01 00:02:00+00