Documenting table and column definitions so data can be discovered

Unity Catalog lets you attach human-readable comments to catalogs, schemas, tables, and columns so that data is discoverable and self-documenting through Catalog Explorer and SQL. These descriptions can be created and maintained via SQL DDL, Catalog Explorer UI edits, or AI-generated suggestions, and they persist as object metadata that governs how users find and understand data.

1 · Learn the must-know

• 1Use COMMENT ON TABLE, COMMENT ON COLUMN, or inline COMMENT clauses in CREATE/ALTER TABLE statements to add or update descriptions via SQL.
• 2In Catalog Explorer, you can manually edit table and column descriptions, or use Databricks Assistant/AI-generated comments (based on schema and sample data) and then review and accept them before saving.
• 3Table and column comments are stored as metadata in Unity Catalog and are visible to any user with sufficient privileges (e.g., SELECT or BROWSE) on that object, supporting data discovery and governance.
• 4ALTER TABLE ... ALTER COLUMN ... COMMENT '...' is used to add or change a column comment without altering the column's data or type.
• 5Comments are preserved across normal table operations (like INSERT, UPDATE, schema evolution via ADD COLUMN) but must be explicitly reapplied if a table is dropped and recreated rather than altered.
• 6Consistent, accurate table and column descriptions are a governance best practice tested on the exam because they directly support search, lineage understanding, and self-service analytics in Unity Catalog.

2 · Check your understanding