Adicionar comentários a ativos de dados e IA

Este artigo apresenta comentários sobre ativos de dados e IA e explica como adicioná-los. Os comentários podem ajudar você e outros usuários a encontrar e gerenciar os ativos de dados e IA necessários.

Os comentários fornecem um campo de metadados para anotar seus objetos protegíveis. Você pode adicionar comentários a qualquer objeto protegível no Catálogo do Unity, como catálogos, esquemas, tabelas, volumes, modelos de IA e muito mais. Você também pode adicionar comentários a colunas de tabela.

Você pode adicionar comentários manualmente ou permitir que o Databricks crie comentários gerados por IA para você. Os comentários gerados por IA (também conhecidos como documentação gerada por IA) estão disponíveis para tabelas e colunas de tabela. Confira, Adicionar comentários gerados por IA em uma tabela.

Quando você modifica comentários para uma tabela do Catálogo do Unity (ou uma tabela do Delta Lake no metastore do Hive herdado), uma operação SET TBLPROPERTIES no histórico de tabelas registra a consulta SQL usada para definir o comentário da tabela.

Antes de começar

Você deve atender aos seguintes requisitos para adicionar ou editar comentários:

• Para adicionar ou editar comentários em um catálogo, esquema, volume, modelo, compartilhamento, destinatário, provedor, credencial de armazenamento, localização externa ou conexão, você deve ser o proprietário do objeto.
• Para adicionar ou editar comentários em uma tabela ou coluna, você deve ser o proprietário ou ter os seguintes privilégios:
  • MODIFY e SELECT na tabela.
  • USE CATALOG e USE SCHEMA no esquema e catálogo pai.
• Você deve usar um SQL warehouse ou outra computação que dê suporte ao Catálogo do Unity (computação compartilhada ou de usuário único).
• Para usar comentários gerados por IA, seu workspace deve estar habilitado para recursos de IA assistencial. Confira, Adicionar comentários gerados por IA em uma tabela.

Adicionar e editar comentários

Você pode adicionar comentários a objetos protegíveis ou editá-los usando comandos SQL ou o Explorador de Catálogo.

Explorador do Catálogo

1. Na barra lateral esquerda do workspace, clique em Catálogo para abrir o Explorador do Catálogo.

2. Pesquise e selecione o objeto que você deseja comentar.

   Os objetos de dados e IA são listados e pesquisáveis no painel Catálogo. Compartilhamentos, credenciais de armazenamento, locais externos e conexões são acessíveis usando o menu que é aberto quando você clica no ícone de engrenagem .

3. Adicione um comentário ou edite um comentário existente.

   • Para adicionar um comentário a uma tabela usando comentários gerados por IA, veja Comentário sugerido por IA no painel direito da guia Visão geral. Pode levar demorar alguns segundos para aparecer. Aceite como está ou Edite e salve-o.
   • Para adicionar um comentário a uma coluna de tabela usando comentários gerados por IA, clique no botão Gerar por IA acima da lista de colunas. O Databricks gera comentários para cada coluna. Aceite-os como estão ou edite-os. Clique na marca de seleção para salvar o comentário.
   • Para adicionar um comentário a um objeto que não dá suporte a comentários gerados por IA, clique em Adicionar comentário para adicionar um comentário.
   • Para adicionar um comentário a uma coluna de tabela sem usar comentários gerados por IA, clique no ícone Adicionar comentário na linha de coluna.
   • Se já existir um comentário, ele aparecerá no painel direito na guia Visão geral ou abaixo do nome do objeto. Se não for gerado por IA, clique no ícone de edição para editá-lo.

Você pode usar o Markdown básico para alterar o estilo de comentários na interface do usuário do Explorador do Catálogo. O estilo de Markdown não é renderizado quando retornado por instruções DESCRIBE. Toda a sintaxe básica tem suporte no Explorador de Catálogo, exceto em imagens, e apenas dois níveis de título são renderizados. Para obter mais informações, confira Sintaxe básica.

Para obter mais informações sobre comentários gerados por IA, consulte Adicionar comentários gerados por IA a uma tabela.

SQL

Você pode usar um comando SQL para adicionar um literal de cadeia de caracteres como um comentário a qualquer objeto protegível no Catálogo do Unity e às tabelas gerenciadas no metastore do Hive herdado. O comando SQL usado depende do objeto ao qual você deseja adicionar ou editar o comentário:

• Para adicionar ou atualizar um comentário para qualquer objeto protegível existente, exceto colunas de tabela, use o comando COMMENT ON. Consulte COMMENT ON.

  Você também pode usar a opção COMMENT com o comando ALTER <object> para o objeto (por exemplo, ALTER TABLE). Consulte o artigo de referência do SQL para o comando ALTER <object>.

• Para adicionar ou atualizar um comentário de coluna para uma tabela existente, use o comando ALTER TABLE com a cláusula ALTER COLUMN e a opção COMMENT na coluna. Consulte as cláusulas ALTER TABLE e ALTER TABLE … COLUMN.

• Para adicionar um comentário ao criar um objeto, use a opção COMMENT com o comando CREATE <object>. Consulte o artigo de referência do SQL para o comando CREATE <object> que você quer usar.