Pular para o conteúdo principal

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 configurável à pesquisa de texto completo do PostgreSQL no Lakebase, incluindo processamento de palavras inteiras e análise morfológica para texto chinês, japonês e coreano (CJK). Configurações de pesquisa de texto criadas com a extensão funcionam com to_tsvector, o operador @@, funções de classificação e índices GIN. Você também pode usar valores tsvector gerados com lakebase_text para classificação BM25.

A extensão fornece os padrões tokenizer_wholeword e tokenizer_morph por meio da interface de dicionário de pesquisa de texto padrão do PostgreSQL. Use tokenizer_wholeword para processamento de palavras inteiras, incluindo normalização, palavras irrelevantes, sinônimos e stemming em inglês. Use tokenizer_morph para análise morfológica CJK.

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.

A atualização de 0.1.x para 0.2.0 não altera a saída de tokenização. A versão 0.2.0 adiciona o padrão tokenizer_morph e as configurações CJK integradas e deixa suas configurações existentes inalteradas, portanto, você não precisa gerar valores tsvector novamente ou reconstruir índices.

Começar rápido​

Escolha um caminho com base no idioma do seu texto:

  • Para inglês e outros idiomas delimitados por espaços em branco, crie um dicionário a partir do padrão tokenizer_wholeword.
  • Para textos em chinês, japonês ou coreano, use uma configuração integrada. Você não precisa criar um dicionário.

Texto de palavra inteira​

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.

Texto CJK​

Instalar a extensão cria as configurações de pesquisa de texto tokenizer_chinese, tokenizer_japanese e tokenizer_korean. Use um deles diretamente para produzir um tsvector, criar um índice GIN e execução queries em texto completo:

SQL
CREATE TABLE chinese_documents (
id BIGSERIAL PRIMARY KEY,
body TEXT NOT NULL,
search_vector TSVECTOR GENERATED ALWAYS AS (
to_tsvector('tokenizer_ext.tokenizer_chinese', body)
) STORED
);

INSERT INTO chinese_documents (body) VALUES
('现代分布式文件系统架构');

CREATE INDEX chinese_idx ON chinese_documents USING gin (search_vector);

-- The built-in Chinese configuration uses mixed mode, so use plainto_tsquery instead of to_tsquery.
SELECT id, body
FROM chinese_documents
WHERE search_vector @@ plainto_tsquery('tokenizer_ext.tokenizer_chinese', '现代分布式');

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.

Tabela

Colunas

Descrição

lakebase_tokenizer_stopwords

name text, word text

Armazena conjuntos de stop-words nomeados para tokenizer_wholeword. A key primária é (name, word).

lakebase_tokenizer_synonyms

name text, word text, synonym text

Armazena substituições um para um nomeadas para tokenizer_wholeword. A key primária é (name, word).

Tabela

Colunas

Descrição

lakebase_tokenizer_stopwords

name text, word text

Armazena conjuntos de stop-words nomeados para tokenizer_wholeword. A key primária é (name, word).

lakebase_tokenizer_synonyms

name text, word text, synonym text

Armazena substituições um para um nomeadas para tokenizer_wholeword. A key primária é (name, word).

Template: tokenizer_morph​

O padrão tokenizer_morph oferece suporte a tokenização para texto em chinês, japonês e coreano na pesquisa de texto completo do PostgreSQL. Use uma configuração de pesquisa de texto integrada ou defina uma personalizada para controlar a geração de termos.

Como funciona​

tokenizer_morph usa o analisador Lindera com dicionários incluídos: Jieba para chinês, IPADIC para japonês e MeCab KoDic para coreano.

Para tokens de parser coreanos, tokenizer_morph primeiro substitui ㆍ (U+318D) por um limite de token.

Para cada token transmitido ao dicionário pelo analisador de pesquisa de texto do PostgreSQL, tokenizer_morph aplica estas operações em ordem:

  1. Normalize: Aplique a normalização Unicode ao token do analisador.
  2. Language: Segmente os tokens do analisador com o analisador de idioma selecionado.
  3. Filtro de símbolos: Descarte segmentos que não contenham letras ou dígitos.
  4. Análise específica de idioma: Transforme cada segmento restante em zero ou mais termos, conforme descrito abaixo.
  5. Lowercase: Converta cada termo em minúsculas.
  6. Stemmer: se habilitado, faça o stemming de termos feitos inteiramente de letras ASCII com o stemmer de inglês incluído. Este passo não faz o stemming de termos CJK.

