Creating an HNSW Index and Reading the Plan

One statement, new plan

CREATE INDEX ... USING hnsw (embedding vector_l2_ops) WITH (m = 16, ef_construction = 64) builds an HNSW graph index. The operator class must match your query operator: vector_l2_ops for <->, vector_cosine_ops for <=>, vector_ip_ops for <#>. Build parameters: m (links per node: more means better recall and a bigger index) and ef_construction (candidates examined while building: higher means a better graph and a slower build). After ANALYZE, EXPLAIN shows an Index Scan using ... with Order By, meaning the planner will use the ANN index. Build indexes after bulk loading (it is faster), allow time and memory for the build (maintenance_work_mem matters), and remember that an index returns approximate results.

Build the index and check the plan, run

I ran this SQL on PostgreSQL 16 with the pgvector extension, version 0.8.6, in a Docker container. After CREATE INDEX and ANALYZE, the same query is planned as an Index Scan using big_hnsw ... Order By (embedding <-> ...) instead of a sequential scan and sort.

CREATE INDEX big_hnsw ON big USING hnsw (embedding vector_l2_ops) WITH (m = 16, ef_construction = 64);
ANALYZE big;
EXPLAIN (COSTS OFF)
SELECT id FROM big ORDER BY embedding <-> (SELECT embedding FROM big WHERE id = 1) LIMIT 10;

Output:

                   QUERY PLAN                   
------------------------------------------------
 Limit
   InitPlan 1 (returns $0)
     ->  Index Scan using big_pkey on big big_1
           Index Cond: (id = 1)
   ->  Index Scan using big_hnsw on big
         Order By: (embedding <-> $0)
(6 rows)

Match the operator class

An index built with vector_cosine_ops is not used by an <-> query. If EXPLAIN shows a sequential scan, check this first.

Quick check: How do you confirm that PostgreSQL uses the HNSW index?

• EXPLAIN shows Index Scan using the index
• The table gets smaller
• The row count changes
• By restarting the server