What you will be able to do
- Explain how comments document securable objects and who can read them
- Identify the privilege needed to add or edit a comment on each kind of object
- Choose the right SQL command to comment an object, a column, or a new object
- Use AI-generated comments responsibly and contrast comments with tags
1.Comments as a discoverability field
A tag puts an object into a category, while a comment explains in words what the object is. Comments give every securable object a free-text metadata field. You can comment catalogs, schemas, tables, volumes, AI models and other securables, as well as individual table columns. A good table comment tells a consumer what the rows mean, where they come from or how to use them, which a name like fct_ord_v2 never will.
The value of a comment depends on who can read it.
This is the reason comments work for discovery. Any user with BROWSE can see them, so people can read what a table holds and decide whether to request access before they are allowed to query a single row.
Checkpoint 1 of 7· Check yourself
Why do comments improve data discoverability across a catalog?
BROWSE is enough to view comments, so people can learn what an object holds without having data access.
“After adding comments to a securable object, any user with BROWSE privileges can view the comments.”Source: docs.databricks.com
Sources1
2.Who can add or edit a comment
Reading a comment needs only BROWSE, but writing one depends on the type of object. You must also run the command on a SQL warehouse or other compute that supports Unity Catalog. Views are the case people most often get wrong: only the owner can comment them, and MANAGE does not help.
| Object | Who can add or edit the comment |
|---|---|
| Catalog, schema, volume, model, share, recipient, provider, storage credential, external location, connection | Owner, or MANAGE on the object |
| Table or table column | Owner, or MODIFY and SELECT on the table plus USE CATALOG and USE SCHEMA on the parents |
| View or materialized view | Owner only (MANAGE is insufficient) |
| Any object (reading the comment) | Any user with BROWSE |
Checkpoint 2 of 7· Match them up
Match each situation to the privilege that settles it.
Tap a term, then the definition that fits it.
Write privileges differ by object type. Views require ownership, and reading requires only BROWSE.
“you must be the owner of the view. Having the MANAGE privilege is insufficient.”Source: docs.databricks.com
Sources1
3.Adding comments with SQL and Catalog Explorer
In Catalog Explorer, you select the object and add or edit the comment on its Overview tab. Shares, storage credentials, external locations and connections are reached through the gear icon. The UI renders basic Markdown, except images. The same comment returned by a DESCRIBE statement shows as raw text.
In SQL, the command depends on what you are commenting:
| Goal | Command |
|---|---|
| Comment an existing securable object (anything except a table column) | COMMENT ON, or the COMMENT option of ALTER <object> |
| Comment a column of an existing table | ALTER TABLE with the ALTER COLUMN clause and the COMMENT option |
| Comment an object as you create it | COMMENT option of CREATE <object> |
Commenting has operational side effects. Saving a comment runs an ALTER command, which can disrupt pipelines and jobs that use the object. On a Unity Catalog table, the change is recorded in table history as a SET TBLPROPERTIES operation together with the SQL that set the comment. Comments also work on Delta tables in the legacy Hive metastore.
Checkpoint 3 of 7· Check yourself
You need to describe the ssn column of an existing Unity Catalog table. Which command does the documentation prescribe?
COMMENT ON covers every securable object except table columns. Column comments on existing tables go through ALTER TABLE with the ALTER COLUMN clause. SET TBLPROPERTIES is only the operation that appears in table history.
“use the ALTER TABLE command with the ALTER COLUMN clause and the COMMENT option on the column.”Source: docs.databricks.com
Sources1
4.AI-generated comments
Writing comments by hand for hundreds of tables rarely gets done, so Databricks can draft them. AI-generated comments, also called AI-generated documentation, are supported for catalogs, schemas, tables, views, materialized views, table columns, functions, models and volumes. A large language model writes the suggestion from object metadata such as the table schema and column names. The workspace must have AI-assistive features enabled. There is no workspace-level or catalog-level switch. You request a suggestion object by object, and you can view, edit and save suggestions only in Catalog Explorer.
To request one, you must own the object or hold MODIFY on it. For views and materialized views, you must be the owner. Suggestions are written in the workspace UI language by default, and the language selector on the AI Suggested Description card can change that.
Checkpoint 4 of 7· Put it in order
Order the steps to add an AI-generated comment to a table.
- 1.In the About this <object> panel, click AI generate
- 2.Click Accept to keep the suggestion, or Edit to change it before saving
- 3.In your Databricks workspace, click Catalog
- 4.Search or browse for the object and select it
You open Catalog Explorer, select the object, request a suggestion, and then review it before saving.
“In the About this <object> panel, click AI generate.”Source: docs.databricks.com
These suggestions are drafts. Databricks strongly recommends human review before saving, because the model can be wrong, and it explicitly says the model is not meant for classification work. To detect sensitive columns, use Data Classification, which applies the class.* system tags.
Checkpoint 5 of 7· Check yourself
A team wants to use AI-generated column comments to find which columns contain PII. What does the documentation say?
AI-generated comments give general, schema-based descriptions. Databricks warns against using them for data classification such as PII detection.
“The model should not be relied on for data classification tasks such as detecting columns with PII.”Source: docs.databricks.com
Checkpoint 6 of 7· Exam question
A metastore admin has defined a governed tag `pii_level` with allowed values `high`, `medium`, and `low`. A data engineer holding `APPLY TAG` on a table successfully sets `pii_level = high` on one column but receives a permission error setting `pii_level = medium` on another column in the same table. What is the most likely cause?
Correct answer: A — The engineer has not been granted `ASSIGN` permission for the `medium` value of this governed tag, even though `APPLY TAG` is held
- A. Governed tags restrict which specific values a user may assign, on top of the general `APPLY TAG` privilege, so having `APPLY TAG` lets a user tag the object at all while a separate `ASSIGN` grant per allowed value controls which values they can use.
- B. Tags, governed or not, can be applied at the column level as well as the table level, so a blanket restriction to table-level tagging does not exist and would not explain the value-specific failure.
- C. Reaching the 50-tag ceiling would block any new tag from being added at all, not just a specific value of an already-partially-applied tag, and nothing in the scenario indicates the limit was hit.
- D. AI-assisted tagging is a suggestion feature for generating descriptions; it has no connection to whether a governed tag's allowed values can be manually assigned via SQL.
Sources2
5.Comments versus tags
Both mechanisms attach metadata to securable objects, but they do different jobs. A tag is a short, structured key/value label that search can match exactly and that ABAC policies can use. A comment is a free-text explanation for people to read. The SQL also differs in a way the exam likes to test, shown in the last row below.
| Aspect | Tags | Comments |
|---|---|---|
| Form | Key with optional value | String literal (basic Markdown in Catalog Explorer) |
| Privilege to add (non-owner, table) | APPLY TAG plus USE SCHEMA and USE CATALOG | MODIFY and SELECT plus USE CATALOG and USE SCHEMA |
| Main SQL | SET TAG / ALTER <object> SET TAGS | COMMENT ON / ALTER <object> COMMENT |
| AI assistance | Not covered by AI-generated comments | AI-generated comments in Catalog Explorer |
| Several columns in one ALTER TABLE | Not supported; one column at a time | Supported |
Checkpoint 7 of 7· Check yourself
You want to update metadata on five columns of one table in a single ALTER TABLE statement. Which is possible?
Tags must be assigned to each column separately, while the COMMENT clause supports multiple columns in one command.
“This differs from the COMMENT clause, which does support multiple columns in one command.”Source: docs.databricks.com
Sources3
Exam traps
Each one states something that sounds right. Open it to see what is actually true.
1.Having MANAGE on a view lets you edit its comment, just as MANAGE does on a schema or catalog.Why is that wrong?
Views and materialized views are the exception. Only the owner can add or edit their comments.
Covered in Who can add or edit a comment
2.AI-generated comments can stand in for sensitive-data classification because they read the schema and describe each column.Why is that wrong?
They give general descriptions that must be reviewed by a person, and Databricks says not to rely on them for classification such as PII detection.
Covered in AI-generated comments
Practise it for real
Document a sensitive column with both a tag and a comment, and confirm that both can be found.
1.On a test table you own, run SET TAG ON COLUMN <table>.ssn pii; on a SQL warehouse (Runtime 16.1+ semantics).
Why: This creates a key-only tag that classifies the column without storing any sensitive value.
You should see: The statement succeeds. Running it a second time with the same key raises an exception.
2.Query information_schema.column_tags in the table's catalog, filtering WHERE tag_name = 'pii'.
Why: INFORMATION_SCHEMA is the SQL way to list tagged objects.
You should see: A row for your table and the ssn column.
3.Add a column comment with ALTER TABLE <table> ALTER COLUMN ssn COMMENT '<description>'.
Why: ALTER TABLE with ALTER COLUMN is the prescribed route for column comments on existing tables.
You should see: The comment appears next to the column in Catalog Explorer, and the table history shows a SET TBLPROPERTIES operation.
4.In Catalog Explorer, click AI generate above the column list and review the suggestions without saving any you disagree with.
Why: AI comments are drafts that need human review.
You should see: One suggestion per column, each with a check mark to accept it.
Stuck? Get a nudge
If the tag search finds nothing, check the key's case: tag keys are case sensitive and search needs an exact match.
Sources
Every claim above is drawn from one of these pages, quoted as it was written on the date shown.
- 1.https://docs.databricks.com/aws/en/commentsOfficial docs
“Comments provide a metadata field for annotating your securable objects.”
↩︎ Comments as a discoverability field“After adding comments to a securable object, any user with BROWSE privileges can view the comments.”
↩︎ Comments as a discoverability field“MODIFY and SELECT on the table. USE CATALOG and USE SCHEMA on the parent catalog and schema.”
↩︎ Who can add or edit a comment“You must use a SQL warehouse or other compute that supports Unity Catalog.”
↩︎ Who can add or edit a comment“To add or update a comment for any existing securable object except table columns, use the COMMENT ON command.”
↩︎ Adding comments with SQL and Catalog Explorer“Saving comments triggers an ALTER SQL command, which can disrupt Databricks pipelines and jobs.”
↩︎ Adding comments with SQL and Catalog Explorer“Markdown styling does not render when returned by DESCRIBE statements.”
↩︎ Adding comments with SQL and Catalog Explorer“you must be the owner of the view. Having the MANAGE privilege is insufficient.”
↩︎ Exam trap 1“you must be the owner of the view. Having the MANAGE privilege is insufficient.”
↩︎ Checkpoint“use the ALTER TABLE command with the ALTER COLUMN clause and the COMMENT option on the column.”
↩︎ Checkpoint - 2.
“Comments are powered by a large language model (LLM) that takes into account object metadata, such as the table schema and column names.”
↩︎ AI-generated comments“There is no workspace-level or catalog-level toggle to enable or disable AI-generated comments.”
↩︎ AI-generated comments“For views and materialized views: You must be the object owner.”
↩︎ AI-generated comments“The model should not be relied on for data classification tasks such as detecting columns with PII.”
↩︎ Exam trap 2“BROWSE allows you to view object metadata, including comments, without requiring USE CATALOG or USE SCHEMA privileges.”
↩︎ Prediction“In the About this <object> panel, click AI generate.”
↩︎ Checkpoint“The model should not be relied on for data classification tasks such as detecting columns with PII.”
↩︎ Checkpoint - 3.
“You cannot assign tags to multiple columns in a single ALTER TABLE command.”
↩︎ Comments versus tags“This differs from the COMMENT clause, which does support multiple columns in one command.”
↩︎ Checkpoint