Indici di ricerca full-text nelle tabelle gestite di Unity Catalog

Un indice di ricerca full-text accelera le ricerche in una o più colonne di testo di una tabella Delta Lake o Iceberg gestita. L'indice supporta la ricerca per sottostringa e la ricerca di parole. Quando si esegue una query sulla tabella con le funzioni search o isearch, Azure Databricks usa l'indice per ignorare i file che non contengono righe corrispondenti. Ciò riduce significativamente la quantità di dati analizzati, soprattutto per ricerche selettive.

Requirements

Gli indici di ricerca full-text richiedono risorse di calcolo, autorizzazioni sulla tabella di base e sullo schema e una configurazione della tabella di base adeguata.

Compute

Gli indici di ricerca full-text sono disponibili solo in Azure Databricks Runtime 18.2 e versioni successive ed è necessario abilitare questa funzionalità Beta nelle impostazioni dell'area di lavoro. Vedere Gestire le anteprime di Azure Databricks.

Permissions

Per creare un indice di ricerca:

• È necessario disporre dell'autorizzazione MODIFY per la tabella a cui si fa riferimento nell'indice di ricerca.
• È necessario disporre dell'autorizzazione CREATE TABLE per lo schema padre. Un proprietario dello schema o un utente con il privilegio MANAGE può concederti privilegi CREATE TABLE sullo schema.

Configurazione delle tabelle

Prima di creare un indice di ricerca full-text, la tabella di base deve soddisfare tutte le operazioni seguenti:

• È necessario creare l'indice nello stesso catalogo e nello stesso schema della tabella di base.
• La tabella è una tabella Delta Lake gestita o una tabella Iceberg gestita.
• Il rilevamento delle righe è abilitato (delta.enableRowTracking = true). Vedi Tracciamento delle righe in Azure Databricks.
• Le colonne indicizzate sono di tipo STRING, VARIANT, STRUCTo ARRAY. STRING colonne usano la regola di confronto UTF8_BINARY.
• Una colonna STRUCT contiene almeno un campo foglia STRING, VARIANT o ARRAY a qualsiasi livello di annidamento; gli altri campi foglia vengono ignorati.
• La tabella non usa funzionalità dell'elenco delle limitazioni, tra cui: OpenSharing, clonazione superficiale, controlli di accesso basati su attributi, criteri di sicurezza a livello di riga e maschere di colonna. Vedere Limitazioni.

Per informazioni sui requisiti del protocollo di tabella, che si applicano alle tabelle Delta Lake e Iceberg, vedere Compatibilità e protocolli delle funzionalità delta Lake.

Crea un indice di ricerca a testo completo

È possibile creare fino a quattro indici in una singola tabella, ognuno in una colonna diversa.

Usare CREATE SEARCH INDEX per creare un indice su una o più colonne di testo. Nell'esempio seguente vengono indicizzate due colonne di testo di una tabella di log esistente:

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

La sintassi completa è:

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

index_name deve essere univoco all'interno dello schema e non può corrispondere a un nome di tabella esistente.

Per controllare la modalità di tokenizzazione del testo, vedere Opzioni.

Opzioni

La OPTIONS clausola accetta le chiavi seguenti:

Per informazioni dettagliate sugli errori di opzione non validi, vedere la condizione di errore SEARCH_INDEX_INVALID_PARAMETERS.

Seleziona un tokenizer per il tuo caso d'uso

Gli indici di ricerca hanno 2 opzioni di tokenizer disponibili, a seconda del caso d'uso:

Per creare un indice n-gram con una dimensione n-gram di 4:

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

Per creare un split indice con una lunghezza minima di token pari a 2:

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

Interrogare i dati usando search e isearch

Azure Databricks dispone di due funzioni SQL per verificare se un criterio di ricerca è presente in una o più destinazioni di testo:

• search: Distinzione tra maiuscole e minuscole.
• isearch: senza distinzione tra maiuscole e minuscole.

