/databricks-unity-catalog

name: databricks-unity-catalog
description: "Unity Catalog governance, access control, and observability. Use to grant or revoke access (GRANT/REVOKE), reason about the privilege model and ownership, set up row-level security and column masks, create external locations and storage credentials, define catalogs/schemas/tables/volumes, answer \"who can read this table\", and query system tables (audit, lineage, billing) or work with volume files in /Volumes/."
compatibility: Requires databricks CLI (>= v1.0.0)
metadata:
  version: "0.3.0"
parent: databricks-core

Unity Catalog

Guidance for Unity Catalog **governance** — access control, the privilege model, external locations, securable DDL, and fine-grained access — plus system tables and volume file operations.

> **Before running `databricks` CLI commands, confirm the CLI and the subcommand exist.** > Run `databricks --version` — this skill assumes the unified CLI (**≥ v1.0.0**). Several > subcommands shown here (`experimental aitools`, `system-schemas`, `external-lineage`, > `grants`) vary by version or workspace availability; if one is missing or rejects a flag, > fall back to the SQL form or the Python SDK rather than guessing. Each reference notes its > own version floor where relevant.

When to Use This Skill

Use this skill when:

**Governance & access control (start here):**

• **Granting or revoking access** — `GRANT`/`REVOKE`, the UC privilege model, ownership (`ALTER … OWNER TO`), `SHOW GRANTS`, "who can read/write this table?"
• **Row- and column-level security** — row filters, column masks, dynamic views with `current_user()` / `is_account_group_member()`
• **External locations & storage credentials** — `CREATE STORAGE CREDENTIAL`, `CREATE EXTERNAL LOCATION`, backing external tables/volumes
• **Securable DDL & metadata** — creating/altering catalogs, schemas, managed vs external tables, views; comments, tags, table properties, ownership

**Observability & files:**

• Working with **volumes** (upload, download, list files in `/Volumes/`)
• Querying **lineage** (table dependencies, column-level lineage)
• Analyzing **audit logs** (who accessed what, permission changes)
• Monitoring **billing and usage** (DBU consumption, cost analysis)
• Tracking **compute resources** (cluster usage, warehouse metrics)
• Reviewing **job execution** (run history, success rates, failures)
• Analyzing **query performance** (slow queries, warehouse utilization)
• Profiling **data quality** (data profiling, drift detection, metric tables)

Reference Files

| Topic | File | Description | |-------|------|-------------| | **Access Control** | [references/1-access-control.md](references/1-access-control.md) | Privilege model, securable hierarchy, GRANT/REVOKE, ownership, inheritance, `SHOW GRANTS` | | **External Locations** | [references/2-external-locations.md](references/2-external-locations.md) | Storage credentials (AWS/Azure/GCP), external locations, validation | | **Securables DDL** | [references/3-securables-ddl.md](references/3-securables-ddl.md) | CREATE/ALTER/DROP catalogs/schemas/tables/views, comments, tags, ownership | | **Fine-Grained Access** | [references/4-fine-grained-access.md](references/4-fine-grained-access.md) | Row filters, column masks, dynamic views | | System Tables | [references/5-system-tables.md](references/5-system-tables.md) | Lineage, audit, billing, compute, jobs, query history | | Volumes | [references/6-volumes.md](references/6-volumes.md) | Volume file operations, permissions, best practices | | Data Profiling | [references/7-data-profiling.md](references/7-data-profiling.md) | Data profiling, drift detection, profile metrics |

Quick Start

Create Unity Catalog Objects (CLI)

**Use `--json` for `create` commands.** Positional argument order differs per command and has changed across CLI versions, so `--json` is the order-independent, version-stable form shown throughout this skill.

# Create a catalog
databricks catalogs create --json '{"name": "my_catalog"}'

# Create a schema
databricks schemas create --json '{"name": "my_schema", "catalog_name": "my_catalog"}'

# Create a managed volume
databricks volumes create --json '{
  "catalog_name": "my_catalog",
  "schema_name": "my_schema",
  "name": "my_volume",
  "volume_type": "MANAGED"
}'

# List catalogs, schemas, volumes (read commands take simple positional args)
databricks catalogs list
databricks schemas list my_catalog
databricks volumes list my_catalog.my_schema

Positional `create` args still work if you prefer them, but the order is **not** uniform across commands — this is the per-command order (and the reason `--json` is recommended):

| Command | Positional `create` order | |---------|---------------------------| | `databricks catalogs create` | `NAME` | | `databricks schemas create` | `NAME CATALOG_NAME` | | `databricks volumes create` | `CATALOG_NAME SCHEMA_NAME NAME VOLUME_TYPE` |

> **CLI surface varies by version.** If a `databricks` subcommand or positional signature is > missing in your install, prefer `--json`, the SQL form, or the Python SDK rather than > guessing flags.

Volume File Operations (CLI)

`databricks fs` requires the `dbfs:` scheme prefix even for UC Volume paths — without it the CLI treats the path as local filesystem and errors with `no such directory`.

# List files in a volume
databricks fs ls dbfs:/Volumes/catalog/schema/volume/path/

# Upload a directory's contents to a volume (-r copies contents, not the directory itself)
databricks fs cp -r --overwrite /tmp/data dbfs:/Volumes/catalog/schema/volume/dest

# Download a file from a volume
databricks fs cp dbfs:/Volumes/catalog/schema/volume/file.csv /tmp/file.csv

# Create a directory in a volume
databricks fs mkdirs dbfs:/Volumes/catalog/schema/volume/new_folder

Grant & Revoke Access

`GRANT`/`REVOKE` is the core governance operation. See [references/1-access-control.md](references/1-access-control.md) for the full privileg