databricks-unity-catalog

Unity Catalog

Unity Catalog 治理指南——访问控制、权限模型、 外部位置、可保护对象 DDL 和细粒度访问——以及系统表和 卷文件操作。

运行 databricks CLI 命令前，请确认 CLI 和子命令均已存在。 运行 databricks --version——本技能要求使用统一 CLI（≥ v1.0.0）。此处展示的若干 子命令（experimental aitools、system-schemas、external-lineage、 grants）会因版本或工作区可用性而异；如果某个子命令不存在或拒绝某个标志， 请改用 SQL 形式或 Python SDK，而不要猜测。相关参考资料会在适用时注明各自的 最低版本要求。

何时使用此技能

在以下情况下使用此技能：

治理与访问控制（从这里开始）：

• 授予或撤销访问权限——GRANT/REVOKE、UC 权限模型、所有权（ALTER … OWNER TO）、SHOW GRANTS、“谁可以读取/写入此表？”
• 行级和列级安全——行筛选器、列掩码、使用 current_user() / is_account_group_member() 的动态视图
• 外部位置和存储凭据——CREATE STORAGE CREDENTIAL、CREATE EXTERNAL LOCATION、底层外部表/卷
• 可保护对象 DDL 和元数据——创建/更改目录、架构、托管表与外部表、视图；注释、标签、表属性、所有权

可观测性与文件：

• 使用卷（上传、下载、列出 /Volumes/ 中的文件）
• 查询数据血缘（表依赖关系、列级数据血缘）
• 分析审计日志（谁访问了什么、权限变更）
• 监控计费和用量（DBU 消耗、成本分析）
• 跟踪计算资源（集群用量、仓库指标）
• 查看作业执行情况（运行历史记录、成功率、失败情况）
• 分析查询性能（慢查询、仓库利用率）
• 分析数据质量（数据分析、漂移检测、指标表）

参考文件

主题	文件	说明
访问控制	references/1-access-control.md	权限模型、可保护对象层级、GRANT/REVOKE、所有权、继承、SHOW GRANTS
外部位置	references/2-external-locations.md	存储凭据（AWS/Azure/GCP）、外部位置、验证
可保护对象 DDL	references/3-securables-ddl.md	CREATE/ALTER/DROP 目录/架构/表/视图、注释、标签、所有权
细粒度访问	references/4-fine-grained-access.md	行筛选器、列掩码、动态视图
系统表	references/5-system-tables.md	数据血缘、审计、计费、计算、作业、查询历史记录
卷	references/6-volumes.md	卷文件操作、权限、最佳实践
数据分析	references/7-data-profiling.md	数据分析、漂移检测、分析指标

快速入门

创建 Unity Catalog 对象（CLI）

对 create 命令使用 --json。 位置参数的顺序因命令而异，且在不同 CLI 版本间有所变化，因此 --json 是本技能中始终采用的、与顺序无关且版本稳定的形式。

# 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

如果你更喜欢使用位置参数，create 命令仍支持这种方式，但不同命令的顺序并不统一——以下是各命令的位置参数顺序（也是推荐使用 --json 的原因）：

命令	create 的位置参数顺序
databricks catalogs create	NAME
databricks schemas create	NAME CATALOG_NAME
databricks volumes create	CATALOG_NAME SCHEMA_NAME NAME VOLUME_TYPE

CLI 的命令接口因版本而异。 如果你安装的版本缺少某个 databricks 子命令或位置参数签名，请优先使用 --json、SQL 形式或 Python SDK，而不是猜测标志。

卷文件操作（CLI）

即使是 UC 卷路径，databricks fs 也要求使用 dbfs: 方案前缀——如果不加此前缀，CLI 会将路径视为本地文件系统路径，并报错 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 是核心治理操作。完整权限模型请参阅 references/1-access-control.md。

-- 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 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`;

常用查询

-- 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;

从 CLI 运行 SQL

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 仓库 Connection details 里复制）。METASTORE_ID（在 references/5-system-tables.md 中使用）——通过 SDK 调用 w.metastores.current().metastore_id 获取，或在 Catalog UI → metastore details 中查看。

实验性 CLI 形式（仅为方便起见）：

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 版本）：

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，而不是猜测标志。

最佳实践

1. 授予最小访问权限 - 遵循最小权限原则；在满足需求的最小可保护对象上授予权限
2. 按日期筛选 - 系统表可能很大；务必使用日期筛选条件
3. 采用适当的保留策略 - 检查工作区的保留设置
4. 计划报告 - 创建计划查询，以便定期监控
5. 优先使用 SQL/SDK，而非实验性 CLI - 除快速检查外，其他情况均应如此

相关技能

本技能负责 Unity Catalog 的治理：访问控制、权限模型、外部位置 / 存储凭据、可保护对象 DDL、精细化访问、系统表和卷。对于相邻领域，请使用对应的兄弟技能：

• databricks-core（声明的父技能）— 身份验证、配置文件选择、通用 CLI，以及目录 / 表的探索
• databricks-metric-views — 指标视图定义 / DDL（WITH METRICS LANGUAGE YAML）
• databricks-iceberg — Managed Iceberg、External Iceberg Reads（以前称为 Uniform），以及面向外部引擎的 Iceberg REST Catalog (IRC) 凭据发放 — 与 UC 存储凭据不同（参见 references/2-external-locations.md）
• databricks-ml-training — UC 模型注册和 @prod / @challenger 别名
• databricks-vector-search — Vector Search 索引
• databricks-pipelines、databricks-jobs、databricks-lakeflow-connect — 通过管道 / 作业 / 托管式摄取来生成表
• databricks-lakebase — Lakebase / 同步表（OLTP）
• databricks-ai-functions — ai_mask / ai_classify 等 AI 函数（AI 转换，而非访问控制 — 参见 references/4-fine-grained-access.md）
• databricks-aibi-dashboards — 基于 UC 数据的 AI/BI 仪表板
• databricks-synthetic-data-gen — 生成存储在 UC 卷中的数据

路线图（尚未涵盖 — 延后至后续版本）

这些治理领域有意不纳入 v0.3.0 的范围，计划在后续版本中推出：

• Delta Sharing / Marketplace / Clean Rooms
• Lakehouse Federation（连接 + 外部目录）
• ABAC / 受治理标签作为策略

资源

• Unity Catalog 权限与可保护对象
• Unity Catalog 系统表
• 审计日志参考
• 管理外部位置和存储凭据