Open-source PostgreSQL diagnostic

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

An open-source Go CLI for testing a failure that latency-only vector benchmarks can miss: a filtered approximate search can lose relevant neighbors, and a seemingly good result can hide a sequential-scan fallback. The tool compares ANN results with exact PostgreSQL ground truth and checks the measured query plans.

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

GoPostgreSQLpgvectorHNSWDockerEXPLAIN JSON

Inspect source View v0.1.1 release

Engineering record

pgvector-filterbench

The current public release is v0.1.1. Treat it as an inspectable early release, not evidence of long-term maintenance, adoption, or production use.

Complementary index reconciler

Verified behavior

System behavior and guardrails

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

Implementation log

Design, operation, and verification notes

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