lakebase_tokenizer

info

Beta

A partir de 15 de junho, o Lakebase estará disponível em Beta no GCP. Consulte Disponibilidade de regiões para ver as regiões compatíveis.

A extensão lakebase_tokenizer adiciona tokenização de palavra inteira configurável à pesquisa de texto completo do PostgreSQL no Lakebase. As configurações de pesquisa de texto criadas com a extensão funcionam com to_tsvector, o operador @@, as funções de classificação e os índices GIN. Você também pode usar valores tsvector gerados com lakebase_text para a classificação BM25.

A extensão fornece o tokenizer_wholeword padrão por meio da interface de dicionário de pesquisa de texto padrão do PostgreSQL. O padrão oferece suporte à conversão para letras minúsculas, normalização Unicode, remoção de acentos, remoção do genitivo em inglês, palavras de parada personalizadas, sinônimos de um para um e lematização em inglês.

Instalar

Instale a extensão no seu banco de dados. Os exemplos nesta página usam um esquema dedicado para facilitar a identificação dos objetos de extensão:

SQL

CREATE SCHEMA IF NOT EXISTS tokenizer_ext;
CREATE EXTENSION IF NOT EXISTS lakebase_tokenizer WITH SCHEMA tokenizer_ext;

A extensão é realocável. Você pode substituir tokenizer_ext por outro esquema ao instalá-lo.

Upgrade the extension

Uma nova versão do Lakebase Search pode adicionar recursos, correções e melhorias de desempenho. O PostgreSQL não atualiza automaticamente a versão da extensão instalada. Verifique as versões instaladas e a última disponível:

SQL

SELECT installed_version, default_version
FROM pg_available_extensions
WHERE name = 'lakebase_tokenizer';

Atualize a extensão para a versão mais recente disponível:

SQL

ALTER EXTENSION lakebase_tokenizer UPDATE;

ALTER EXTENSION does not regenerate stored tsvector values or rebuild dependent GIN or lakebase_bm25 indexes. If an update changes tokenization output, regenerate stored tsvector values and follow the notas sobre a versão for any required index maintenance.

Início rápido com tokenizer_wholeword

O exemplo a seguir cria um dicionário a partir do padrão tokenizer_wholeword e, em seguida, mapeia tipos de tokens comuns do PostgreSQL para ele em uma configuração de busca textual:

SQL

CREATE TEXT SEARCH DICTIONARY documents_dict (
  TEMPLATE          = tokenizer_ext.tokenizer_wholeword,
  Lowercase         = 'true',
  StripAccents      = 'true',
  Stemmer           = 'english'
);

CREATE TEXT SEARCH CONFIGURATION documents_cfg (COPY = pg_catalog.simple);

ALTER TEXT SEARCH CONFIGURATION documents_cfg
  ALTER MAPPING FOR asciiword, word, numword, hword_numpart, hword_part, hword_asciipart
  WITH documents_dict;

Use a configuração para produzir um tsvector, crie um índice GIN e execute queries em texto completo:

SQL

CREATE TABLE documents (
  id            BIGSERIAL PRIMARY KEY,
  body          TEXT NOT NULL,
  search_vector TSVECTOR GENERATED ALWAYS AS (
    to_tsvector('documents_cfg', body)
  ) STORED
);

INSERT INTO documents (body) VALUES
  ('Cats are running near the café.'),
  ('A dog is sleeping in the house.');

CREATE INDEX documents_search_idx ON documents USING gin (search_vector);

SELECT id, body
FROM documents
WHERE search_vector @@ plainto_tsquery('documents_cfg', 'running café');

Use a mesma configuração de busca de texto para documentos e queries para que ambos os lados apliquem a mesma estratégia e opções de tokenização.

Template: tokenizer_wholeword

Como funciona

Para cada tokens passado para o dicionário pelo analisador de busca de texto do PostgreSQL, tokenizer_wholeword aplica estas operações:

1. Lowercase: converter o token para minúsculas.
2. Normalize: aplicar a normalização Unicode.
3. StripAccents: Remover acentos.
4. EnglishPossessive: Remover um sufixo possessivo em inglês quando pelo menos um caractere permanecer.
5. Stopwords: não emita nenhum lexema e pare o processamento se o token corresponder a uma palavra de parada configurada. O token é omitido do tsvector gerado.
6. Synonyms: emitir a substituição configurada e interromper o processamento se o token corresponder a um sinônimo.
7. Stemmer: Se nenhum sinônimo corresponder e a stemming estiver ativada, aplique o stemmer em inglês.

