![\"Build\"](\"https://github.com/timescale/pg_vectorsearch/actions/workflows/build.yml/badge.svg?branch=main&event=push\"){kind=icon}
A PostgreSQL extension for high-performance approximate nearest neighbor (ANN) search.
\n\n\nStatus: alpha. Meant for testing, not production. Upgrading between prereleases may not be possible; plan to drop and recreate the extension and its indexes. See the changelog for known issues.
\n
prism_rebalance (see Maintenance)vector and halfvec columns as-is (see Existing pgvector tables)![\"PRISM\"](\"https://github.com/timescale/pg_vectorsearch/blob/main/images/prism-logo.jpg\"){kind=logo}
PRISM (Partitioned Routing Index for Similarity Matching) is a PostgreSQL-native index access method that is conceptually similar to pgvector's IVFFlat, but it is built around state-of-the-art quantization, routing, and partitioning techniques. It is implemented in C for high performance and seamless integration with PostgreSQL.
\nThe result: an index that is significantly faster than pgvector's IVFFlat and HNSW, for both querying and index building. In fact, compared to graph-based HNSW, PRISM is faster at equivalent recall on a 100-million-vector dataset, on an instance with a quarter of the memory.
\nTo achieve this performance, PRISM uses a hierarchical centroid tree to partition vectors into clusters, and relies on the PostgreSQL buffer cache to keep that tree warm in memory. Vectors are RaBitQ-quantized and stored in posting lists with a page layout optimized for SIMD distance computation. The RaBitQ encoding carries error bounds that let a search rule out vectors that cannot possibly be nearest neighbors, so far fewer of them need reranking against the full-precision vectors stored in the table.
\nQuery Flow:\n1. Traverse centroid tree to find nearest clusters (buffer cache)\n2. Scan posting lists for candidates (buffer cache, async I/O)\n3. RaBitQ two-stage filtering: estimate → error bound → rerank\n4. Full-precision reranking from heap\n5. Return k nearest neighbors\nFor detailed architecture, see docs/architecture.md.
\nInstall the extension first; see Building.
\nThere are two ways to use a PRISM index. Pick the one that matches where your vectors live:
\npg_vectorsearch's own vec32 (float32) or vec16 (float16) columns. No other extension is needed.vector or halfvec columns? Install pg_vectorsearch next to pgvector and build a PRISM index on those columns as they are. Your table and queries stay unchanged.Both paths build the same index and use the same operators (<->, <#>, <=>) and tuning knobs.
CREATE EXTENSION pg_vectorsearch;\n\n-- PLAIN keeps the vector inline. EXTERNAL (the default) toasts a value\n-- over ~2 kB, and rerank then pays an extra fetch the planner does not cost.\n (\n id serial PRIMARY KEY,\n embedding vec32(3) STORAGE PLAIN\n);\n\n-- Load first; the index is sized from the row count at CREATE INDEX.\n-- 500 rows is enough for the planner to use the index.\nINSERT INTO items (embedding)\nSELECT ARRAY[i::real, (i % 7)::real, (i % 5)::real]::vec32\nFROM generate_series(1, 1000) i;\n\n-- For inner product or cosine, see Operator classes below.\n items USING prism (embedding vec32_l2_ops);\n\n-- 0 = auto (~0.95 recall). Raise for recall, lower for speed.\nSET prism.nprobe = 40;\n\nSELECT * FROM items\nORDER BY embedding <-> '[3,1,2]'\nLIMIT 5;\nUse vec16 instead of vec32 to halve the space vectors take in the table, with the matching vec16_* operator classes.
If you already have a table with pgvector's vector or halfvec columns, you can build a PRISM index on it directly. Nothing about the table or your queries needs to change. vec32 and vec16 are binary-compatible with pgvector's vector and halfvec but have different names, so the two extensions can be installed side by side, even in the same schema.
-- The table you already have, included so the example runs on its own.\nCREATE EXTENSION vector;\n\n (\n id bigserial PRIMARY KEY,\n body text,\n embedding vector(384)\n);\n\n ON documents USING hnsw (embedding vector_l2_ops);\n\n-- Install pg_vectorsearch next to pgvector and build the index on the\n-- existing column. The column is not rewritten or copied.\nCREATE EXTENSION pg_vectorsearch;\n\n\n ON documents USING prism (embedding vec32_l2_ops);\n\n-- Your queries keep working as before. PRISM is normally faster, so\n-- the planner should prefer it over the HNSW index while both exist.\n-- Verify with an EXPLAIN:\nEXPLAIN (COSTS OFF)\nSELECT id, body\nFROM documents\nORDER BY embedding <-> (SELECT embedding FROM documents WHERE id = 42)\nLIMIT 10;\n-- Limit\n-- InitPlan 1\n-- -> Index Scan using documents_pkey on documents documents_1\n-- Index Cond: (id = 42)\n-- -> Index Scan using documents_embedding_prism on documents\n-- Order By: (embedding <-> (InitPlan 1).col1)\n\n-- Once you are happy with it, drop the HNSW index.\n documents_embedding_hnsw;\nUse the PRISM operator class for the same distance metric as your HNSW index.
\nPick the operator class for your distance metric and column type. L2 is the default.
\n| Distance | \nOperator | \nvec32 / vector | \nvec16 / halfvec | \n
|---|---|---|---|
| L2 | \n<-> | \nvec32_l2_ops | \nvec16_l2_ops | \n
| Inner product | \n<#> | \nvec32_ip_ops | \nvec16_ip_ops | \n
| Cosine | \n<=> | \nvec32_cosine_ops | \nvec16_cosine_ops | \n
When replacing an HNSW index, pgvector's vector_<metric>_ops maps to vec32_<metric>_ops and halfvec_<metric>_ops to vec16_<metric>_ops.
Defaults are tuned from large-scale benchmarks; most deployments only ever adjust prism.nprobe. See the tuning guide for every index parameter and GUC, their tradeoffs, and when changing them makes sense.
An insert appends to whichever posting list its vector routes to, so lists grow as rows arrive and never split on their own. Besides REINDEX, the prism_rebalance procedure splits oversized lists in place. See the maintenance guide for how it works and its current limitations.
Requirements:
\n# Release build\n\n\n# Build and install to PostgreSQL\n\nSee the development guide for build options.
\n