databricks-iceberg

Databricks 上的 Apache Iceberg

Databricks 提供多种使用 Apache Iceberg 的方式：原生托管 Iceberg 表、用于 Delta 与 Iceberg 互操作的 UniForm，以及供外部引擎访问的 Iceberg REST Catalog（IRC）。

---

关键规则（始终遵循）

• 必须使用 Unity Catalog — 所有 Iceberg 功能都要求工作区启用 UC
• 不得在 Databricks Runtime（DBR）中安装 Iceberg 库（DBR 内置了 Iceberg 支持；添加库会导致版本冲突）
• 不得设置 write.metadata.path 或 write.metadata.previous-versions-max — Databricks 会自动管理元数据位置；覆盖这些设置会导致数据损坏
• 必须在编写代码前确定适合用例的 Iceberg 模式 — 请参阅下文的适用场景部分
• 必须了解 PARTITIONED BY 和 CLUSTER BY 为外部引擎生成相同的 Iceberg 元数据 — UC 会维护一个 Iceberg 分区规范，其中的分区字段对应于聚类键，因此通过 IRC 读取的外部引擎会看到一张分区化的 Iceberg 表（不是 Hive 风格的分区表，而是使用规范 Iceberg 分区字段的表），并且可以按这些字段进行分区裁剪；UC 内部会将这些字段用作 liquid clustering 键；两种语法的唯一区别是：(1) PARTITIONED BY 是标准 Iceberg DDL（任何引擎都可以创建该表），而 CLUSTER BY 是仅限 DBR 的 DDL；(2) PARTITIONED BY 会自动处理 DV/行跟踪属性，而在 v2 上使用 CLUSTER BY 时需要手动设置 TBLPROPERTIES
• 不得在托管 Iceberg 表上将基于表达式的分区转换（bucket()、years()、months()、days()、hours()）与 PARTITIONED BY 搭配使用 — 仅支持直接引用列；表达式转换会导致错误
• 在 Iceberg v2 表上使用 CLUSTER BY 时，必须禁用删除向量和行跟踪 — 在 TBLPROPERTIES 中设置 'delta.enableDeletionVectors' = false 和 'delta.enableRowTracking' = false（Iceberg v3 会自动处理；PARTITIONED BY 在 v2 和 v3 上都会自动处理）

---

核心概念

概念	概述
托管 Iceberg 表	使用 USING ICEBERG 创建的原生 Iceberg 表 — 可在 Databricks 和外部 Iceberg 引擎中完整读写
外部 Iceberg 读取（Uniform）	自动生成 Iceberg 元数据的 Delta 表 — 外部按 Iceberg 读取，内部按 Delta 写入
兼容模式	适用于 SDP 管道中流式表和物化视图的 UniForm 变体
Iceberg REST Catalog（IRC）	Unity Catalog 内置的 REST 端点，实现 Iceberg REST Catalog 规范 — 使外部引擎（Spark、PyIceberg、Snowflake）能够访问由 UC 管理的 Iceberg 数据
Iceberg v3	新一代格式（DBR 18 LTS+）— 删除向量、VARIANT 类型、行谱系

---

快速入门

创建托管 Iceberg 表

-- No clustering
CREATE TABLE my_catalog.my_schema.events
USING ICEBERG
AS SELECT * FROM raw_events;

-- PARTITIONED BY (recommended for cross-platform): standard Iceberg syntax, works on EMR/OSS Spark/Trino/Flink
-- auto-disables DVs and row tracking — no TBLPROPERTIES needed on v2 or v3
CREATE TABLE my_catalog.my_schema.events
USING ICEBERG
PARTITIONED BY (event_date)
AS SELECT * FROM raw_events;

-- CLUSTER BY on Iceberg v2 (DBR-only syntax): must manually disable DVs and row tracking
CREATE TABLE my_catalog.my_schema.events
USING ICEBERG
TBLPROPERTIES (
  'delta.enableDeletionVectors' = false,
  'delta.enableRowTracking' = false
)
CLUSTER BY (event_date)
AS SELECT * FROM raw_events;

-- CLUSTER BY on Iceberg v3 (DBR-only syntax): no TBLPROPERTIES needed
CREATE TABLE my_catalog.my_schema.events
USING ICEBERG
TBLPROPERTIES ('format-version' = '3')
CLUSTER BY (event_date)
AS SELECT * FROM raw_events;

在现有 Delta 表上启用 UniForm

ALTER TABLE my_catalog.my_schema.customers
SET TBLPROPERTIES (
  'delta.columnMapping.mode' = 'name',
  'delta.enableIcebergCompatV2' = 'true',
  'delta.universalFormat.enabledFormats' = 'iceberg'
);

---

