lakebase_vector

The lakebase_vector extension adds approximate nearest-neighbor (ANN) vector search to Lakebase via the lakebase_ann index type. It is a drop-in companion to pgvector: the same vector types, distance operators, and query syntax work without modification.

Install

First, enable Lakebase Search in your project settings. Then install the extension:

CREATE EXTENSION IF NOT EXISTS lakebase_vector CASCADE;

The CASCADE keyword automatically installs pgvector as a dependency.

Quick start

-- Create a table with a vector column
CREATE TABLE items (id BIGSERIAL PRIMARY KEY, embedding VECTOR(3));

-- Insert sample data
INSERT INTO items (embedding)
SELECT ARRAY[random(), random(), random()]::real[]
FROM generate_series(1, 1000);

-- Create a lakebase_ann index
CREATE INDEX ON items USING lakebase_ann (embedding vector_l2_ops);

-- Query using standard pgvector distance operators
SELECT * FROM items ORDER BY embedding <-> '[3,1,2]' LIMIT 5;

Populate from synced tables

If you're loading embeddings from Unity Catalog rather than inserting them directly, synced tables can map a lakehouse embedding column straight to a Postgres vector column during sync, instead of the default JSONB mapping. See Custom type mapping for Lakebase Search.

Configure the index

Set build_mode at index creation to control the accuracy/speed tradeoff:

• standard (default): balances recall and index build time. Use for most workloads.
• quality: improves recall but takes longer to build.

CREATE INDEX ON items USING lakebase_ann (embedding vector_l2_ops)
WITH (build_mode = 'quality');

The fast build mode remains supported for backward compatibility.

By default, lakebase_ann chooses lists based on the statistics of the table and the configuration of the index. Set lists to control the partition layout explicitly:

CREATE INDEX ON items USING lakebase_ann (embedding vector_l2_ops)
WITH (lists = '1000');

Build indexes concurrently

Use CREATE INDEX CONCURRENTLY to build without locking the table, then REINDEX CONCURRENTLY to rebuild without downtime:

CREATE INDEX CONCURRENTLY items_embedding_ann ON items
  USING lakebase_ann (embedding vector_l2_ops);

REINDEX INDEX CONCURRENTLY items_embedding_ann;

Tune search accuracy

Before tuning, call lakebase_ann_index_info(index_name) to get the index's lists, default_probes, and default_epsilon values.

Use lakebase_ann.probes at query time to control how many IVF partitions are searched. Higher values improve recall at the cost of query speed. The default is 'auto'. Test different values to meet your recall target.

The shape of probes must match the shape of lists. Call lakebase_ann_index_info to find your lists array, then set one value for a one-level index or two comma-separated values for a two-level index:

-- Check your index's lists array first
SELECT lakebase_ann_index_info('items_embedding_ann');

-- Then set probes to match the shape of lists.
-- One-level index (single-value lists): set one value.
SET lakebase_ann.probes TO '10';

-- Two-level index: set two ascending comma-separated values, for example '10, 20'.
-- Flat index (empty lists): leave probes set to ''.

SELECT * FROM items ORDER BY embedding <-> '[3,1,2]' LIMIT 10;

lakebase_ann.epsilon controls how many candidates are reranked using full-precision distances. Higher values rerank more candidates and take longer. The default value of 'auto' works well for most workloads. During flat search on a small dataset, epsilon still controls full-precision reranking.

Prefilter

By default, Postgres applies non-vector filter conditions after the ANN index returns candidate rows. Enable lakebase_ann.prefilter to evaluate those conditions before full-precision distance reranking:

SET lakebase_ann.prefilter TO on;

SELECT * FROM items
WHERE id % 100 = 0
ORDER BY embedding <-> '[3,1,2]'
LIMIT 10;

Prefiltering works best when the filter is cheap to evaluate and removes most rows. Leave it off for filters that match many rows or require expensive calculations, since evaluating the filter inside the index can add overhead.

Operator classes

Choose the operator class that matches how your embeddings were trained, and use the same metric for the index and the query:

• vector_cosine_ops (<=>) is cosine similarity. Use it for most text embeddings. This is the most common choice.
• vector_l2_ops (<->) is Euclidean (L2) distance. Use it when absolute spatial distance matters and vectors are not normalized.
• vector_ip_ops (<#>) is negative inner product. Use it when vectors are pre-normalized to unit length. For unit vectors, inner product equals cosine similarity and is typically faster.

Index options reference

GUC reference

Utility functions

Next steps

• lakebase_text
• Lakebase Search