lakebase_vector
lakebase_vector 拡張は lakebase_ann インデックスタイプを通じてLakebaseにapproximate nearest-neighbor (ANN) ベクトル検索を追加します。これはpgvectorのそのまま使えるコンパニオンです。同じベクトルタイプ、距離演算子、クエリー構文は修正なしで機能します。
インストール
まず、プロジェクト設定でLakebase Searchを有効にしてください。次に、拡張機能をインストールします。
CREATE EXTENSION IF NOT EXISTS lakebase_vector CASCADE;
CASCADE キーワードは、pgvector を依存関係として自動的にインストールします。
拡張機能とインデックスをアップグレードする
Lakebase Search の新しいリリースでは、機能、修正、およびパフォーマンスの向上の追加が行われます。Lakebase Search は Lakebase のアップデートの一部としてリリースされますが、すべてが自動的にアップグレードされるわけではありません。lakebase_vector では、次の 2 つの要素が個別にアップグレードされ、互いに関係のないバージョン番号が付けられます：
- 拡張機能のバージョン は、データ型、関数、演算子、および
lakebase_annインデックス アクセス メソッドを含め、CREATE EXTENSION lakebase_vectorが作成する SQL オブジェクトのバージョンです。このバージョンはSELECT installed_version FROM pg_available_extensions WHERE name = 'lakebase_vector'によって報告されます。ALTER EXTENSION lakebase_vector UPDATEはこのバージョンを更新します。 - インデックス ストレージ フォーマット は、
lakebase_annインデックスのディスク上のLayoutです。拡張機能により、アップデートで更新されたインデックス ストレージ フォーマットが導入され、より多くの機能が解放されてパフォーマンスが向上する場合があります。新しく作成されたすべてのインデックスは自動的に最新のストレージ フォーマットを使用します。一方、既存のインデックスは、新しいストレージ フォーマットが利用可能になった後、REINDEX INDEX CONCURRENTLYを使用して新しいフォーマットにアップグレードできます。
アップグレードは緊急ではありません。この拡張機能は、古いバージョンの SQL オブジェクトおよびインデックス ストレージ フォーマットと互換性がありますが、最新の状態を維持することで、サポートされている最適なパフォーマンスのパスが維持され、後で大規模な移行を行う必要がなくなるため、無期限に延期するのではなく、都合の良いときにアップグレードしてください。
利用可能な最新の拡張機能のバージョンは SELECT default_version FROM pg_available_extensions WHERE name = 'lakebase_vector' によって報告されます。
最新のストレージ フォーマットのバージョンは _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';
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 列に直接マッピングできます（default JSONB マッピングの代わり）。Lakebase Search のカスタム型マッピングを参照してください。
インデックスを設定
インデックス作成時に build_mode を設定して、精度と速度のトレードオフを制御します。
standard(default):再現率とインデックス構築時間のバランスをとります。ほとんどのワークロードで使用します。quality: 再現率を向上させますが、構築に大幅に時間がかかります。最大5,000万個のベクトルを持つテーブルにのみ使用してください。
CREATE INDEX ON items USING lakebase_ann (embedding vector_l2_ops)
WITH (build_mode = 'standard');
fastビルドモードは、後方互換性のために引き続きサポートされています。
By default、lakebase_ann はテーブルの統計情報とインデックスの構成に基づいてリストを選択します。パーティション"Layout"を明示的に制御するには、lists を設定します：
CREATE INDEX ON items USING lakebase_ann (embedding vector_l2_ops)
WITH (lists = '1000');
インデックス構築時間
より大きな 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)を呼び出してインデックスのlists、default_probes、default_epsilonの値を取得します。
クエリー時に lakebase_ann.probes を使用して、検索する反転ファイル (IVF) パーティションの数を制御します。値を大きくすると、レイテンシーを犠牲にしてリコールが改善します。default値 'auto' は、それらの間のバランスの取れたトレードオフを提供します。より詳細な制御を行うには、lakebase_ann_advise を使用して 推奨されるプローブ値を取得します。
probesの形状はlistsの形状と一致している必要があります。lakebase_ann_index_infoを呼び出してlists配列を見つけ、1レベルのインデックスには値を1つ、2レベルのインデックスにはコンマ区切りの値を2つ設定します。
|
|
|---|---|
|
|
|
|
|
|
小さなデータセットでは、lakebase_annはIVFパーティショニングの代わりに完全（フラット）検索を使用し、lakebase_ann_index_infoは空のlistsとdefault_probesを返します。この場合、probesは''に設定したままにしてください。listsが空でない場合、形状がlistsと一致しないprobes値はエラーの原因となります。
-- 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 フル精度の距離を使用して再ランク付けされる候補の数を制御します。値を大きくすると、より多くの候補が再ランク付けされ、時間がかかります。The default value of 'auto' works well for most workloads.小さなデータセットでのフラット検索中も、epsilon がフル精度の再ランク付けを制御します。
推奨されるプローブ値の取得
lakebase_ann_advise、lakebase_ann_tune、lakebase_ann_latency、lakebase_ann_sampleはlakebase_vector 1.1.2を必要とします以上。インストールされているバージョンを確認して拡張機能を更新する方法については、拡張機能とインデックスのアップグレードを参照してください。
lakebase_ann_advise 再現率の昇順で候補の probes 値を返します。0.5 から 0.9 までは 0.1 ステップ、0.91 から 0.99 までは 0.01 ステップです。各行には、推定再現率とウォームアップ後に測定されたクエリーレイテンシーが含まれます。検索ワークロードからの実際のクエリーを入力として使用します。それらが利用できない場合、lakebase_ann_sample を使用してインデックス付きテーブルからベクトルをサンプリングします。以下の例は、両方のオプションを示しています。
-- Option 1: real queries in a separate table
SELECT probes, recall, avg_ms, p50_ms, p95_ms
FROM lakebase_ann_advise(
'items_embedding_idx'::regclass,
ARRAY(
SELECT embedding FROM queries
WHERE embedding IS NOT NULL
LIMIT 512
)
);
-- Option 2: sampled from the indexed table
-- NULL::items specifies items as the table to sample from.
SELECT probes, recall, avg_ms, p50_ms, p95_ms
FROM lakebase_ann_advise(
'items_embedding_idx'::regclass,
ARRAY(
SELECT embedding FROM lakebase_ann_sample(NULL::items, 512)
WHERE embedding IS NOT NULL
)
);
列 | 説明 |
|---|---|
|
|
| サンプル クエリーの推定 recall@10。 |
| ミリ秒単位での単一クエリーの平均、中央値、および 95 パーセンタイルの待機時間。 |
リコールターゲットを満たす最速の行を選択し、その probes 値を適用します：
SET lakebase_ann.probes TO '10';
再現率とレイテンシーは、lakebase_ann.epsilonが1.9に設定された上位10個のクエリーに対して推定されており、実際のクエリーと異なる場合があります。本番運用で probes 値を使用する前に、可能であればワークロードでその再現率とレイテンシーを確認してください。
インデックスに空の lists がある場合、調整対象がないため lakebase_ann_advise は行を返しません。
大規模なインデックスでは、lakebase_ann_advise呼び出しに20分以上かかる場合があります。クエリーベクトルが多いほど、呼び出しは遅くなります。再現率と実行時間のバランスをとるには、512個のクエリーベクトルから始めます。
lakebase_ann_advise lakebase_ann_tuneを呼び出して推奨probes値を取得し、lakebase_ann_latencyを呼び出してそのレイテンシを測定します。lakebase_ann_tuneまたはlakebase_ann_latencyのいずれかを単独で使用することもできます。ユーティリティ関数を参照してください。
lakebase_ann_advise および lakebase_ann_tune では、インデックス付きテーブルでテーブルレベルの SELECTが必要であり、そのテーブルのロールに行レベルセキュリティ (RLS)が適用されている場合はエラーが返されます。lakebase_ann_sampleおよび lakebase_ann_latency はRLSポリシーを適用し、ロールが表示できる行のみを読み取ります。
プリフィルター
By default、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(default): 検索に使用されるホット部分全体を事前にウォーミングします。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_cosine_ops(<=>) はコサイン類似度です。ほとんどのテキスト埋め込みに使用してください。これは最も一般的な選択肢です。vector_l2_ops(<->) はユークリッド (L2) 距離です。絶対的な空間距離が重要であり、ベクトルが正規化されていない場合に使用してください。vector_ip_ops（<#>）は負の内積です。ベクトルが単位長に事前正規化されている場合に使用します。単位ベクトルでは、内積はコサイン類似度に等しく、通常、より高速です。
インデックス オプション リファレンス
オプション | Type | デフォルト | 説明 |
|---|---|---|---|
| string |
| 精度と速度のトレードオフを制御します。インデックスの構築にかなりの時間がかかりますが、リコールを向上させたい場合は |
| string |
| IVFパーティションのLayoutを設定します。 |
GUC参照
パラメーター | Type | デフォルト | 説明 |
|---|---|---|---|
| string |
| 各レベルでスキャンするIVFパーティションの数。値を大きくするとリコールは向上しますが、レイテンシが増加します。形状は |
| string |
| フル精度の距離を使用して再ランク付けされる候補の数を制御します。値を大きくすると、より多くの候補が再ランク付けされますが、時間がかかります。 |
| enum |
| フル精度の距離による再ランク付けの前に、非ベクトルフィルターを評価します。有効な値は |
ユーティリティ関数
関数 | 戻り値 | 説明 |
|---|---|---|
| 無効 | 頻繁にアクセスされるインデックスデータをメモリに読み込みます。有効な |
| TEXT |
|
|
| サンプルクエリーベクトルの |
|
| サンプルクエリーベクトルの |
|
|
|
|
|
|