lakebase_vector

lakebase_vector 拡張は lakebase_ann インデックスタイプを通じてLakebaseにapproximate nearest-neighbor (ANN) ベクトル検索を追加します。これはpgvectorのそのまま使えるコンパニオンです。同じベクトルタイプ、距離演算子、クエリー構文は修正なしで機能します。

インストール

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

SQL

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 を使用して、最新のストレージ フォーマットに再構築できます。

SQL

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 読み取りと書き込みの継続を許可しますが、時間がかかります。

クイックスタート

SQL

-- 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：再現率を向上させますが、構築に時間がかかります。

SQL

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

fastビルドモードは、後方互換性のために引き続きサポートされています。

By default、lakebase_ann はテーブルの統計情報とインデックスの構成に基づいてリストを選択します。パーティション"Layout"を明示的に制御するには、lists を設定します：

SQL

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

インデックス構築時間

より大きな shared_buffers を使用すると、インデックスのビルド時間を大幅に短縮できます。Lakebaseは、大規模な固定サイズのコンピュート上でのみこの最適化を有効にします。インデックス構築を最適化する前に、現在の値を確認してください。

SQL

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 の値は効果がありません。

SQL

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 では、インデックスの構築または再構築中も読み取りと書き込みを継続できます：

SQL

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パーティションの数を制御します。値を大きくすると再現率は向上しますが、クエリー速度が低下します。The defaultは'auto'です。再現率のターゲットを満たすために、さまざまな値をテストしてください。

probesの形状はlistsの形状と一致している必要があります。lakebase_ann_index_infoを呼び出してlists配列を見つけ、1レベルのインデックスには値を1つ、2レベルのインデックスにはコンマ区切りの値を2つ設定します。

lists インデックス情報から	probes 設定する
[] （空）	''
[222]	'22'
[3333, 33333]	'33, 333'

lists インデックス情報から	probes 設定する
[] （空）	''
[222]	'22'
[3333, 33333]	'33, 333'

注記

小さなデータセットでは、lakebase_annはIVFパーティショニングの代わりに完全（フラット）検索を使用し、lakebase_ann_index_infoは空のlistsとdefault_probesを返します。この場合、probesは''に設定したままにしてください。listsが空でない場合、形状がlistsと一致しないprobes値はエラーの原因となります。

SQL

-- 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 がフル精度の再ランク付けを制御します。

プリフィルター

By default、PostgresはANNインデックスが候補行を返した後に、非ベクトルフィルター条件を適用します。フル精度の距離リランキングの前にそれらの条件を評価するには、lakebase_ann.prefilterを有効にしてください：

SQL

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: ルーティング構造のみを事前にウォームアップします。このオプションは、大規模なインデックスに対してより高速であり、優れたコストパフォーマンスのトレードオフを提供します。

SQL

-- 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	<=>

距離メトリクス	オペレータークラス	クエリ演算子
L2 （ユークリッド）	vector_l2_ops	<->
負の内積	vector_ip_ops	<#>
コサイン類似度	vector_cosine_ops	<=>

エンベディングのトレーニング方法に合ったオペレータークラスを選択し、インデックスとクエリに同じメトリクスを使用してください。

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

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

オプション	Type	デフォルト	説明
build_mode	string	'standard'	精度と速度のトレードオフを制御します。インデックス構築に時間はかかりますが、より高い再現率を得るには 'quality' を使用してください。下位互換性を維持するため、'fast' は引き続きサポートされます。
lists	string	'auto'	IVFパーティションのLayoutを設定します。'auto'を使用すると、拡張機能はテーブルの統計情報とインデックスの構成に基づいて値を選択します。1レベルのインデックスには'1000'のような単一の整数を、2レベルのインデックスには'100, 1000'のような昇順のコンマ区切りの整数を2つ設定します。

オプション	Type	デフォルト	説明
build_mode	string	'standard'	精度と速度のトレードオフを制御します。インデックス構築に時間はかかりますが、より高い再現率を得るには 'quality' を使用してください。下位互換性を維持するため、'fast' は引き続きサポートされます。
lists	string	'auto'	IVFパーティションのLayoutを設定します。'auto'を使用すると、拡張機能はテーブルの統計情報とインデックスの構成に基づいて値を選択します。1レベルのインデックスには'1000'のような単一の整数を、2レベルのインデックスには'100, 1000'のような昇順のコンマ区切りの整数を2つ設定します。

GUC参照

パラメーター	Type	デフォルト	説明
lakebase_ann.probes	string	'auto'	各レベルでスキャンするIVFパーティションの数。値を大きくすると再現率は向上しますが、クエリー速度が低下します。形状はlakebase_ann_index_infoのlists配列と一致している必要があります。
lakebase_ann.epsilon	string	'auto'	フル精度の距離を使用して再ランク付けされる候補の数を制御します。値を大きくすると、より多くの候補が再ランク付けされますが、時間がかかります。
lakebase_ann.prefilter	enum	off	フル精度の距離による再ランク付けの前に、非ベクトルフィルターを評価します。有効な値は on および off です。ほとんどの候補行を除外する、低コストのフィルターに最適です。

パラメーター	Type	デフォルト	説明
lakebase_ann.probes	string	'auto'	各レベルでスキャンするIVFパーティションの数。値を大きくすると再現率は向上しますが、クエリー速度が低下します。形状はlakebase_ann_index_infoのlists配列と一致している必要があります。
lakebase_ann.epsilon	string	'auto'	フル精度の距離を使用して再ランク付けされる候補の数を制御します。値を大きくすると、より多くの候補が再ランク付けされますが、時間がかかります。
lakebase_ann.prefilter	enum	off	フル精度の距離による再ランク付けの前に、非ベクトルフィルターを評価します。有効な値は on および off です。ほとんどの候補行を除外する、低コストのフィルターに最適です。

ユーティリティ関数

関数	戻り値	説明
lakebase_ann_prewarm(regclass, scope text DEFAULT 'search')	無効	頻繁にアクセスされるインデックスデータをメモリに読み込みます。有効な scope の値は search および routing です。
lakebase_ann_index_info(regclass)	TEXT	version、 lists、 default_probes、および default_epsilon を含め、インデックスのメタデータを JSON テキストとして返します。

関数	戻り値	説明
lakebase_ann_prewarm(regclass, scope text DEFAULT 'search')	無効	頻繁にアクセスされるインデックスデータをメモリに読み込みます。有効な scope の値は search および routing です。
lakebase_ann_index_info(regclass)	TEXT	version、 lists、 default_probes、および default_epsilon を含め、インデックスのメタデータを JSON テキストとして返します。

次のステップ

• lakebase_text
• Lakebase Search