halfvec, binary quantization & big embeddings

The options at a glance#

halfvec: half the bytes, almost all the recall#

A halfvec stores each element as a 16-bit float — about three significant digits, range ±65,504. Normalised embeddings sit far inside that range, so the rounding barely moves distances. You can either store halfvec columns, or keep full precision in the table and index a cast:

demo=# CREATE INDEX ON items USING hnsw ((embedding::halfvec(64)) halfvec_cosine_ops);
CREATE INDEX

demo=# EXPLAIN (COSTS OFF) SELECT id FROM items ORDER BY embedding::halfvec(64) <=> (SELECT embedding FROM items WHERE id = 1)::halfvec(64) LIMIT 10;
                                    QUERY PLAN                                     
-----------------------------------------------------------------------------------
 Limit
   InitPlan 1
     ->  Index Scan using items_pkey on items items_1
           Index Cond: (id = 1)
   ->  Index Scan using items_embedding_idx3 on items
         Order By: ((embedding)::halfvec(64) <=> ((InitPlan 1).col1)::halfvec(64))
(6 rows)

Recall and latency for the two were the same within noise: the expression index scored 0.949 at ef_search = 40 (3.0 ms median). The halfvec index also built faster — 2.9 min versus 3.4 min — because two elements fit on each 8 KB page instead of one.

Indexing more than 2,000 dimensions#

OpenAI's text-embedding-3-large returns 3,072 dimensions by default, and pgvector refuses to index it as vector:

column cannot have more than 2000 dimensions for hnsw index
column cannot have more than 2000 dimensions for ivfflat index

A halfvec expression index works up to 4,000 dimensions. On 99,000 3,072-dim DBpedia vectors:

Index: 773 MB, built in 5.4 min. Exact search over the same table took 716 ms per query. Above 4,000 dimensions you'll see column cannot have more than 4000 dimensions for hnsw index — use binary quantization or reduce dimensions.

Binary quantization with re-ranking#

binary_quantize() keeps one bit per dimension — 1 if the element is positive. Hamming distance between those bit strings roughly tracks angular distance, so a bit index can shortlist candidates cheaply; the full vectors, still in the table, then put them in the right order:

demo=# CREATE INDEX ON items USING hnsw ((binary_quantize(embedding)::bit(64)) bit_hamming_ops);
CREATE INDEX

demo=# EXPLAIN (COSTS OFF)
demo-# SELECT id FROM (
demo-#   SELECT id, embedding FROM items
demo-#   ORDER BY binary_quantize(embedding)::bit(64) <~> binary_quantize((SELECT embedding FROM items WHERE id = 1))
demo-#   LIMIT 40
demo-# ) candidates
demo-# ORDER BY embedding <=> (SELECT embedding FROM items WHERE id = 1)
demo-# LIMIT 10;
                                                     QUERY PLAN                                                     
--------------------------------------------------------------------------------------------------------------------
 Limit
   InitPlan 1
     ->  Index Scan using items_pkey on items items_1
           Index Cond: (id = 1)
   ->  Sort
         Sort Key: ((candidates.embedding <=> (InitPlan 1).col1))
         ->  Subquery Scan on candidates
               ->  Limit
                     InitPlan 2
                       ->  Index Scan using items_pkey on items items_2
                             Index Cond: (id = 1)
                     ->  Index Scan using items_binary_quantize_idx on items
                           Order By: ((binary_quantize(embedding))::bit(64) <~> binary_quantize((InitPlan 2).col1))
(13 rows)

On its own the bit index scored 0.699 at 1,536 dims — useful only as a filter. Re-ranking 160 candidates gave 0.985 in 5.7 ms; 640 candidates gave 0.997 in 20 ms. At 3,072 dims the extra bits helped only slightly — 0.930 vs 0.918 with 40 candidates, and about the same (0.986) at 160.

• Index size: 48 MB for 100K × 1,536 — 16× smaller than the vector index. Build: 39 s.
• The catch: re-ranking reads full vectors from the table, so the table (or at least the hot part) should still be cached.
• Set hnsw.ef_search ≥ the candidate count or the inner query returns fewer candidates than its LIMIT.

Shortening embeddings#

OpenAI's v3 models are trained so that the first k dimensions form a usable embedding on their own (request them with the dimensions parameter, or truncate and re-normalise). How much does that lose? We truncated the 3,072-dim vectors, re-normalised them, ran exact search, and compared the top-10 with exact search on the full vectors:

This measures agreement with the full model, not retrieval quality on a labelled task — but it tells you how much ranking changes. We also checked that truncating the 3,072-dim output to 1,536 and re-normalising matches what the API returns when you request 1,536 dimensions: across 2,000 articles the cosine similarity between the two averaged 0.99999 (minimum 0.997) — effectively the same vectors.

You can also keep full vectors and index only a prefix with subvector(), re-ranking with the full vector (pattern).

Which to use#

Size your options with the storage calculator, or let the index planner choose.

Frequently asked questions