reorg(percentile approximation): migrate to new hyperfunctions template (timescale#1799)

Co-authored-by: Lana Brindley <[email protected]>

Author: charislam

_tutorials/deprecated.json

@@ -0,0 +1 @@
+[]

api/_hyperfunctions/tdigest/approx_percentile.md

@@ -0,0 +1,53 @@
+---
+api_name: approx_percentile()
+excerpt: Estimate the value at a given percentile from a `tdigest`
+topics: [hyperfunctions]
+api:
+  license: community
+  type: function
+  toolkit: true
+  version:
+    experimental: 0.2.0
+    stable: 1.0.0
+hyperfunction:
+  family: percentile approximation
+  type: accessor
+  aggregates:
+    - tdigest()
+api_details:
+  summary: Estimate the approximate value at a percentile from a `tdigest` aggregate.
+  signatures:
+    - language: sql
+      code: |
+        approx_percentile(
+          percentile DOUBLE PRECISION,
+          tdigest  TDigest
+        ) RETURNS DOUBLE PRECISION
+  parameters:
+    required:
+      - name: percentile
+        type: DOUBLE PRECISION
+        description: The percentile to compute. Must be within the range `[0.0, 1.0]`.
+      - name: tdigest
+        type: TDigest
+        description: The `tdigest` aggregate.
+    returns:
+      - column: approx_percentile
+        type: DOUBLE PRECISION
+        description: The estimated value at the requested percentile.
+  examples:
+    - description: >
+        Estimate the value at the first percentile, given a sample containing the
+        numbers from 0 to 100.
+      command:
+        code: |
+          SELECT
+            approx_percentile(0.01, tdigest(data))
+          FROM generate_series(0, 100) data;
+      return:
+        code: |
+          approx_percentile
+          -------------------
+                      0.999
+---
+

api/_hyperfunctions/tdigest/approx_percentile_rank.md

@@ -0,0 +1,53 @@
+---
+api_name: approx_percentile_rank()
+excerpt: Estimate the percentile of a given value from a `tdigest`
+topics: [hyperfunctions]
+api:
+  license: community
+  type: function
+  toolkit: true
+  version:
+    experimental: 0.2.0
+    stable: 1.0.0
+hyperfunction:
+  family: percentile approximation
+  type: accessor
+  aggregates:
+    - tdigest()
+api_details:
+  summary: Estimate the the percentile at which a given value would be located.
+  signatures:
+    - language: sql
+      code: |
+        approx_percentile_rank(
+          value DOUBLE PRECISION,
+          digest TDigest
+        ) RETURNS DOUBLE PRECISION
+  parameters:
+    required:
+      - name: value
+        type: DOUBLE PRECISION
+        description: The value to estimate the percentile of.
+      - name: digest
+        type: TDigest
+        description: The `tdigest` aggregate.
+    returns:
+      - column: approx_percentile_rank
+        type: DOUBLE PRECISION
+        description: The estimated percentile associated with the provided value.
+  examples:
+    - description: >
+        Estimate the percentile rank of the value `99`, given a sample containing
+        the numbers from 0 to 100.
+      command:
+        code: |
+          SELECT
+            approx_percentile_rank(99, tdigest(data))
+          FROM generate_series(0, 100) data;
+      return:
+        code: |
+          approx_percentile_rank
+          ----------------------------
+                  0.9851485148514851
+---
+

api/_hyperfunctions/tdigest/examples.md

@@ -0,0 +1,31 @@
+---
+section: hyperfunction
+subsection: tdigest()
+---
+
+### Aggregate and roll up percentile data to calculate daily percentiles
+
+Create an hourly continuous aggregate that contains a percentile aggregate:
+
+```sql
+CREATE MATERIALIZED VIEW foo_hourly
+WITH (timescaledb.continuous)
+AS SELECT
+    time_bucket('1 h'::interval, ts) as bucket,
+    tdigest(value) as tdigest
+FROM foo
+GROUP BY 1;
+```
+
+You can use accessors to query directly from the continuous aggregate for
+hourly data. You can also roll the hourly data up into daily buckets, then
+calculate approximate percentiles:
+
+```sql
+SELECT
+    time_bucket('1 day'::interval, bucket) as bucket,
+    approx_percentile(0.95, rollup(tdigest)) as p95,
+    approx_percentile(0.99, rollup(tdigest)) as p99
+FROM foo_hourly
+GROUP BY 1;
+```

api/_hyperfunctions/tdigest/intro.md

@@ -0,0 +1,30 @@
+---
+section: hyperfunction
+subsection: tdigest()
+---
+
+Estimate the value at a given percentile, or the percentile rank of a given
+value, using the t-digest algorithm. This estimation is more memory- and
+CPU-efficient than an exact calculation using PostgreSQL's `percentile_cont` and
+`percentile_disc` functions.
+
+`tdigest` is one of two advanced percentile approximation aggregates provided in
+TimescaleDB Toolkit. It is a space-efficient aggregation, and it provides more
+accurate estimates at extreme quantiles than traditional methods.
+
+`tdigest` is somewhat dependent on input order. If `tdigest` is run on the same
+data arranged in different order, the results should be nearly equal, but they
+are unlikely to be exact.
+
+The other advanced percentile approximation aggregate is
+[`uddsketch`][uddsketch], which produces stable estimates within a guaranteed
+relative error. If you aren't sure which to use, try the default percentile
+estimation method, [`percentile_agg`][percentile_agg]. It uses the `uddsketch`
+algorithm with some sensible defaults.
+
+For more information about percentile approximation algorithms, see the
+[algorithms overview][algorithms].
+
+[algorithms]: /timescaledb/:currentVersion:/how-to-guides/hyperfunctions/percentile-approx/advanced-agg/
+[percentile_agg]: /api/:currentVersion:/hyperfunctions/percentile-approximation/uddsketch/#percentile_agg
+[uddsketch]: /api/:currentVersion:/hyperfunctions/percentile-approximation/uddsketch/

api/_hyperfunctions/tdigest/max_val

@@ -0,0 +1,49 @@
+---
+api_name: max_val()
+excerpt: Get the maximum value from a `tdigest`
+topics: [hyperfunctions]
+api:
+  license: community
+  type: function
+  toolkit: true
+  version:
+    experimental: 0.1.0
+    stable: 1.0.0
+hyperfunction:
+  family: percentile approximation
+  type: accessor
+  aggregates:
+    - tdigest()
+api_details:
+  summary: >
+    Get the maximum value from a `tdigest`. This accessor allows you to
+    calculate the maximum alongside percentiles, without needing to create
+    two separate aggregates from the same raw data.
+  signatures:
+    - code: |
+        max_val(
+          digest TDigest
+        ) RETURNS DOUBLE PRECISION
+  parameters:
+    required:
+      - name: digest
+        type: TDigest
+        description: The digest to extract the max value from.
+    returns:
+      - column: max_val
+        type: DOUBLE PRECISION
+        description: The maximum value entered into the `tdigest`.
+  examples:
+    - description: >
+        Get the maximum of the integers from 1 to 100.
+      command:
+        code: |
+          SELECT max_val(tdigest(100, data))
+            FROM generate_series(1, 100) data;
+      return:
+        code: |
+          max_val
+          ---------
+              100
+---
+

api/_hyperfunctions/tdigest/mean.md

@@ -0,0 +1,51 @@
+---
+api_name: mean()
+excerpt: Calculate the exact mean from values in a `tdigest`
+topics: [hyperfunctions]
+api:
+  license: community
+  type: function
+  toolkit: true
+  version:
+    experimental: 0.1.0
+    stable: 1.0.0
+hyperfunction:
+  family: percentile approximation
+  type: accessor
+  aggregates:
+    - tdigest()
+api_details:
+  summary: >
+    Calculate the exact mean of the values in a `tdigest` aggregate. Unlike
+    percentile calculations, the mean calculation is exact. This accessor
+    allows you to calculate the mean alongside percentiles, without needing to
+    create two separate aggregates from the same raw data.
+  signatures:
+    - language: sql
+      code: |
+        mean(
+          digest TDigest
+        ) RETURNS DOUBLE PRECISION
+  parameters:
+    required:
+      - name: digest
+        type: TDigest
+        description: The `tdigest` aggregate to extract the mean from.
+    returns:
+      - column: mean
+        type: DOUBLE PRECISION
+        description: The mean of the values in the `tdigest` aggregate.
+  examples:
+    - description: >
+        Calculate the mean of the integers from 0 to 100.
+      command:
+        code: |
+          SELECT mean(tdigest(data))
+          FROM generate_series(0, 100) data;
+      return:
+        code: |
+          mean
+          ------
+          50
+---
+

api/_hyperfunctions/tdigest/min_val

@@ -0,0 +1,49 @@
+---
+api_name: min_val()
+excerpt: Get the minimum value from a `tdigest`
+topics: [hyperfunctions]
+api:
+  license: community
+  type: function
+  toolkit: true
+  version:
+    experimental: 0.1.0
+    stable: 1.0.0
+hyperfunction:
+  family: percentile approximation
+  type: accessor
+  aggregates:
+    - tdigest()
+api_details:
+  summary: >
+    Get the minimum value from a `tdigest`. This accessor allows you to
+    calculate the minimum alongside percentiles, without needing to create
+    two separate aggregates from the same raw data.
+  signatures:
+    - code: |
+        min_val(
+          digest TDigest
+        ) RETURNS DOUBLE PRECISION
+  parameters:
+    required:
+      - name: digest
+        type: TDigest
+        description: The digest to extract the minimum value from.
+    returns:
+      - column: max_val
+        type: DOUBLE PRECISION
+        description: The minimum value entered into the `tdigest`.
+  examples:
+    - description: >
+        Get the minimum of the integers from 1 to 100.
+      command:
+        code: |
+          SELECT max_val(tdigest(100, data))
+            FROM generate_series(1, 100) data;
+      return:
+        code: |
+          min_val
+          ---------
+                1
+---
+

api/_hyperfunctions/tdigest/num_vals.md

@@ -0,0 +1,50 @@
+---
+api_name: num_vals()
+excerpt: Get the number of values contained in a `tdigest`
+topics: [hyperfunctions]
+api:
+  license: community
+  type: function
+  toolkit: true
+  version:
+    experimental: 0.1.0
+    stable: 1.0.0
+hyperfunction:
+  family: percentile approximation
+  type: accessor
+  aggregates:
+    - tdigest()
+api_details:
+  summary: >
+    Get the number of values contained in a `tdigest` aggregate. This accessor
+    allows you to calculate a count alongside percentiles, without needing to
+    create two separate aggregates from the same raw data.
+  signatures:
+    - language: sql
+      code: |
+        num_vals(
+          digest TDigest
+        ) RETURNS DOUBLE PRECISION
+  parameters:
+    required:
+      - name: digest
+        type: TDigest
+        description: The `tdigest` aggregate to extract the number of values from.
+    returns:
+      - column: num_vals
+        type: DOUBLE PRECISION
+        description: The number of values in the `tdigest` aggregate.
+  examples:
+    - description: >
+        Count the number of integers from 0 to 100.
+      command:
+        code: |
+          SELECT num_vals(tdigest(data))
+          FROM generate_series(0, 100) data;
+      return:
+        code: |
+          num_vals
+          -----------
+              101
+---
+