Back to Details

databricks-unity-catalog

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Unity Catalog

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.
本指南介绍Unity Catalog的治理相关内容——包括访问控制、权限模型、外部存储位置、可保护对象DDL、细粒度访问控制，以及系统表和卷文件操作。
在运行
databricks
CLI命令前，请确认CLI及对应的子命令已存在。 运行
databricks --version
——本技能基于统一CLI（≥ v1.0.0）开发。本文展示的部分子命令（
experimental aitools
、
system-schemas
、
external-lineage
、
grants
）会因版本或工作区可用性不同而存在差异；如果某个子命令缺失或拒绝执行某个参数，请优先使用SQL形式或Python SDK，而非尝试猜测参数。相关参考内容会注明最低版本要求。

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)
在以下场景中使用本技能：
治理与访问控制（从这里开始）：
  • 授予或撤销访问权限——
    GRANT
    /
    REVOKE
    、UC权限模型、所有权（
    ALTER … OWNER TO
    ）、
    SHOW GRANTS
    、“谁可以读写该表？”
  • 行级与列级安全——行过滤器、列掩码、结合
    current_user()
    /
    is_account_group_member()
    的动态视图
  • 外部存储位置与存储凭据——
    CREATE STORAGE CREDENTIAL
    、
    CREATE EXTERNAL LOCATION
    、外部表/卷的底层配置
  • 可保护对象DDL与元数据——创建/修改catalog、schema、托管表与外部表、视图；注释、标签、表属性、所有权
可观测性与文件操作：
  • 处理卷（上传、下载、列出/Volumes/中的文件）
  • 查询数据血缘（表依赖关系、列级血缘）
  • 分析审计日志（谁访问了什么内容、权限变更记录）
  • 监控计费与使用情况（DBU消耗、成本分析）
  • 追踪计算资源（集群使用情况、仓库指标）
  • 查看任务执行情况（运行历史、成功率、失败记录）
  • 分析查询性能（慢查询、仓库利用率）
  • 数据质量分析（数据探查、漂移检测、指标表）

Reference Files

参考文档

TopicFileDescription
Access Controlreferences/1-access-control.mdPrivilege model, securable hierarchy, GRANT/REVOKE, ownership, inheritance, 
SHOW GRANTS
External Locationsreferences/2-external-locations.mdStorage credentials (AWS/Azure/GCP), external locations, validation
Securables DDLreferences/3-securables-ddl.mdCREATE/ALTER/DROP catalogs/schemas/tables/views, comments, tags, ownership
Fine-Grained Accessreferences/4-fine-grained-access.mdRow filters, column masks, dynamic views
System Tablesreferences/5-system-tables.mdLineage, audit, billing, compute, jobs, query history
Volumesreferences/6-volumes.mdVolume file operations, permissions, best practices
Data Profilingreferences/7-data-profiling.mdData profiling, drift detection, profile metrics
主题文件描述
访问控制references/1-access-control.md权限模型、可保护对象层级、GRANT/REVOKE、所有权、权限继承、
SHOW GRANTS
外部存储位置references/2-external-locations.md存储凭据（AWS/Azure/GCP）、外部存储位置、验证
可保护对象DDLreferences/3-securables-ddl.mdCREATE/ALTER/DROP catalogs/schemas/tables/views、注释、标签、所有权
细粒度访问控制references/4-fine-grained-access.md行过滤器、列掩码、动态视图
系统表references/5-system-tables.md数据血缘、审计、计费、计算、任务、查询历史
卷references/6-volumes.md卷文件操作、权限、最佳实践
数据探查references/7-data-profiling.md数据探查、漂移检测、探查指标

Quick Start

快速开始

Create Unity Catalog Objects (CLI)

创建Unity Catalog对象（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.
bash
undefined
创建命令请使用
--json
参数。不同命令的位置参数顺序不同，且在CLI版本迭代中发生过变更，因此本文全程使用
--json
形式，该形式不受参数顺序影响且在各版本中保持稳定。
bash
undefined

Create a catalog

创建catalog

databricks catalogs create --json '{"name": "my_catalog"}'
databricks catalogs create --json '{"name": "my_catalog"}'

Create a schema

创建schema

