Índices de pesquisa de texto completo no Unity Catalog ger tabelas

info

Beta

Este recurso está em versão Beta. Os administradores do espaço de trabalho podem controlar o acesso a este recurso na página de Pré-visualizações . Veja as prévias do Gerenciador Databricks.

Um índice de pesquisa de texto completo acelera as buscas em uma ou mais colunas de texto de uma tabela de gerenciamento Delta Lake ou Iceberg . O índice suporta correspondência de subcadeias de caracteres e correspondência de palavras. Ao consultar a tabela com as funções search ou isearch , o Databricks usa o índice para ignorar arquivos que comprovadamente não contêm linhas correspondentes. Isso reduz significativamente a quantidade de dados analisados, especialmente para pesquisas seletivas.

importante

Não há garantia de que os índices criados durante a versão Beta sejam compatíveis com versões posteriores. Quando o recurso atingir a versão prévia pública, você deverá excluir os índices existentes e criar novos.

Requisitos

Os índices de pesquisa de texto completo têm requisitos de compute, permissões de tabela base e esquema, além de configuração da tabela base.

compute

Os índices de pesquisa de texto completo estão disponíveis apenas no Databricks Runtime 18.2 e versões superiores, e você deve habilitar esse recurso Beta nas configurações do seu workspace . Veja as prévias do Gerenciador Databricks.

Permissões

Para criar um índice de pesquisa:

• Você deve ter a permissão MODIFY para a tabela referenciada no índice de pesquisa.
• Você deve ter a permissão CREATE TABLE no esquema pai. Um proprietário de esquema ou usuário com o privilégio de gerenciar pode conceder a você CREATE TABLE privilégios no esquema.

Configuração da tabela

Antes de criar um índice de pesquisa de texto completo, a tabela base deve satisfazer todos os seguintes requisitos:

• Você deve criar o índice no mesmo catálogo e esquema da tabela base.
• A mesa é um gerô Delta Lake ou um gerô Iceberg .
• O envio de linha está habilitado (delta.enableRowTracking = true). Veja Acompanhamento de linha no Databricks.
• As colunas indexadas são do tipo STRING, VARIANT, STRUCT ou ARRAY. As colunas STRING usam a ordenação UTF8_BINARY .
• Uma coluna STRUCT contém pelo menos um campo folha STRING, VARIANT ou ARRAY em qualquer nível de aninhamento; outros campos folha são ignorados.
• A tabela não utiliza nenhum recurso da lista de limitações, incluindo: Delta Sharing, clonagem superficial, controles de acesso baseados em atributos, políticas de segurança em nível de linha e máscaras de coluna. Consulte as limitações.

Para obter informações sobre os requisitos de protocolo de tabela, que se aplicam tanto às tabelas Delta Lake quanto às Iceberg , consulte Compatibilidade e protocolos de recursosDelta Lake.

Criar um índice de pesquisa de texto completo

É possível criar até quatro índices em uma tabela única, cada um em uma coluna diferente.

Use CREATE SEARCH INDEX para criar um índice em uma ou mais colunas de texto. O exemplo a seguir indexa duas colunas de texto de uma tabela de log existente:

SQL

CREATE SEARCH INDEX log_idx
ON logs (message, error_detail);

A sintaxe completa é:

SQL

CREATE SEARCH INDEX [IF NOT EXISTS] index_name
  ON table_name ( column_name [, column_name ...] )
  [OPTIONS ( option_key = option_value [, ... ] )]

index_name Deve ser único dentro do esquema e não pode corresponder a um nome de tabela existente.

Para controlar como o texto é tokenizado, consulte Opções.

atenção

Se CREATE SEARCH INDEX e REFRESH INDEX falharem durante a execução, execute REFRESH INDEX para recuperar de uma falha parcial.

Opções

A cláusula OPTIONS aceita a seguinte chave:

Chave	Valores	Padrão	Descrição
tokenizer	ngram, split	ngram	Como o texto é tokenizado para indexação. Consulte Selecionar um tokenizador para o seu caso de uso.
ngram_size	inteiro em [3, 10]	5	Comprimento dos n-gramas produzidos. Válido somente quando tokenizer = 'ngram'.
min_token_length	inteiro >= 1	3	Comprimento mínimo dos tokens a serem mantidos. Tokens menores que este são descartados durante a indexação. Válido somente quando tokenizer = 'split'.

Para obter informações detalhadas sobre erros de opções inválidas, consulte a condição de erro SEARCH_INDEX_INVALID_PARAMETERS.

Selecione um tokenizador adequado ao seu caso de uso.

Os índices de pesquisa têm 2 opções de tokenização disponíveis, dependendo do seu caso de uso:

Tokenizador	Caso de uso	Descrição
ngram	Correspondência de subcadeia de caracteres.	Divide o texto em n-gramas sobrepostos de comprimento ngram_size.
split	Verificações de contenção de palavras inteiras.	Divide o texto em tokens de palavras. Um token é uma execução de letras Unicode (\p{L}) e marcas de combinação (\p{M}); qualquer outro caractere é um delimitador.

Para criar um índice n-gram com um tamanho de n-gram igual a 4:

SQL

CREATE SEARCH INDEX log_ngram_idx
  ON logs (message)
  OPTIONS (tokenizer = 'ngram', ngram_size = 4);