O passo de análise específico da linguagem aplica estas regras:

Chinês

  • Expansão de subpalavras: No modo mixed, adicione os termos de dois e três caracteres contidos no dicionário agrupado.

Japonês

  • Filtragem de partes da fala: descartar partículas reconhecidas, verbos auxiliares, conjunções, preenchimentos, sons não verbais, símbolos não alfabéticos e segmentos marcados その他,間投.
  • Conversão de forma base: use a forma base do dicionário de cada segmento reconhecido restante quando disponível. Caso contrário, mantenha sua forma de superfície.
  • Filtragem de stop-words: Descarte um termo que corresponda à lista integrada de palavras de função comuns em japonês.
  • Derivação de katakana: Remoção de um ー final de um termo com pelo menos quatro caracteres, cujos caracteres estejam todos no bloco katakana (U+30A0 a U+30FF).

Coreano

  • Decomposição: nos modos discard e mixed, dividir um segmento reconhecido composto, flexionado ou pré-analisado quando o dicionário fornece seus componentes. discard emite os componentes no lugar do termo completo, e mixed emite ambos.
  • Filtragem gramatical: Aplique a filtragem ao termo completo e a cada componente de forma independente. Omitir termos com tag como partículas, terminações, afixos, advérbios, determinantes, interjeições, pontuação, símbolos ou formas não analisáveis.
  • Conversão de leitura de Hangul: use a leitura de Hangul do dicionário para um termo completo retido quando disponível. Os componentes mantêm sua forma de dicionário.

O parser de busca de texto do PostgreSQL divide o texto em espaços em branco e pontuação antes de chamar tokenizer_morph. Cada tokens de parser pode conter até 2046 bytes, e tokens mais longos são ignorados com um AVISO. A maioria dos caracteres chineses, japoneses e coreanos usa 3 bytes em UTF-8, portanto, uma execução de mais de 682 desses caracteres sem espaços em branco ou pontuação é omitida dos resultados to_tsvector.

Idiomas e modos suportados​

Os modos disponíveis dependem da linguagem. Cada exemplo mostra o texto de origem → termos emitidos:

Idioma

Mode

Comportamento

Exemplo

Chinês

none

Emite palavras da segmentação padrão sem adicionar termos de pesquisa mais curtos.

现代分布式文件系统架构 → 现代, 分布式文件系统, 架构

Chinês

mixed

Mantém palavras da segmentação padrão e adiciona termos de pesquisa mais curtos de algumas palavras mais longas.

现代分布式文件系统架构 → 现代, 分布式文件系统, 分布, 分布式, 布式, 文件, 系统, 架构

Japonês

none

Favorece compostos de dicionário mais longos.

関西国際空港へのアクセス → 関西国際空港, アクセス

Japonês

discard

Produz termos mais granulares para alguns compostos longos sem também manter sua forma completa.

関西国際空港へのアクセス → 関西, 国際, 空港, アクセス

Coreano

none

Mantém entradas de dicionário compostas e flexionadas como termos completos.

한국어 형태소 분석 → 한국어, 형태소, 분석

Coreano

discard

Quando uma forma composta ou flexionada pode ser dividida, emite suas partes em vez do termo completo.

한국어 형태소 분석 → 한국, 어, 형태, 소, 분석

Coreano

mixed

Quando uma forma composta ou flexionada pode ser dividida, emite tanto o termo completo quanto suas partes.

한국어 형태소 분석 → 한국어, 한국, 어, 형태소, 형태, 소, 분석

Idioma

Mode

Comportamento

Exemplo

Chinês

none

Emite palavras da segmentação padrão sem adicionar termos de pesquisa mais curtos.

现代分布式文件系统架构 → 现代, 分布式文件系统, 架构

Chinês

mixed

Mantém palavras da segmentação padrão e adiciona termos de pesquisa mais curtos de algumas palavras mais longas.

现代分布式文件系统架构 → 现代, 分布式文件系统, 分布, 分布式, 布式, 文件, 系统, 架构

Japonês

none

Favorece compostos de dicionário mais longos.

関西国際空港へのアクセス → 関西国際空港, アクセス

Japonês

discard

Produz termos mais granulares para alguns compostos longos sem também manter sua forma completa.

関西国際空港へのアクセス → 関西, 国際, 空港, アクセス

Coreano

none

Mantém entradas de dicionário compostas e flexionadas como termos completos.

한국어 형태소 분석 → 한국어, 형태소, 분석

Coreano

discard

