Documentar dados no Gerenciador de Catálogos usando comentários de markdown

  • Artigo

Os usuários podem utilizar o Gerenciador de Catálogos para exibir comentários sobre ativos de dados, como catálogos, esquemas e tabelas. Este artigo descreve como proprietários de objetos ou usuários com permissão para modificar objetos podem adicionar esses comentários manualmente usando o Gerenciador de Catálogos.

Observação

Em tabelas e colunas, o Gerenciador de Catálogos também permite que você veja e aplique sugestões de comentários geradas por IA. Confira, Adicionar comentários gerados por IA em uma tabela.

Caso esteja usando o Catálogo do Unity, use o Explorador do Catálogo para adicionar e editar comentários em todos os objetos que não estejam em um catálogo do Compartilhamento Delta.

Para os dados no metastore do Hive, use o Explorador do Catálogo para editar somente os comentários de tabela.

O markdown fornece um conjunto robusto de opções para documentar dados, aprimorando as opções que os usuários do Azure Databricks têm para aumentar a descoberta e a compreensão dos ativos de dados compartilhados. O uso de comentários de markdown não afeta o desempenho da consulta. O markdown não é renderizado quando retornado por instruções DESCRIBE.

Adicionar comentários de markdown a objetos de dados usando o Gerenciador de Catálogos

O Explorador do Catálogo exibe comentários para catálogos, esquemas, tabelas e outros ativos abaixo do nome do objeto.

  • Se não existir comentários, a opção Adicionar comentário será mostrada.
  • Você pode alternar a exibição de comentários com as opções Ocultar comentário e Mostrar comentário.

O markdown nos comentários da tabela é renderizado no Explorador do Catálogo assim que você salva as alterações.

  • Clique no ícone de lápis para modificar os comentários.
  • Clique em Salvar para atualizar os comentários.

Você também pode usar o SQL para adicionar comentários de tabela durante a criação da tabela ou ações ALTER TABLE.

Ao modificar comentários em uma tabela do Delta Lake, uma operação SET TBLPROPERTIES no histórico de tabelas registra a consulta SQL usada para definir os comentários da tabela atual.

Exemplo de documentação de markdown com suporte

O Explorador do Catálogo dá suporte à sintaxe de markdown básica. Você não pode usar o markdown para emojis, imagens e tabelas de markdown renderizadas. O Explorador do Catálogo renderiza apenas dois níveis de cabeçalhos markdown.

O exemplo a seguir mostra um bloco de código de markdown bruto. Copie este markdown para um comentário no Explorador do Catálogo e clique em Salvar para visualizá-lo.

# 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)

Mais recursos

Você também pode usar a seguinte funcionalidade para adicionar comentários a objetos de dados:

  • O comando COMMENT ON. Essa opção não dá suporte a comentários de coluna.
  • A opção COMMENT ao usar o comando CREATE <object> ou ALTER <object>. Por exemplo, confira CREATE TABLE [USING] e ALTER TABLE. Essa opção dá suporte a comentários de coluna.
  • Comentários gerados por IA (também conhecidos como documentação gerada por IA) no Gerenciador de Catálogos. Você pode exibir um comentário sugerido por um LLM (modelo de linguagem grande) que leva em conta os metadados da tabela, como os nomes do esquema e da coluna da tabela, e editar ou aceitar o comentário como está para adicioná-lo. Essa opção é compatível somente com tabelas e colunas. Confira, Adicionar comentários gerados por IA em uma tabela.