Para criar um índice split com um comprimento mínimo de tokens igual a 2:

SQL

CREATE SEARCH INDEX log_word_idx
  ON logs (message)
  OPTIONS (tokenizer = 'split', min_token_length = 2);

Consulta uso de dados search e isearch

O Databricks possui duas funções SQL para testar se um padrão de pesquisa está presente em um ou mais alvos de texto:

• search: Maiúsculas e minúsculas.
• isearchNão diferencia maiúsculas de minúsculas.

Selecione search ou isearch com base na sua necessidade de distinção entre maiúsculas e minúsculas. Quando as colunas indexadas são cobertas por um índice de pesquisa de texto completo, o Databricks usa o índice para ignorar arquivos que comprovadamente não contenham linhas correspondentes. Os índices de pesquisa não afetam os resultados.

Os índices aceleram as consultas principalmente quando o padrão de pesquisa aparece em uma pequena fração dos arquivos da tabela.

SQL

search( target [, target ... ] , 'pattern' [, mode => 'substring' | 'word' ] )
isearch( target [, target ... ] , 'pattern' [, mode => 'substring' | 'word' ] )

Argumentos

search e isearch aceitam os seguintes argumentos:

• target deve ser do tipo STRING, VARIANT, STRUCT ou ARRAY, os mesmos tipos que a indexação permite. Os alvos são desduplicados.
• pattern Deve ser uma string literal não nula.
• mode especifica como pattern corresponde a cada target:
  • substring (default): pattern é correspondido como uma substring dentro de cada target.
  • word: pattern é dividido em tokens de palavras usando a mesma regra do tokenizador split . A função retorna verdadeiro se cada palavra em pattern aparece em pelo menos um alvo, independentemente da ordem. Consulte Selecionar um tokenizador para o seu caso de uso.

Devoluções

search e isearch retorna um valor BOOLEAN com lógica de três valores:

• true se pelo menos um alvo não nulo corresponder.
• null se nenhum alvo não nulo corresponder, mas pelo menos um alvo for null.
• false se todos os alvos forem diferentes de zero e nenhum corresponder.

Exemplos

Os exemplos a seguir mostram consultas comuns com search e isearch :

SQL

-- Case-insensitive substring search across one column.
SELECT * FROM logs
WHERE isearch(message, 'connection refused');

-- Case-sensitive substring search across multiple columns.
SELECT * FROM logs
WHERE search(message, error_detail, '550e8400-e29b-41d4-a716-446655440000');

-- Word search: matches rows containing all three words, in any order.
SELECT * FROM audit_logs
WHERE search(message, 'user admin login', mode => 'word');

gerenciar índices

importante

Os índices de pesquisa de texto completo não são atualizados automaticamente quando a tabela base é alterada. Veja atualizar um índice.

O Databricks mantém a correção das consultas, independentemente da atualização do índice. Quando uma tabela contém dados não indexados, a consulta usa o índice existente para acelerar o acesso aos registros indexados e realiza uma varredura da tabela para os registros não indexados.

Utilize as seguintes operações para gerenciar índices de pesquisa de texto completo:

Descreva ou view um índice.

Para view informações sobre um índice:

SQL

DESCRIBE INDEX log_idx;

atualizar um índice

Os índices de pesquisa de texto completo não são atualizados automaticamente quando a tabela base é alterada.

Para atualizar o índice, adicione entradas para novas linhas:

SQL

REFRESH INDEX log_idx;

REFRESH INDEX É uma operação incremental, somente de acréscimo. Ele indexa novos dados, mas não remove entradas de linhas excluídas.

Para atualizar o índice, adicionando entradas para novas linhas e removendo entradas para linhas excluídas, use REFRESH INDEX ... FULL:

SQL

REFRESH INDEX log_idx FULL;

Uma refresh completa requer mais recursos compute do que uma refresh incremental. Com o tempo, as atualizações incrementais acumulam entradas obsoletas, o que aumenta o tamanho do índice e afeta negativamente o desempenho.

Remover um índice

Para eliminar um índice, execute o seguinte:

SQL

DROP INDEX log_idx;

Para evitar erros devido à falta de índices, utilize:

SQL

DROP INDEX IF EXISTS log_idx;

nota

Se você excluir a tabela base, o comando também excluirá os índices de pesquisa de texto completo.

Limitações

Os índices de pesquisa de texto completo apresentam as seguintes limitações:

• Renomear uma coluna indexada na tabela base ou alterar seu tipo de dados não é suportado.
• Tabelas com Delta Sharing não são suportadas. Se você adicionar a tabela base como uma origem ou destino Delta Sharing após criar o índice, Databricks ignorará o índice de pesquisa.
• Tabelas com clones superficiais não são suportadas. Se você adicionar a tabela base como uma fonte de clonagem superficial após criar o índice, o Databricks ignorará o índice de pesquisa.
• Tabelas com controles de acesso baseados em atributos, máscaras de coluna ou políticas de segurança em nível de linha não são suportadas. Se você adicionar qualquer um desses controles a uma tabela com um índice de pesquisa, o Databricks ignorará o índice de pesquisa. Consulte Conceitos básicos para controle de acesso baseado em atributos (ABAC).