Índices de pesquisa em texto completo nas tabelas geridas do Unity Catalog

Um índice de pesquisa em texto completo acelera pesquisas numa ou mais colunas de texto de uma tabela gerida de Delta Lake ou Iceberg. O índice suporta correspondência de substrings e correspondência de palavras. Quando consultas a tabela com as funções search ou isearch, Azure Databricks usa o índice para saltar ficheiros que garantidamente não contêm linhas correspondentes. Isto reduz significativamente a quantidade de dados digitalizados, especialmente para consultas seletivas.

Requirements

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

Computação

Os índices de pesquisa em texto completo estão disponíveis apenas no Azure Databricks Runtime 18.2 e superiores, e deve ativar esta funcionalidade Beta nas definições do seu espaço de trabalho. Ver Gerir as pré-visualizações de Azure Databricks.

Permissions

Para criar um índice de pesquisa:

• Tem de ter a permissão MODIFY para a tabela referenciada no índice de pesquisa.
• Tem de ter a permissão CREATE TABLE no esquema principal. O proprietário do esquema ou um utilizador com o privilégio MANAGE pode conceder-lhe privilégios CREATE TABLE no esquema.

Configuração da tabela

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

• Tem de criar o índice no mesmo catálogo e esquema da tabela base.
• A tabela é uma tabela gerida do Delta Lake ou uma tabela gerida do Iceberg.
• O rastreamento de linhas está ativado (delta.enableRowTracking = true). Veja rastreio de linhas no Azure Databricks.
• Colunas indexadas são do tipo STRING, VARIANT, STRUCT, ou ARRAY. STRING as colunas usam a ordenação UTF8_BINARY.
• Uma STRUCT coluna contém pelo menos um STRING, VARIANT, ou ARRAY campo de folhas em qualquer profundidade de nidificação; outros campos de folhas são ignorados.
• A tabela não utiliza quaisquer funcionalidades da lista de limitações, incluindo: OpenSharing, clonagem superficial, controlos de acesso baseados em atributos, políticas de segurança ao nível das linhas e máscaras de coluna. Consulte Limitações.

Para informações sobre requisitos de protocolo de tabelas, que se aplicam tanto às tabelas Delta Lake como às Iceberg, consulte compatibilidade de características e protocolos Delta Lake.

Criar um índice de pesquisa em texto completo

Pode criar até quatro índices numa única tabela, cada um numa coluna diferente.

Use CREATE SEARCH INDEX para criar um índice sobre uma ou mais colunas de texto. O exemplo seguinte indexa duas colunas de texto de uma tabela logarítmica 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 único dentro do esquema e não pode corresponder a um nome de tabela existente.

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

Opções

A OPTIONS cláusula aceita as seguintes chaves:

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

Selecione um tokenizador para o seu caso de uso

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

Para criar um índice de n-gramas 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 uma extensão mínima 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

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

• search: Sensível de maiúsculas e minúsculas.
• isearch: Não sensível a maiúsculas e minúsculas.

Selecione search ou isearch com base no seu requisito de sensibilidade a maiúsculas e minúsculas. Quando as colunas indexadas estão abrangidas por um índice de pesquisa de texto completo, o Azure Databricks usa o índice para ignorar ficheiros que, comprovadamente, 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 numa pequena fração dos ficheiros da tabela.

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

Arguments

search e isearch aceitam os seguintes argumentos:

• target devem ser do tipo STRING, VARIANT, STRUCT, ou ARRAY, os mesmos tipos que a indexação permite. Os alvos são deduplicados.
• pattern deve ser uma cadeia de caracteres literal que não seja nula.
• mode especifica como pattern corresponde a cada target:
  • substring (por defeito): pattern é emparelhado como uma subcadeia dentro de cada target.
  • word: pattern é separado em tokens de palavras usando a mesma regra que o tokenizador split. A função retorna verdadeira se cada palavra em pattern aparecer em pelo menos um alvo, independentemente da ordem. Veja Selecionar um tokenizador para o seu caso de uso.

Devoluções

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

• true se pelo menos um alvo não nulo coincidir.
• null Se nenhum destino não nulo corresponder, mas pelo menos um destino for null.
• false se todos os alvos forem não-nulos e nenhum corresponder.

Exemplos

Os exemplos seguintes 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');

Gestão de índices

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

Descreva ou veja um índice

Para ver informações sobre um índice:

DESCRIBE INDEX log_idx;

Atualizar um índice

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

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

REFRESH INDEX log_idx;

REFRESH INDEX é uma operação incremental, apenas para acrescentar. Indexa novos dados, mas não remove entradas para linhas eliminadas.

Para atualizar o índice, tanto para adicionar entradas para novas linhas como para remover entradas para linhas eliminadas, use REFRESH INDEX ... FULL:

REFRESH INDEX log_idx FULL;

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

Eliminar um índice

Para eliminar um índice, execute o seguinte:

DROP INDEX log_idx;

Para evitar erros por falta de índices, use:

DROP INDEX IF EXISTS log_idx;

Limitações

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

• Renomear uma coluna indexada na tabela base, ou alterar o seu tipo de dados, não é suportado.
• Tabelas com OpenSharing não são suportadas. Se adicionar a tabela base como código fonte ou destino OpenSharing após criar o índice, o Azure Databricks ignora o índice de pesquisa.
• As tabelas com clonagens superficiais não são suportadas. Se adicionares a tabela base como uma fonte clone superficial após criar o índice, o Azure Databricks ignora o índice de pesquisa.
• Tabelas com controlos de acesso baseados em atributos, máscaras de coluna ou políticas de segurança ao nível de linha não são suportadas. Se adicionar algum destes controlos a uma tabela com um índice de pesquisa, o Azure Databricks ignora o índice de pesquisa. Ver Conceitos Fundamentais para controlo de acesso baseado em atributos (ABAC).