lakebase_text
L'extension lakebase_text ajoute la recherche en texte intégral BM25 à Lakebase via le type d'index lakebase_bm25. Il est compatible avec le type tsvector standard et les opérateurs de requête de PostgreSQL.
Installer
Tout d'abord, activez la recherche Lakebase dans les paramètres de votre projet. Puis installez l'extension :
CREATE EXTENSION IF NOT EXISTS lakebase_text;
Mettre à niveau l’extension et les index
A new Lakebase Search release can add features, fixes, and performance improvements. Although Lakebase Search is released as part of Lakebase updates, it does not upgrade everything automatically. In lakebase_text, two things upgrade separately and carry version numbers that are unrelated to each other:
- The extension version is the version of the SQL objects that
CREATE EXTENSION lakebase_textcreates, including its data types, functions, operators, and thelakebase_bm25index access method. This version is reported bySELECT installed_version FROM pg_available_extensions WHERE name = 'lakebase_text'.ALTER EXTENSION lakebase_text UPDATEupdates this version. - The index storage format correspond au layout sur disque d’un index
lakebase_bm25. L’extension peut introduire de nouveaux formats de stockage d’index lors d’une mise à jour, ce qui permet de débloquer de nouvelles fonctionnalités et d’offrir de meilleures performances. Tous les nouveaux index créés utilisent automatiquement le format de stockage le plus récent, tandis que les index existants peuvent être mis à niveau vers le nouveau format à l’aide deREINDEX INDEX CONCURRENTLYune fois qu’un format de stockage plus récent est disponible.
Upgrading is not urgent. The extension is compatible with SQL objects and index storage formats from older versions, but staying current keeps you on the supported, best-performing path and avoids a larger migration later, so upgrade when convenient rather than deferring indefinitely.
La dernière version d’extension disponible est signalée par SELECT default_version FROM pg_available_extensions WHERE name = 'lakebase_text'.
Pourquoi lakebase_text au lieu de la recherche en texte intégral GIN standard ?
La recherche en texte intégral intégré de PostgreSQL utilise des index GIN et ts_rank pour le scoring de pertinence. ts_rank n'utilise pas de statistiques de corpus globales, de sorte que les scores se dégradent à mesure que les données augmentent. lakebase_text améliore cela de deux manières :
- Le classement BM25 tient compte de la fréquence des termes, de la longueur des documents et des statistiques à l'échelle du corpus simultanément, ce qui produit des scores de pertinence plus précis que le TF-IDF.
- Top-K pushdown utilise Block-Max WAND pour renvoyer uniquement les K résultats les plus pertinents de l'index, sans évaluer chaque correspondance dans le jeu de résultats.
Quick start
Créez l’index lakebase_bm25 après l’insertion de données. BM25 calcule des statistiques à l’échelle du corpus au moment de la création de l’index, et non de manière incrémentielle. L’index doit donc être créé sur une table renseignée.
-- 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;
L’opérateur <@> renvoie un score BM25 négatif. Le classement par score croissant renvoie d'abord les résultats les plus pertinents.
Un parcours d’index lakebase_bm25 peut omettre un nombre quelconque de lignes dont la valeur <@> est exactement 0.0. Ne comptez pas sur le renvoi de lignes à distance nulle ni sur leur ordre. Pour évaluer chaque ligne, définissez lakebase_bm25.enable_scan sur off afin d’utiliser à la place un parcours séquentiel.
Remplir à partir de tables synchronisées
Si vous chargez du texte source depuis Unity Catalog plutôt que de l'insérer directement, les tables synchronisées peuvent générer une colonne tsvector pendant la synchronisation, prête à être indexée avec lakebase_bm25 dès que la synchronisation est terminée. Consultez Custom type mapping for Lakebase Search.
Maintenir l'index précis
Les statistiques BM25 sont calculées au moment de la création de l'index et mises à jour par VACUUM. Pour la plupart des charges de travail, un VACUUM régulier maintient des scores précis. Après le chargement en masse d'une grande quantité de nouvelles données, exécutez VACUUM manuellement :
VACUUM documents;
Pour préserver les performances des requêtes (query) et des mises à jour, VACUUM doit nettoyer l’index rapidement. Pour une table dédiée à la recherche de texte, Databricks recommande de définir autovacuum_vacuum_insert_scale_factor sur 0 afin que le threshold d’autovacuum déclenché par les insertions n’augmente pas avec la table :
ALTER TABLE documents SET (
autovacuum_vacuum_insert_scale_factor = 0
);
Avec le facteur de montée en charge défini sur 0, autovacuum_vacuum_insert_threshold détermine le nombre fixe de tuples insérés qui déclenche l’autovacuum. Ajustez ce threshold en fonction de votre charge de travail.
Les statistiques globales BM25 ne sont pas versionnées par MVCC. Si VACUUM met à jour les statistiques alors qu’une transaction utilise un ancien instantané MVCC, la transaction peut calculer des scores à l’aide de statistiques plus récentes que son instantané de ligne. La visibilité des lignes reste conforme à MVCC, mais les scores, les classements et les résultats top-K peuvent changer au cours d’une transaction REPEATABLE READ. Ne comptez pas sur des classements BM25 stables sur l’instantané pour un(e) VACUUM concurrent(e), y compris avec autovacuum.
Optimiser la recherche
GUCs au niveau de la session
parameter | Type | Par défaut | Description |
|---|---|---|---|
| entier |
| Nombre maximal de résultats renvoyés par l'index. |
| booléen |
| Lorsque |
| booléen |
| Définissez sur |
SET lakebase_bm25.default_limit TO 20;
SET lakebase_bm25.prefilter = on;
Les GUC l'emportent sur les paramètres de stockage d'index lorsque les deux sont définis.
Paramètres de stockage d'index
Définissez ces options au moment de la création de l'index ou avec ALTER INDEX:
parameter | Type | Par défaut | Plage | Description |
|---|---|---|---|---|
| réel |
| De 1,2 à 2,0 | Saturation de la fréquence des termes. Des valeurs plus élevées accordent plus de poids aux termes répétés. |
| réel |
| 0,0 à 1,0 | Normalisation de la longueur du document. |
| entier |
| de 1 à 65535 | Limite de fallback lorsque le GUC de session n'est pas défini. |
| booléen |
| N/A | Paramètre de préfiltre fallback lorsque le GUC de session n'est pas défini. |
-- 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);
Référence de l'API
Types
bm25query_tsvector: Combine une query tsvector avec l’identifiant de l’index cible. Utilisé comme opérande de droite de <@>.
Opérateurs
Opérateur | Signature | Renvoie | Description |
|---|---|---|---|
|
|
| Renvoie un score BM25 négatif. Triez par ordre croissant pour obtenir les résultats les plus pertinents en premier. |
Fonctions
Fonction | Renvoie | Description |
|---|---|---|
|
| Construit un objet de query BM25 à partir d'un |
Classes d'opérateurs
Classe | Default pour | Description |
|---|---|---|
|
| Mappe |