Adicionar palavras de parada e sinônimos

O padrão tokenizer_wholeword pode carregar stop-words personalizados e sinônimos de tabelas SQL lakebase_tokenizer_stopwords e lakebase_tokenizer_synonyms gerenciadas por extensão. A coluna name agrupa as linhas em um conjunto que você seleciona com a opção de dicionário Stopwords ou Synonyms.

SQL

INSERT INTO tokenizer_ext.lakebase_tokenizer_stopwords (name, word) VALUES
  ('app_stopwords', 'the'),
  ('app_stopwords', 'and'),
  ('app_stopwords', 'or');

INSERT INTO tokenizer_ext.lakebase_tokenizer_synonyms (name, word, synonym) VALUES
  ('app_synonyms', 'usa', 'united_states'),
  ('app_synonyms', 'uk', 'united_kingdom');

Faça referência aos conjuntos ao criar ou alterar um dicionário de tokenizer_wholeword:

SQL

ALTER TEXT SEARCH DICTIONARY documents_dict (
  Stopwords = 'app_stopwords',
  Synonyms  = 'app_synonyms'
);

A extensão compara palavras de parada e palavras de origem de sinônimos com cada token após aplicar Lowercase, Normalize, StripAccents e EnglishPossessive, mas antes de aplicar Stemmer. As entradas do catálogo não são transformadas automaticamente, portanto, armazene-as na forma exata produzida por essas opções habilitadas:

• Com Lowercase = 'true', use entradas em minúsculas. Com Lowercase = 'false', a capitalização deve corresponder ao token.
• Com Normalize ativado, armazene as entradas na forma de normalização Unicode selecionada.
• Com StripAccents = 'true', armazene a forma sem acentos. Por exemplo, armazene cafe para corresponder a café.
• Armazene a forma antes do stemming. Por exemplo, com Stemmer = 'english', uma entrada run não corresponde a running. Adicione running para filtrar ou substituir esse token.

Set names can contain up to 256 bytes. Words and synonyms can contain up to 1024 bytes. Each named stop-word or synonym set can contain up to 100,000 rows.

Uma substituição de sinônimo é emitida exatamente como foi armazenada e não é processada pelo stemmer. Os sinônimos dão suporte a uma substituição para cada palavra de origem. Para representar uma substituição de várias palavras como um único lexema, use um separador como um underscore, como em united_states.

Após alterar um conjunto, o proprietário de cada dicionário que faz referência ao conjunto deve executar um ALTER TEXT SEARCH DICTIONARY sem efeito para forçar uma recarga:

SQL

ALTER TEXT SEARCH DICTIONARY documents_dict (dummy);

A opção dummy não existe em tokenizer_wholeword. Omitir um valor solicita que o PostgreSQL remova essa opção inexistente, o que invalida o cache sem alterar nenhuma das opções configuradas do dicionário.

After reloading the dictionary, regenerate the stored tsvector values by rewriting the source rows:

SQL

UPDATE documents SET body = body;

Funções e acesso

Use two roles to separate application access from tokenizer administration:

• app_role usa dicionários existentes. É preciso ter USAGE nos esquemas relevantes e SELECT nas tabelas do catálogo de extensão, mas não é necessário possuir os dicionários.
• tokenizer_admin gerencia conjuntos de palavras de parada e sinônimos, cria e possui dicionários e configurações de pesquisa de texto, e executa o comando de recarregamento após alterar um conjunto.

Conceder acesso ao esquema de extensão e às tabelas do catálogo:

SQL

GRANT USAGE ON SCHEMA tokenizer_ext TO app_role, tokenizer_admin;

GRANT SELECT ON
  tokenizer_ext.lakebase_tokenizer_stopwords,
  tokenizer_ext.lakebase_tokenizer_synonyms
TO app_role;

GRANT SELECT, INSERT, UPDATE, DELETE ON
  tokenizer_ext.lakebase_tokenizer_stopwords,
  tokenizer_ext.lakebase_tokenizer_synonyms
TO tokenizer_admin;

tokenizer_admin também precisa de CREATE no esquema onde os dicionários e as configurações de pesquisa de texto são armazenados. Crie esses objetos como tokenizer_admin ou transfira a propriedade deles para ele. O acesso de gravação às tabelas do catálogo não concede a propriedade dos dicionários existentes.

Opções

