IVFFlat indexes in pgvector

How IVFFlat works#

At build time, k-means picks lists centre points from the data and assigns every vector to its nearest centre. A query compares itself with all centres, then scans every vector in the probes nearest lists. Vectors near a cell boundary are the problem: their true neighbours may sit in the next cell over.

Real k-means and IVF search on 500 random 2-D points, in your browser. Drag the query to a cell boundary with probes = 1 and watch true neighbours go missing.

Creating the index#

demo=# CREATE INDEX ON items USING ivfflat (embedding vector_cosine_ops) WITH (lists = 100);
CREATE INDEX

demo=# SET ivfflat.probes = 10;
SET

Unlike HNSW, IVFFlat learns from the rows present at build time. Built on an empty table, it warns — and recall collapses as rows arrive:

demo=# CREATE TABLE empty_items (id bigserial PRIMARY KEY, embedding vector(3));
CREATE TABLE

demo=# CREATE INDEX ON empty_items USING ivfflat (embedding vector_l2_ops) WITH (lists = 100);
NOTICE:  ivfflat index created with little data
DETAIL:  This will cause low recall.
HINT:  Drop the index until the table has more data.
CREATE INDEX

probes: the recall knob#

Each line is a different lists value on the same 100,000 rows. At probes = 1, more lists means fewer vectors per list and worse recall. As probes rises, every configuration converges; what changes is how much work it takes. Setting it is the same as for HNSW:

SET ivfflat.probes = 16;          -- session
SET LOCAL ivfflat.probes = 32;    -- one transaction

Choosing lists#

We built three indexes at each size — rows / 1000, √rows, and one deliberately large — and swept probes:

Read the curves by latency, not by probe count. More lists need more probes for the same recall, but each probe scans a smaller list, so per millisecond the larger lists values came out ahead at both sizes: at 500K rows, 2,000 lists reached 0.942 in 32 ms while 500 lists took 56 ms for 0.951. What you pay is build time — k-means over more centres — 8.5 min versus 1.7 min. The rows / 1000 rule is a reasonable middle; go higher if query latency matters more than rebuild time.

IVFFlat vs HNSW#

Choose IVFFlat for large, mostly static tables where build time or build memory is the binding constraint and you can rebuild periodically. Choose HNSW otherwise. Don't choose IVFFlat to save disk: for full-size embeddings it isn't smaller — use halfvec for that.

Iterative scans#

Since 0.8.0, IVFFlat can keep probing additional lists until a filtered query has enough rows: SET ivfflat.iterative_scan = relaxed_order; (capped by ivfflat.max_probes). Only relaxed_order is supported for IVFFlat. Details and measurements in the filtering guide.

When to rebuild#

List centres are fixed at build time. If your data distribution shifts — a new product category, a new language, a different embedding model — recall degrades even though nothing errors. Rebuild with REINDEX INDEX CONCURRENTLY after large changes, and re-derive lists from the new row count.

Frequently asked questions