pg_stl

PostgreSQL 时间序列分析函数

概览

扩展包名版本分类许可证语言
pg_stl1.0.0TIMEPostgreSQLC
ID扩展名BinLibLoadCreateTrustReloc模式
1130pg_stl-
相关扩展timescaledb timeseries periods

ACF, PACF, STL decomposition, and Holt-Winters forecasting.

版本

类型仓库版本PG 大版本包名依赖
EXTPIGSTY1.0.01817161514pg_stl-
RPMPIGSTY1.0.01817161514pg_stl_$v-
DEBPIGSTY1.0.01817161514postgresql-$v-pg-stl-
OS / PGPG18PG17PG16PG15PG14
el8.x86_64PIGSTY MISSPIGSTY MISS
el8.aarch64PIGSTY MISSPIGSTY MISS
el9.x86_64PIGSTY MISSPIGSTY MISS
el9.aarch64PIGSTY MISSPIGSTY MISS
el10.x86_64PIGSTY MISSPIGSTY MISS
el10.aarch64PIGSTY MISSPIGSTY MISS
d12.x86_64PIGSTY MISSPIGSTY MISS
d12.aarch64PIGSTY MISSPIGSTY MISS
d13.x86_64PIGSTY MISSPIGSTY MISS
d13.aarch64
PIGSTY 1.0.0
PIGSTY 1.0.0
PIGSTY 1.0.0
PIGSTY MISSPIGSTY MISS
u22.x86_64PIGSTY MISSPIGSTY MISS
u22.aarch64
PIGSTY 1.0.0
PIGSTY 1.0.0
PIGSTY 1.0.0
PIGSTY MISSPIGSTY MISS
u24.x86_64PIGSTY MISSPIGSTY MISS
u24.aarch64
PIGSTY 1.0.0
PIGSTY 1.0.0
PIGSTY 1.0.0
PIGSTY MISSPIGSTY MISS
u26.x86_64PIGSTY MISSPIGSTY MISS
u26.aarch64PIGSTY MISSPIGSTY MISS

构建

您可以使用 pig build 命令构建 pg_stl 扩展的 RPM / DEB 包:

pig build pkg pg_stl         # 构建 RPM / DEB 包

安装

您可以直接安装 pg_stl 扩展包的预置二进制包,首先确保 PGDGPIGSTY 仓库已经添加并启用:

pig repo add pgsql -u          # 添加仓库并更新缓存

使用 pig 或者是 apt/yum/dnf 安装扩展:

pig install pg_stl;          # 当前活跃 PG 版本安装
pig ext install -y pg_stl -v 18  # PG 18
pig ext install -y pg_stl -v 17  # PG 17
pig ext install -y pg_stl -v 16  # PG 16
dnf install -y pg_stl_18       # PG 18
dnf install -y pg_stl_17       # PG 17
dnf install -y pg_stl_16       # PG 16
apt install -y postgresql-18-pg-stl   # PG 18
apt install -y postgresql-17-pg-stl   # PG 17
apt install -y postgresql-16-pg-stl   # PG 16

创建扩展

CREATE EXTENSION pg_stl;

用法

pg_stl 为 PostgreSQL 提供时间序列分析函数:自相关、偏自相关、STL 分解和 Holt-Winters 预测。上游 README 和 SQL 定义面向 PostgreSQL 16+。

自相关

acf_array(data double precision[], lags integer) 返回 lag 1..lags 的自相关值:

CREATE EXTENSION pg_stl;

SELECT acf_array(
  array_agg(revenue ORDER BY date)::double precision[],
  28
)
FROM daily_sales;

README 描述了如何把 71421 等 lag 上的峰值作为周周期性的信号。当序列太短、lags < 1lags >= n 时,该函数返回 NULL

偏自相关

pacf_array(data double precision[], lags integer) 使用 Durbin-Levinson 递推返回偏自相关值:

WITH series AS (
  SELECT array_agg(value ORDER BY ts)::double precision[] AS values
  FROM measurements
)
SELECT
  unnest(acf_array(values, 20)) AS acf,
  unnest(pacf_array(values, 20)) AS pacf
FROM series;

当你想在扣除较短 lag 的影响后观察某个 lag 的直接关系时,可以使用 PACF。

STL 分解

stl_decompose 会把序列分解为 trend、seasonal 和 residual 三个数组:

WITH data AS (
  SELECT array_agg(revenue ORDER BY month)::double precision[] AS values
  FROM monthly_revenue
),
decomposed AS (
  SELECT (stl_decompose(values, 12)).*
  FROM data
)
SELECT
  unnest(trend) AS trend,
  unnest(seasonal) AS seasonal,
  unnest(residual) AS residual
FROM decomposed;

SQL 定义中的函数签名为:

stl_decompose(
  y double precision[],
  period integer,
  seasonal integer DEFAULT 7,
  robust boolean DEFAULT true,
  trend integer DEFAULT 0,
  low_pass integer DEFAULT 0,
  inner_iter integer DEFAULT 2,
  outer_iter integer DEFAULT 0
) RETURNS stl_result

只需要单个分量时,可以使用便捷函数:

SELECT stl_trend(values, 12) FROM series;
SELECT stl_seasonal(values, 12) FROM series;
SELECT stl_residual(values, 12) FROM series;

有序聚合辅助函数

SQL 文件还定义了 stl_collect_ordered(tbl regclass, val text, ord text),用于按顺序把某一列收集为 double precision[]

SELECT stl_decompose(
  stl_collect_ordered('monthly_revenue'::regclass, 'revenue', 'month'),
  12
);

Holt-Winters 预测

holt_winters_predict(seasonal_type text, period_length int, start_data_array real[]) 会向前预测一个季节周期。seasonal_type'mult' 时表示乘法季节性,为 'add' 时表示加法季节性:

SELECT *
FROM holt_winters_predict(
  'mult',
  4,
  (SELECT array_agg(revenue ORDER BY date)::real[] FROM sales)
);

SQL 实现会自动选择平滑系数:先进行 500 次随机初始化,再以 0.001 步长细化搜索,以最小化平方误差。辅助函数 holt_winters_mse(...) 作为预测器使用的误差计算例程一并提供。

注意事项

  • stl_decompose 需要一个不含 NULLdouble precision[]
  • README 说明序列长度至少应为 2 * period
  • seasonal 必须是不小于 3 的奇数。
  • Holt-Winters 需要 real[] 输入,并且只支持 'mult''add' 两种季节类型。

最后修改 2026-06-18: extension data update (63e2bd9)