lakebase_vector

lakebase_vector拡張機能は、lakebase_ann インデックスの種類を使用して、ほぼ最近隣 (ANN) ベクター検索を Lakebase に追加します。 これは pgvector のドロップイン コンパニオンです。同じベクター型、距離演算子、およびクエリ構文は変更なしで機能します。

Install

まず、プロジェクト設定で Lakebase Search を有効にします 。 次に、拡張機能をインストールします。

CREATE EXTENSION IF NOT EXISTS lakebase_vector CASCADE;

CASCADE キーワードは、依存関係としてpgvectorを自動的にインストールします。

拡張とインデックスのアップグレード

新しいLakebase Searchリリースは、機能、修正、パフォーマンス向上を追加できます。 Lakebase SearchはLakebaseのアップデートの一部としてリリースされていますが、すべてを自動的にアップグレードするわけではありません。 lakebase_vectorでは、2つのものが別々にアップグレードし、互いに無関係なバージョン番号を持ちます。

• 拡張バージョン とは、 CREATE EXTENSION lakebase_vector 作成するSQLオブジェクトのバージョンであり、そのデータ型、関数、演算子、 lakebase_ann インデックスアクセスメソッドが含まれます。 このバージョンは、 SELECT installed_version FROM pg_available_extensions WHERE name = 'lakebase_vector'によって報告されています。 ALTER EXTENSION lakebase_vector UPDATE このバージョンを更新します。
• インデックス保存形式は 、 lakebase_ann インデックスのディスク上レイアウトです。 この拡張機能はアップデートでインデックス保存フォーマットの更新を導入し、より多くの機能を解放し、より良いパフォーマンスを提供する可能性があります。 新たに作成されたすべてのインデックスは自動的に最新のストレージフォーマットを使用し、既存のインデックスは新しいストレージフォーマットが利用可能になった後に REINDEX INDEX CONCURRENTLY を使って新しいフォーマットにアップグレードできます。

アップグレードは急ぎではありません。 この拡張機能は古いバージョンのSQLオブジェクトやインデックスストレージ形式に対応していますが、最新を維持しておくことでサポートされた最良の性能の道を保ち、後々の大規模な移行を避けられます。したがって、無期限に先延ばしにするよりも、便利なタイミングでアップグレードしてください。

最新のストレージフォーマットは _2です。 以下のクエリは、古いストレージ形式を使用しているすべてのインデックスを見つけます。 その後、 REINDEX INDEX や REINDEX INDEX CONCURRENTLYで最新のストレージ形式に再構築できます:

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

簡単スタート

-- 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');

インデックスのビルド時間

大きな shared_buffers はインデックスのビルド時間を大幅に短縮できます。 Lakebaseは 、より大きな固定サイズの計算でのみこの最適化を可能にします。 インデックスビルドを最適化する前に現在の値を必ず確認してください:

SHOW shared_buffers;

shared_buffersが1GB以下であれば、インデックスビルドを始める前に一時的に固定サイズの計算にリサイズすることを検討してください。

また、並列作業者の数を増やすことでインデックス作成を加速することもできます。

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) を呼び出して、インデックスの lists、 default_probes、および default_epsilon 値を取得します。

クエリ時に lakebase_ann.probes を使って、検索するIVFパーティションの数を制御します。 値を大きくすると、クエリ速度を犠牲にして再現率が向上します。 既定値は 'auto' です。 想起目標を達成するために異なる値を試してください。

probesの形はlistsの形に合わなければなりません。 lakebase_ann_index_infoを呼び出してlists配列を見つけ、1レベルインデックスには1つの値、2レベルインデックスにはカンマ区切られた2つの値を設定します。

-- 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');

演算子クラス

埋め込みのトレーニング方法に一致する演算子クラスを選択し、インデックスとクエリに同じメトリックを使用します。

• vector_cosine_ops (<=>)はコサイン類似性である。 ほとんどのテキスト埋め込みで使用します。 これが最も一般的な選択肢です。
• vector_l2_ops (<->) はユークリッド (L2) 距離です。 絶対空間距離が重要であり、ベクトルが正規化されていない場合に使用します。
• vector_ip_ops (<#>)は負の内部積である。 ベクトルが単位長に事前に正規化されている場合に使用します。 単位ベクトルの場合、内部積はコサインの類似性に等しく、通常は高速です。

インデックス オプションリファレンス

GUC リファレンス

ユーティリティ関数

次のステップ

• lakebase_text
• レイクベース・サーチ