IVFFlat vs HNSW Indexes

pgvector offers IVFFlat (inverted file with coarse quantization) and HNSW (hierarchical navigable small world) for approximate nearest neighbor search. Choose based on recall targets, RAM budget, and build-time tolerance.

Recipe

-- IVFFlat: cluster lists, probe at query time
CREATE INDEX ON documents
  USING ivfflat (embedding extensions.vector_cosine_ops)
  WITH (lists = 100);
 
SET ivfflat.probes = 10;
 
-- HNSW: graph index (pgvector 0.5+, default choice for many workloads)
CREATE INDEX ON documents
  USING hnsw (embedding extensions.vector_cosine_ops)
  WITH (m = 16, ef_construction = 64);
 
SET hnsw.ef_search = 40;

When to reach for this: Table exceeds ~50k vectors and exact ORDER BY distance LIMIT k misses latency SLO.

Working Example

-- Benchmark recall vs latency (run in staging with labeled query set)
EXPLAIN (ANALYZE, BUFFERS)
SELECT id, embedding <=> $1 AS dist
FROM documents
ORDER BY embedding <=> $1
LIMIT 10;
 
-- Compare index scans
DROP INDEX IF EXISTS documents_ivfflat_idx;
CREATE INDEX documents_ivfflat_idx ON documents
  USING ivfflat (embedding extensions.vector_cosine_ops) WITH (lists = 200);
 
DROP INDEX IF EXISTS documents_hnsw_idx;
CREATE INDEX documents_hnsw_idx ON documents
  USING hnsw (embedding extensions.vector_cosine_ops)
  WITH (m = 16, ef_construction = 128);
 
-- Measure: p50/p95 latency, recall@10 vs brute force on sample queries

What this demonstrates:

• IVFFlat needs lists tuning and ivfflat.probes at query time
• HNSW exposes m, ef_construction at build and hnsw.ef_search at query
• EXPLAIN ANALYZE confirms index scan vs seq scan
• Recall measurement requires brute-force gold standard on held-out queries

Deep Dive

IVFFlat

Build: k-means clusters (lists centroids). Each vector assigned to nearest list.

Query: Search probes nearest lists, then exact distance within those lists.

Pros: Lower memory than HNSW for some shapes; mature on older pgvector.

Cons: Recall sensitive to data distribution; needs REINDEX after large data shifts; lists should scale with sqrt(rows) rule of thumb.

-- lists heuristic for N rows: sqrt(N) to N/1000
-- 1M rows: lists between 1000 and 10000 depending on benchmarks

HNSW

Build: Layered graph connecting neighbors.

Pros: Strong recall/latency default for pgvector 0.8+; less sensitive to insert order than IVFFlat.

Cons: Higher RAM during build; index larger on disk; vacuum interactions need monitoring at scale.

Decision Matrix

Index Maintenance

-- After bulk embed import
REINDEX INDEX CONCURRENTLY documents_hnsw_idx;
ANALYZE documents;
 
-- Monitor invalid indexes
SELECT indexrelid::regclass FROM pg_index WHERE NOT indisvalid;

Gotchas

• IVFFlat before data loaded - Empty table build yields useless centroids. Fix: Build index after bulk load or use REINDEX after import completes.
• lists = 1 - Absurd recall. Fix: Start sqrt(n) and sweep probes in benchmark script.
• ef_search too low - HNSW misses neighbors. Fix: Raise hnsw.ef_search until recall@k plateaus on golden set.
• Opclass mismatch - Still the top pgvector footgun. Fix: vector_cosine_ops with <=>.
• CONCURRENTLY build failure - Invalid HNSW left behind. Fix: Drop invalid index; reduce maintenance_work_mem spikes or build off-peak without CONCURRENTLY on empty clone.
• Comparing apples to oranges - Different k, different metrics. Fix: Fixed k=10, same 100 queries, same distance operator for all runs.

Alternatives

FAQs

Related

• pgvector Basics - operators and types
• pgvector at Scale - memory and vacuum
• RAG Storage Schema - schema layout
• REINDEX CONCURRENTLY - online rebuild
• pgvector Best Practices - do not trust defaults

Stack versions: This page was written for PostgreSQL 18.4 (stable 18, maintenance 17), pgvector 0.8+, PostGIS 3.5+, pgbouncer 1.x, and Patroni 3.x.