Merge #692

692: Pre-stabilization changes for state_agg - part 1 r=Smittyvb a=Smittyvb

- Adds optional `start` and `end` parameters to `duration_in` to only get the duration in the specified range. If `end` is omitted all states after `start` are included. `interpolated_duration_in` now uses these ones as well.
- Renames `state_agg` -> `compressed_state_agg` (final name TBD), `timeline_agg` -> `state_agg`
- Removes mostly unused `next` parameters from interpolated state aggregate functions

Closes #687. Related to #691.

Co-authored-by: Smitty <[email protected]>

Author: bors[bot]

Changelog.md

@@ -11,6 +11,9 @@ This changelog should be updated as part of a PR if the work is worth noting (mo
 #### Bug fixes
 
 #### Other notable changes
+- [#692](https://github.com/timescale/timescaledb-toolkit/pull/692): Support specifying a range to `duration_in` to specify a time range to get states in for state aggregates
+- [#692](https://github.com/timescale/timescaledb-toolkit/pull/692): Removed `next` parameter from interpolated state aggregate functions
+- [#692](https://github.com/timescale/timescaledb-toolkit/pull/692): Renamed `state_agg` to `compact_state_agg` and `timeline_agg` to `state_agg`
 
 #### Shout-outs
 

docs/state_agg.md

@@ -46,15 +46,15 @@ INSERT INTO states_test_5 VALUES
 Compute the amount of time spent in a state as INTERVAL.
 
 ```SQL
-SELECT toolkit_experimental.duration_in('ERROR', toolkit_experimental.state_agg(ts, state)) FROM states_test;
+SELECT toolkit_experimental.duration_in('ERROR', toolkit_experimental.compact_state_agg(ts, state)) FROM states_test;
 ```
 ```output
  interval
 ----------
  00:00:03
 ```
 ```SQL
-SELECT toolkit_experimental.duration_in(2, toolkit_experimental.state_agg(ts, state)) FROM states_test_4;
+SELECT toolkit_experimental.duration_in(2, toolkit_experimental.compact_state_agg(ts, state)) FROM states_test_4;
 ```
 ```output
  interval
@@ -67,7 +67,7 @@ Extract as number of seconds:
 ```SQL
 SELECT
   EXTRACT(epoch FROM
-    toolkit_experimental.duration_in('ERROR', toolkit_experimental.state_agg(ts, state))
+    toolkit_experimental.duration_in('ERROR', toolkit_experimental.compact_state_agg(ts, state))
   )::INTEGER
 FROM states_test;
 ```
@@ -77,11 +77,71 @@ FROM states_test;
        3
 ```
 
+#### duration_in for a range
+```SQL
+SELECT toolkit_experimental.duration_in('OK', toolkit_experimental.state_agg(ts, state), '2020-01-01 00:01:00+00', '2 days') FROM states_test;
+```
+```output
+ duration_in
+-------------
+ 00:00:57
+```
+```SQL
+SELECT toolkit_experimental.duration_in('OK', toolkit_experimental.state_agg(ts, state), '2020-01-01 00:01:00+00', NULL) FROM states_test;
+```
+```output
+ duration_in
+-------------
+ 00:00:57
+```
+```SQL
+SELECT toolkit_experimental.duration_in('OK', toolkit_experimental.state_agg(ts, state), '2020-01-01 00:01:00+00') FROM states_test;
+```
+```output
+ duration_in
+-------------
+ 00:00:57
+```
+```SQL
+SELECT toolkit_experimental.duration_in(51351, toolkit_experimental.state_agg(ts, state), '2020-01-01 00:01:00+00', '2 days') FROM states_test_4;
+```
+```output
+ duration_in
+-------------
+ 00:00:57
+```
+```SQL
+SELECT toolkit_experimental.duration_in(51351, toolkit_experimental.state_agg(ts, state), '2020-01-01 00:01:00+00', NULL) FROM states_test_4;
+```
+```output
+ duration_in
+-------------
+ 00:00:57
+```
+
+```SQL
+SELECT toolkit_experimental.duration_in('OK', toolkit_experimental.state_agg(ts, state), '2020-01-01 00:00:15+00', '30 seconds') FROM states_test;
+```
+```output
+ duration_in
+-------------
+ 00:00:30
+```
+
+```SQL
+SELECT toolkit_experimental.duration_in('OK', toolkit_experimental.state_agg(ts, state), '2020-01-01 00:00:15+00', '1 minute 1 second') FROM states_test;
+```
+```output
+ duration_in
+-------------
+ 00:00:58
+```
+
 ### into_values
 
 ```SQL
 SELECT state, duration FROM toolkit_experimental.into_values(
-    (SELECT toolkit_experimental.state_agg(ts, state) FROM states_test))
+    (SELECT toolkit_experimental.compact_state_agg(ts, state) FROM states_test))
     ORDER BY state, duration;
 ```
 ```output
@@ -94,7 +154,7 @@ SELECT state, duration FROM toolkit_experimental.into_values(
 ```
 ```SQL
 SELECT state, duration FROM toolkit_experimental.into_int_values(
-    (SELECT toolkit_experimental.state_agg(ts, state) FROM states_test_4))
+    (SELECT toolkit_experimental.compact_state_agg(ts, state) FROM states_test_4))
     ORDER BY state, duration;
 ```
 ```output
@@ -110,7 +170,7 @@ SELECT state, duration FROM toolkit_experimental.into_int_values(
 
 ```SQL
 SELECT state, start_time, end_time FROM toolkit_experimental.state_timeline(
-    (SELECT toolkit_experimental.timeline_agg(ts, state) FROM states_test))
+    (SELECT toolkit_experimental.state_agg(ts, state) FROM states_test))
     ORDER BY start_time;
 ```
 ```output
@@ -125,7 +185,7 @@ ERROR | 2020-01-01 00:01:00+00 | 2020-01-01 00:01:03+00
 
 ```SQL
 SELECT state, start_time, end_time FROM toolkit_experimental.state_int_timeline(
-    (SELECT toolkit_experimental.timeline_agg(ts, state) FROM states_test_4))
+    (SELECT toolkit_experimental.state_agg(ts, state) FROM states_test_4))
     ORDER BY start_time;
 ```
 ```output
@@ -141,7 +201,7 @@ state | start_time             | end_time
 
 ```SQL
 SELECT state, start_time, end_time FROM toolkit_experimental.state_timeline(
-    (SELECT toolkit_experimental.timeline_agg(ts, state) FROM states_test_2))
+    (SELECT toolkit_experimental.state_agg(ts, state) FROM states_test_2))
     ORDER BY start_time;
 ```
 ```output
@@ -158,7 +218,7 @@ START | 2019-12-31 00:00:00+00 | 2019-12-31 00:00:11+00
 SELECT start_time, end_time
 FROM toolkit_experimental.state_periods(
     'OK',
-    (SELECT toolkit_experimental.timeline_agg(ts, state) FROM states_test)
+    (SELECT toolkit_experimental.state_agg(ts, state) FROM states_test)
 )
 ORDER BY start_time;
 ```
@@ -173,7 +233,7 @@ start_time             | end_time
 SELECT start_time, end_time
 FROM toolkit_experimental.state_periods(
     51351,
-    (SELECT toolkit_experimental.timeline_agg(ts, state) FROM states_test_4)
+    (SELECT toolkit_experimental.state_agg(ts, state) FROM states_test_4)
 )
 ORDER BY start_time;
 ```
@@ -188,7 +248,7 @@ start_time             | end_time
 SELECT start_time, end_time
 FROM toolkit_experimental.state_periods(
     'ANYTHING',
-    (SELECT toolkit_experimental.timeline_agg(ts, state) FROM states_test)
+    (SELECT toolkit_experimental.state_agg(ts, state) FROM states_test)
 )
 ORDER BY start_time;
 ```
@@ -201,10 +261,9 @@ start_time             | end_time
 
 ```SQL
 SELECT state, start_time, end_time FROM toolkit_experimental.interpolated_state_timeline(
-    (SELECT toolkit_experimental.timeline_agg(ts, state) FROM states_test),
+    (SELECT toolkit_experimental.state_agg(ts, state) FROM states_test),
     '2019-12-31', '1 days',
-    (SELECT toolkit_experimental.timeline_agg(ts, state) FROM states_test_3),
-    (SELECT toolkit_experimental.timeline_agg(ts, state) FROM states_test_3)
+    (SELECT toolkit_experimental.state_agg(ts, state) FROM states_test_3)
 )
 ORDER BY start_time;
 ```
@@ -220,10 +279,9 @@ ERROR | 2020-01-01 00:01:00+00 | 2020-01-01 00:01:03+00
 
 ```SQL
 SELECT state, start_time, end_time FROM toolkit_experimental.interpolated_state_timeline(
-    (SELECT toolkit_experimental.timeline_agg(ts, state) FROM states_test),
+    (SELECT toolkit_experimental.state_agg(ts, state) FROM states_test),
     '2019-12-31', '5 days',
-    (SELECT toolkit_experimental.timeline_agg(ts, state) FROM states_test_3),
-    (SELECT toolkit_experimental.timeline_agg(ts, state) FROM states_test_3)
+    (SELECT toolkit_experimental.state_agg(ts, state) FROM states_test_3)
 )
 ORDER BY start_time;
 ```
@@ -239,10 +297,9 @@ ERROR | 2020-01-01 00:01:00+00 | 2020-01-01 00:01:03+00
 
 ```SQL
 SELECT state, start_time, end_time FROM toolkit_experimental.interpolated_state_timeline(
-    (SELECT toolkit_experimental.timeline_agg(ts, state) FROM states_test),
+    (SELECT toolkit_experimental.state_agg(ts, state) FROM states_test),
     '2019-12-31', '1 days',
-    (SELECT toolkit_experimental.timeline_agg(ts, state) FROM states_test_2),
-    (SELECT toolkit_experimental.timeline_agg(ts, state) FROM states_test_2)
+    (SELECT toolkit_experimental.state_agg(ts, state) FROM states_test_2)
 )
 ORDER BY start_time;
 ```
@@ -259,10 +316,9 @@ ERROR | 2020-01-01 00:01:00+00 | 2020-01-01 00:01:03+00
 
 ```SQL
 SELECT state, start_time, end_time FROM toolkit_experimental.interpolated_state_timeline(
-    (SELECT toolkit_experimental.timeline_agg(ts, state) FROM states_test),
+    (SELECT toolkit_experimental.state_agg(ts, state) FROM states_test),
     '2019-12-31', '5 days',
-    (SELECT toolkit_experimental.timeline_agg(ts, state) FROM states_test_2),
-    (SELECT toolkit_experimental.timeline_agg(ts, state) FROM states_test_2)
+    (SELECT toolkit_experimental.state_agg(ts, state) FROM states_test_2)
 )
 ORDER BY start_time;
 ```
@@ -283,10 +339,9 @@ ERROR | 2020-01-01 00:01:00+00 | 2020-01-01 00:01:03+00
 ```SQL
 SELECT start_time, end_time FROM toolkit_experimental.interpolated_state_periods(
     'OK',
-    (SELECT toolkit_experimental.timeline_agg(ts, state) FROM states_test),
+    (SELECT toolkit_experimental.state_agg(ts, state) FROM states_test),
     '2019-12-31', '1 days',
-    (SELECT toolkit_experimental.timeline_agg(ts, state) FROM states_test_3),
-    (SELECT toolkit_experimental.timeline_agg(ts, state) FROM states_test_3)
+    (SELECT toolkit_experimental.state_agg(ts, state) FROM states_test_3)
 )
 ORDER BY start_time;
 ```
@@ -300,10 +355,9 @@ start_time             | end_time
 ```SQL
 SELECT start_time, end_time FROM toolkit_experimental.interpolated_state_periods(
     'START',
-    (SELECT toolkit_experimental.timeline_agg(ts, state) FROM states_test),
+    (SELECT toolkit_experimental.state_agg(ts, state) FROM states_test),
     '2019-12-31', '5 days',
-    (SELECT toolkit_experimental.timeline_agg(ts, state) FROM states_test_3),
-    (SELECT toolkit_experimental.timeline_agg(ts, state) FROM states_test_3)
+    (SELECT toolkit_experimental.state_agg(ts, state) FROM states_test_3)
 )
 ORDER BY start_time;
 ```
@@ -316,10 +370,9 @@ start_time             | end_time
 ```SQL
 SELECT start_time, end_time FROM toolkit_experimental.interpolated_state_periods(
     'STOP',
-    (SELECT toolkit_experimental.timeline_agg(ts, state) FROM states_test),
+    (SELECT toolkit_experimental.state_agg(ts, state) FROM states_test),
     '2019-12-31', '1 days',
-    (SELECT toolkit_experimental.timeline_agg(ts, state) FROM states_test_2),
-    (SELECT toolkit_experimental.timeline_agg(ts, state) FROM states_test_2)
+    (SELECT toolkit_experimental.state_agg(ts, state) FROM states_test_2)
 )
 ORDER BY start_time;
 ```
@@ -333,10 +386,9 @@ start_time             | end_time
 ```SQL
 SELECT start_time, end_time FROM toolkit_experimental.interpolated_state_periods(
     'STOP',
-    (SELECT toolkit_experimental.timeline_agg(ts, state) FROM states_test),
+    (SELECT toolkit_experimental.state_agg(ts, state) FROM states_test),
     '2019-12-31', '5 days',
-    (SELECT toolkit_experimental.timeline_agg(ts, state) FROM states_test_2),
-    (SELECT toolkit_experimental.timeline_agg(ts, state) FROM states_test_2)
+    (SELECT toolkit_experimental.state_agg(ts, state) FROM states_test_2)
 )
 ORDER BY start_time;
 ```
@@ -352,7 +404,7 @@ start_time             | end_time
 ```SQL
 WITH buckets AS (SELECT
     date_trunc('minute', ts) as dt,
-    toolkit_experimental.state_agg(ts, state) AS sa
+    toolkit_experimental.compact_state_agg(ts, state) AS sa
 FROM states_test
 GROUP BY date_trunc('minute', ts))
 SELECT toolkit_experimental.duration_in(
@@ -370,7 +422,7 @@ FROM buckets;
 ```SQL
 WITH buckets AS (SELECT
     date_trunc('minute', ts) as dt,
-    toolkit_experimental.state_agg(ts, state) AS sa
+    toolkit_experimental.compact_state_agg(ts, state) AS sa
 FROM states_test
 GROUP BY date_trunc('minute', ts))
 SELECT toolkit_experimental.duration_in(
@@ -388,7 +440,7 @@ FROM buckets;
 ```SQL
 WITH buckets AS (SELECT
     date_trunc('minute', ts) as dt,
-    toolkit_experimental.timeline_agg(ts, state) AS sa
+    toolkit_experimental.state_agg(ts, state) AS sa
 FROM states_test
 GROUP BY date_trunc('minute', ts))
 SELECT toolkit_experimental.state_timeline(
@@ -409,7 +461,7 @@ FROM buckets;
 ```SQL
 WITH buckets AS (SELECT
     date_trunc('minute', ts) as dt,
-    toolkit_experimental.timeline_agg(ts, state) AS sa
+    toolkit_experimental.state_agg(ts, state) AS sa
 FROM states_test
 GROUP BY date_trunc('minute', ts)
 HAVING date_trunc('minute', ts) != '2020-01-01 00:01:00+00'::timestamptz)
@@ -429,7 +481,7 @@ FROM buckets;
 ```SQL
 WITH buckets AS (SELECT
     date_trunc('minute', ts) as dt,
-    toolkit_experimental.timeline_agg(ts, state) AS sa
+    toolkit_experimental.state_agg(ts, state) AS sa
 FROM states_test_5
 GROUP BY date_trunc('minute', ts)
 HAVING date_trunc('minute', ts) != '2020-01-01 00:01:00+00'::timestamptz)