Document data with markdown comments

For data in the Hive metastore, you can use Data Explorer to edit table comments only. Markdown comments for all database objects render in Data 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

Data Explorer displays comments for tables 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 Data 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

Data Explorer supports basic markdown syntax. You cannot use markdown for emojis, images, and rendered markdown tables. Data 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 Data 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