Index de recherche en texte intégral sur les tables gérées par le catalogue Unity

Un index de recherche en texte intégral accélère les recherches sur une ou plusieurs colonnes de texte d’une table Delta Lake ou Iceberg managée. L’index prend en charge la correspondance des sous-chaînes et la correspondance de mots. Lorsque vous interrogez la table avec les fonctions search ou isearch, Azure Databricks utilise l’index pour ignorer les fichiers garantis de ne pas contenir de lignes correspondantes. Cela réduit considérablement la quantité de données analysées, en particulier pour les recherches sélectives.

Requirements

Les index de recherche en texte intégral ont des exigences en matière de calcul, de table de base et d’autorisations de schéma et de configuration de table de base.

Compute

Les index de recherche en texte intégral sont disponibles uniquement dans Azure Databricks Runtime 18.2 et versions ultérieures, et vous devez activer cette fonctionnalité bêta dans les paramètres de votre espace de travail. Consultez Gérer les préversions d’Azure Databricks.

Permissions

Pour créer un index de recherche :

• Vous devez disposer de l’autorisation MODIFY pour la table référencée dans l’index de recherche.
• Vous devez disposer de l’autorisation CREATE TABLE sur le schéma parent. Un propriétaire de schéma ou un utilisateur disposant du privilège MANAGE peut vous CREATE TABLE accorder des privilèges sur le schéma.

Configuration de table

Avant de créer un index de recherche en texte intégral, la table de base doit satisfaire toutes les conditions suivantes :

• Vous devez créer l’index dans le même catalogue et le même schéma que la table de base.
• La table est une table Delta Lake gérée ou une table Iceberg managée.
• Le suivi des lignes est activé (delta.enableRowTracking = true). Consultez le suivi des lignes dans Azure Databricks.
• Les colonnes indexées sont de type STRING, VARIANT, STRUCTou ARRAY. Les colonnes STRING utilisent le classement UTF8_BINARY.
• Une colonne de type STRUCT contient au moins un champ feuille de type STRING, VARIANT ou ARRAY, à n'importe quel niveau d'imbrication ; les autres champs feuilles sont ignorés.
• Le tableau n’utilise aucune fonctionnalité de la liste des limitations, notamment : OpenSharing, clonage peu profond, contrôles d’accès basés sur les attributs, stratégies de sécurité au niveau des lignes et masques de colonne. Consultez Limitations.

Pour plus d’informations sur les exigences de protocole de table, qui s’appliquent aux tables Delta Lake et Iceberg, consultez la compatibilité des fonctionnalités et les protocoles Delta Lake.

Créer un index de recherche en texte intégral

Vous pouvez créer jusqu’à quatre index sur une table unique, chacune sur une colonne différente.

Permet CREATE SEARCH INDEX de créer un index sur une ou plusieurs colonnes de texte. L’exemple suivant indexe deux colonnes de texte d’une table de journal existante :

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

La syntaxe complète est la suivante :

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

index_name doit être unique dans le schéma et ne peut pas correspondre à un nom de table existant.

Pour contrôler la façon dont le texte est tokenisé, consultez Options.

Options

La OPTIONS clause accepte les clés suivantes :

Pour plus d’informations sur les erreurs liées à des options non valides, consultez la condition d’erreur SEARCH_INDEX_INVALID_PARAMETERS.

Sélectionner un tokenizer pour votre cas d’usage

Les index de recherche ont 2 options de tokenizer disponibles, en fonction de votre cas d’usage :

Pour créer un index n-gramme avec une taille de n-gramme égale à 4 :

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

Pour créer un split index avec une longueur minimale de jeton de 2 :

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

Interroger des données à l’aide search et isearch

Azure Databricks a deux fonctions SQL pour tester si un modèle de recherche est présent dans une ou plusieurs cibles de texte :

• search : sensible à la casse.
• isearch : insensible à la casse.

Sélectionnez search ou isearch selon vos besoins en matière de sensibilité à la casse. Lorsque les colonnes indexées sont couvertes par un index de recherche en texte intégral, Azure Databricks utilise l’index pour ignorer les fichiers garantis de ne pas contenir de lignes correspondantes. Les index de recherche n’affectent pas les résultats.

Les index accélèrent les requêtes le plus lorsque le modèle de recherche apparaît dans une petite fraction des fichiers de la table.

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

Arguments

search et isearch acceptez les arguments suivants :

• targetdoit être de type STRING, , VARIANTSTRUCTou ARRAY, les mêmes types que l’indexation autorise. Les doublons parmi les cibles sont supprimés.
• pattern doit être un littéral de chaîne non nul.
• mode spécifie comment pattern correspond à chaque target:
  • substring (valeur par défaut) : pattern est mis en correspondance en tant que sous-chaîne dans chaque target.
  • word: pattern est divisé en jetons de mots selon la même règle que le tokeniseur split. La fonction retourne vrai si chaque mot de pattern apparaît dans au moins une cible, quel que soit l’ordre. Consultez Sélectionner un tokenizer pour votre cas d’usage.

Returns

search et isearch renvoient une valeur BOOLEAN à logique ternaire :

• true si au moins une cible non nulle correspond.
• null si aucune cible non nulle ne correspond mais qu’au moins une cible est null.
• false si toutes les cibles sont non nulles et qu’aucune ne correspond.

Exemples

Les exemples suivants illustrent les requêtes search et isearch courantes :

-- 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');

Gérer les index

Utilisez les opérations suivantes pour gérer les index de recherche en texte intégral :

Décrire ou afficher un index

Pour afficher des informations sur un index :

DESCRIBE INDEX log_idx;

Actualiser un index

Les index de recherche en texte intégral ne sont pas mis à jour automatiquement lorsque la table de base change.

Pour mettre à jour l’index, ajoutez des entrées pour les nouvelles lignes :

REFRESH INDEX log_idx;

REFRESH INDEX est une opération incrémentielle et d’ajout uniquement. Il indexe de nouvelles données, mais ne supprime pas les entrées pour les lignes supprimées.

Pour mettre à jour l’index, ajoutez des entrées pour de nouvelles lignes et supprimez des entrées pour les lignes supprimées, utilisez REFRESH INDEX ... FULL:

REFRESH INDEX log_idx FULL;

Une actualisation complète nécessite plus de ressources de calcul qu’une actualisation incrémentielle. Au fil du temps, les actualisations incrémentielles accumulent des entrées obsolètes, ce qui augmente la taille de l’index et affecte négativement les performances.

Supprimer un index

Pour supprimer un index, exécutez ce qui suit :

DROP INDEX log_idx;

Pour éviter une erreur pour les index manquants, utilisez :

DROP INDEX IF EXISTS log_idx;

Limites

Les index de recherche en texte intégral présentent les limitations suivantes :

• Renommer une colonne indexée dans la table de base, ou modifier son type de données, n’est pas pris en charge.
• Les tables avec OpenSharing ne sont pas prises en charge. Si vous ajoutez la table de base en tant que source ou cible OpenSharing après avoir créé l’index, Azure Databricks ignore l’index de recherche.
• Les tables avec des clones superficiels ne sont pas prises en charge. Si vous ajoutez la table de base en tant que source de clone peu profonde après avoir créé l’index, Azure Databricks ignore l’index de recherche.
• Les tables avec des contrôles d’accès basés sur des attributs, des masques de colonne ou des stratégies de sécurité au niveau des lignes ne sont pas prises en charge. Si vous ajoutez l’un de ces contrôles à une table avec un index de recherche, Azure Databricks ignore l’index de recherche. Consultez les concepts fondamentaux du contrôle d’accès basé sur les attributs (ABAC).