Documentar datos en Catalog Explorer con comentarios en Markdown

  • Artículo

Los usuarios pueden usar Catalog Explorer para ver comentarios sobre recursos de datos como catálogos, esquemas y tablas. En este artículo se describe cómo los propietarios o usuarios de objetos que tienen permiso para modificar tales objetos pueden agregar esos comentarios manualmente mediante el Catalog Explorer.

Nota:

En el caso de las tablas y columnas, Catalog Explorer también permite ver sugerencias de comentarios generados por IA y aplicarlas. Consulte Agregar comentarios generados por IA a una tabla.

Si usa Unity Catalog, puede usar el Catalog Explorer para agregar y editar comentarios en todos los objetos distintos de los de un catálogo de Delta Sharing.

En el caso de los datos del metastore de Hive, puede usar Catalog Explorer para editar solo los comentarios de la tabla.

Markdown proporciona un sólido conjunto de opciones para documentar datos, mejorando las opciones que tienen los usuarios de Azure Databricks para aumentar la capacidad de descubrimiento y comprensión de los recursos de datos compartidos. El uso de comentarios de Markdown no afecta al rendimiento de las consultas. Markdown no se representa cuando lo devuelven instrucciones DESCRIBE.

Agregar comentarios en Markdown a objetos de datos con Catalog Explorer

Catalog Explorer muestra comentarios para catálogos, esquemas, tablas y otros recursos debajo del nombre del objeto.

  • Si no existe ningún comentario, se muestra una opción Agregar comentario.
  • Puede alternar la presentación de comentarios con las opciones Ocultar comentario y Mostrar comentario.

Markdown en los comentarios de la tabla se representa en Catalog Explorer tan pronto como guarde los cambios.

  • Haga clic en el icono de lápiz para modificar los comentarios.
  • Haga clic en Guardar para actualizar los comentarios.

También puede usar SQL para añadir comentarios a la tabla durante la creación de la misma o durante las acciones ALTER TABLE.

Al modificar comentarios en una tabla de Delta Lake, una operación SET TBLPROPERTIES en el historial de tablas registra la consulta SQL utilizada para definir los comentarios de la tabla actual.

Ejemplo de documentación de Markdown admitida

Catalog Explorer admite la sintaxis básica de markdown. No puede usar Markdown para emojis, imágenes y tablas de Markdown representadas. Catalog Explorer representa solo dos niveles de encabezados de markdown.

En el ejemplo siguiente se muestra un bloque de código de Markdown sin formato. Copie este markdown en un comentario en eCatalog Explorer y haga clic en Guardar para obtener una vista previa.

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

Más recursos

También puede usar la siguiente funcionalidad para agregar comentarios a objetos de datos:

  • El comando COMMENT ON. Esta opción no admite comentarios de columnas.
  • La opción COMMENT cuando se usa el comando CREATE <object> o ALTER <object>. Por ejemplo, consulte CREATE TABLE [USING] y ALTER TABLE. Esta opción admite comentarios de columna.
  • Comentarios generados por IA (también conocidos como documentación generada por IA) en Catalog Explorer. Puede ver un comentario sugerido por un modelo de lenguaje grande (LLM) que tiene en cuenta los metadatos de las tablas, como el esquema de tabla y los nombres de columna, y editar o aceptar el comentario tal cual para agregarlo. Esta opción solo admite tablas y columnas. Consulte Agregar comentarios generados por IA a una tabla.