lakebase_vector
This feature is in Beta. Workspace admins can control access to this feature from the Previews page. See Manage Databricks previews.
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:
|
|
|---|---|
|
|
|
|
|
|
On a small dataset, lakebase_ann uses exact (flat) search instead of IVF partitioning, and lakebase_ann_index_info returns empty lists and default_probes. In this case, leave probes set to ''. When lists is not empty, a probes value whose shape does not match lists causes an error.
-- 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
Distance metric | Operator class | Query operator |
|---|---|---|
L2 (Euclidean) |
|
|
Negative inner product |
|
|
Cosine similarity |
|
|
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
Option | Type | Default | Description |
|---|---|---|---|
| string |
| Controls the accuracy/speed tradeoff. Use |
| string |
| Sets the IVF partition layout. With |
GUC reference
Parameter | Type | Default | Description |
|---|---|---|---|
| string |
| Number of IVF partitions to scan at each level. Higher values improve recall at the cost of query speed. The shape must match the |
| string |
| Controls how many candidates are reranked using full-precision distances. Higher values rerank more candidates and take longer. |
| enum |
| Evaluates non-vector filters before full-precision distance reranking. Valid values are |
Utility functions
Function | Returns | Description |
|---|---|---|
| void | Loads an index into memory to eliminate cold-start latency on the first query. |
| text | Returns index metadata as text, including |