Add comments to data
This article introduces comments for data and explains how to add them. Comments can help you and other users find and manage the data you need.
Comments provide a metadata field for annotating your securable objects. You can add comments to any securable object in Unity Catalog, such as catalogs, schemas, tables, volumes, and more. You can also add comments to table columns.
You can add comments manually.
When you modify comments for a Unity Catalog table (or a Delta Lake table in the legacy Hive metastore), a SET TBLPROPERTIES
operation in the table history records the SQL query that was used to define the table comment.
Before you begin
You must meet the following requirements in order to add or edit comments:
- To add or edit comments on a catalog, schema, volume, model, share, recipient, provider, storage credential, external location, or connection, you must be the owner of the object.
- To add or edit comments on a table or column, you must be the owner or have the following privileges:
MODIFY
andSELECT
on the table.USE CATALOG
andUSE SCHEMA
on the parent catalog and schema.
- You must use a SQL warehouse or other compute that supports Unity Catalog (shared or single-user compute).
Add and edit comments
You can add comments to securable objects or edit them using SQL commands or Catalog Explorer.
Catalog Explorer
In the workspace sidebar, click Catalog to open Catalog Explorer.
Search for and select the object you want to comment on.
Data is listed and searchable in the Catalog pane. Shares, storage credentials, external locations, and connections are accessible using the menu that opens when you click the gear icon.
Add a comment or edit an existing comment.
- To add a comment to a table using AI-generated comments, view the AI Suggested Comment in the right pane of the Overview tab. It might take a few seconds to appear. Either Accept it as-is or Edit and save it.
- To add a comment to a table column using AI-generated comments, click the AI generate button above the column list. Databricks generates comments for each column. Accept them as-is or edit them. Click the check mark to save the comment.
- To add a comment to an object that doesn't support AI-generated comments, click Add comment to add a comment.
- To add a comment to a table column without using AI-generated comments, click the Add comment icon in the column row.
- If a comment already exists, it appears in the right pane on the Overview tab or below the object name. If it is not AI-generated, click the edit icon to edit it.
You can use basic Markdown to style comments in the Catalog Explorer UI. Markdown styling does not render when returned by DESCRIBE
statements. All basic syntax is supported in Catalog Explorer except images, and only two heading levels are rendered. For more information, see Basic Syntax.
SQL
You can use a SQL command to add a string literal as a comment to any securable object in Unity Catalog and to tables managed in the legacy Hive metastore. The SQL command you use depends on the object you want to add or edit the comment for:
To add or update a comment for any existing securable object except table columns, use the
COMMENT ON
command. See COMMENT ON.You can also use the
COMMENT
option with theALTER <object>
command for the object (for example,ALTER TABLE
). See the SQL reference article for theALTER <object>
command.To add or update a column comment for an existing table, use the
ALTER TABLE
command with theALTER COLUMN
clause and theCOMMENT
option on the column. See ALTER TABLE and ALTER TABLE … COLUMN clause.To add a comment when you create an object, use the
COMMENT
option with theCREATE <object>
command. See the SQL reference article for theCREATE <object>
command that you want to use.