uddsketch() 和 percentile_agg() 函数

工具包（Toolkit）TimescaleDB Toolkit 函数在 Timescale 社区版中可用。它们已自动包含在 Timescale 中，但对于自托管的 TimescaleDB 必须单独安装。点击了解更多。

Timescale Cloud：性能、规模、企业级

自托管产品

MST

使用 UddSketch 算法估算给定百分位数的值，或给定值的百分位排名。这种估算比使用 PostgreSQL 的 `percentile_cont` 和 `percentile_disc` 函数进行精确计算更节省内存和 CPU。

`uddsketch` 是 TimescaleDB Toolkit 中提供的两种高级百分位近似聚合之一。它能在保证的相对误差范围内产生稳定的估算。

另一种高级百分位近似聚合是 `tdigest`，它在极端分位数处更准确，但在某种程度上取决于输入顺序。

如果您不确定要使用哪种聚合，请尝试默认的百分位估算方法 `percentile_agg`。它使用 `uddsketch` 算法和一些合理的默认值。

有关百分位近似算法的更多信息，请参阅算法概述。

此组中的函数

uddsketch: 在 `uddsketch` 中聚合数据，以便进一步计算百分位估算值

percentile_agg: 使用一些合理的默认值，在 uddsketch 中聚合数据，以便进一步计算百分位估算值

approx_percentile: 从 `uddsketch` 聚合中估算给定百分位数的值
approx_percentile_array: 从 `uddsketch` 聚合中估算给定百分位数数组的值
approx_percentile_rank: 从 `uddsketch` 估算给定值的百分位数
error: 获取 `uddsketch` 的最大相对误差
mean: 从 `uddsketch` 中的值计算精确平均值
num_vals: 获取 `uddsketch` 中包含的值的数量

rollup: 合并多个 `uddsketch`

函数详情

uddsketch(
    size INTEGER,
    max_error DOUBLE PRECISION,
    value DOUBLE PRECISION
) RETURNS UddSketch

这是使用 `uddsketch` 算法计算近似百分位数的第一步。使用 `uddsketch` 从原始数据创建中间聚合。然后，此中间形式可由本组中的一个或多个访问器用于计算最终结果。

或者，在应用访问器之前，可以使用 `rollup()` 组合多个此类中间聚合对象。

如果您不确定 `size` 和 `max_error` 的值应如何设置，请尝试使用替代聚合函数 `percentile_agg()`。`percentile_agg` 也会创建 `UddSketch`，但它会为 `size` 和 `max_error` 设置一些合理的默认值，这些值适用于许多用例。

必填参数

名称	类型	描述
`size`	`INTEGER`	`uddsketch` 中桶的最大数量。提供更大的值会使聚合更有可能保持所需的误差，但可能会增加内存使用。
`max_error`	`DOUBLE PRECISION`	草图的期望最大相对误差。如果为数据分布提供的桶太少，则实际误差可能会超过此值。您可以使用 `error` 函数获取实际误差。
`value`	`DOUBLE PRECISION`	要聚合以便进一步计算的列。

列	类型	描述
`uddsketch`	`UddSketch`	使用 `uddsketch` 算法计算百分位数而创建的百分位估算器对象

示例

给定一个名为 `samples` 的表，其中包含名为 `data` 的列，使用 `data` 列构建 `uddsketch`。最大使用 100 个桶，相对误差为 0.01


SELECT uddsketch(100, 0.01, data) FROM samples;

percentile_agg(
  value DOUBLE PRECISION
) RETURNS UddSketch

这是计算近似百分位数的替代第一步。它通过使用一些合理的默认值来创建 `UddSketch`，从而提供了一些额外的便利。在内部，它调用 `uddsketch`，使用 200 个桶和 0.001 的最大误差率。

使用 `percentile_agg` 从原始数据创建中间聚合。然后，此中间形式可由本组中的一个或多个访问器用于计算最终结果。

或者，在应用访问器之前，可以使用 `rollup()` 组合多个此类中间聚合对象。

必填参数

名称	类型	描述
`value`	`DOUBLE PRECISION`	要聚合以进行百分位计算的值列

