Working PR for Toolkit 1.3 (github#522)

* Toolkit How To docs (github#504) * File setup to rename section and move install doc in * Add pages for hyperloglog and counter agg from previous PRs * Add approx percentile blog post link. * Add new pages to top level page list * Remove unused entry * Index & metadata for hyperfunctions. * Editing metadata * initcaps in index * Add new bucket items with filler content. * Update index and add other required pages * Add first draft content * First draft content for remaining dummy text * Add directory type in index * Add comment * Update xrefs in top level pages, add advanced page, edits. * typos * Updates per feedback * Complete edits on counter aggs example * Add whitespace around procedure tags * Add function pipeline content with FIXME blog link * Final editing pass * Toolkit API docs (github#514) * add trailing slash (github#505) * Create 'legend' for API reference tags (github#503) * write page * update link name * typo * Apply suggestions from code review Co-authored-by: Lana Brindley <[email protected]> * Update api-tag-overview.md Remove 'Edition' * add line breaks * Update api/api-tag-overview.md Co-authored-by: Lana Brindley <[email protected]> Co-authored-by: Lana Brindley <[email protected]> * Update max storage to 16TB, and some light editing. (github#507) * Update title of Promscale tutorial (github#512) * Add approx count distinct functions * Add counter agg functions * Procedure styling jacob (github#515) * update * add procedure block instructions * convert styling to procedrue on cloud/disk management * Apply suggestions from code review Co-authored-by: Lana Brindley <[email protected]> Co-authored-by: Lana Brindley <[email protected]> * Update xrefs in approx count distincts pages * Update xrefs in stats agg pages * Update xrefs in gapfilling pages (+ light editing) * Update xrefs in percentil approx pages (+ light editing) * Update xrefs in counter agg pages * Update xrefs in time-weighted average pages * Add missing call * Updates index with new structure, and adds top pages for each family * Fix typo in index * Edit index pages * hyperfunctions intro * Updated advanced aggs pages with links to HowTo * Add toolkit matrix table portions to function family pages * Add links to function family pages * Add missing link ref * Fix bad link * Final editing pass (1 of 2) * Final editing pass (2 of 2) Co-authored-by: Jacob Prall <[email protected]> * Update timescaledb/how-to-guides/hyperfunctions/about-hyperfunctions.md Adds link to function pipelines blog post Co-authored-by: Lana Brindley <[email protected]> Co-authored-by: Jacob Prall <[email protected]>
jnidzwetzki · Oct 19, 2021 · f281a55 · f281a55
1 parent 0a1b5f4
commit f281a55
Show file tree

Hide file tree

Showing 72 changed files with 2,725 additions and 742 deletions.
diff --git a/api/_template.md b/api/_template.md
@@ -11,15 +11,15 @@ Use a highlight for any important information. Choose `note`, `important`, or `w
 </highlight>
 -->
 
-## Required Arguments
+## Required arguments
 
 |Name|Type|Description|
 |-|-|-|
 |<FIXME>|<FIXME>|<FIXME>|
 
 <!---Any special notes about the required arguments-->
 
-### Optional Arguments
+### Optional arguments
 
 |Name|Type|Description|
 |-|-|-|
@@ -35,7 +35,7 @@ Use a highlight for any important information. Choose `note`, `important`, or `w
 
 <!---Any special notes about the returns-->
 
-## Sample Usage
+## Sample usage
 <!---Single sentence description of what this example does-->
 
 ``` sql

diff --git a/api/approx_count_distincts.md b/api/approx_count_distincts.md
@@ -0,0 +1,20 @@
+# Approximate count distincts
+This section includes functions related to approximating distinct counts.
+Approximate count distincts are used to find the number of unique values, or
+cardinality, in a large dataset. For more information about approximate count
+distinct functions, see the
+[hyperfunctions documentation][hyperfunctions-approx-count-distincts].
+
+Some hyperfunctions are included in the default TimescaleDB product. For
+additional hyperfunctions, you need to install the
+[Timescale Toolkit][install-toolkit] PostgreSQL extension.
+
+|Hyperfunction family|Types|API Calls|Included by default|Toolkit required|
+|-|-|-|-|-|
+|Approximate count distincts|Hyperloglog|[`hyperloglog`](hyperfunctions/approx_count_distincts/hyperloglog/)|❌|✅|
+|||[`rollup`](hyperfunctions/approx_count_distincts/rollup-hyperloglog/)|❌|✅|
+|||[`distinct_count`](hyperfunctions/approx_count_distincts/distinct_count/)|❌|✅|
+|||[`stderror`](hyperfunctions/approx_count_distincts/stderror/)|❌|✅|
+
+[hyperfunctions-approx-count-distincts]: timescaledb/:currentVersion:/how-to-guides/hyperfunctions/approx-count-distincts/
+[install-toolkit]: timescaledb/:currentVersion:/how-to-guides/hyperfunctions/install-toolkit
diff --git a/api/approx_percentile.md b/api/approx_percentile.md
@@ -9,6 +9,9 @@ approx_percentile(
 ) RETURNS DOUBLE PRECISION
 ```
 
+For more information about percentile approximation functions, see the
+[hyperfunctions documentation][hyperfunctions-percentile-approx].
+
 ## Required arguments
 
 |Name|Type|Description|
@@ -34,3 +37,6 @@ approx_percentile
 -------------------
              0.999
 ```
+
+
+[hyperfunctions-percentile-approx]: timescaledb/:currentVersion:/how-to-guides/hyperfunctions/percentile-approx/
diff --git a/api/approx_percentile_rank.md b/api/approx_percentile_rank.md
@@ -1,6 +1,5 @@
-## approx_percentile_rank()  <tag type="toolkit">Toolkit</tag>
-
-Estimate what percentile a given value would be located at in a UddSketch.
+# approx_percentile_rank()  <tag type="toolkit">Toolkit</tag>
+Estimate what percentile a given value would be located at in a `UddSketch`.
 
 ```SQL
 approx_percentile_rank(
@@ -9,20 +8,25 @@ approx_percentile_rank(
 ) RETURNS UddSketch
 ```
 
-### Required arguments
+*   For more information about percentile approximation algorithms, see
+    [advanced aggregation methods][advanced-agg].
+*   For more information about percentile approximation functions, see the
+    [hyperfunctions documentation][hyperfunctions-percentile-approx].
+
+## Required arguments
 
 |Name|Type|Description|
 |---|---|---|
 |`value`|`DOUBLE PRECISION`|The value to estimate the percentile of|
-|`sketch`|`UddSketch`|The sketch to compute the percentile on.
+|`sketch`|`UddSketch`|The sketch to compute the percentile on|
 
-### Returns
+## Returns
 
 |Column|Type|Description|
 |---|---|---|
 |`approx_percentile_rank`|`DOUBLE PRECISION`|The estimated percentile associated with the provided value|
 
-### Sample usage
+## Sample usage
 
 ```SQL
 SELECT
@@ -34,3 +38,7 @@ FROM generate_series(0, 100) data;
 ----------------------------
          0.9851485148514851
 ```
+
+
+[hyperfunctions-percentile-approx]: timescaledb/:currentVersion:/how-to-guides/hyperfunctions/percentile-approx/
+[advanced-agg]: /timescaledb/:currentVersion:/how-to-guides/hyperfunctions/percentile-approx/advanced-agg/
diff --git a/api/average.md b/api/average.md
@@ -1,4 +1,4 @@
-## average() <tag type="toolkit">Toolkit</tag>
+# average() <tag type="toolkit">Toolkit</tag>
 
 ```SQL
 average(
@@ -8,16 +8,21 @@ average(
 
 A function to compute a time weighted average from a `TimeWeightSummary`.
 
+*   For more information about time-weighted average functions, see the
+    [hyperfunctions documentation][hyperfunctions-time-weight-average].
+*   For more information about statistical aggregate functions, see the
+    [hyperfunctions documentation][hyperfunctions-stats-agg].
+
 ### Required arguments
 
 |Name|Type|Description|
-|---|---|---|
+|-|-|-|
 |`tws`|`TimeWeightSummary`|The input TimeWeightSummary from a [`time_weight`](/hyperfunctions/time-weighted-averages/time_weight/) call|
 
 ### Returns
 
 |Column|Type|Description|
-|---|---|---|
+|-|-|-|
 |`average`|`DOUBLE PRECISION`|The time weighted average computed from the `TimeWeightSummary`|
 
 ### Sample usage
@@ -35,3 +40,6 @@ FROM (
 ) t
 ```
 
+
+[hyperfunctions-time-weight-average]: timescaledb/:currentVersion:/how-to-guides/hyperfunctions/time-weighted-averages/
+[hyperfunctions-stats-agg]: timescaledb/:currentVersion:/how-to-guides/hyperfunctions/stats-aggs/
diff --git a/api/corr.md b/api/corr.md
@@ -0,0 +1,48 @@
+# corr() <tag type="toolkit" content="toolkit" />
+The correlation coefficient of the least squares fit line of the adjusted
+counter value. Given that the slope of a line for any counter value must be
+non-negative, this must also always be non-negative and in the range from 0.0 to
+1.0. It measures how well the least squares fit the available data, where a
+value of 1.0 represents the strongest correlation between time and the counter
+increasing.
+
+```sql
+corr(
+    summary CounterSummary
+) RETURNS DOUBLE PRECISION
+```
+
+For more information about counter aggregation functions, see the
+[hyperfunctions documentation][hyperfunctions-counter-agg].
+
+## Required arguments
+
+|Name|Type|Description|
+|-|-|-|
+|summary|CounterSummary|The input CounterSummary from a counter_agg call|
+
+## Returns
+
+|Name|Type|Description|
+|-|-|-|
+|corr|DOUBLE PRECISION|The correlation coefficient computed from the least squares fit of the adjusted counter values input to the CounterSummary|
+
+## Sample usage
+
+```sql
+SELECT
+    id,
+    bucket,
+    corr(summary)
+FROM (
+    SELECT
+        id,
+        time_bucket('15 min'::interval, ts) AS bucket,
+        counter_agg(ts, val) AS summary
+    FROM foo
+    GROUP BY id, time_bucket('15 min'::interval, ts)
+) t
+```
+
+
+[hyperfunctions-counter-agg]: timescaledb/:currentVersion:/how-to-guides/hyperfunctions/counter-aggregation/
diff --git a/api/counter_agg_point.md b/api/counter_agg_point.md
@@ -0,0 +1,65 @@
+# counter_agg() <tag type="toolkit" content="toolkit" />
+An aggregate that produces a CounterSummary from timestamps and associated
+values.
+
+For more information about counter aggregation functions, see the
+[hyperfunctions documentation][hyperfunctions-counter-agg].
+
+## Required arguments
+
+|Name|Type|Description|
+|-|-|-|
+|ts|TIMESTAMPZ|The time at each point|
+|value|DOUBLE PRECISION|The value at each point to use for the counter aggregate|
+
+The `value` argument is currently only accepted as a DOUBLE PRECISION number,
+because it is the most common type for counters, even though other numeric
+types, such as BIGINT, might sometimes be more intuitive. If you store a value
+as a different numeric type you can cast to DOUBLE PRECISION on input to the
+function.
+
+<highlight type="note">
+Note that both `ts` and `value` can be NULL, but the aggregate is not evaluated
+on NULL values. This means that if the aggregate receives a NULL value, it will
+return NULL, it will not return an error.
+</highlight>
+
+### Optional arguments
+
+|Name|Type|Description|
+|-|-|-|
+|bounds|TSTZRANGE|A range of timestamptz|
+
+The `bounds` argument represents the largest and smallest possible times that
+could be input to this aggregate. Calling with NULL, or leaving out the
+argument, results in an unbounded `CounterSummary`. Bounds are required for
+extrapolation, but not for other accessor functions.
+
+## Returns
+
+|Column|Type|Description|
+|-|-|-|
+|counter_agg|CounterSummary|A CounterSummary object that can be passed to accessor functions or other objects in the counter aggregate API|
+
+<!---Any special notes about the returns-->
+
+## Sample usage
+This example produces a CounterSummary from timestamps and associated values.
+
+``` sql
+WITH t as (
+    SELECT
+        time_bucket('1 day'::interval, ts) as dt,
+        counter_agg(ts, val) AS cs -- get a CounterSummary
+    FROM foo
+    WHERE id = 'bar'
+    GROUP BY time_bucket('1 day'::interval, ts)
+)
+SELECT
+    dt,
+    irate_right(cs) -- extract instantaneous rate from the CounterSummary
+FROM t;
+```
+
+
+[hyperfunctions-counter-agg]: timescaledb/:currentVersion:/how-to-guides/hyperfunctions/counter-aggregation/
diff --git a/api/counter_aggs.md b/api/counter_aggs.md
@@ -0,0 +1,33 @@
+# Counter aggregation
+This section contains functions related to counter aggregation. Counter
+aggregation functions are used to continue accumulating data while ignoring any
+interruptions or resets. For more information about counter aggregation
+functions, see the [hyperfunctions documentation][hyperfunctions-counter-agg].
+
+Some hyperfunctions are included in the default TimescaleDB product. For
+additional hyperfunctions, you need to install the
+[Timescale Toolkit][install-toolkit] PostgreSQL extension.
+
+|Hyperfunction family|Types|API Calls|Included by default|Toolkit required|
+|-|-|-|-|-|
+|Counter aggregation|Counter aggregates|[`counter_agg`](/hyperfunctions/counter_aggs/counter_agg_point/)|❌|✅|
+|||[`rollup`](/hyperfunctions/counter_aggs/rollup-counter/)|❌|✅|
+|||[`corr`](/hyperfunctions/counter_aggs/corr/)|✅|❌|
+|||[`counter_zero_time`](/hyperfunctions/counter_aggs/counter_zero_time/)|✅|❌|
+|||[`delta`](/hyperfunctions/counter_aggs/delta/)|✅|❌|
+|||[`extrapolated_delta`](/hyperfunctions/counter_aggs/extrapolated_delta/)|✅|❌|
+|||[`extrapolated_rate`](/hyperfunctions/counter_aggs/extrapolated_rate/)|✅|❌|
+|||[`idelta`](/hyperfunctions/counter_aggs/idelta/)|✅|❌|
+|||[`intercept`](/hyperfunctions/counter_aggs/intercept/)|✅|❌|
+|||[`irate`](/hyperfunctions/counter_aggs/irate/)|✅|❌|
+|||[`num_changes`](/hyperfunctions/counter_aggs/num_changes/)|✅|❌|
+|||[`num_elements`](/hyperfunctions/counter_aggs/num_elements/)|✅|❌|
+|||[`num_resets`](/hyperfunctions/counter_aggs/num_resets/)|✅|❌|
+|||[`rate`](/hyperfunctions/counter_aggs/rate/)|✅|❌|
+|||[`slope`](/hyperfunctions/counter_aggs/slope/)|✅|❌|
+|||[`time_delta`](/hyperfunctions/counter_aggs/time_delta/)|✅|❌|
+|||[`with_bounds`](/hyperfunctions/counter_aggs/with_bounds/)|❌|✅|
+
+
+[hyperfunctions-counter-agg]: timescaledb/:currentVersion:/how-to-guides/hyperfunctions/counter-aggregation/
+[install-toolkit]: timescaledb/:currentVersion:/how-to-guides/hyperfunctions/install-toolkit
diff --git a/api/counter_zero_time.md b/api/counter_zero_time.md
@@ -0,0 +1,43 @@
+# counter_zero_time() <tag type="toolkit" content="toolkit" />
+The time at which the counter value is predicted to have been zero based on the
+least squares fit line computed from the points in the CounterSummary.
+
+```sql
+counter_zero_time(
+    summary CounterSummary
+) RETURNS TIMESTAMPTZ
+```
+
+For more information about counter aggregation functions, see the
+[hyperfunctions documentation][hyperfunctions-counter-agg].
+
+## Required arguments
+
+|Name|Type|Description|
+|-|-|-|
+|summary|CounterSummary|The input CounterSummary from a counter_agg call|
+
+## Returns
+
+|Name|Type|Description|
+|-|-|-|
+|counter_zero_time|TIMESTAMPTZ|The time at which the counter value is predicted to have been zero based onthe least squares fit of the points input to the CounterSummary|
+
+## Sample usage
+
+```sql
+SELECT
+    id,
+    bucket,
+    counter_zero_time(summary)
+FROM (
+    SELECT
+        id,
+        time_bucket('15 min'::interval, ts) AS bucket,
+        counter_agg(ts, val) AS summary
+    FROM foo
+    GROUP BY id, time_bucket('15 min'::interval, ts)
+) t
+```
+
+[hyperfunctions-counter-agg]: timescaledb/:currentVersion:/how-to-guides/hyperfunctions/counter-aggregation/
diff --git a/api/delta.md b/api/delta.md
@@ -0,0 +1,42 @@
+# delta() <tag type="toolkit" content="toolkit" />
+The change in the counter over the time period. This is the raw or simple delta
+computed by accounting for resets and subtracting the last seen value from the
+first.
+
+```sql
+delta(
+    summary CounterSummary
+) RETURNS DOUBLE PRECISION
+```
+
+For more information about counter aggregation functions, see the
+[hyperfunctions documentation][hyperfunctions-counter-agg].
+
+## Required arguments
+
+|Name|Type|Description|
+|-|-|-|
+|summary|CounterSummary|The input CounterSummary from a counter_agg call|
+
+## Returns
+
+|Name|Type|Description|
+|-|-|-|
+|delta|DOUBLE PRECISION|The delta computed from the CounterSummary|
+
+## Sample usage
+
+```sql
+SELECT
+    id,
+    delta(summary)
+FROM (
+    SELECT
+        id,
+        counter_agg(ts, val) AS summary
+    FROM foo
+    GROUP BY id
+) t
+```
+
+[hyperfunctions-counter-agg]: timescaledb/:currentVersion:/how-to-guides/hyperfunctions/counter-aggregation/