lakebase_text
A extensão lakebase_text adiciona pesquisa de texto completo BM25 ao Lakebase através do tipo de índice lakebase_bm25. É compatível com o tipo tsvector padrão do PostgreSQL e operadores de consulta.
Instalar
Primeiro, habilite a Pesquisa Lakebase nas configurações do seu projeto. Em seguida, instale a extensão:
CREATE EXTENSION IF NOT EXISTS lakebase_text;
Atualizar a extensão e os índices
Uma nova versão do Lakebase Search pode adicionar recursos, correções e melhorias de desempenho. Embora o Lakebase Search seja lançado como parte das atualizações do Lakebase, ele não atualiza tudo automaticamente. Em lakebase_text, duas coisas são atualizadas separadamente e possuem números de versão que não estão relacionados entre si:
- A versão da extensão é a versão dos objetos SQL que
CREATE EXTENSION lakebase_textcria, incluindo seus tipos de dados, funções, operadores e o método de acesso ao índicelakebase_bm25. Esta versão é informada porSELECT installed_version FROM pg_available_extensions WHERE name = 'lakebase_text'.ALTER EXTENSION lakebase_text UPDATEatualiza esta versão. - O formato de armazenamento de índice é a disposição em disco de um índice
lakebase_bm25. A extensão pode introduzir formatos de armazenamento de índice atualizados em uma atualização, desbloqueando mais recursos e oferecendo melhor desempenho. Todos os índices recém-criados usam automaticamente o formato de armazenamento mais recente, enquanto os índices existentes podem ser atualizados para o novo formato usandoREINDEX INDEX CONCURRENTLYapós a disponibilização de um formato de armazenamento mais novo.
A atualização não é urgente. A extensão é compatível com objetos SQL e formatos de armazenamento de índice de versões mais antigas, mas manter-se atualizado mantém você no caminho compatível e de melhor desempenho e evita uma migração maior posteriormente; portanto, atualize quando for conveniente em vez de adiar indefinidamente.
A versão mais recente disponível da extensão é informada por SELECT default_version FROM pg_available_extensions WHERE name = 'lakebase_text'.
Por que lakebase_text em vez da pesquisa de texto completo GIN padrão
A pesquisa de texto completo integrada do PostgreSQL usa índices GIN e ts_rank para pontuação de relevância. ts_rank não usa estatísticas globais de corpus, portanto as pontuações se degradam conforme os dados crescem. lakebase_text aprimora isso de duas maneiras:
- O ranking BM25 leva em conta a frequência do termo, o comprimento do documento e as estatísticas de todo o corpus simultaneamente, produzindo pontuações de relevância mais precisas do que o TF-IDF.
- Top-K pushdown usa Block-Max WAND para retornar apenas os K resultados mais relevantes do índice, sem pontuar cada correspondência no conjunto de resultados.
Início rápido
Crie o índice lakebase_bm25 após inserir os dados. O BM25 calcula estatísticas de todo o corpus no momento da criação do índice, não incrementalmente, portanto, o índice deve ser criado em uma tabela populada.
-- 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;
O operador <@> retorna uma pontuação BM25 negativa. A ordenação por pontuação ascendente retorna os resultados mais relevantes primeiro.
Uma verificação de índice lakebase_bm25 pode omitir qualquer número de linhas cujo valor de <@> seja exatamente 0.0. Não confie no retorno de linhas com distância zero ou na ordem delas. Para avaliar todas as linhas, defina lakebase_bm25.enable_scan como off para usar uma verificação sequencial.
Popular a partir de tabelas sincronizadas
Se você estiver carregando texto de origem do Unity Catalog em vez de inseri-lo diretamente, as tabelas sincronizadas podem gerar uma coluna tsvector durante a sincronização, pronta para indexar com lakebase_bm25 assim que a sincronização for concluída. Consulte Mapeamento de tipo personalizado para o Lakebase Search.
Mantenha o índice preciso
As estatísticas BM25 são computadas no tempo de construção do índice e atualizadas pelo vacuum. Para a maioria das cargas de trabalho, o vacuum regular mantém as pontuações precisas. Após o carregamento em massa de uma grande quantidade de novos dados, execute o vacuum manualmente:
VACUUM documents;
Para manter o desempenho de query e atualização, VACUUM deve limpar o índice prontamente. Para uma tabela dedicada à pesquisa de texto, o Databricks recomenda definir autovacuum_vacuum_insert_scale_factor como 0 para que o limite do autovacuum acionado por inserção não cresça com a tabela:
ALTER TABLE documents SET (
autovacuum_vacuum_insert_scale_factor = 0
);
Com o fator de escala definido como 0, autovacuum_vacuum_insert_threshold determina o número fixo de tuplas inseridas que Trigger o autovacuum. Ajuste esse limite com base em sua carga de trabalho.
As estatísticas globais do BM25 não têm versão MVCC. Se VACUUM atualizar as estatísticas enquanto uma transação estiver usando um snapshot MVCC mais antigo, a transação poderá calcular pontuações usando estatísticas mais recentes do que seu snapshot de linha. A visibilidade das linhas permanece compatível com MVCC, mas pontuações, classificações e resultados top-K podem mudar dentro de uma transação REPEATABLE READ. Não confie em classificações do BM25 estáveis com base em snapshot em um VACUUM concorrente, incluindo o autovacuum.
Ajustar pesquisa
GUCs em nível de sessão
Parâmetro | Tipo | Padrão | Descrição |
|---|---|---|---|
| inteiro |
| Número máximo de resultados retornados do índice. |
| boolean |
| Quando |
| boolean |
| Defina como |
SET lakebase_bm25.default_limit TO 20;
SET lakebase_bm25.prefilter = on;
GUCs têm precedência sobre os parâmetros de armazenamento de índice quando ambos estão definidos.
Parâmetros de armazenamento de índice
Defina estas opções no momento da criação do índice ou com ALTER INDEX:
Parâmetro | Tipo | Padrão | Intervalo | Descrição |
|---|---|---|---|---|
| real |
| 1,2 a 2,0 | Saturação de frequência de termos. Valores mais altos dão mais peso a termos repetidos. |
| real |
| 0,0 a 1,0 | Normalização de comprimento do documento. |
| inteiro |
| 1 a 65535 | Limite de fallback quando o GUC da sessão não está definido. |
| boolean |
| N/A | Configuração de pré-filtro de fallback quando o GUC da sessão não está definido. |
-- 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);
Referência de API
Tipos
bm25query_tsvector: combina uma consulta tsvector com o identificador de índice de destino. Usado como operando direito de <@>.
Operadores
Operador | Assinatura | Devolve | Descrição |
|---|---|---|---|
|
|
| Retorna uma pontuação BM25 negativa. Ordene de forma ascendente para obter os resultados mais relevantes primeiro. |
Funções
Função | Devolve | Descrição |
|---|---|---|
|
| Constrói um objeto de consulta BM25 a partir de um |
Classes de operador
Aula | Default para | Descrição |
|---|---|---|
|
| Mapeia as colunas |