列	类型	描述
`percentile_agg`	`UddSketch`	使用 `UddSketch` 算法计算百分位数而创建的百分位估算器对象

示例

创建一个连续聚合，用于存储百分位聚合对象。这些对象以后可与多个访问器一起用于回顾性分析


CREATE MATERIALIZED VIEW foo_hourly
WITH (timescaledb.continuous)
AS SELECT
    time_bucket('1 h'::interval, ts) as bucket,
    percentile_agg(value) as pct_agg
FROM foo
GROUP BY 1;

approx_percentile(
  percentile DOUBLE PRECISION,
  uddsketch  UddSketch
) RETURNS DOUBLE PRECISION

从 `uddsketch` 聚合中估算给定百分位数的近似值。

必填参数

名称	类型	描述
`percentile`	`DOUBLE PRECISION`	要计算的百分位数。必须在 `[0.0, 1.0]` 范围内。
`sketch`	`UddSketch`	`uddsketch` 聚合。

列	类型	描述
`approx_percentile`	`DOUBLE PRECISION`	在请求百分位数处的估算值。

示例

在给定包含从 0 到 100 的数字的样本的情况下，估算第一个百分位数处的值


SELECT
  approx_percentile(0.01, uddsketch(data))
FROM generate_series(0, 100) data;


approx_percentile
-------------------
            0.999

approx_percentile_array(
  percentiles DOUBLE PRECISION[],
  uddsketch  UddSketch
) RETURNS DOUBLE PRECISION[]

从 `uddsketch` 聚合中估算百分位数数组的近似值。

必填参数

名称	类型	描述
`percentiles`	`DOUBLE PRECISION[]`	要计算的百分位数数组。必须在 `[0.0, 1.0]` 范围内。
`sketch`	`UddSketch`	`uddsketch` 聚合。

列	类型	描述
`approx_percentile_array`	`DOUBLE PRECISION[]`	在请求百分位数处的估算值。

示例

在给定包含从 0 到 100 的数字的样本的情况下，估算第 90、50 和 20 个百分位数处的值


SELECT
  approx_percentile_array(array[0.9,0.5,0.2], uddsketch(100,0.005,data))
FROM generate_series(0, 100) data;


approx_percentile_array
-------------------
 {90.0,50.0,20.0}

approx_percentile_rank(
  value DOUBLE PRECISION,
  sketch UddSketch
) RETURNS DOUBLE PRECISION

估算给定值所处的百分位数。

必填参数

名称	类型	描述
`value`	`DOUBLE PRECISION`	要估算其百分位数的值。
`sketch`	`UddSketch`	`uddsketch` 聚合。

列	类型	描述
`approx_percentile_rank`	`DOUBLE PRECISION`	与提供的值关联的估算百分位数。

示例

在给定包含从 0 到 100 的数字的样本的情况下，估算值 `99` 的百分位排名


SELECT
  approx_percentile_rank(99, uddsketch(data))
FROM generate_series(0, 100) data;


approx_percentile_rank
----------------------------
        0.9851485148514851

error(
  sketch UddSketch
) RETURNS DOUBLE PRECISION

获取 `uddsketch` 的最大相对误差。正确的（非估算的）百分位数落在由 `approx_percentile(sketch) +/- (approx_percentile(sketch) * error(sketch))` 定义的范围内。

必填参数

名称	类型	描述
`sketch`	`UddSketch`	要确定误差的 `uddsketch`。

列	类型	描述
`error`	`DOUBLE PRECISION`	任何百分位估算的最大相对误差。

示例

使用 `uddsketch` 估算百分位数时计算最大相对误差


SELECT error(uddsketch(data))
FROM generate_series(0, 100) data;


error
-------
0.001

mean(
  sketch UddSketch
) RETURNS DOUBLE PRECISION

计算 `uddsketch` 中值的精确平均值。与百分位计算不同，平均值计算是精确的。此访问器允许您在计算百分位数的同时计算平均值，而无需从相同原始数据创建两个单独的聚合。

必填参数

名称	类型	描述
`sketch`	`UddSketch`	要从中提取平均值的 `uddsketch`。

