lakebase_vector

擴充 lakebase_vector 功能透過索引類型為 Lakebase lakebase_ann 新增了近似最近鄰（ANN）向量搜尋功能。 它是 pgvector 的可直接補充：相同的向量類型、距離運算子和查詢語法都能使用，且不需修改。

Install

首先，在專案設定 中啟用 Lakebase Search 。 然後安裝擴充功能：

CREATE EXTENSION IF NOT EXISTS lakebase_vector CASCADE;

關鍵字 CASCADE 會 pgvector 自動安裝為相依項目。

升級擴充與索引

新的 Lakebase Search 版本可以新增功能、修正與效能提升。 雖然 Lakebase Search 是作為 Lakebase 更新的一部分釋出，但它並非自動升級所有資料。 在 lakebase_vector中，有兩個東西分別升級，並攜帶彼此無關的版本號：

• 擴充版本 是建立 SQL 物件 CREATE EXTENSION lakebase_vector 的版本，包括資料型別、函式、運算子及 lakebase_ann 索引存取方法。 此版本由 SELECT installed_version FROM pg_available_extensions WHERE name = 'lakebase_vector'。 ALTER EXTENSION lakebase_vector UPDATE 更新本版本。
• 索引儲存格式 是索引在磁碟上的佈局 lakebase_ann 。 擴充功能可能會在更新中引入更新的索引儲存格式，解鎖更多功能並帶來更佳的效能。 所有新建立的索引會自動使用最新的儲存格式，而現有索引則可在有新儲存格式可用後升級為新格式 REINDEX INDEX CONCURRENTLY 。

升級並不急迫。 這個擴充功能相容於舊版本的 SQL 物件和索引儲存格式，但保持最新能讓你走在支援且效能最佳的路徑上，避免日後大規模遷移，因此方便時升級，而非無限期拖延。

Note

最新可用的擴充套件版本由 報告。SELECT default_version FROM pg_available_extensions WHERE name = 'lakebase_vector'

最新的儲存格式版本為 _2。 以下查詢會找到所有使用舊儲存格式的索引。 接著你可以用或REINDEX INDEX CONCURRENTLY：重建到最新的儲存格式REINDEX INDEX：

SELECT oid::regclass AS index, lakebase_ann_index_info(oid::regclass)::json ->> 'version' AS storage_format_version
FROM pg_class
WHERE relam = (SELECT oid FROM pg_am WHERE amname = 'lakebase_ann') AND relkind = 'i';

Note

REINDEX INDEX CONCURRENTLY 允許讀取和寫入繼續，但會花比較多時間。

快速入門

-- 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 items_embedding_idx 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;

從同步資料表填充

如果你是從 Unity Catalog 載入嵌入，而不是直接插入， 同步表格 可以在同步時將 lakehouse 嵌入欄位直接映射到 Postgres vector 欄位，而不是預設 JSONB 的映射。 請參閱 湖底搜尋的自訂類型映射。

設定索引

在索引建立時設定 build_mode 以控制準確度與速度的權衡：

• standard （預設）：平衡召回與索引建立時間。 大多數工作負載都用。
• quality：提升回憶能力，但累積時間較長。

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

fast建置模式仍支援向下相容。

預設情況下， lakebase_ann 會根據表格的統計數據和索引的配置選擇清單。 設定 lists 為明確控制分割區佈局：

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

Index 建置時間

較大的可以 shared_buffers 大幅縮短指數建立時間。 Lakebase 僅在 較大的固定大小計算上實現此優化。 在優化索引建構前，先檢查目前的數值：

SHOW shared_buffers;

如果 shared_buffers 1 GB 或更少，建議在開始索引建置前暫時調整為較大的固定大小運算。

你也可以透過增加平行工作者的數量來加快索引的建立。

配置參數 max_parallel_maintenance_workers 設定可由單一工具指令（如 CREATE INDEX）啟動的最大平行工作者數量。

max_parallel_workers配置參數設定計算能支援平行運算的最大工作者數量。 超過此限制的數值 max_parallel_maintenance_workers 則無影響。

max_worker_processes組態參數設定計算器可支援的最大背景程序數量。 Lakebase 是根據運算大小來管理這個設定的。 超過此限制的數值 max_parallel_workers 則無影響。

SHOW max_worker_processes;
-- Set both values to the desired parallelism minus one.
SET max_parallel_workers = 15;
SET max_parallel_maintenance_workers = 15;

同時進行建置索引

CREATE INDEX CONCURRENTLY 並 REINDEX INDEX CONCURRENTLY 允許在建立或重建索引時繼續讀取與寫入：

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

REINDEX INDEX CONCURRENTLY items_embedding_idx_concurrent;