Seleziona search o isearch in base al requisito di distinzione tra maiuscole e minuscole. Quando le colonne indicizzate sono coperte da un indice di ricerca full-text, Azure Databricks utilizza l'indice per saltare i file che sicuramente non contengono righe corrispondenti. Gli indici di ricerca non influiscono sui risultati.

Gli indici accelerano la maggior parte delle query quando il criterio di ricerca viene visualizzato in una piccola frazione dei file della tabella.

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

Arguments

search e isearch accettano i seguenti argomenti:

• targetdeve essere di tipo STRING, VARIANTSTRUCT, o ARRAY, gli stessi tipi consentiti dall'indicizzazione. Le destinazioni vengono deduplicate.
• pattern deve essere una stringa letterale non nulla.
• mode specifica come pattern corrisponde a ogni target:
  • substring (impostazione predefinita): pattern viene trovato come sottostringa all'interno di ogni target.
  • word: pattern è suddiviso in token di parola usando la stessa regola del split tokenizer. La funzione restituisce true se ogni parola in pattern viene visualizzata in almeno una destinazione, indipendentemente dall'ordine. Consulta Seleziona un tokenizer in base al tuo caso d'uso.

Returns

search e isearch restituiscono un BOOLEAN valore con logica a tre valori:

• true se almeno una destinazione non Null corrisponde.
• null se nessun target non null corrisponde, ma almeno un target è null.
• false se tutte le destinazioni sono non nulle e nessuna coincide.

Examples

I seguenti esempi mostrano query comuni di 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');

Gestire gli indici

Usare le operazioni seguenti per gestire gli indici di ricerca full-text:

Descrivere o visualizzare un indice

Per visualizzare informazioni su un indice:

DESCRIBE INDEX log_idx;

Aggiornare un indice

Gli indici di ricerca full-text non vengono aggiornati automaticamente quando cambia la tabella di base.

Per aggiornare l'indice, aggiungere voci per le nuove righe:

REFRESH INDEX log_idx;

REFRESH INDEX è un'operazione incrementale di sola aggiunta. Indicizza i nuovi dati, ma non rimuove le voci relative alle righe cancellate.

Per aggiornare l'indice, sia aggiungendo voci relative alle nuove righe sia rimuovendo voci relative alle righe eliminate, utilizzare REFRESH INDEX ... FULL:

REFRESH INDEX log_idx FULL;

Un aggiornamento completo richiede più risorse di calcolo rispetto a un aggiornamento incrementale. Nel corso del tempo, gli aggiornamenti incrementali accumulano voci non aggiornate, che aumentano le dimensioni dell'indice e influiscono negativamente sulle prestazioni.

Eliminare un indice

Per eliminare un indice, eseguire quanto segue:

DROP INDEX log_idx;

Per evitare un errore per gli indici mancanti, usare:

DROP INDEX IF EXISTS log_idx;

Limitazioni

Gli indici di ricerca full-text presentano le limitazioni seguenti:

• La ridenominazione di una colonna indicizzata nella tabella di base o la modifica del tipo di dati non è supportata.
• Le tabelle con OpenSharing non sono supportate. Se si aggiunge la tabella di base come origine o destinazione OpenSharing dopo la creazione dell'indice, Azure Databricks ignora l'indice di ricerca.
• Le tabelle con cloni superficiali non sono supportate. Se si aggiunge la tabella di base come origine clone superficiale dopo la creazione dell'indice, Azure Databricks ignora l'indice di ricerca.
• Le tabelle con controlli di accesso basato su attributi, maschere di colonna o criteri di sicurezza a livello di riga non sono supportate. Se si aggiunge uno di questi controlli a una tabella con un indice di ricerca, Azure Databricks ignora l'indice di ricerca. Vedere Concetti di base per il controllo degli accessi in base agli attributi.See Core concepts for attribute-based access control (ABAC).