lakebase_text
lakebase_text拡張機能は、lakebase_bm25インデックスタイプを介してLakebaseにBM25全文検索を追加します。PostgreSQLの標準tsvector型およびクエリ演算子と互換性があります。
インストール
まず、プロジェクト設定でLakebase Searchを有効にしてください。次に、拡張機能をインストールします。
CREATE EXTENSION IF NOT EXISTS lakebase_text;
拡張機能とインデックスをアップグレードする
Lakebase Searchの新しいリリースにより、機能、修正、パフォーマンスの向上が追加される場合があります。Lakebase SearchはLakebaseのアップデートの一環としてリリースされますが、すべてが自動的にアップグレードされるわけではありません。lakebase_textでは、次の2つの要素が個別にアップグレードされ、互いに関連のないバージョン番号が付けられます。
- 拡張機能のバージョン は、データ型、関数、演算子、
lakebase_bm25インデックスアクセス方法など、CREATE EXTENSION lakebase_textが作成するSQLオブジェクトのバージョンです。このバージョンはSELECT installed_version FROM pg_available_extensions WHERE name = 'lakebase_text'によって報告されます。ALTER EXTENSION lakebase_text UPDATEがこのバージョンを更新します。 - インデックスのストレージ形式 は、
lakebase_bm25インデックスのディスク上の Layout です。この拡張機能では、アップデートで更新されたインデックスストレージ形式が導入され、より多くの機能が解放されてパフォーマンスが向上する場合があります。新しく作成されたすべてのインデックスは自動的に最新のストレージ形式を使用します。一方、既存のインデックスは、より新しいストレージ形式が利用可能になった後、REINDEX INDEX CONCURRENTLYを使用して新しい形式にアップグレードできます。
アップグレードは緊急ではありません。この拡張機能は、古いバージョンの SQL オブジェクトおよびインデックスのストレージ形式と互換性がありますが、最新の状態を維持することでサポートされている最もパフォーマンスの高いパスが維持され、後で大規模な移行を行う必要がなくなるため、無期限に延期するのではなく、都合の良いときにアップグレードしてください。
利用可能な最新の拡張機能バージョンは SELECT default_version FROM pg_available_extensions WHERE name = 'lakebase_text' によって報告されます。
標準のGIN全文検索ではなくlakebase_textを使用する理由
PostgreSQL の組み込み全文検索は、関連性スコアリングに GIN インデックスとts_rank使用します。ts_rankグローバルコーパス統計を使用しないため、データが増えるにつれてスコアが低下します。lakebase_textこれを2つの点で改善しています。
- BM25ランキング は、単語の出現頻度、文書の長さ、およびコーパス全体の統計情報を同時に考慮するため、TF-IDFよりも正確な関連性スコアを生成します。
- Top-K pushdown はBlock-Max WANDを使用して、インデックスからK個の最も関連性の高い結果のみを返し、結果セット内のすべてのマッチをスコアリングしません。
クイックスタート
データ挿入後にlakebase_bm25インデックスを作成します。BM25は、インデックス作成時にコーパス全体の統計情報を計算するため、増分的に計算するのではなく、インデックスはデータが格納されたテーブル上に作成する必要があります。
-- Create a table with a generated tsvector column
CREATE TABLE documents (
id SERIAL PRIMARY KEY,
passage TEXT,
vector TSVECTOR GENERATED ALWAYS AS (to_tsvector('english', passage)) STORED
);
-- Insert data before building the BM25 index
INSERT INTO documents (passage) VALUES
('Postgres is a powerful open-source relational database.'),
('Vector search finds semantically similar results.'),
('BM25 ranking improves full-text search relevance scores.');
-- Create the BM25 index on the populated table
CREATE INDEX documents_passage_bm25 ON documents USING lakebase_bm25 (vector);
-- Query: lower score means more relevant
SELECT id, passage,
vector <@> to_bm25query(to_tsvector('english', 'database'), 'documents_passage_bm25') AS score
FROM documents
ORDER BY score
LIMIT 5;
<@>演算子は負のBM25スコアを返します。スコアを昇順で並べ替えることにより、最も関連性の高い結果が最初に返されます。
lakebase_bm25 インデックススキャンでは、<@> の値が正確に 0.0 である任意の数の行を省略できます。距離がゼロの行が返されることや、その順序に依存しないでください。すべての行を評価するには、lakebase_bm25.enable_scan を off に設定して、代わりに順次スキャンを使用します。
同期テーブルから入力
ソーステキストを直接挿入するのではなく Unity Catalog から読み込む場合、同期テーブルは同期中に tsvector カラムを生成でき、同期が完了するとすぐに lakebase_bm25 でインデックスを作成できるようになります。Lakebase Search のカスタム型マッピングを参照してください。
インデックスの精度を維持する
BM25統計は、インデックス構築時に計算され、VACUUMによって更新されます。ほとんどのワークロードで、定期的なVACUUMはスコアを正確に保ちます。大量の新しいデータを一括ロードした後、手動でVACUUMを実行してください。
VACUUM documents;
クエリーおよび更新のパフォーマンスを維持するため、VACUUM はインデックスを速やかにクリーンアップする必要があります。テキスト検索専用のテーブルの場合、挿入によって Trigger されるオートバキュームの threshold がテーブルとともに大きくならないように、Databricks では autovacuum_vacuum_insert_scale_factor を 0 に設定することをお勧めします。
ALTER TABLE documents SET (
autovacuum_vacuum_insert_scale_factor = 0
);
スケールファクターが 0 に設定されている場合、autovacuum_vacuum_insert_threshold は自動バキュームを Trigger する挿入されたタプルの固定数を決定します。ワークロードに基づいてその threshold をチューニングします。
BM25 のグローバル統計情報は MVCC バージョン管理されません。トランザクションが古い MVCC スナップショットを使用している間に VACUUM が統計情報を更新した場合、トランザクションは行のスナップショットよりも新しい統計情報を使用してスコアを計算する可能性があります。行の可視性は MVCC 準拠のままですが、スコア、ランキング、および上位 K 件の結果は REPEATABLE READ トランザクション内で変更される可能性があります。自動バキュームを含む並列 VACUUM 全体で、スナップショットで安定した BM25 ランキングに依存しないでください。
検索の調整
セッションレベルGUC
パラメーター | Type | デフォルト | 説明 |
|---|---|---|---|
| 整数 |
| インデックスから返される結果の最大数。 |
| boolean |
|
|
| boolean |
| インデックスをバイパスしてシーケンシャルスキャンを強制するには、 |
SET lakebase_bm25.default_limit TO 20;
SET lakebase_bm25.prefilter = on;
GUCは、両方が設定されている場合、インデックスストレージパラメーターよりも優先されます。
インデックスストレージパラメーター
これらのオプションは、インデックス作成時またはALTER INDEXで設定します：
パラメーター | Type | デフォルト | 範囲 | 説明 |
|---|---|---|---|---|
| real |
| 1.2～2.0 | 用語頻度飽和。値が大きいほど、繰り返される用語により重みが与えられます。 |
| real |
| 0.0〜1.0 | ドキュメント長正規化。 |
| 整数 |
| 1～65535 | セッションGUCが設定されていない場合のフォールバック制限。 |
| boolean |
| N/A | セッションGUCが設定されていない場合のフォールバックプリフィルタ設定。 |
-- Set parameters at index creation (use a new name — the Quick start already created documents_passage_bm25)
CREATE INDEX documents_passage_bm25_tuned ON documents USING lakebase_bm25 (vector)
WITH (default_limit = 20, k1 = 1.5);
-- Update parameters on an existing index
ALTER INDEX documents_passage_bm25_tuned SET (default_limit = 50);
APIリファレンス
タイプ
bm25query_tsvectorクエリtsvectorとターゲットインデックス識別子を組み合わせます。<@> の右の被演算子として使用されます。
オペレーター
オペレーター | シグネチャ | 戻り値 | 説明 |
|---|---|---|---|
|
|
| 負のBM25スコアを返します。最も関連性の高い結果を最初に表示するには、昇順で並べ替えてください。 |
関数
関数 | 戻り値 | 説明 |
|---|---|---|
|
|
|
演算子クラス
クラス | デフォルト | 説明 |
|---|---|---|
|
|
|