databricks schemas create --json '{"name": "my_schema", "catalog_name": "my_catalog"}'
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" }'
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)

列出catalog、schema、卷（查询命令支持简单的位置参数）

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.
databricks catalogs list databricks schemas list my_catalog databricks volumes list my_catalog.my_schema

如果你偏好使用位置参数创建对象，该方式依然可用，但不同命令的参数顺序**并不统一**——以下是各命令的参数顺序（这也是推荐使用`--json`的原因）：

| 命令 | 创建命令的位置参数顺序 |
|---------|---------------------------|
| `databricks catalogs create` | `NAME` |
| `databricks schemas create`  | `NAME CATALOG_NAME` |
| `databricks volumes create`  | `CATALOG_NAME SCHEMA_NAME NAME VOLUME_TYPE` |

> **CLI功能随版本变化**。如果你的CLI版本中缺失某个`databricks`子命令或位置参数签名，请优先使用`--json`、SQL形式或Python SDK，而非尝试猜测参数。

Volume File Operations (CLI)

卷文件操作（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
.
bash
undefined
databricks fs
命令要求UC卷路径必须带有
dbfs:
前缀——如果缺少该前缀，CLI会将路径视为本地文件系统，从而抛出
no such directory
错误。
bash
undefined

List files in a volume

列出卷中的文件

databricks fs ls dbfs:/Volumes/catalog/schema/volume/path/
databricks fs ls dbfs:/Volumes/catalog/schema/volume/path/

Upload a directory's contents to a volume (-r copies contents, not the directory itself)

将目录内容上传至卷（-r参数复制目录内容而非目录本身）

databricks fs cp -r --overwrite /tmp/data dbfs:/Volumes/catalog/schema/volume/dest
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
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
undefined
databricks fs mkdirs dbfs:/Volumes/catalog/schema/volume/new_folder
undefined

Grant & Revoke Access

授予与撤销访问权限

GRANT
/
REVOKE
is the core governance operation. See references/1-access-control.md for the full privilege model.
sql
-- Grant read access on a schema to a group
GRANT USE CATALOG ON CATALOG analytics TO `data_readers`;
GRANT USE SCHEMA ON SCHEMA analytics.gold TO `data_readers`;
GRANT SELECT ON SCHEMA analytics.gold TO `data_readers`;

-- Who can access this table?
SHOW GRANTS ON TABLE analytics.gold.customers;

-- Revoke
REVOKE SELECT ON SCHEMA analytics.gold FROM `data_readers`;
GRANT
/
REVOKE
是核心治理操作。完整权限模型请参考references/1-access-control.md。
sql
-- 授予某个组对schema的读取权限
GRANT USE CATALOG ON CATALOG analytics TO `data_readers`;
GRANT USE SCHEMA ON SCHEMA analytics.gold TO `data_readers`;
GRANT SELECT ON SCHEMA analytics.gold TO `data_readers`;

-- 谁可以访问该表？
SHOW GRANTS ON TABLE analytics.gold.customers;

-- 撤销权限
REVOKE SELECT ON SCHEMA analytics.gold FROM `data_readers`;

Enable System Tables Access

启用系统表访问权限

sql
-- Grant access to system tables
GRANT USE CATALOG ON CATALOG system TO `data_engineers`;
GRANT USE SCHEMA ON SCHEMA system.access TO `data_engineers`;
GRANT SELECT ON SCHEMA system.access TO `data_engineers`;
sql
-- 授予系统表访问权限
GRANT USE CATALOG ON CATALOG system TO `data_engineers`;
GRANT USE SCHEMA ON SCHEMA system.access TO `data_engineers`;
GRANT SELECT ON SCHEMA system.access TO `data_engineers`;

Common Queries

常用查询语句

sql
-- Table lineage: What tables feed into this table?
SELECT source_table_full_name, source_column_name
FROM system.access.table_lineage
WHERE target_table_full_name = 'catalog.schema.table'
  AND event_date >= current_date() - 7;

-- Audit: Recent permission changes
SELECT event_time, user_identity.email, action_name, request_params
FROM system.access.audit
WHERE action_name LIKE '%GRANT%' OR action_name LIKE '%REVOKE%'
ORDER BY event_time DESC
LIMIT 100;

