TimescaleDB API 参考超函数百分位数近似

uddsketch() 和 percentile_agg() 函数

ToolkitTimescaleDB Toolkit 函数在 Timescale Community Edition 下可用。它们自动包含在 Timescale 中，但必须为自托管 TimescaleDB 单独安装。点击了解更多。

简介

使用 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整数uddsketch 中的最大桶数。在此处提供较大的值可以使聚合更有可能保持所需的误差，但也可能会增加内存使用量。
max_error双精度浮点数sketch 的所需最大相对误差。如果为数据分布提供的桶太少，则真实误差可能会超过此值。您可以使用 error 函数获取真实误差。
value双精度浮点数要聚合以进行进一步计算的列。
返回
列类型描述
uddsketchUddSketch用于使用 uddsketch 算法计算百分位数的百分位数估计器对象
示例

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

SELECT uddsketch(100, 0.01, data) FROM samples;
percentile_agg(
  value DOUBLE PRECISION
) RETURNS UddSketch

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

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

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

必需参数
名称类型描述
value双精度浮点数要聚合以进行百分位数计算的值列
返回
列类型描述
percentile_aggUddSketch用于使用 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 聚合估计百分位的近似值。

必需参数
名称类型描述
百分位数双精度浮点数要计算的百分位数。必须在 [0.0, 1.0] 范围内。
sketchUddSketchuddsketch 聚合。
返回
列类型描述
approx_percentile双精度浮点数请求的百分位数的估计值。
示例

估计第一个百分位的值，给定一个包含从 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 聚合估计百分位数数组的近似值。

必需参数
名称类型描述
百分位数数组双精度浮点数数组要计算的百分位数数组。必须在 [0.0, 1.0] 范围内。
sketchUddSketchuddsketch 聚合。
返回
列类型描述
approx_percentile_array双精度浮点数数组请求的百分位数数组的估计值。
示例

估计第 90、50 和 20 个百分位的值，给定一个包含从 0 到 100 的数字的样本

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双精度浮点数要估计百分位数的值。
sketchUddSketchuddsketch 聚合。
返回
列类型描述
approx_percentile_rank双精度浮点数与提供的值关联的估计百分位数。
示例

估计值 99 的百分位排名，给定一个包含从 0 到 100 的数字的样本

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)) 定义的范围内。

必需参数
名称类型描述
sketchUddSketch要确定误差的 uddsketch。
返回
列类型描述
error双精度浮点数任何百分位数估计的最大相对误差。
示例

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

SELECT error(uddsketch(data))
FROM generate_series(0, 100) data;
error
-------
0.001
mean(
  sketch UddSketch
) RETURNS DOUBLE PRECISION

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

必需参数
名称类型描述
sketchUddSketch要从中提取平均值的 uddsketch。
返回
列类型描述
mean双精度浮点数uddsketch 中值的平均值。
示例

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

SELECT mean(uddsketch(data))
FROM generate_series(0, 100) data;
mean
------
50
num_vals(
  sketch UddSketch
) RETURNS DOUBLE PRECISION

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

必需参数
名称类型描述
sketchUddSketch要从中提取值数量的 uddsketch。
返回
列类型描述
num_vals双精度浮点数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 汇总到每日桶中。

必需参数
名称类型描述
sketchUddSketch要汇总的 uddsketch 聚合。
返回
列类型描述
rollupUddSketch通过组合输入 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;

关键词

percentile approximationhyperfunctionsToolkit

在此页面上发现问题？报告问题 或 在 GitHub 上编辑此页面。

上一页time_bucket_gapfill下一页tdigest

相关内容

tdigest()
tdigest() 函数的 API 参考
Hyperfunctions
使用超函数简化数据分析
Downsampling functions
降采样函数的 API 参考
days_in_month()
计算给定 timestamptz 的月份天数
month_normalize()
根据月份天数标准化每月指标
Saturating math functions
饱和运算函数的 API 参考