hdr_histogram

概览

Official v1.0.0 release asset installs control/SQL 1.0; the Git tag declares 1.0.0. Extension license is MIT; packages also include the CC0-1.0 HdrHistogram_c library. PG14-18; requires zlib. Default lossless merge depends on accumulator range/order; left mode can discard samples.

版本

构建

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

pig build pkg hdr_histogram         # 构建 RPM / DEB 包

安装

您可以直接安装 hdr_histogram 扩展包的预置二进制包，首先确保 PGDG 和 PIGSTY 仓库已经添加并启用：

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

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

pig install hdr_histogram;          # 当前活跃 PG 版本安装

pig ext install -y hdr_histogram -v 18  # PG 18
pig ext install -y hdr_histogram -v 17  # PG 17
pig ext install -y hdr_histogram -v 16  # PG 16
pig ext install -y hdr_histogram -v 15  # PG 15
pig ext install -y hdr_histogram -v 14  # PG 14

dnf install -y hdr_histogram_18       # PG 18
dnf install -y hdr_histogram_17       # PG 17
dnf install -y hdr_histogram_16       # PG 16
dnf install -y hdr_histogram_15       # PG 15
dnf install -y hdr_histogram_14       # PG 14

apt install -y postgresql-18-hdr-histogram   # PG 18
apt install -y postgresql-17-hdr-histogram   # PG 17
apt install -y postgresql-16-hdr-histogram   # PG 16
apt install -y postgresql-15-hdr-histogram   # PG 15
apt install -y postgresql-14-hdr-histogram   # PG 14

创建扩展：

CREATE EXTENSION hdr_histogram;

用法

来源：

• README.md
• hdr_histogram–1.0.0.sql
• hdr_histogram.c
• META.json
• .github/workflows/ci.yml
• hdr_histogram.control
• 官方 1.0.0 发布归档

hdr_histogram 存储压缩 HDR 直方图，以可配置精度计算分位数。hdr_add 聚合数值样本，hdr_merge 合并已存储的直方图。上游 CI 包含 PostgreSQL 14–18。扩展可信、可迁移，依赖 zlib；拥有数据库 CREATE 权限的角色可以安装。

Pigsty 软件包使用的官方 1.0.0 发布归档安装的 control/SQL 版本为 1.0，而 Git 标签内的 control 文件声明 1.0.0。应检查实际安装的扩展版本，不能直接从软件包版本推断。

核心用法

CREATE EXTENSION hdr_histogram;
SELECT hdr_percentile(hdr_add(1.0), 50);
SET hdr_histogram.merge_mode = 'lossless';
SELECT hdr_percentile(hdr_add(latency::double precision), 99)
FROM (VALUES (100), (200), (300), (500)) AS samples(latency);
CREATE TABLE latency_histograms (recorded_at timestamptz, hist hdr_histogram);
SELECT hdr_percentile(hdr_merge(hist), 99) FROM latency_histograms;

运行边界

样本会转换为 int64，因此应统一计量单位。默认最大值为 1e9、精度为三位有效数字；hdr_histogram.lowest、hdr_histogram.highest 和 hdr_histogram.sig_figs 控制新直方图参数。非有限值或超出范围的样本会报错。hdr_percentile 接受 0 到 100 的分位点；hdr_min、hdr_max、hdr_mean、hdr_stddev、hdr_total_count、hdr_sig_figs、hdr_lowest 和 hdr_highest 用于检查直方图。默认 merge_mode 为 lossless，不兼容的合并会报错；strict 要求参数相同，left 可能丢弃超出累加器范围的值，union 会扩展范围和精度。首次调用直方图函数会加载库；示例先调用函数，再设置会话 GUC。核心功能无需共享预加载。分位数是误差有界的估计，不是精确的顺序统计量。