-- Billing: DBU usage by workspace
SELECT workspace_id, sku_name, SUM(usage_quantity) AS total_dbus
FROM system.billing.usage
WHERE usage_date >= current_date() - 30
GROUP BY workspace_id, sku_name;
sql
-- 表血缘：哪些表是该表的上游数据源？
SELECT source_table_full_name, source_column_name
FROM system.access.table_lineage
WHERE target_table_full_name = 'catalog.schema.table'
  AND event_date >= current_date() - 7;

-- 审计：近期权限变更记录
SELECT event_time, user_identity.email, action_name, request_params
FROM system.access.audit
WHERE action_name LIKE '%GRANT%' OR action_name LIKE '%REVOKE%'
ORDER BY event_time DESC
LIMIT 100;

-- 计费：各工作区的DBU使用情况
SELECT workspace_id, sku_name, SUM(usage_quantity) AS total_dbus
FROM system.billing.usage
WHERE usage_date >= current_date() - 30
GROUP BY workspace_id, sku_name;

Running SQL from the CLI

从CLI运行SQL

databricks experimental aitools tools query
is an experimental command. The 
experimental
namespace is not guaranteed to be stable across CLI versions and may be absent in your install. Prefer running system-table SQL from a SQL warehouse (SQL editor, scheduled query) or the Python SDK (
w.statement_execution.execute_statement
), or a notebook. Use the experimental CLI only for quick ad-hoc checks.
Getting the IDs these examples use. 
WAREHOUSE_ID
— run 
databricks warehouses list
(or copy it from a SQL warehouse's Connection details in the UI). 
METASTORE_ID
(used in references/5-system-tables.md) — 
w.metastores.current().metastore_id
via the SDK, or the Catalog UI → metastore details.
Experimental CLI form (convenience only):
bash
databricks experimental aitools tools query --warehouse WAREHOUSE_ID "
  SELECT source_table_full_name, target_table_full_name
  FROM system.access.table_lineage
  WHERE event_date >= current_date() - 7
"
Stable SDK fallback (works on any CLI version):
python
from databricks.sdk import WorkspaceClient

w = WorkspaceClient()
resp = w.statement_execution.execute_statement(
    warehouse_id="WAREHOUSE_ID",
    statement="""
        SELECT source_table_full_name, target_table_full_name
        FROM system.access.table_lineage
        WHERE event_date >= current_date() - 7
        LIMIT 100
    """,
)
for row in resp.result.data_array or []:
    print(row)
CLI surface varies by version. If a 
databricks
subcommand (e.g. an 
experimental
tool, 
system-schemas
, or 
external-lineage
) is missing, fall back to the SQL warehouse or the Python SDK shown above rather than guessing flags.
databricks experimental aitools tools query
是实验性命令。
experimental
命名空间在CLI版本迭代中不保证稳定性，可能在你的版本中缺失。优先从SQL仓库（SQL编辑器、定时查询）或Python SDK（
w.statement_execution.execute_statement
）或笔记本中运行系统表SQL。仅在快速临时检查时使用该实验性CLI命令。
获取示例中使用的ID。
WAREHOUSE_ID
——运行
databricks warehouses list
（或从UI中SQL仓库的“连接详情”中复制）。
METASTORE_ID
（在references/5-system-tables.md中使用）——通过SDK执行
w.metastores.current().metastore_id
获取，或从Catalog UI → 元数据存储详情中获取。
实验性CLI形式（仅用于便捷操作）：
bash
databricks experimental aitools tools query --warehouse WAREHOUSE_ID "
  SELECT source_table_full_name, target_table_full_name
  FROM system.access.table_lineage
  WHERE event_date >= current_date() - 7
"
稳定SDK替代方案（适用于所有CLI版本）：
python
from databricks.sdk import WorkspaceClient

w = WorkspaceClient()
resp = w.statement_execution.execute_statement(
    warehouse_id="WAREHOUSE_ID",
    statement="""
        SELECT source_table_full_name, target_table_full_name
        FROM system.access.table_lineage
        WHERE event_date >= current_date() - 7
        LIMIT 100
    """,
)
for row in resp.result.data_array or []:
    print(row)
CLI功能随版本变化。如果某个
databricks
子命令（如
experimental
工具、
system-schemas
或
external-lineage
）缺失，请使用上述SQL仓库或Python SDK替代，而非尝试猜测参数。

Best Practices

最佳实践

  1. Grant minimal access - Apply least privilege; grant at the narrowest securable that works
  2. Filter by date - System tables can be large; always use date filters
  3. Use appropriate retention - Check your workspace's retention settings
  4. Schedule reports - Create scheduled queries for regular monitoring
  5. Prefer SQL/SDK over experimental CLI - For anything beyond quick checks
  1. 最小权限原则 - 应用权限最小化策略；仅在最窄的可保护对象范围内授予必要权限
  2. 按日期过滤 - 系统表数据量可能很大；请始终使用日期过滤条件
  3. 设置合适的保留期限 - 检查工作区的保留设置
  4. 定时生成报告 - 创建定时查询以实现常规监控
  5. 优先使用SQL/SDK而非实验性CLI - 除快速检查外的场景均优先使用

Related Skills

相关技能

This skill owns Unity Catalog governance: access control, the privilege model, external locations / storage credentials, securable DDL, fine-grained access, system tables, and volumes. For adjacent concerns, use the sibling skill instead:
  • databricks-core (declared parent) — auth, profile selection, generic CLI, and catalog/table exploration
  • databricks-metric-views — metric view definitions / DDL (
    WITH METRICS LANGUAGE YAML
    )
  • databricks-iceberg — Managed Iceberg, External Iceberg Reads (fka Uniform), and Iceberg REST Catalog (IRC) credential vending for external engines — distinct from UC storage credentials (see references/2-external-locations.md)
  • databricks-ml-training — UC model registration and 
    @prod
    /
    @challenger
    aliases
  • databricks-vector-search — Vector Search indexes
  • databricks-pipelines, databricks-jobs, databricks-lakeflow-connect — producing tables via pipelines/jobs/managed ingestion
  • databricks-lakebase — Lakebase / synced tables (OLTP)
  • databricks-ai-functions — AI functions such as 
    ai_mask
    / 
    ai_classify
    (AI transforms, not access control — see references/4-fine-grained-access.md)
  • databricks-aibi-dashboards — AI/BI dashboards on UC data
  • databricks-synthetic-data-gen — generating data stored in UC volumes
本技能负责Unity Catalog的治理：访问控制、权限模型、外部存储位置/存储凭据、可保护对象DDL、细粒度访问控制、系统表和卷。对于相关场景，请使用以下关联技能：
  • databricks-core（父技能）——认证、配置文件选择、通用CLI、catalog/表探索
  • databricks-metric-views——指标视图定义/DDL（
    WITH METRICS LANGUAGE YAML
    ）
  • databricks-iceberg——托管Iceberg、外部Iceberg读取（原Uniform）、以及为外部引擎提供Iceberg REST Catalog (IRC) 凭据发放——与UC存储凭据不同（详见references/2-external-locations.md）
  • databricks-ml-training——UC模型注册与
    @prod
    /
    @challenger
    别名
  • databricks-vector-search——向量搜索索引
  • databricks-pipelines、databricks-jobs、databricks-lakeflow-connect——通过管道/任务/托管 ingestion生成表
  • databricks-lakebase——Lakebase/同步表（OLTP）
  • databricks-ai-functions——AI函数如
    ai_mask
    /
    ai_classify
    （AI转换，而非访问控制——详见references/4-fine-grained-access.md）
  • databricks-aibi-dashboards——基于UC数据的AI/BI仪表盘
  • databricks-synthetic-data-gen——生成存储在UC卷中的合成数据

Roadmap (not yet covered — deferred to a later version)

路线图（暂未覆盖，将在后续版本中支持）

These governance areas are intentionally out of scope for v0.3.0 and planned for later:
  • Delta Sharing / Marketplace / Clean Rooms
  • Lakehouse Federation (connections + foreign catalogs)
  • ABAC / governed tags as policy
以下治理领域在v0.3.0版本中明确不包含，计划在后续版本中支持：
  • Delta Sharing/Marketplace/Clean Rooms
  • Lakehouse Federation（连接与外部catalog）
  • ABAC/受治理标签作为策略

Resources

参考资源