读写能力矩阵

表类型	Databricks 读取	Databricks 写入	外部 IRC 读取	外部 IRC 写入
托管 Iceberg（USING ICEBERG）	是	是	是	是
Delta + UniForm	是（按 Delta 读取）	是（按 Delta 写入）	是（按 Iceberg 读取）	否
Delta + 兼容模式	是（按 Delta 读取）	是	是（按 Iceberg 读取）	否

---

参考文件

文件	摘要	关键词
references/1-managed-iceberg-tables.md	创建和管理原生 Iceberg 表 — DDL、DML、Liquid Clustering、Predictive Optimization、Iceberg v3、限制	CREATE TABLE USING ICEBERG、CTAS、MERGE、时间旅行、删除向量、VARIANT
references/2-uniform-and-compatibility.md	将 Delta 表设为可读的 Iceberg 表 — 常规表使用 UniForm，流式表和 MV 使用 Compatibility Mode	UniForm、universalFormat、Compatibility Mode、流式表、物化视图、SDP
references/3-iceberg-rest-catalog.md	通过 IRC 端点向外部引擎开放 Databricks 表 — 身份验证、凭据发放、IP 访问列表	IRC、REST Catalog、凭据发放、EXTERNAL USE SCHEMA、PAT、OAuth
references/4-snowflake-interop.md	Snowflake 与 Databricks 双向集成 — 目录集成、外部目录、发放的凭据	Snowflake、目录集成、外部卷、发放的凭据、REFRESH_INTERVAL_SECONDS
references/5-external-engine-interop.md	通过 IRC 连接 PyIceberg、OSS Spark、AWS EMR、Apache Flink 和 Kafka Connect	PyIceberg、OSS Spark、EMR、Flink、Kafka Connect、pyiceberg.yaml

---

适用场景

• 创建新的 Iceberg 表 → references/1-managed-iceberg-tables.md
• 将现有 Delta 表设为可读的 Iceberg 表 → references/2-uniform-and-compatibility.md
• 将流式表或 MV 设为可读的 Iceberg 表 → references/2-uniform-and-compatibility.md（Compatibility Mode 部分）
• 选择 Managed Iceberg、UniForm 或 Compatibility Mode → references/2-uniform-and-compatibility.md 中的决策表
• 通过 REST API 向外部引擎开放 Databricks 表 → references/3-iceberg-rest-catalog.md
• 将 Databricks 与 Snowflake 集成（任一方向） → references/4-snowflake-interop.md
• 连接 PyIceberg、OSS Spark、Flink、EMR 或 Kafka → references/5-external-engine-interop.md

---

常见问题

问题	解决方案
不支持更改数据馈送（CDF）	托管的 Iceberg 表不支持 CDF。如果需要 CDF，请使用 Delta + UniForm。
UniForm 异步延迟	Iceberg 元数据是异步生成的。写入后，外部引擎可能需要短暂等待才能看到最新数据。使用 DESCRIBE EXTENDED table_name 检查状态。
压缩编解码器变更	托管的 Iceberg 表默认使用 zstd 压缩（而非 snappy）。不支持 zstd 的旧版 Iceberg 读取器会运行失败。请验证读取器兼容性，或将 write.parquet.compression-codec 设为 snappy。
Snowflake 的 1000 次提交限制	Snowflake 的 Iceberg 目录集成只能查看最近的 1000 次 Iceberg 提交。高频写入器必须压缩元数据，否则 Snowflake 将无法查看较早的数据。
UniForm 与删除向量	UniForm 要求禁用删除向量（delta.enableDeletionVectors = false）。如果表已启用删除向量，请先将其禁用，再启用 UniForm。
Iceberg 不支持浅克隆	Iceberg 表不支持 SHALLOW CLONE。请改用 DEEP CLONE 或 CREATE TABLE ... AS SELECT。
与外部引擎的版本不匹配	确保外部引擎使用的 Iceberg 库版本与表的格式版本兼容。Iceberg v3 表需要 Iceberg 库 1.9.0+。

---

相关技能

• databricks-unity-catalog — 目录／架构管理、治理、系统表
• databricks-pipelines — SDP 管道（流式表、使用 Compatibility Mode 的物化视图）
• databricks-python-sdk — 用于 Databricks 操作的 Python SDK 和 REST API
• databricks-dbsql — SQL 仓库功能、查询模式

---

资源

• Iceberg 概览 — Databricks 上 Iceberg 的主要入口
• UniForm — Delta 通用格式
• Iceberg REST Catalog — IRC 端点和外部引擎访问
• Compatibility Mode — 适用于流式表和 MV 的 UniForm
• Iceberg v3 — 新一代格式功能
• 外部表 — 读取外部目录数据