pgvector_hypo

pgvector_hypo is a PostgreSQL extension for testing hypothetical pgvector IVFFlat indexes.

A hypothetical index does not build or store a real index. It lets you run EXPLAIN to answer:

Would PostgreSQL choose this IVFFlat index for my query?

This can save the time and disk space required to build several real indexes just to compare their plans.

Important

pgvector_hypo is an experimental 0.1.0 release for PostgreSQL 16 and pgvector 0.8.x. It predicts PostgreSQL's planner choice and costs. It does not predict query speed, recall, index build time, or production performance.

Installation

Binary package — recommended

Binary packages do not require a C compiler or PostgreSQL server headers. pgvector 0.8.x must already be installed for the same PostgreSQL 16 installation.

Download packages from the v0.1.0 release.

Debian or Ubuntu on x86-64

After configuring the PostgreSQL PGDG repository:

curl -LO https://github.com/varadfromeast/pgvector_hypo/releases/download/v0.1.0/postgresql-16-pgvector-hypo_0.1.0-1_amd64.deb
sudo apt install ./postgresql-16-pgvector-hypo_0.1.0-1_amd64.deb

The package depends on postgresql-16 and postgresql-16-pgvector 0.8.0 or newer.

macOS on Apple Silicon

The current macOS binary supports arm64 (uname -m on Apple Silicon).

VERSION=0.1.0
curl -LO "https://github.com/varadfromeast/pgvector_hypo/releases/download/v${VERSION}/pgvector_hypo-${VERSION}-pg16-macos-arm64.tar.gz"
curl -LO "https://github.com/varadfromeast/pgvector_hypo/releases/download/v${VERSION}/pgvector_hypo-${VERSION}-pg16-macos-arm64.tar.gz.sha256"
shasum -a 256 -c "pgvector_hypo-${VERSION}-pg16-macos-arm64.tar.gz.sha256"
tar -xzf "pgvector_hypo-${VERSION}-pg16-macos-arm64.tar.gz"
PG_CONFIG=/path/to/postgresql-16/bin/pg_config \
  "./pgvector_hypo-${VERSION}-pg16-macos-arm64/install.sh"

The installer checks the PostgreSQL major version, operating system, CPU architecture, and pgvector dependency before copying files. Intel macOS currently uses the source installation below.

Installation from source

Use this path when there is no binary for your operating system or CPU. Building from source requires PostgreSQL 16 server development files, pgvector 0.8.x, a C compiler, and make.

git clone --branch v0.1.0 \
  https://github.com/varadfromeast/pgvector_hypo.git
cd pgvector_hypo
make PG_CONFIG=/path/to/postgresql-16/bin/pg_config
sudo make install PG_CONFIG=/path/to/postgresql-16/bin/pg_config

Enable the extension

In every database where you want to test hypothetical indexes:

CREATE EXTENSION vector;
CREATE EXTENSION pgvector_hypo;

Usage

Create a table and check its current plan:

CREATE TABLE items (
    id bigserial PRIMARY KEY,
    category integer,
    embedding vector(3)
);

EXPLAIN
SELECT id
FROM items
ORDER BY embedding <-> '[0,0,0]'::vector
LIMIT 5;

Register a hypothetical IVFFlat index by passing a normal CREATE INDEX statement:

SELECT * FROM pgvector_hypo_create_index(
    'CREATE INDEX ON items USING ivfflat '
    '(embedding vector_l2_ops) WITH (lists = 100)'
);

Run the same EXPLAIN again. If PostgreSQL prefers the hypothetical index, the plan contains a clearly fake name:

Index Scan using "<16383>pgvector_hypo_items_embedding_ivfflat" on items

Inspect, remove, or reset hypothetical indexes:

SELECT * FROM pgvector_hypo_list_indexes;
SELECT pgvector_hypo_drop_index(indexrelid);
SELECT pgvector_hypo_reset();

Hypothetical indexes belong only to the current database session and disappear when that session ends.

Supported indexes

The current release supports:

• PostgreSQL 16 with pgvector 0.8.x;
• fixed-dimension vector, halfvec, and bit keys;
• all seven official IVFFlat opclasses: vector and halfvec L2, inner product, and cosine, plus bit Hamming;
• one ordinary column or immutable expression;
• partial indexes and compatible partitioned-table definitions;
• generated columns and materialized views;
• nearest-neighbor ordering with <->, <#>, <=>, or <~>.

See the complete compatibility matrix for accepted and rejected definitions.

Safety

Hypothetical indexes are available only during top-level plain EXPLAIN. Normal queries, EXPLAIN ANALYZE, and EXPLAIN EXECUTE cannot use them. Nothing is added to PostgreSQL's index catalogs and no relation file is created.

The current public-data evidence has two unwaived planner-choice mismatches at one build-sensitive fixed-bit boundary. Definition coverage, execution safety, and numeric-error gates pass, but the strict release gate remains open. See compatibility evidence.

Documentation

• How pgvector_hypo works
• C source architecture
• Real-world validation
• Issue implementation explainers

Development

Build and test against PostgreSQL 16:

make PG_CONFIG=/path/to/postgresql-16/bin/pg_config
sudo make install PG_CONFIG=/path/to/postgresql-16/bin/pg_config
make installcheck PG_CONFIG=/path/to/postgresql-16/bin/pg_config
make pycheck

See CONTRIBUTING.md for the application and evidence checks. Report security issues through SECURITY.md.