Document data with markdown comments

Catalog Explorer renders comments with standard markdown format for database objects such as tables, schema, and catalogs.

If you’re using Unity Catalog, you can use Catalog Explorer to add and edit comments on all objects other than those in a Delta Sharing catalog.

For data in the Hive metastore, you can use Catalog Explorer to edit table comments only. Markdown comments for all database objects render in Catalog Explorer, but you can’t edit comments for schemas or views in the Hive metastore

Markdown provides a robust set of options for documenting data, enhancing the options Databricks users have for increasing the discoverability and understanding of shared data assets. Using markdown comments has no impact on query performance. Markdown does not render when returned by DESCRIBE statements.

How to add markdown comments to data objects

Catalog Explorer displays comments for catalogs, schemas, tables, and other assets below the object name.

  • If no comment exists, an Add comment option is shown.

  • You can toggle comment display with the Hide comment and Show comment options.

Markdown in table comments renders in Catalog Explorer as soon as you save changes.

  • Click the pencil icon to modify comments.

  • Click Save to update comments.

You can also use SQL to add table comments during table creation or ALTER TABLE actions.

When modifying comments on a Delta Lake table, a SET TBLPROPERTIES operation in the table history records the SQL query used to define the current table comments.

Example of supported markdown documentation

Catalog Explorer supports basic markdown syntax. You cannot use markdown for emojis, images, and rendered markdown tables. Catalog Explorer renders only two levels of markdown headers.

The following example shows a code block of raw markdown. Copy this markdown to a comment in Catalog Explorer and click Save to preview.

# 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