Add comments to data and AI assets

This article introduces comments for data and AI assets and explains how to add them. Comments can help you and other users find and manage the data and AI assets 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, AI models, and more. You can also add comments to table columns.

You can add comments manually, or you can let Databricks create AI-generated comments for you. AI-generated comments (also known as AI-generated documentation) are available for tables and table columns. See Add AI-generated comments to Unity Catalog objects.

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 and SELECT on the table.

    • USE CATALOG and USE 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).

  • To use AI-generated comments, your workspace must be enabled for AI-assistive features. See Add AI-generated comments to Unity Catalog objects.

Add and edit comments

You can add comments to securable objects or edit them using SQL commands or Catalog Explorer.

  1. In the workspace sidebar, click Catalog icon Catalog to open Catalog Explorer.

  2. Search for and select the object you want to comment on.

    Data and AI objects are 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 gear icon.

  3. 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 Icon to add a column tag or comment 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 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.

For more information about AI-generated comments, see Add AI-generated comments to Unity Catalog objects.

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 the ALTER <object> command for the object (for example, ALTER TABLE). See the SQL reference article for the ALTER <object> command.

  • To add or update a column comment for an existing table, use the ALTER TABLE command with the ALTER COLUMN clause and the COMMENT 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 the CREATE <object> command. See the SQL reference article for the CREATE <object> command that you want to use.