Quando uma forma composta ou flexionada pode ser dividida, emite suas partes em vez do termo completo.

한국어 형태소 분석 → 한국, 어, 형태, 소, 분석

Coreano

mixed

Quando uma forma composta ou flexionada pode ser dividida, emite tanto o termo completo quanto suas partes.

한국어 형태소 분석 → 한국어, 한국, 어, 형태소, 형태, 소, 분석

No modo mixed, faça a query com plainto_tsquery. Quando uma palavra de query produz múltiplos lexemas, to_tsquery, websearch_to_tsquery e phraseto_tsquery os join com o operador <->, que requer posições adjacentes. O modo mixed insere posições extras para os termos adicionais, de modo que essas condições de frase podem perder correspondências esperadas. Para queries baseadas em posição, defina uma configuração personalizada com o modo none ou discard.

Usar as configurações integradas​

A instalação da extensão cria estas configurações de pesquisa de texto:

Configuração

Dicionário

Idioma

Mode

tokenizer_chinese

tokenizer_chinese_dict

Chinês

mixed

tokenizer_japanese

tokenizer_japanese_dict

Japonês

discard

tokenizer_korean

tokenizer_korean_dict

Coreano

discard

Configuração

Dicionário

Idioma

Mode

tokenizer_chinese

tokenizer_chinese_dict

Chinês

mixed

tokenizer_japanese

tokenizer_japanese_dict

Japonês

discard

tokenizer_korean

tokenizer_korean_dict

Coreano

discard

Os três dicionários definem Stemmer = 'english' e usam os default Normalize = 'NFKC' e Lowercase = 'true'.

Para obter exemplos de ponta a ponta que usam essas configurações, consulte CJK text.

Definir uma configuração personalizada​

Para escolher outro modo ou alterar as opções default, crie um dicionário do padrão tokenizer_morph e uma configuração de pesquisa de texto que mapeie os tipos de tokens PostgreSQL para ele, conforme mostrado abaixo. Este exemplo usa o modo chinês none para consultas de frase:

SQL
CREATE TEXT SEARCH DICTIONARY chinese_none_dict (
TEMPLATE = tokenizer_ext.tokenizer_morph,
Language = 'chinese',
Mode = 'none',
Stemmer = 'english'
);

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

ALTER TEXT SEARCH CONFIGURATION chinese_none_cfg
ALTER MAPPING FOR asciiword, word, numword, hword_asciipart, hword_part, hword_numpart
WITH chinese_none_dict;

SELECT to_tsvector('chinese_none_cfg', '现代分布式文件系统架构')
@@ phraseto_tsquery('chinese_none_cfg', '分布式文件系统 架构');

Opções​

Especifique as opções de tokenizer_morph 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

Language

chinese, japanese ou korean

Obrigatório

Seleciona o analisador específico da linguagem.

Mode

none, discard ou mixed

Obrigatório

Controla a saída composta e de subpalavras. Os modos suportados dependem de Language: none ou mixed para chinês, none ou discard para japonês e none, discard ou mixed para coreano.

Normalize

NFC, NFKC ou none

NFKC

Normaliza o texto antes da segmentação. NFC preserva distinções de compatibilidade. Por exemplo, ABC de largura total é convertido em letras minúsculas para abc em vez de ser convertido em abc, portanto, não é reduzido.

Lowercase

boolean

true

Converte lexemas emitidos para minúsculas. Stemmer = 'english' exige Lowercase = 'true'.

Stemmer

english

Nenhuma

Remove apenas lexemas feitos inteiramente de letras ASCII. Omitir esta opção para desativar a derivação de inglês.

Opção

Tipo

Padrão

Descrição

Language

chinese, japanese ou korean

Obrigatório

Seleciona o analisador específico da linguagem.

Mode

none, discard ou mixed

Obrigatório

Controla a saída composta e de subpalavras. Os modos suportados dependem de Language: none ou mixed para chinês, none ou discard para japonês e none, discard ou mixed para coreano.

Normalize

NFC, NFKC ou none

NFKC

Normaliza o texto antes da segmentação. NFC preserva distinções de compatibilidade. Por exemplo, ABC de largura total é convertido em letras minúsculas para abc em vez de ser convertido em abc, portanto, não é reduzido.

Lowercase

boolean

true

Converte lexemas emitidos para minúsculas. Stemmer = 'english' exige Lowercase = 'true'.

Stemmer

english

Nenhuma

Remove apenas lexemas feitos inteiramente de letras ASCII. Omitir esta opção para desativar a derivação de inglês.

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​