調音搜尋準確度

調整前，先呼叫lakebase_ann_index_info(index_name)取得索引、 listsdefault_probes、 default_epsilon 和 數值。

在查詢時使用 lakebase_ann.probes 來控制搜尋的 IVF 分割區數量。 較高的值能提升回憶性，但代價是查詢速度下降。 預設值為 'auto'。 測試不同的數值以達到你的回憶目標。

的 probes 形狀必須與 的 lists形狀相符。 呼叫 lakebase_ann_index_info 以找到你的 lists 陣列，然後為一級索引設定一個值，或為兩級索引設兩個逗號分隔值：

lists 資料來源：索引資訊	probes 設定
[] （空的）	''
[222]	'22'
[3333, 33333]	'33, 333'

Note

在小型資料集中，使用 lakebase_ann 精確（平面）搜尋取代 IVF 分割，回 lakebase_ann_index_info 傳空值 lists 與 default_probes。 此時，讓 probes 為 ''。 當 lists 不空時， probes 形狀不符 lists 的值會產生錯誤。

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

-- 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 控制有多少候選人會被重新排序，使用全精度距離。 數值越高，候選人重新排序越多，所需時間越長。 預設值 對 'auto' 大多數工作負載來說運作良好。 在小型資料集的平面搜尋中，仍 epsilon 能控制全精度重新排序。

預濾波器

預設情況下，Postgres 會在 ANN 索引回傳候選列後套用非向量濾鏡條件。 允許 lakebase_ann.prefilter 在全精度距離重新排序前評估這些條件：

SET lakebase_ann.prefilter TO on;

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

預過濾最好是在篩選器便宜且能去除大部分資料列時。 對於匹配多列或需要昂貴計算的過濾器，則不關閉，因為在索引內評估過濾器會增加開銷。

指數預熱

計算開始後，將 lakebase_ann_prewarm 索引中經常存取的部分載入記憶體。 該 scope 參數接受以下值：

• search （預設值）：預熱用於搜尋的全部熱區。
• routing：只預熱路由結構。 此選項較快，且對大型指數提供更佳的成本效益取捨。

-- Prewarm the full search scope
SELECT lakebase_ann_prewarm('items_embedding_idx');

-- Prewarm only routing structures
SELECT lakebase_ann_prewarm('items_embedding_idx', scope => 'routing');

運算子類別

距離度量	操作員類別	查詢運算子
L2（歐幾里得）	vector_l2_ops	<->
負內積	vector_ip_ops	<#>
餘弦相似性	vector_cosine_ops	<=>

選擇與你嵌入訓練方式相符的運算子類別，並使用相同的指標作為索引和查詢：

• vector_cosine_ops （<=>） 是餘弦相似度。 大多數文字嵌入都用它。 這是最常見的選擇。
• vector_l2_ops （<->） 是歐幾里得（L2）距離。 當絕對空間距離很重要且向量未正規化時，才會用它。
• vector_ip_ops （<#>） 是負內積。 當向量預正規化為單位長度時使用。 對於單位向量，內積等於餘弦相似度，通常速度更快。

索引選項參考

Option	類型	預設	Description
build_mode	字串	'standard'	控制準確度與速度的權衡。 'quality'為了更好的記憶，但代價是要花更長的指數建造。 'fast' 仍支援向下相容。
lists	字串	'auto'	設定試管嬰兒的分割區佈局。 當 'auto'，擴展則根據表格的統計量和索引的配置選擇一個值。 為單一整數，如 '1000' 一級索引，或兩個遞增逗號分隔整數，如 '100, 1000' 兩級索引。

GUC 參考

參數	類型	預設	Description
lakebase_ann.probes	字串	'auto'	每個層級要掃描多少個試管嬰兒分區。 較高的值能提升回憶性，但代價是查詢速度下降。 該形狀必須與 中的lakebase_ann_index_info陣列相符lists。
lakebase_ann.epsilon	字串	'auto'	控制有多少候選人會被重新排序，使用全精度距離。 數值越高，候選人重新排序越多，所需時間越長。
lakebase_ann.prefilter	列舉	off	在全精度距離重新排序前，評估非向量濾波器。 有效值為 on 和 off。 最適合用便宜的濾波器，能去除大部分候選列。

公用程式函數

功能	Returns	Description
lakebase_ann_prewarm(regclass, scope text DEFAULT 'search')	無效	將頻繁存取的索引資料載入記憶體。 有效的 scope 值為 search 和 routing。
lakebase_ann_index_info(regclass)	收發簡訊	回傳索引元資料以 JSON 文字呈現，包括 version、 lists、 default_probes和 default_epsilon。

下一步

• lakebase_text
• 湖底搜尋