Document data in Catalog Explorer using markdown comments

Users can use Catalog Explorer to view comments about data assets like catalogs, schemas, and tables. This article describes how object owners or users with modify permission on objects can add those comments manually using Catalog Explorer.

Note

For tables and columns, Catalog Explorer also lets you see AI-generated comment suggestions and apply them. See Add AI-generated comments to a table.

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 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.

Add markdown comments to data objects using Catalog Explorer

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
```

[Link](https://www.markdownguide.org/cheat-sheet/#basic-syntax)

More resources

You can also use the following functionality to add comments to data objects:

  • The COMMENT ON command. This option does not support column comments.

  • The COMMENT option when you use the CREATE <object> or ALTER <object> command. For example, see CREATE TABLE [USING] and ALTER TABLE. This option supports column comments.

  • AI-generated comments (also known as AI-generated documentation) in Catalog Explorer. You can view a comment suggested by a large language model (LLM) that takes into account the table metadata, such as the table schema and column names, and edit or accept the comment as-is to add it. This option supports tables and columns only. See Add AI-generated comments to a table.