列	类型	描述
`mean`	`DOUBLE PRECISION`	`uddsketch` 中值的平均值。

示例

计算从 0 到 100 的整数的平均值


SELECT mean(uddsketch(data))
FROM generate_series(0, 100) data;


mean
------
50

num_vals(
  sketch UddSketch
) RETURNS DOUBLE PRECISION

获取 `uddsketch` 中包含的值的数量。此访问器允许您在计算百分位数的同时计算计数，而无需从相同原始数据创建两个单独的聚合。

必填参数

名称	类型	描述
`sketch`	`UddSketch`	要从中提取值数量的 `uddsketch`。

列	类型	描述
`num_vals`	`DOUBLE PRECISION`	`uddsketch` 中值的数量。

示例

计数从 0 到 100 的整数


SELECT num_vals(uddsketch(data))
FROM generate_series(0, 100) data;


num_vals
-----------
    101

rollup(
  sketch UddSketch
) RETURNS UddSketch

将由 `uddsketch` 生成的多个中间 `uddsketch` 聚合合并为一个中间 `uddsketch` 聚合。例如，您可以使用 `rollup` 将 15 分钟桶的 `uddsketch` 合并为每日桶。

必填参数

名称	类型	描述
`sketch`	`UddSketch`	要合并的 `uddsketch` 聚合。

列	类型	描述
`rollup`	`UddSketch`	通过组合输入 `uddsketch` 聚合而创建的新 `uddsketch` 聚合。

扩展示例

聚合并合并百分位数据，以使用 `percentile_agg` 计算每日百分位数

创建包含百分位聚合的每小时连续聚合


CREATE MATERIALIZED VIEW foo_hourly
WITH (timescaledb.continuous)
AS SELECT
    time_bucket('1 h'::interval, ts) as bucket,
    percentile_agg(value) as pct_agg
FROM foo
GROUP BY 1;

您可以使用访问器直接从连续聚合查询每小时数据。您也可以将每小时数据合并为每日桶，然后计算近似百分位数


SELECT
    time_bucket('1 day'::interval, bucket) as bucket,
    approx_percentile(0.95, rollup(pct_agg)) as p95,
    approx_percentile(0.99, rollup(pct_agg)) as p99
FROM foo_hourly
GROUP BY 1;

聚合并合并百分位数据，以使用 `uddsketch` 计算每日百分位数

创建包含百分位聚合的每小时连续聚合


CREATE MATERIALIZED VIEW foo_hourly
WITH (timescaledb.continuous)
AS SELECT
    time_bucket('1 h'::interval, ts) as bucket,
    uddsketch(value) as uddsketch
FROM foo
GROUP BY 1;

您可以使用访问器直接从连续聚合查询每小时数据。您也可以将每小时数据合并为每日桶，然后计算近似百分位数


SELECT
    time_bucket('1 day'::interval, bucket) as bucket,
    approx_percentile(0.95, rollup(uddsketch)) as p95,
    approx_percentile(0.99, rollup(uddsketch)) as p99
FROM foo_hourly
GROUP BY 1;

uddsketch() 和 percentile_agg() 函数

相关超函数组

两步聚合

此组中的函数

聚合

替代聚合

访问器

Rollup（合并）

函数详情

uddsketch()

percentile_agg()

approx_percentile()

approx_percentile_array()

approx_percentile_rank()

error()

mean()

num_vals()

rollup()

扩展示例

聚合并合并百分位数据，以使用 `percentile_agg` 计算每日百分位数

聚合并合并百分位数据，以使用 `uddsketch` 计算每日百分位数

uddsketch() 和 percentile_agg() 函数

简介

相关超函数组

两步聚合

此组中的函数

聚合

替代聚合

访问器

Rollup（合并）

函数详情

uddsketch()

percentile_agg()

approx_percentile()

approx_percentile_array()

approx_percentile_rank()

error()

mean()

num_vals()

rollup()

扩展示例

聚合并合并百分位数据，以使用 `percentile_agg` 计算每日百分位数

聚合并合并百分位数据，以使用 `uddsketch` 计算每日百分位数

相关内容