hdr_histogram

Overview

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.

Version

Build

You can build the RPM / DEB packages for hdr_histogram using pig build:

pig build pkg hdr_histogram         # build RPM / DEB packages

Install

You can install hdr_histogram directly. First, make sure the PGDG and PIGSTY repositories are added and enabled:

pig repo add pgsql -u          # Add repo and update cache

Install the extension using pig or apt/yum/dnf:

pig install hdr_histogram;          # Install for current active PG version

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:

CREATE EXTENSION hdr_histogram;

Usage

Sources:

• README.md
• hdr_histogram–1.0.0.sql
• hdr_histogram.c
• META.json
• .github/workflows/ci.yml
• hdr_histogram.control
• Official 1.0.0 release archive

hdr_histogram stores compressed HDR histograms and computes percentiles with configurable precision. hdr_add aggregates numeric samples; hdr_merge combines stored histograms. PostgreSQL 14–18 appear in upstream CI. The trusted, relocatable extension requires zlib and can be installed by a role with CREATE privilege on the database.

The official 1.0.0 release archive used for Pigsty packages installs control/SQL version 1.0; the Git tag’s control file declares 1.0.0. Check the installed extension version rather than inferring it from the package version.

Core Workflow

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;

Operational Boundaries

Samples are converted to int64, so choose one unit consistently. The default highest value is 1e9 with three significant figures; hdr_histogram.lowest, hdr_histogram.highest and hdr_histogram.sig_figs configure new histograms. Nonfinite and out-of-range values error. hdr_percentile accepts a percentile from 0 to 100; hdr_min, hdr_max, hdr_mean, hdr_stddev, hdr_total_count, hdr_sig_figs, hdr_lowest and hdr_highest inspect a histogram. The default merge_mode lossless rejects incompatible merges; strict requires identical parameters, left can discard values outside the accumulator range, and union expands range/precision. The first histogram function call loads the library; the example calls it before applying session GUCs. No shared preload is required for core use. Percentiles are bounded-error estimates, not exact order statistics.