Skip to content

Commit a472264

Browse files
syvbsyvb
authored
Document changes to state_agg/timeline_agg in Toolkit 1.13 (#1871)
* Document changes to state_agg/timeline_agg in Toolkit 1.13 * fix lacking mention of TimelineAgg * Use better examples for state_agg changes * Expand on use cases for integer states
1 parent 9802f9a commit a472264

11 files changed

+474
-28
lines changed

‎api/duration_in.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ hyperfunction:
1414
family: state aggregates
1515
type: accessor
1616
aggregates:
17-
- state_agg()
17+
- state_agg() | timeline_agg()
1818
---
1919

2020
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
2929

3030
|Name|Type|Description|
3131
|-|-|-|
32-
|`state`|`TEXT`|State to query|
33-
|`aggregate`|`stateagg`|Previously created aggregate|
32+
|`state`|`TEXT` or `BIGINT`|State to query|
33+
|`aggregate`|`StateAgg` or `TimelineAgg`|Previously created aggregate|
3434

3535
## Returns
3636

@@ -75,4 +75,4 @@ If you prefer to see the result in seconds, [`EXTRACT`][extract] the epoch from
7575
the returned result.
7676

7777
[extract]: https://www.postgresql.org/docs/current/functions-datetime.html#FUNCTIONS-DATETIME-EXTRACT
78-
[state_agg]: /api/:currentVersion:/hyperfunctions/frequency-analysis/state_agg/
78+
[state_agg]: /api/:currentVersion:/hyperfunctions/state-aggregates/state_agg/

‎api/interpolated_duration_in.md‎

Lines changed: 13 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ hyperfunction:
1414
family: state aggregates
1515
type: accessor
1616
aggregates:
17-
- state_agg()
17+
- state_agg() | timeline_agg()
1818
---
1919

2020
import Experimental from 'versionContent/_partials/_experimental.mdx';
@@ -24,16 +24,16 @@ import Experimental from 'versionContent/_partials/_experimental.mdx';
2424
Calculate the total duration in a given state from a [state aggregate][state_agg].
2525
Unlike [`duration_in`][duration_in], you can use this function across multiple state
2626
aggregates that cover different time buckets. Any missing values at the time bucket
27-
boundaries are interpolated from adjacent StateAggs.
27+
boundaries are interpolated from adjacent StateAggs/TimelineAggs.
2828

29-
```SQL
29+
```sql
3030
interpolated_duration_in(
31-
state TEXT,
32-
tws StateAgg,
31+
state [TEXT | BIGINT],
32+
tws [StateAgg | TimelineAgg],
3333
start TIMESTAMPTZ,
3434
interval INTERVAL,
35-
prev StateAgg,
36-
next StateAgg
35+
prev [StateAgg | TimelineAgg],
36+
next [StateAgg | TimelineAgg]
3737
) RETURNS DOUBLE PRECISION
3838
```
3939

@@ -43,17 +43,17 @@ interpolated_duration_in(
4343

4444
|Name|Type|Description|
4545
|-|-|-|
46-
|`state`|`TEXT`|State to query|
47-
|`aggregate`|`StateAgg`|Previously created state_agg aggregate|
46+
|`state`|`TEXT` or `BIGINT`|State to query|
47+
|`aggregate`|`StateAgg` or `TimelineAgg`|Previously created state_agg aggregate|
4848
|`start`|`TIMESTAMPTZ`|The start of the interval which this function should cover (if there is a preceeding point)|
4949
|`interval`|`INTERVAL`|The length of the interval|
5050

5151
### Optional arguments
5252

5353
|Name|Type|Description|
5454
|-|-|-|
55-
|`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.|
56-
|`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.|
55+
|`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.|
56+
|`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.|
5757

5858
## Returns
5959

@@ -113,6 +113,6 @@ Which gives the result:
113113
If you prefer to see the result in seconds, [`EXTRACT`][extract] the epoch from
114114
the returned result.
115115

116-
[duration_in]: /api/:currentVersion:/hyperfunctions/frequency-analysis/duration_in/
116+
[duration_in]: /api/:currentVersion:/hyperfunctions/state-aggregates/duration_in/
117117
[extract]: https://www.postgresql.org/docs/current/functions-datetime.html#FUNCTIONS-DATETIME-EXTRACT
118-
[state_agg]: /api/:currentVersion:/hyperfunctions/frequency-analysis/state_agg/
118+
[state_agg]: /api/:currentVersion:/hyperfunctions/state-aggregates/state_agg/

‎api/interpolated_state_periods.md‎

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
---
2+
api_name: interpolated_state_periods()
3+
excerpt: Get time periods for a state from a timeline aggregate
4+
topics: [hyperfunctions]
5+
keywords: [duration, states, hyperfunctions, Toolkit]
6+
api:
7+
license: community
8+
type: function
9+
experimental: true
10+
toolkit: true
11+
version:
12+
experimental: 1.13.0
13+
hyperfunction:
14+
family: state aggregates
15+
type: accessor
16+
aggregates:
17+
- state_agg() | timeline_agg()
18+
---
19+
20+
import Experimental from 'versionContent/_partials/_experimental.mdx';
21+
22+
# interpolated_state_periods() <tag type="toolkit">Toolkit</tag><tag type="experimental-toolkit">Experimental</tag>
23+
24+
Returns the times in a given state in a [timeline aggregate][state_agg].
25+
26+
Unlike [`state_periods`][state_periods], you can use this function across multiple state
27+
aggregates that cover different time buckets. Any missing values at the time bucket
28+
boundaries are interpolated from adjacent TimelineAggs.
29+
30+
```sql
31+
interpolated_state_periods(
32+
state [TEXT | BIGINT],
33+
tws [StateAgg | TimelineAgg],
34+
start TIMESTAMPTZ,
35+
interval INTERVAL,
36+
prev [StateAgg | TimelineAgg],
37+
next [StateAgg | TimelineAgg]
38+
) RETURNS (TIMESTAMPTZ, TIMESTAMPTZ)
39+
```
40+
41+
<Experimental />
42+
43+
## Required arguments
44+
45+
|Name|Type|Description|
46+
|-|-|-|
47+
|`state`|`TEXT` or `BIGINT`|State to query|
48+
|`aggregate`|`TimelineAgg`|Previously created state_agg aggregate|
49+
|`start`|`TIMESTAMPTZ`|The start of the interval which this function should cover (if there is a preceeding point)|
50+
|`interval`|`INTERVAL`|The length of the interval|
51+
52+
### Optional arguments
53+
54+
|Name|Type|Description|
55+
|-|-|-|
56+
|`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.|
57+
|`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.|
58+
59+
## Returns
60+
61+
|Column|Type|Description|
62+
|-|-|-|
63+
|`start_time`|`TIMESTAMPTZ`|The time the state started at (inclusive)|
64+
|`end_time`|`TIMESTAMPTZ`|The time the state ended at (exclusive)|
65+
66+
## Sample usage
67+
68+
Getting the interpolated history of states in a timeline aggregate:
69+
70+
```sql
71+
SELECT
72+
bucket,
73+
(toolkit_experimental.interpolated_state_periods(
74+
'OK',
75+
summary,
76+
bucket,
77+
'15 min',
78+
LAG(summary) OVER (ORDER by bucket),
79+
LEAD(summary) OVER (ORDER by bucket)
80+
)).*
81+
FROM (
82+
SELECT
83+
time_bucket('1 min'::interval, ts) AS bucket,
84+
toolkit_experimental.timeline_agg(ts, state) AS summary
85+
FROM states_test
86+
GROUP BY time_bucket('1 min'::interval, ts)
87+
) t;
88+
```
89+
90+
Example output:
91+
92+
```
93+
bucket | start_time | end_time
94+
------------------------+------------------------+------------------------
95+
2020-01-01 00:00:00+00 | 2020-01-01 00:00:11+00 | 2020-01-01 00:15:00+00
96+
2020-01-01 00:01:00+00 | 2020-01-01 00:01:03+00 | 2020-01-01 00:16:00+00
97+
```
98+
99+
[state_agg]: /api/:currentVersion:/hyperfunctions/state-aggregates/state_agg/
100+
[state_periods]: /api/:currentVersion:/hyperfunctions/state-aggregates/state_periods/

‎api/interpolated_state_timeline.md‎

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
---
2+
api_name: interpolated_state_timeline()
3+
excerpt: Get time periods for a state from a timeline aggregate
4+
topics: [hyperfunctions]
5+
keywords: [duration, states, hyperfunctions, Toolkit]
6+
api:
7+
license: community
8+
type: function
9+
experimental: true
10+
toolkit: true
11+
version:
12+
experimental: 1.13.0
13+
hyperfunction:
14+
family: state aggregates
15+
type: accessor
16+
aggregates:
17+
- state_agg() | timeline_agg()
18+
---
19+
20+
import Experimental from 'versionContent/_partials/_experimental.mdx';
21+
22+
# interpolated_state_timeline() <tag type="toolkit">Toolkit</tag><tag type="experimental-toolkit">Experimental</tag>
23+
24+
Returns the interpolated timeline of states in a [timeline aggregate][state_agg].
25+
26+
Unlike [`state_timeline`][state_timeline], you can use this function across multiple state
27+
aggregates that cover different time buckets. Any missing values at the time bucket
28+
boundaries are interpolated from adjacent TimelineAggs.
29+
30+
```sql
31+
interpolated_state_timeline(
32+
tws [StateAgg | TimelineAgg],
33+
start TIMESTAMPTZ,
34+
interval INTERVAL,
35+
prev [StateAgg | TimelineAgg],
36+
next [StateAgg | TimelineAgg]
37+
) RETURNS (TIMESTAMPTZ, TIMESTAMPTZ)
38+
```
39+
40+
<Experimental />
41+
42+
## Required arguments
43+
44+
|Name|Type|Description|
45+
|-|-|-|
46+
|`aggregate`|`TimelineAgg`|Previously created state_agg aggregate|
47+
|`start`|`TIMESTAMPTZ`|The start of the interval which this function should cover (if there is a preceeding point)|
48+
|`interval`|`INTERVAL`|The length of the interval|
49+
50+
### Optional arguments
51+
52+
|Name|Type|Description|
53+
|-|-|-|
54+
|`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.|
55+
|`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.|
56+
57+
## Returns
58+
59+
|Column|Type|Description|
60+
|-|-|-|
61+
|`state`|`TEXT` or `BIGINT`|A state found in the `TimelineAgg`|
62+
|`start_time`|`TIMESTAMPTZ`|The time the state started at (inclusive)|
63+
|`end_time`|`TIMESTAMPTZ`|The time the state ended at (exclusive)|
64+
65+
## Sample usage
66+
67+
Getting the interpolated history of states in a timeline aggregate:
68+
69+
```sql
70+
SELECT
71+
bucket,
72+
(toolkit_experimental.interpolated_state_timeline(
73+
summary,
74+
bucket,
75+
'15 min',
76+
LAG(summary) OVER (ORDER by bucket),
77+
LEAD(summary) OVER (ORDER by bucket)
78+
)).*
79+
FROM (
80+
SELECT
81+
time_bucket('1 min'::interval, ts) AS bucket,
82+
toolkit_experimental.timeline_agg(ts, state) AS summary
83+
FROM states_test
84+
GROUP BY time_bucket('1 min'::interval, ts)
85+
) t;
86+
```
87+
88+
Example output:
89+
90+
```
91+
bucket | state | start_time | end_time
92+
------------------------+-------+------------------------+------------------------
93+
2020-01-01 00:00:00+00 | START | 2020-01-01 00:00:00+00 | 2020-01-01 00:00:11+00
94+
2020-01-01 00:00:00+00 | OK | 2020-01-01 00:00:11+00 | 2020-01-01 00:15:00+00
95+
2020-01-01 00:01:00+00 | ERROR | 2020-01-01 00:01:00+00 | 2020-01-01 00:01:03+00
96+
2020-01-01 00:01:00+00 | OK | 2020-01-01 00:01:03+00 | 2020-01-01 00:16:00+00
97+
2020-01-01 00:02:00+00 | STOP | 2020-01-01 00:02:00+00 | 2020-01-01 00:02:00+00
98+
```
99+
100+
[state_agg]: /api/:currentVersion:/hyperfunctions/state-aggregates/state_agg/
101+
[state_timeline]: /api/:currentVersion:/hyperfunctions/state-aggregates/state_timeline/

‎api/into_values-state_agg.md‎

Lines changed: 10 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ hyperfunction:
1414
family: state aggregates
1515
type: accessor
1616
aggregates:
17-
- state_agg()
17+
- state_agg() | timeline_agg()
1818
---
1919

2020
import Experimental from 'versionContent/_partials/_experimental.mdx';
@@ -25,8 +25,12 @@ Returns the data accumulated in a [state aggregate][state_agg].
2525

2626
```sql
2727
into_values (
28-
agg StateAgg
28+
agg [StateAgg | TimelineAgg]
2929
) RETURNS (TEXT, BIGINT)
30+
31+
into_int_values (
32+
agg [StateAgg | TimelineAgg]
33+
) RETURNS (INT, BIGINT)
3034
```
3135

3236
<Experimental />
@@ -35,14 +39,14 @@ into_values (
3539

3640
|Name|Type|Description|
3741
|-|-|-|
38-
|`agg`|`StateAgg`|The aggregate to display data for|
42+
|`agg`|`StateAgg` or `TimelineAgg`|The aggregate to display data for|
3943

4044
## Returns
4145

4246
|Column|Type|Description|
4347
|-|-|-|
44-
|`state`|`TEXT`|A state found in the `StateAgg`|
45-
|`duration`|`BIGINT`|The duration of time spent in that state|
48+
|`state`|`TEXT`|A state found in the `StateAgg` or `TimelineAgg`|
49+
|`duration`|`BIGINT` or `INT`|The duration of time spent in that state|
4650

4751
## Sample usage
4852

@@ -66,4 +70,4 @@ OK | 106000000
6670
START | 11000000
6771
```
6872

69-
[state_agg]: /api/:currentVersion:/hyperfunctions/frequency-analysis/state_agg/
73+
[state_agg]: /api/:currentVersion:/hyperfunctions/state-aggregates/state_agg/

‎api/page-index/page-index.js‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -636,6 +636,26 @@ module.exports = [
636636
title: "into_values (for state_agg)",
637637
href: "into_values-state_agg",
638638
},
639+
{
640+
title: "rollup (for state_agg)",
641+
href: "rollup-state_agg",
642+
},
643+
{
644+
title: "state_timeline",
645+
href: "state_timeline",
646+
},
647+
{
648+
title: "state_periods",
649+
href: "state_periods",
650+
},
651+
{
652+
title: "interpolated_state_periods",
653+
href: "interpolated_state_periods",
654+
},
655+
{
656+
title: "interpolated_state_timeline",
657+
href: "interpolated_state_timeline",
658+
},
639659
],
640660
},
641661
],

0 commit comments

Comments
 (0)