Especifique as opções de tokenizer_wholeword em CREATE TEXT SEARCH DICTIONARY ou ALTER TEXT SEARCH DICTIONARY. Os nomes das opções não diferenciam maiúsculas de minúsculas.

Opção	Tipo	Padrão	Descrição
Lowercase	boolean	true	Converte tokens em minúsculas antes de aplicar outras operações. Stemmer = 'english' exige Lowercase = 'true'.
Normalize	NFC, NFD, NFKC, NFKD ou none	none	Aplica a forma de normalização Unicode selecionada. Isso padroniza a representação, mas não remove caracteres. Por exemplo, NFC torna o é pré-composto e o e seguidos por um equivalente de acento agudo combinante.
EnglishPossessive	boolean	true	Remove um sufixo final 's, ’s ou ＇s quando pelo menos um caractere precede o sufixo. Um sufixo independente permanece inalterado.
StripAccents	boolean	false	Aplica a normalização NFKD e remove marcas de combinação. Por exemplo, café se torna cafe. When this option is enabled, omit Normalize because the NFKD step makes any separate Unicode normalization redundant.
Stopwords	definir o nome	Nenhuma	Usa o conjunto nomeado de tokenizer_ext.lakebase_tokenizer_stopwords.
Synonyms	definir o nome	Nenhuma	Uses the named set of one-to-one replacements from tokenizer_ext.lakebase_tokenizer_synonyms.
Stemmer	english	Nenhuma	Usa o Snowball 3.1.0 incluído no pacote Stemmer em inglês. Omitir esta opção para desativar a lematização. O stemmer não inclui uma lista de stop words.

Opção	Tipo	Padrão	Descrição
Lowercase	boolean	true	Converte tokens em minúsculas antes de aplicar outras operações. Stemmer = 'english' exige Lowercase = 'true'.
Normalize	NFC, NFD, NFKC, NFKD ou none	none	Aplica a forma de normalização Unicode selecionada. Isso padroniza a representação, mas não remove caracteres. Por exemplo, NFC torna o é pré-composto e o e seguidos por um equivalente de acento agudo combinante.
EnglishPossessive	boolean	true	Remove um sufixo final 's, ’s ou ＇s quando pelo menos um caractere precede o sufixo. Um sufixo independente permanece inalterado.
StripAccents	boolean	false	Aplica a normalização NFKD e remove marcas de combinação. Por exemplo, café se torna cafe. When this option is enabled, omit Normalize because the NFKD step makes any separate Unicode normalization redundant.
Stopwords	definir o nome	Nenhuma	Usa o conjunto nomeado de tokenizer_ext.lakebase_tokenizer_stopwords.
Synonyms	definir o nome	Nenhuma	Uses the named set of one-to-one replacements from tokenizer_ext.lakebase_tokenizer_synonyms.
Stemmer	english	Nenhuma	Usa o Snowball 3.1.0 incluído no pacote Stemmer em inglês. Omitir esta opção para desativar a lematização. O stemmer não inclui uma lista de stop words.

Tabelas do catálogo

Tabela	Colunas	Descrição
lakebase_tokenizer_stopwords	name text, word text	Armazena conjuntos de palavras de parada (stop words) nomeados para padrões de tokenizadores que oferecem suporte a Stopwords. A chave primária é (name, word).
lakebase_tokenizer_synonyms	name text, word text, synonym text	Armazena substituições nomeadas de um para um para padrões de tokenizador que dão suporte a Synonyms. A chave primária é (name, word).

Tabela	Colunas	Descrição
lakebase_tokenizer_stopwords	name text, word text	Armazena conjuntos de palavras de parada (stop words) nomeados para padrões de tokenizadores que oferecem suporte a Stopwords. A chave primária é (name, word).
lakebase_tokenizer_synonyms	name text, word text, synonym text	Armazena substituições nomeadas de um para um para padrões de tokenizador que dão suporte a Synonyms. A chave primária é (name, word).

Usar a classificação BM25 com lakebase_text

As configurações de busca de texto criadas com lakebase_tokenizer produzem valores de PostgreSQL tsvector padrão que são compatíveis com lakebase_text. Para usar o ranking de relevância do BM25 e a recuperação top-K, crie um índice lakebase_bm25 na mesma coluna do tsvector. Para obter informações sobre instalação, criação de índices e sintaxe de query, consulte lakebase_text.

Passos seguintes

• lakebase_text
• Pesquisa no Lakebase