Documenter des données dans Catalog Explorer à l’aide de commentaires Markdown

  • Article

Vous pouvez utiliser Catalog Explorer pour afficher des commentaires sur des ressources de données telles que des catalogues, des schémas et des tables. Cet article décrit comment les propriétaires d’objets ou les utilisateurs disposant d’autorisations de modification sur des objets peuvent ajouter ces commentaires manuellement à l’aide de Catalog Explorer.

Remarque

Pour les tables et les colonnes, Catalog Explorer vous permet également de voir des suggestions de commentaires générées par l’IA et de les appliquer. Consultez Ajouter des commentaires générés par l’IA à une table.

Si vous utilisez Unity Catalog, vous pouvez utiliser Catalog Explorer pour ajouter et modifier des commentaires sur tous les objets autres que ceux d'un catalogue Delta Sharing.

Pour les données du metastore Hive, vous pouvez utiliser Catalog Explorer pour modifier les commentaires de table uniquement.

Markdown fournit un ensemble robuste d’options pour documenter les données, en améliorant les options dont disposent les utilisateurs d’Azure Databricks pour améliorer la détectabilité et la compréhension des ressources de données partagées. L’utilisation de commentaires Markdown n’a aucun impact sur les performances des requêtes. Markdown ne s’affiche pas lorsqu’il est retourné par des instructions DESCRIBE.

Ajouter des commentaires markdown à des objets de données à l’aide de Catalog Explorer

Catalog Explorer affiche des commentaires pour les catalogues, les schémas et les tables et les autres ressources sous le nom de l'objet.

  • Si aucun commentaire n’existe, une option Ajouter un commentaire s’affiche.
  • Vous pouvez activer/désactiver l’affichage des commentaires avec les options Masquer le commentaire et Afficher le commentaire .

Markdown dans les commentaires de table s'affiche dans Catalog Explorer dès que vous enregistrez les modifications.

  • Cliquez sur l’icône de crayon pour modifier les commentaires.
  • Cliquez sur Enregistrer pour mettre à jour les commentaires.

Vous pouvez également utiliser SQL pour ajouter des commentaires de table lors de la création de la table ou des actions ALTER TABLE.

Lors de la modification de commentaires sur une table Delta Lake, une opération SET TBLPROPERTIES dans l’historique de table enregistre la requête SQL utilisée pour définir les commentaires de table actuels.

Exemple de documentation Markdown prise en charge

Catalog Explorer prend en charge la syntaxe Markdown de base. Vous ne pouvez pas utiliser Markdown pour les emojis, les images et les tables Markdown rendues. Catalog Explorer affiche uniquement deux niveaux d'en-têtes Markdown.

L’exemple suivant montre un bloc de code Markdown brut. Copiez ce Markdown dans un commentaire dans Catalog Explorer, puis cliquez sur Enregistrer pour afficher l'aperçu.

# Header 1
## Header 2

**bold text**

*italics text*

~~strikethrough text~~

`monospace text`

---

> Block quote

Ordered list:
1. Item 1
1. Item 2
1. Item 3

Unordered list:
- Item a
- Item b
- Item c

def my_function() : return my_value


[Link](https://www.markdownguide.org/cheat-sheet/#basic-syntax)

Plus de ressources

Vous pouvez également utiliser la fonctionnalité suivante pour ajouter des commentaires à des objets de données :

  • La commande COMMENT ON. Cette option ne prend pas en charge les commentaires de colonne.
  • L’option COMMENT lorsque vous utilisez la commande CREATE <object> ou ALTER <object>. Pour obtenir des exemples, consultez CREATE TABLE [USING] et ALTER TABLE. Cette option prend en charge les commentaires de colonne.
  • Commentaires générés par l’IA (également appelés documentation générée par l’IA) dans Catalog Explorer. Vous pouvez afficher un commentaire suggéré par un modèle de langage volumineux (LLM) qui prend en compte les métadonnées de la table, telles que le schéma de table et les noms de colonnes, et modifier le commentaire ou l’accepter tel quel pour l’ajouter. Cette option prend uniquement en charge les tables et les colonnes. Consultez Ajouter des commentaires générés par l’IA à une table.