Índices de pesquisa de texto completo em tabelas gerenciadas no Unity Catalog

Importante

Esse recurso está em Beta. Os administradores do workspace podem controlar o acesso a esse recurso na página Visualizações . Consulte Gerenciar visualizações do Azure Databricks.

Um índice de pesquisa de texto completo acelera consultas em uma ou mais colunas de texto de uma tabela gerenciada do Delta Lake ou Iceberg. O índice dá suporte à correspondência de subcadeia de caracteres e à correspondência de palavras. Quando você consulta a tabela com as funções search ou isearch, Azure Databricks usa o índice para ignorar arquivos que têm a garantia de não conter linhas correspondentes. Isso reduz significativamente a quantidade de dados verificados, especialmente para pesquisas seletivas.

Importante

Os índices criados durante a versão Beta não têm garantia de serem compatíveis com versões posteriores. Quando o recurso atinge a Visualização Pública, você deve remover índices existentes e criar novos.

Requirements

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

Computação

Os índices de pesquisa de texto completo estão disponíveis apenas em Azure Databricks Runtime 18.2 e superior, e você deve habilitar esse recurso Beta nas configurações do workspace. Consulte Gerenciar visualizações do Azure Databricks.

Permissions

Para criar um índice de pesquisa:

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

Configuração de tabelas

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

• Você deve criar o índice no mesmo catálogo e esquema que a tabela base.
• A tabela é uma tabela Delta Lake gerenciada ou uma tabela Iceberg gerenciada.
• O acompanhamento de linhas está habilitado (delta.enableRowTracking = true). Consulte acompanhamento de linhas no Databricks.
• As colunas indexadas são do tipo STRING, VARIANTou STRUCTARRAY. STRING as colunas usam a UTF8_BINARY ordenação.
• 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 usa nenhum recurso da lista de limitações, incluindo: Compartilhamento Delta, clonagem superficial, controles de acesso baseados em atributo, políticas de segurança em nível de linha e máscaras de coluna. Confira Limitações.

Para obter informações sobre os requisitos de protocolo de tabela, que se aplicam às tabelas Delta Lake e Iceberg, consulte a compatibilidade de recursos e protocolos do Delta Lake.

Criar um índice de pesquisa de texto completo

Você pode criar até quatro índices em uma única tabela, 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:

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

A sintaxe completa é:

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

index_name deve ser exclusivo dentro do esquema e não pode corresponder a um nome de tabela existente.

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

Warning

Se CREATE SEARCH INDEX e REFRESH INDEX falhar na execução intermediária, execute REFRESH INDEX para se recuperar de uma falha parcial.

Opções

A OPTIONS cláusula aceita as seguintes chaves:

Chave	Valores	Default	Description
tokenizer	ngram, split	ngram	Como o texto é tokenizado para indexação. Consulte Selecionar um tokenizador para seu caso de uso.
ngram_size	inteiro em [3, 10]	5	Comprimento dos n-gramas produzidos. Somente válido quando tokenizer = 'ngram'.
min_token_length	inteiro >= 1	3	Comprimento mínimo dos tokens a serem mantidos. Tokens mais curtos do que esses são descartados durante a indexação. Somente válido 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 para seu caso de uso

Os índices de pesquisa têm duas opções de tokenizer disponíveis, dependendo do seu caso de uso:

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

Para criar um índice de n-grama com um tamanho de n-grama de 4:

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

Para criar um índice split com um tamanho mínimo do token de 2:

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

Consultar dados usando search e isearch

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

• search: diferencia maiúsculas de minúsculas.
• isearch: não diferencia maiúsculas de minúsculas.

Selecione search ou isearch com base na sua necessidade de diferenciar maiúsculas de minúsculas. Quando as colunas indexadas estão incluídas em um índice de pesquisa de texto completo, o Azure Databricks usa o índice para ignorar arquivos que certamente não contêm linhas correspondentes. Os índices de pesquisa não afetam os resultados.

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

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

Arguments

search e isearch aceite os seguintes argumentos:

• target deve ser do tipo STRING, VARIANT, STRUCTou ARRAY, os mesmos tipos que a indexação permite. Os destinos são desduplicados.
• pattern deve ser um literal de cadeia de caracteres não nula.
• mode especifica como pattern corresponde a cada target:
  • substring (padrão): pattern corresponde a uma subcadeia dentro de cada target.
  • word: pattern é segmentado em tokens de palavra usando a mesma regra do tokenizador split. A função retorna true se cada palavra em pattern aparecer em pelo menos um destino, independentemente da ordem. Consulte Selecionar um tokenizador para seu caso de uso.

Returns

search e isearch retornam um valor BOOLEAN com lógica ternária:

• true se pelo menos um destino não nulo corresponder.
• null se não houver correspondências de destino não nulas, mas pelo menos um destino for null.
• false se todos os alvos forem não nulos e nenhum corresponder.

Exemplos

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

-- 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. Consulte Atualizar um índice.

Azure Databricks mantém a correção da consulta, 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 usa uma verificação de tabela para os registros não indexados.

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

Descrever ou exibir um índice

Para exibir informações sobre um índice:

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, adicionando entradas para novas linhas:

REFRESH INDEX log_idx;

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

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

REFRESH INDEX log_idx FULL;

Uma atualização completa requer mais recursos de computação do que uma atualização incremental. Com o tempo, as atualizações incrementais acumulam entradas obsoletas, que aumentam o tamanho do índice e afetam negativamente o desempenho.

Excluir um índice

Para remover um índice, execute o seguinte:

DROP INDEX log_idx;

Para evitar um erro devido à ausência de índices, use:

DROP INDEX IF EXISTS log_idx;

Note

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

Limitações

Os índices de pesquisa de texto completo têm as seguintes limitações:

• Não há suporte para renomear uma coluna indexada na tabela base ou alterar seu tipo de dados.
• Não há suporte para tabelas com compartilhamento Delta. Se você adicionar a tabela base como uma origem ou destino de Compartilhamento Delta depois de criar o índice, Azure Databricks ignorará o índice de pesquisa.
• Não há suporte para tabelas com clones rasos. Se você adicionar a tabela base como uma fonte de clone superficial depois de criar o índice, Azure Databricks ignorará o índice de pesquisa.
• Não há suporte para tabelas com controles de acesso baseados em atributo, máscaras de coluna ou políticas de segurança em nível de linha. Se você adicionar qualquer um desses controles a uma tabela com um índice de pesquisa, Azure Databricks ignorará o índice de pesquisa. Consulte Conceitos fundamentais do controle de acesso baseado em atributos (ABAC).