pg_sorted_heap 0.13.0 released

I am pleased to announce pg_sorted_heap 0.13.0, a PostgreSQL extension for physically sorted heap storage, zone-map pruning, planner-integrated vector search, and a narrow fact-shaped GraphRAG query surface.

Repository:

https://github.com/skuznetsov/pg_sorted_heap

Release:

https://github.com/skuznetsov/pg_sorted_heap/releases/tag/v0.13.0

What is pg_sorted_heap?

pg_sorted_heap is a PostgreSQL extension that adds:

  • sorted_heap: a table access method that keeps rows physically ordered by primary key and prunes heap blocks with per-page zone maps.
  • sorted_hnsw: a planner-integrated HNSW index access method for built-in vector types.
  • svec and hsvec: float32 and float16 vector types for PostgreSQL.
  • Fact-shaped GraphRAG helpers for retrieving and reranking graph-shaped facts directly inside PostgreSQL.

The storage side is aimed at workloads where physical locality matters: time-series data, event logs, IoT readings, ordered IDs, and large tables with range predicates on primary-key columns.

The vector and GraphRAG side is aimed at applications that want retrieval to stay inside PostgreSQL instead of introducing a separate vector-search sidecar.

What is new in 0.13.0?

The main change in 0.13.0 is that the narrow fact-shaped GraphRAG contract is now part of the stable release surface.

The stable GraphRAG API includes:

  • sorted_heap_graph_rag(...)
  • sorted_heap_graph_register(...)
  • sorted_heap_graph_config(...)
  • sorted_heap_graph_unregister(...)
  • sorted_heap_graph_rag_stats()
  • sorted_heap_graph_rag_reset_stats()

This contract is intentionally narrow. It is designed for fact tables clustered by (entity_id, relation_id, target_id), or by an equivalent registered alias mapping. Queries start with ANN seed retrieval, expand through one or more relation hops, and then exact-rerank the expanded candidate set.

Example:

SELECT *
FROM sorted_heap_graph_rag(
    'facts'::regclass,
    '[0.1,0.2,0.3,...]'::svec,
    relation_path := ARRAY[1, 2],
    ann_k := 64,
    top_k := 10,
    score_mode := 'path'
);

0.13.0 also adds a stable routed GraphRAG entry point for multi-shard or multi-tenant application flows:

  • sorted_heap_graph_route(...)
  • sorted_heap_graph_route_plan(...)

This gives applications one dispatcher for exact-key routing, range routing, profiles, policies, and defaults.

Other release highlights

0.13.0 also includes:

  • Schema registration for non-canonical fact tables, so GraphRAG can be used with existing column names.
  • Backend-local GraphRAG stage stats: seed count, expanded rows, reranked rows, returned rows, and per-stage timing.
  • Lifecycle hardening across extension upgrade, dump/restore, crash recovery, concurrent online compact, and concurrent online merge.
  • A shared-cache correctness fix for sorted_hnsw multi-index workloads.
  • sorted_hnsw.build_sq8, an opt-in low-memory index-build mode for constrained builders.
  • An experimental FlashHadamard retrieval lane. This is documented and tested, but it is not the default ANN path and not part of the stable GraphRAG contract.

Benchmark snapshots

These are workload-specific benchmark snapshots from the release notes, not universal performance claims.

AWS Gutenberg workload, about 104K x 2880D, top-10:

  • sorted_hnsw (svec): 1.287 ms, 100.0% Recall@10
  • sorted_hnsw (hsvec): 1.404 ms, 100.0% Recall@10
  • pgvector halfvec: 2.031 ms, 99.8% Recall@10

AWS fact-shaped multihop GraphRAG workload, 5K chains, 384D:

  • sorted_heap_expand_twohop_path_rerank(): median 0.962 ms
  • sorted_heap_graph_rag_twohop_path_scan(): median 1.025 ms
  • pgvector parity row: median 1.434 ms
  • Qdrant parity row: median 3.355 ms

Installation

Requirements:

  • PostgreSQL 16, 17, or 18
  • Standard PGXS build toolchain with pg_config in PATH

Build from source:

git clone https://github.com/skuznetsov/pg_sorted_heap.git
cd pg_sorted_heap
make
make install

Enable the extension:

CREATE EXTENSION pg_sorted_heap;

Upgrade an existing installation:

ALTER EXTENSION pg_sorted_heap UPDATE TO '0.13.0';

Minimal examples

Create a physically sorted table:

CREATE TABLE events (
    id      bigint PRIMARY KEY,
    ts      timestamptz,
    payload text
) USING sorted_heap;

SELECT sorted_heap_compact('events'::regclass);

Create a planner-integrated HNSW index:

CREATE TABLE documents (
    id        bigserial PRIMARY KEY,
    embedding svec(384),
    content   text
);

CREATE INDEX documents_embedding_idx
ON documents USING sorted_hnsw (embedding)
WITH (m = 16, ef_construction = 200);

SET sorted_hnsw.ef_search = 96;

SELECT id, content
FROM documents
ORDER BY embedding <=> '[0.1,0.2,0.3,...]'::svec
LIMIT 10;

Create a stable fact-shaped GraphRAG table:

CREATE TABLE facts (
    entity_id   int4,
    relation_id int2,
    target_id   int4,
    embedding   svec(384),
    payload     text,
    PRIMARY KEY (entity_id, relation_id, target_id)
) USING sorted_heap;

CREATE INDEX facts_embedding_idx
ON facts USING sorted_hnsw (embedding)
WITH (m = 24, ef_construction = 200);

Verification

The 0.13.0 release-candidate checks include:

  • SQL regression coverage for pg_sorted_heap, sorted_hnsw, and graph_rag
  • GraphRAG lifecycle coverage for upgrade and dump/restore
  • crash recovery checks
  • concurrent online-operation checks
  • pg_upgrade coverage from PostgreSQL 16 to 18 and from 17 to 18
  • sorted_hnsw chunked/shared-cache integration checks

For local verification:

make test-release

For the narrower GraphRAG release bundle:

make test-graphrag-release
  • Repository: https://github.com/skuznetsov/pg_sorted_heap
  • Documentation: https://skuznetsov.github.io/pg_sorted_heap/
  • Release notes: https://github.com/skuznetsov/pg_sorted_heap/releases/tag/v0.13.0
  • Issues: https://github.com/skuznetsov/pg_sorted_heap/issues