ILIndexLane Send the issue

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.

GoPostgreSQLpgvectorHNSWDockerEXPLAIN JSON
Inspect sourceView v0.1.0 release

What this proves

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

Project scope

pgvector-filterbench

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.

Version 0.1.0 · Apache-2.0 · Go

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

Complementary index reconciler

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.

Need a related technical system or diagnostic path?

Discuss a related search or database diagnosticBack to built systems