Ajouter des commentaires aux ressources de données et d’IA

Cet article présente les commentaires pour les ressources de données et d’IA et explique comment les ajouter. Les commentaires peuvent vous aider, vous et d’autres utilisateurs, à trouver et gérer les ressources de données et d’IA dont vous avez besoin.

Les commentaires fournissent un champ de métadonnées pour annoter vos objets sécurisables. Vous pouvez ajouter des commentaires à n’importe quel objet sécurisable dans Unity Catalog, comme les catalogues, les schémas, les tables, les volumes, les modèles IA, etc. Vous pouvez également ajouter des commentaires à des colonnes de table.

Vous pouvez ajouter des commentaires manuellement, ou vous pouvez laisser Databricks créer des commentaires générés par l’IA pour vous. Les commentaires générés par l’IA (également appelés documentation générée par l’IA) sont disponibles pour les tables et les colonnes de table. Consultez Ajouter des commentaires générés par l’IA à une table.

Lorsque vous modifiez des commentaires pour une table Unity Catalog (ou une table Delta Lake dans le metastore Hive hérité), une opération SET TBLPROPERTIES dans l’historique des tables enregistre la requête SQL utilisée pour définir le commentaire de table.

Avant de commencer

Vous devez répondre aux exigences suivantes pour ajouter ou modifier des commentaires :

• Pour ajouter ou modifier des commentaires sur un catalogue, un schéma, un volume, un modèle, un partage, un destinataire, un fournisseur, des informations d’identification de stockage, un emplacement externe ou une connexion, vous devez être le propriétaire de l’objet.
• Pour ajouter ou modifier des commentaires sur une table ou une colonne, vous devez être le propriétaire ou disposer des privilèges suivants :
  • MODIFY et SELECT sur la table.
  • USE CATALOG et USE SCHEMA sur le catalogue et le schéma parents.
• Vous devez utiliser un entrepôt SQL ou un autre calcul prenant en charge Unity Catalog (calcul partagé ou mono-utilisateur).
• Pour utiliser des commentaires générés par l’IA, votre espace de travail doit être activé pour les fonctionnalités d’assistance par IA. Consultez Ajouter des commentaires générés par l’IA à une table.

Ajouter et modifier des commentaires

Vous pouvez ajouter des commentaires à des objets sécurisables ou les modifier à l’aide de commandes SQL ou de l’Explorateur de catalogues.

Explorateur de catalogues

1. Dans la barre latérale de l’espace de travail, cliquez sur Catalogue pour ouvrir l’Explorateur de catalogues.

2. Recherchez et sélectionnez l’objet sur lequel vous souhaitez ajouter des commentaires.

   Les objets Données et IA sont répertoriés et peuvent faire l’objet d’une recherche dans le volet Catalogue . Les partages, les informations d’identification de stockage, les emplacements externes et les connexions sont accessibles à l’aide du menu qui s’ouvre lorsque vous cliquez sur l’icône d’engrenage .

3. Ajoutez un commentaire ou modifiez un commentaire existant.

   • Pour ajouter un commentaire à une table à l’aide de commentaires générés par l’IA, affichez Commentaire suggéré par l’IA dans le volet droit de l’onglet Vue d’ensemble. L’affichage peut prendre quelques secondes. Cliquez sur Accepter pour l’utiliser tel quel ou sur Modifier, puis enregistrez-le.
   • Pour ajouter un commentaire à une colonne de table à l’aide de commentaires générés par l’IA, cliquez sur le bouton Générer par IA au-dessus de la liste des colonnes. Databricks génère des commentaires pour chaque colonne. Acceptez-les comme tel quel ou modifiez-les. Cliquez sur la coche pour enregistrer les modifications.
   • Pour ajouter un commentaire à un objet qui ne prend pas en charge les commentaires générés par l’IA, cliquez sur Ajouter un commentaire pour ajouter un commentaire.
   • Pour ajouter un commentaire à une colonne de table sans utiliser de commentaires générés par l’IA, cliquez sur l’icône Ajouter un commentaire dans la ligne de colonne.
   • Si un commentaire existe déjà, il apparaît dans le volet droit sous l’onglet Vue d’ensemble ou sous le nom de l’objet. S’il n’est pas généré par l’IA, cliquez sur l’icône de modification pour le modifier.

Vous pouvez utiliser la syntaxe Markdown de base pour mettre en forme des commentaires dans l’interface utilisateur de l’Explorateur de catalogues. La mise en forme Markdown ne s’affiche pas lorsqu’elle est retournée par des instructions DESCRIBE. Toutes les syntaxes de base sont prises en charge dans l’Explorateur de catalogues, à l’exception des images, et seuls deux niveaux de titre sont affichés. Pour plus d’informations, consultez Syntaxe de base.

Pour plus d’informations sur les commentaires générés par l’IA, consultez Ajouter des commentaires générés par l’IA à une table.

SQL

Vous pouvez utiliser une commande SQL pour ajouter un littéral de chaîne en tant que commentaire à n’importe quel objet sécurisable dans Unity Catalog et aux tables gérées dans le metastore Hive hérité. La commande SQL que vous utilisez dépend de l’objet pour lequel vous souhaitez ajouter ou modifier un commentaire :

• Pour ajouter ou mettre à jour un commentaire pour n’importe quel objet sécurisable existant, à l’exception des colonnes de table, utilisez la commande COMMENT ON. Voir COMMENT ON.

  Vous pouvez également utiliser l’option COMMENT avec la commande ALTER <object> de l’objet (par exemple, ALTER TABLE). Consultez l’article de référence SQL pour la commande ALTER <object>.

• Pour ajouter ou mettre à jour un commentaire de colonne pour une table existante, utilisez la commande ALTER TABLE avec la clause ALTER COLUMN et l’option COMMENT sur la colonne. Voir ALTER TABLE et Clause ALTER TABLE ... COLUMN.

• Pour ajouter un commentaire lorsque vous créez un objet, utilisez l’option COMMENT avec la commande CREATE <object>. Consultez l’article de référence SQL pour la commande CREATE <object> que vous souhaitez utiliser.