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

uddsketch()和 percentile_agg()函数

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

简介

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

uddsketch 是 TimescaleDB 工具包中提供的两个高级百分位数近似聚合之一。它在保证的相对误差范围内生成稳定的估计。

另一个高级百分位数近似聚合是 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 设置了一些合理的默认值，这些值应该适用于许多用例。

必需参数
名称类型描述
sizeINTEGERuddsketch 中的最大桶数。在此提供更大的值可以使聚合更有可能保持所需的误差，但可能会增加内存使用量。
max_errorDOUBLE PRECISION草图所需的相对误差最大值。如果为数据分布提供的桶数太少，则实际误差可能会超过此值。您可以使用 error 函数获取实际误差。
valueDOUBLE PRECISION要聚合的列，以便进行进一步计算。
返回值
列类型描述
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() 在应用访问器之前将多个这样的中间聚合对象组合在一起。

必需参数
名称类型描述
valueDOUBLE PRECISION要聚合的值列，以便进行百分位数计算
返回值
列类型描述
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 聚合中估算近似百分位数的值。

必需参数
名称类型描述
percentileDOUBLE PRECISION要计算的百分位数。必须在 [0.0, 1.0] 范围内。
sketchUddSketchuddsketch 聚合。
返回值
列类型描述
approx_percentileDOUBLE 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 聚合中估算百分位数数组的近似值。

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

估算第 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

估算给定值将位于的百分位数。

必需参数
名称类型描述
valueDOUBLE PRECISION要估算百分位数的值。
sketchUddSketchuddsketch 聚合。
返回值
列类型描述
approx_percentile_rankDOUBLE PRECISION与提供的价值相关的估计百分位数。
示例

估算值 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。
返回值
列类型描述
errorDOUBLE PRECISION任何百分位数估计的最大相对误差。
示例

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

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

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

必需参数
名称类型描述
sketchUddSketch要从中提取平均值的 uddsketch。
返回值
列类型描述
meanDOUBLE PRECISIONuddsketch 中值的平均值。
示例

计算从 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_valsDOUBLE PRECISIONuddsketch 中的值的数量。
示例

计算从 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;

关键词

百分位数近似超函数工具包

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

上一页time_bucket_gapfill下一页tdigest

相关内容

tdigest()
tdigest() 函数的 API 参考
超函数
使用超函数简化数据分析
降采样函数
降采样函数的 API 参考
days_in_month()
根据 timestamptz 计算月份的天数
month_normalize()
根据月份的天数对每月指标进行归一化
饱和数学函数
饱和数学函数的 API 参考