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

Important

Cette fonctionnalité est en version bêta. Pour utiliser cette fonctionnalité, un administrateur de l’espace de travail doit activer SQL : index de recherche en texte intégral pour les tables gérées par Unity Catalog depuis la page Fonctionnalités en version préliminaire. Consultez Gérer les préversions d’Azure Databricks.

Trouver des lignes contenant un mot ou une sous-chaîne spécifique, comme un code d’erreur dans les messages de journal, peut nécessiter de scanner de grandes quantités de texte. 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 qui ne peuvent pas contenir de lignes correspondantes. Cela réduit considérablement la quantité de données analysées, en particulier pour les recherches sélectives.

Important

Les index créés pendant la version bêta ne sont pas garantis pour être compatibles avec les versions ultérieures. Lorsque la fonctionnalité atteint la préversion publique, vous devez supprimer les index existants et en créer de nouveaux.

Quand utiliser les index de recherche en texte intégral

Créez un index de recherche en texte intégral lorsque :

  • Vous recherchez régulièrement dans une ou plusieurs colonnes de texte d’une grande table gérée des mots ou des sous-chaînes.
  • Le motif de recherche apparaît dans une petite fraction des fichiers de la table. Les indices accélèrent le plus ces recherches sélectives.
  • Vous pouvez écrire les requêtes en utilisant les fonctions search ou isearch. Voir Interrogez les données à l’aide de search et isearch.

Ne créez pas d’index sur une table qui utilise une fonctionnalité listée dans les Limitations, comme la sécurité au niveau des lignes ou les masques de colonne. Azure Databricks ignore l’index sur ces tables.

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 ne sont disponibles que dans Databricks Runtime 18.3 et versions ultérieures, et vous devez activer cette fonction 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 répondre à toutes ces exigences :

  • 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.
  • L’optimisation prédictive est activée. Consultez Activer l’optimisation prédictive.
  • 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.

Note

Si CREATE SEARCH INDEX échoue, relancez-le.

Options

L’instruction OPTIONS accepte ces clés :

Clé Valeurs Par défaut Description
tokenizer ngram, split ngram Comment le texte est tokenisé pour l’indexation. Consultez Sélectionner un tokenizer pour votre cas d’usage.
ngram_size nombre entier dans [3, 10] 5 Longueur des n-grammes produits. Valide uniquement lorsque tokenizer = 'ngram'.
min_token_length entier >= 1 3 Longueur minimale des jetons à conserver. Les jetons plus courts que cette longueur sont supprimés lors de l’indexation. Valide uniquement lorsque tokenizer = 'split'.

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 :

Générateur de jetons Cas d’utilisation Description
ngram Correspondance de sous-chaîne. Fractionne le texte en n-grammes qui se chevauchent de longueur ngram_size.
split Vérifications de la présence de mots entiers. Divise le texte en unités lexicales. Un jeton est une série de lettres Unicode (\p{L}) et des marques de combinaison (\p{M}) ; tout autre caractère est un délimiteur.

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 acceptent ces arguments :

  • 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

Ces exemples montrent 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');

Rafraîchissement automatique de l’index

L’optimisation prédictive maintient les index de recherche en texte intégral à jour au fur et à mesure que la table de base évolue. Il ajoute des entrées pour les nouvelles lignes et supprime les entrées pour les lignes supprimées. Les rafraîchissements s’exécutent en arrière-plan, donc les données récemment écrites peuvent prendre du temps à être indexées.

On ne peut pas faire tourner REFRESH INDEX manuellement.

Si vous désactivez l’optimisation prédictive sur la table de base, ses indices cessent de se rafraîchir. Les requêtes restent correctes, mais elles scannent les données que l’index ne couvre pas, donc elles ralentissent à mesure que la table change. Pour reprendre les rafraîchissements, réactivez l’optimisation prédictive.

Les actualisations d’index s’exécutent comme des opérations d’optimisation prédictive sur le calcul serverless et sont facturées à votre compte. Voir Calcul et facturation.

Pour suivre les actualisations des index, interrogez la table du système d’optimisation prédictive pour le type d’opération REFRESH_INDEX. Ces lignes portent le nom et l’ID de l’index dans table_name et table_id. Consultez Informations de référence des tables système d’optimisation prédictive.

Gérer les index

Important

Azure Databricks conserve l’exactitude des requêtes, quelle que soit l’actualisation de l’index. Lorsqu’une table contient des données non indexées, la requête utilise l’index existant pour accélérer l’accès aux enregistrements indexés et utilise une analyse de table pour les enregistrements non indexés.

Utilisez ces opérations 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;

Supprimer un index

Pour supprimer un index, exécutez :

DROP INDEX log_idx;

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

DROP INDEX IF EXISTS log_idx;

Note

Si vous supprimez la table de base, la commande supprime également les index de recherche en texte intégral.

Limites

Les index de recherche en texte intégral comportent 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).