Open-source PostgreSQL diagnostic

pgvector-filterbench — filtered HNSW recall and query-plan audit

An open-source Go tool that checks whether filtered pgvector searches return the right results and use the intended HNSW index. It compares approximate results with exact PostgreSQL matches and measures recall, latency, and query plans.

Project: pgvector-filterbench
Release: Version 0.1.1
License: Apache-2.0
Language: Go

GoPostgreSQLpgvectorHNSWDockerEXPLAIN JSON

View source code View v0.1.1 release

About the project

pgvector-filterbench

Early release: v0.1.1. Source and releases are public. No production adoption or long-term maintenance history is claimed.

Complementary index reconciler

What it does

Compares filtered ANN output with exact PostgreSQL ground truth
Verifies the configured HNSW index was actually used for every measured plan
Tests filtered-search strategies and HNSW parameters against chosen thresholds
Produces privacy-safe reports and keeps the benchmark transaction read-only

How it works

What it checks

Seeded query-vector sampling or external JSONL query vectors
Exact ground truth inside read-only transactions
Bounded, strict-iterative, and relaxed-iterative HNSW strategies
Recall@k, same-rank, and latency across configured parameter sweeps
EXPLAIN (ANALYZE, VERBOSE, FORMAT JSON) for the measured query shape
Expected schema, table, HNSW index, opclass, and actual index use
Privacy-safe JSON and Markdown reports with row-level data omitted by default

Safety and interpretation

Exact scans can put meaningful load on PostgreSQL even though the benchmark performs no writes. Use a replica or staging database for large workloads, bound the sample and matrix, and configure statement and lock timeouts. Recall values from the included deterministic demo corpus are observations, not promises for another dataset or HNSW build.

Search IndexLane