Document data with markdown comments
Data 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 Data 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 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
How to add markdown comments to data objects
Data Explorer displays comments for catalogs, schemas, and 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 ``` [Link](https://www.markdownguide.org/cheat-sheet/#basic-syntax)