Notes

Tune pgvector HNSW for recall and filtered queries

Start with default graph settings, tune ef_search against exact results, and enable iterative scans for filtered queries. Build memory and graph construction settings solve different problems.

Start with HNSW’s default graph settings, then increase hnsw.ef_search until recall and latency meet your target. For selective filters, enable iterative scans so the executor can request more candidates. Rebuilding the graph should come after measuring query-time tuning, because larger graphs cost memory and slower writes as well as build time.

These examples follow pgvector 0.8.7, available in November 2026. Iterative scans require 0.8.0 or newer. Check the installed extension separately from the PostgreSQL server version:

SELECT extversion FROM pg_extension WHERE extname = 'vector';

Build a graph with an explicit metric

Use a scratch database for this example. A three-dimensional column keeps the SQL readable; production dimensions must match the embedding model.

CREATE EXTENSION IF NOT EXISTS vector;
CREATE TABLE hnsw_demo (
    id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
    category_id integer NOT NULL,
    embedding vector(3) NOT NULL
);
INSERT INTO hnsw_demo (category_id, embedding)
SELECT g % 10, ARRAY[random(), random(), random()]::vector
FROM generate_series(1, 10000) AS g;

SET maintenance_work_mem = '256MB';
CREATE INDEX hnsw_demo_cosine ON hnsw_demo
USING hnsw (embedding vector_cosine_ops)
WITH (m = 16, ef_construction = 64);
ANALYZE hnsw_demo;

m, default 16, limits the graph’s connections per layer. Increasing it can improve navigation but enlarges the graph. ef_construction, default 64, controls the candidate list during graph construction; a larger value can improve graph quality at the cost of build and insertion work. These are index settings, so changing them is different from tuning a query’s search budget.

maintenance_work_mem controls the memory available to build the graph. The 256 MB above is an example budget, not a universal recommendation. When the graph stops fitting, pgvector emits a notice and construction slows. Keep enough headroom for other database activity and concurrent maintenance.

Tune the query budget

BEGIN;
SET LOCAL hnsw.ef_search = 100;
SET LOCAL hnsw.iterative_scan = strict_order;
EXPLAIN (ANALYZE, BUFFERS)
SELECT id, embedding <=> '[1,0,0]'::vector AS distance
FROM hnsw_demo
WHERE category_id = 3
ORDER BY embedding <=> '[1,0,0]'::vector
LIMIT 10;
COMMIT;

ef_search defaults to 40. Increasing it explores more candidates, usually trading latency for recall. SET LOCAL limits the experiment to the transaction, which is especially helpful with pooled connections. strict_order maintains distance ordering among returned results; it does not turn approximate search into exact search.

Approximate-index filtering occurs after candidate retrieval. A category matching 10% of rows may leave only about four survivors from 40 candidates, though the actual distribution depends on the graph and data. Iterative scans continue searching until enough rows survive or a resource limit is reached. hnsw.max_scan_tuples and hnsw.scan_mem_multiplier bound further exploration and memory. relaxed_order permits less strict ordering in exchange for better search flexibility; re-sort its materialized results if the final output needs strict order.

Measure against exact results

For the same query set and snapshot, collect an exact baseline in a transaction with SET LOCAL enable_indexscan = off. Compare the overlap of the approximate and exact top ten: recall@10 is intersection size divided by ten when ten exact matches exist. Include selective and broad filters, and record latency percentiles alongside recall.

The planner may reasonably prefer a sequential scan for the tiny demo table. Inspect the plan before attributing its performance to HNSW. At production scale, consider a normal index on a selective filter, partial HNSW indexes for a few stable categories, or partitioning where the workload warrants it.

Go deeper into HNSW navigation and filtered serving.