Document changes to state_agg/timeline_agg in Toolkit 1.13

api/duration_in.md

@@ -14,7 +14,7 @@ hyperfunction:
   family: state aggregates
   type: accessor
   aggregates:
-    - state_agg()
+    - state_agg() | timeline_agg()
 ---
 
 import Experimental from 'versionContent/_partials/_experimental.mdx';
@@ -29,8 +29,8 @@ Use this function to report the total duration for a given state in a [state agg
 
 |Name|Type|Description|
 |-|-|-|
-|`state`|`TEXT`|State to query|
-|`aggregate`|`stateagg`|Previously created aggregate|
+|`state`|`TEXT` or `BIGINT`|State to query|
+|`aggregate`|`StateAgg` or `TimelineAgg`|Previously created aggregate|
 
 ## Returns
 
@@ -75,4 +75,4 @@ If you prefer to see the result in seconds, [`EXTRACT`][extract] the epoch from
 the returned result.
 
 [extract]: https://www.postgresql.org/docs/current/functions-datetime.html#FUNCTIONS-DATETIME-EXTRACT
-[state_agg]: /api/:currentVersion:/hyperfunctions/frequency-analysis/state_agg/
+[state_agg]: /api/:currentVersion:/hyperfunctions/state-aggregates/state_agg/

api/interpolated_duration_in.md

@@ -14,7 +14,7 @@ hyperfunction:
   family: state aggregates
   type: accessor
   aggregates:
-    - state_agg()
+    - state_agg() | timeline_agg()
 ---
 
 import Experimental from 'versionContent/_partials/_experimental.mdx';
@@ -24,16 +24,16 @@ import Experimental from 'versionContent/_partials/_experimental.mdx';
 Calculate the total duration in a given state from a [state aggregate][state_agg].
 Unlike [`duration_in`][duration_in], 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 StateAggs.
+boundaries are interpolated from adjacent StateAggs/TimelineAggs.
 
-```SQL
+```sql
 interpolated_duration_in(
-    state TEXT,
-    tws StateAgg,
+    state [TEXT | BIGINT],
+    tws [StateAgg | TimelineAgg],
     start TIMESTAMPTZ,
     interval INTERVAL,
-    prev StateAgg,
-    next StateAgg
+    prev [StateAgg | TimelineAgg],
+    next [StateAgg | TimelineAgg]
 ) RETURNS DOUBLE PRECISION
 ```
 
@@ -43,17 +43,17 @@ interpolated_duration_in(
 
 |Name|Type|Description|
 |-|-|-|
-|`state`|`TEXT`|State to query|
-|`aggregate`|`StateAgg`|Previously created state_agg aggregate|
+|`state`|`TEXT` or `BIGINT`|State to query|
+|`aggregate`|`StateAgg` or `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`|`StateAgg`|The `StateAgg` from the prior interval, used to interpolate the value at `start`. If `NULL`, the first timestamp in `aggregate` will be used as the start of the interval.|
-|`next`|`StateAgg`|The `StateAgg` from the following interval, used to interpolate the value at `start` + `interval`. If `NULL`, the last timestamp in `aggregate` will be used as the end of the interval.|
+|`prev`|`StateAgg` or `TimelineAgg`|The `StateAgg` or `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`|`StateAgg` or `TimelineAgg`|The `StateAgg` or `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
 
@@ -113,6 +113,6 @@ Which gives the result:
 If you prefer to see the result in seconds, [`EXTRACT`][extract] the epoch from
 the returned result.
 
-[duration_in]: /api/:currentVersion:/hyperfunctions/frequency-analysis/duration_in/
+[duration_in]: /api/:currentVersion:/hyperfunctions/state-aggregates/duration_in/
 [extract]: https://www.postgresql.org/docs/current/functions-datetime.html#FUNCTIONS-DATETIME-EXTRACT
-[state_agg]: /api/:currentVersion:/hyperfunctions/frequency-analysis/state_agg/
+[state_agg]: /api/:currentVersion:/hyperfunctions/state-aggregates/state_agg/

api/interpolated_state_periods.md

@@ -0,0 +1,100 @@
+---
+api_name: interpolated_state_periods()
+excerpt: Get time periods for a state from a timeline aggregate
+topics: [hyperfunctions]
+keywords: [duration, states, hyperfunctions, Toolkit]
+api:
+  license: community
+  type: function
+  experimental: true
+  toolkit: true
+  version:
+    experimental: 1.13.0
+hyperfunction:
+  family: state aggregates
+  type: accessor
+  aggregates:
+    - state_agg() | timeline_agg()
+---
+
+import Experimental from 'versionContent/_partials/_experimental.mdx';
+
+# interpolated_state_periods()  <tag type="toolkit">Toolkit</tag><tag type="experimental-toolkit">Experimental</tag>
+
+Returns the times in a given state in a [timeline aggregate][state_agg].  
+
+Unlike [`state_periods`][state_periods], 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.
+
+```sql
+interpolated_state_periods(
+    state [TEXT | BIGINT],
+    tws [StateAgg | TimelineAgg],
+    start TIMESTAMPTZ,
+    interval INTERVAL,
+    prev [StateAgg | TimelineAgg],
+    next [StateAgg | TimelineAgg]
+) RETURNS (TIMESTAMPTZ, TIMESTAMPTZ)
+```
+
+<Experimental />
+
+## Required arguments
+
+|Name|Type|Description|
+|-|-|-|
+|`state`|`TEXT` or `BIGINT`|State to query|
+|`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|
+|-|-|-|
+|`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:
+
+```sql
+SELECT
+    bucket,
+    (toolkit_experimental.interpolated_state_periods(
+        'OK',
+        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         |       start_time       |        end_time
+------------------------+------------------------+------------------------
+ 2020-01-01 00:00:00+00 | 2020-01-01 00:00:11+00 | 2020-01-01 00:15:00+00
+ 2020-01-01 00:01:00+00 | 2020-01-01 00:01:03+00 | 2020-01-01 00:16:00+00
+```
+
+[state_agg]: /api/:currentVersion:/hyperfunctions/state-aggregates/state_agg/
+[state_periods]: /api/:currentVersion:/hyperfunctions/state-aggregates/state_periods/

api/interpolated_state_timeline.md

@@ -0,0 +1,101 @@
+---
+api_name: interpolated_state_timeline()
+excerpt: Get time periods for a state from a timeline aggregate
+topics: [hyperfunctions]
+keywords: [duration, states, hyperfunctions, Toolkit]
+api:
+  license: community
+  type: function
+  experimental: true
+  toolkit: true
+  version:
+    experimental: 1.13.0
+hyperfunction:
+  family: state aggregates
+  type: accessor
+  aggregates:
+    - state_agg() | timeline_agg()
+---
+
+import Experimental from 'versionContent/_partials/_experimental.mdx';
+
+# interpolated_state_timeline()  <tag type="toolkit">Toolkit</tag><tag type="experimental-toolkit">Experimental</tag>
+
+Returns the interpolated timeline of states in a [timeline aggregate][state_agg].  
+
+Unlike [`state_timeline`][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.
+
+```sql
+interpolated_state_timeline(
+    tws [StateAgg | TimelineAgg],
+    start TIMESTAMPTZ,
+    interval INTERVAL,
+    prev [StateAgg | TimelineAgg],
+    next [StateAgg | TimelineAgg]
+) RETURNS (TIMESTAMPTZ, TIMESTAMPTZ)
+```
+
+<Experimental />
+
+## 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:
+
+```sql
+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
+```
+
+[state_agg]: /api/:currentVersion:/hyperfunctions/state-aggregates/state_agg/
+[state_timeline]: /api/:currentVersion:/hyperfunctions/state-aggregates/state_timeline/

api/into_values-state_agg.md

@@ -14,7 +14,7 @@ hyperfunction:
   family: state aggregates
   type: accessor
   aggregates:
-    - state_agg()
+    - state_agg() | timeline_agg()
 ---
 
 import Experimental from 'versionContent/_partials/_experimental.mdx';
@@ -25,8 +25,12 @@ Returns the data accumulated in a [state aggregate][state_agg].
 
 ```sql
 into_values (
-    agg StateAgg
+    agg [StateAgg | TimelineAgg]
 ) RETURNS (TEXT, BIGINT)
+
+into_int_values (
+    agg [StateAgg | TimelineAgg]
+) RETURNS (INT, BIGINT)
 ```
 
 <Experimental />
@@ -35,14 +39,14 @@ into_values (
 
 |Name|Type|Description|
 |-|-|-|
-|`agg`|`StateAgg`|The aggregate to display data for|
+|`agg`|`StateAgg` or `TimelineAgg`|The aggregate to display data for|
 
 ## Returns
 
 |Column|Type|Description|
 |-|-|-|
-|`state`|`TEXT`|A state found in the `StateAgg`|
-|`duration`|`BIGINT`|The duration of time spent in that state|
+|`state`|`TEXT`|A state found in the `StateAgg` or `TimelineAgg`|
+|`duration`|`BIGINT` or `INT`|The duration of time spent in that state|
 
 ## Sample usage
 
@@ -66,4 +70,4 @@ OK    | 106000000
 START |  11000000
 ```
 
-[state_agg]: /api/:currentVersion:/hyperfunctions/frequency-analysis/state_agg/
+[state_agg]: /api/:currentVersion:/hyperfunctions/state-aggregates/state_agg/

api/page-index/page-index.js

@@ -636,6 +636,26 @@ module.exports = [
                 title: "into_values (for state_agg)",
                 href: "into_values-state_agg",
               },
+              {
+                title: "rollup (for state_agg)",
+                href: "rollup-state_agg",
+              },
+              {
+                title: "state_timeline",
+                href: "state_timeline",
+              },
+              {
+                title: "state_periods",
+                href: "state_periods",
+              },
+              {
+                title: "interpolated_state_periods",
+                href: "interpolated_state_periods",
+              },
+              {
+                title: "interpolated_state_timeline",
+                href: "interpolated_state_timeline",
+              },
             ],
           },
         ],