📚 课程目录第4章表创建与DDL操作

表创建与 DDL 操作：用 SQL 与 API 定义 Iceberg 表

在 Iceberg 的世界里，建表不是简单地在元数据里登记一个名字，而是定义一张表的“数据契约”。这张契约决定了数据文件如何组织、如何被查询优化器裁剪、以及表在演进时能承受多大的变更。理解 Iceberg 的 DDL，核心在于把握三个层次：Catalog 中的表标识、表元数据文件（Metadata File）、以及数据文件清单（Manifest List）。当你执行一条 CREATE TABLE 语句时，Iceberg 并不会立刻创建数据目录，而是先在 Catalog 中注册表，并生成第一个元数据版本，指向一个空的 Manifest List。

核心原理：元数据三层结构与 DDL 的对应关系

Iceberg 表之所以能支持原子性的 DDL 变更，是因为它采用了“元数据版本链”的设计。每次 DDL（如 ALTER TABLE）都会生成一个新的元数据文件，并更新 Catalog 中的指针。这个机制与 Hive 直接修改 Metastore 中的字段字符串有本质区别——Iceberg 的每一次变更都产生一个不可变的快照，查询始终基于某个一致的快照版本。

关键映射关系：

CREATE TABLE → 在 Catalog 中注册表，生成版本号为 v1 的元数据文件，包含 Schema、分区规范、表属性。
ALTER TABLE ADD COLUMN → 生成 v2 元数据文件，Schema 演进，但旧数据文件不受影响（读取时通过 ID 映射）。
ALTER TABLE SET TBLPROPERTIES → 修改表属性（如 write.format.default），生成新元数据版本，不触碰数据文件。

理解这个原理后，你会发现 Iceberg 的 DDL 操作天然具备以下优势：无锁并发（多个客户端可同时提交 DDL，通过乐观锁解决冲突）、时间旅行（旧版本元数据仍可访问）、Schema 演进安全（删除字段不会物理删除底层数据）。

方法流程：使用 Spark SQL 创建与管理 Iceberg 表

在实际项目中，最常见的 DDL 执行引擎是 Spark SQL（或 Flink SQL）。以下流程以 Spark 3.x + Iceberg 1.4+ 为例，展示从建表到调整表结构的完整路径。

第一步：创建带分区和表属性的表

-- 在 Spark SQL 中创建 Iceberg 表
CREATE TABLE prod.db.sales (
    order_id     BIGINT,
    customer_id  BIGINT,
    amount       DECIMAL(10,2),
    order_ts     TIMESTAMP,
    region       STRING
)
USING iceberg
PARTITIONED BY (days(order_ts), region)
TBLPROPERTIES (
    'write.format.default' = 'parquet',
    'write.target-file-size-bytes' = '536870912',  -- 512MB
    'history.expire.min-snapshots' = '3',
    'commit.retry.num-retries' = '5'
);

这段 DDL 中，PARTITIONED BY 使用了 Iceberg 的隐藏分区特性——days(order_ts) 表示按订单时间戳的日期做分区，但表中并不存在一个名为 days(order_ts) 的物理列。查询时你仍然可以按 order_ts 过滤，Iceberg 会自动推导分区裁剪条件。

第二步：Schema 演进（ALTER TABLE）

-- 添加字段（支持指定位置）
ALTER TABLE prod.db.sales ADD COLUMN payment_method STRING AFTER amount;

-- 修改字段注释
ALTER TABLE prod.db.sales ALTER COLUMN region COMMENT '销售区域编码';

-- 删除字段（仅删除元数据，不删除底层数据）
ALTER TABLE prod.db.sales DROP COLUMN customer_id;

-- 重命名字段
ALTER TABLE prod.db.sales RENAME COLUMN payment_method TO pay_type;

重要提示：Iceberg 的 Schema 演进通过字段 ID 而非字段名来映射数据。即使你重命名了字段，旧数据文件中的列值依然能正确对应到新字段名上。这是 Iceberg 与 Hive 表最大的区别之一——Hive 重命名列后，旧分区数据可能读不到。

第三步：调整分区规范（重分区）

-- Iceberg 1.4+ 支持分区演进（Partition Evolution）
ALTER TABLE prod.db.sales REPLACE PARTITIONED BY (months(order_ts));

-- 查看当前分区规范
SHOW CREATE TABLE prod.db.sales;

分区演进是 Iceberg 的杀手级特性。在 Hive 中，改变分区策略必须重建整张表并迁移数据；而 Iceberg 允许你直接修改分区规范，旧数据文件继续沿用旧分区布局，新写入的数据使用新分区布局，查询引擎会自动合并两个分区布局的扫描结果。

案例：从 Hive 表迁移到 Iceberg 表的 DDL 对比

假设你有一个 Hive 外部表，希望在不中断业务的情况下迁移到 Iceberg。以下对比展示了两种表在 DDL 层面的关键差异：

操作	Hive 表	Iceberg 表
创建表	`CREATE TABLE ... STORED AS PARQUET`	`CREATE TABLE ... USING iceberg`
添加字段	`ALTER TABLE ADD COLUMNS`（可能影响旧分区读取）	`ALTER TABLE ADD COLUMN`（安全，旧数据自动映射）
修改分区	不支持，需重建表	`REPLACE PARTITIONED BY` 支持原地演进
删除字段	危险，可能导致数据错位	安全，仅逻辑删除
表属性更新	`ALTER TABLE SET TBLPROPERTIES`	同左，但支持更多 Iceberg 专属属性

迁移时，你可以使用 CREATE TABLE ... AS SELECT（CTAS）将 Hive 表数据导入 Iceberg 表，或者使用 ALTER TABLE ... SET TBLPROPERTIES ('iceberg.catalog'='...') 进行原地升级（需谨慎评估版本兼容性）。

误区与复盘：DDL 操作中的常见陷阱

陷阱一：误以为 DROP COLUMN 会释放存储空间。 Iceberg 的删除字段只是从 Schema 中移除引用，底层 Parquet 文件中的列数据仍然存在。如果需要彻底清理，必须执行 REWRITE FILES 重写数据文件。

陷阱二：忽略表属性 write.metadata.previous-versions-max 的默认值。 频繁执行 DDL 会积累大量元数据版本，如果不设置保留数量，元数据目录会无限膨胀。建议设置 'write.metadata.previous-versions-max' = '20' 或启用自动清理。

陷阱三：在并发环境中盲目执行 ALTER TABLE。 虽然 Iceberg 支持乐观锁并发，但如果两个会话同时修改 Schema（例如一个添加字段，另一个删除字段），后提交的操作可能因冲突而失败。建议使用 ALTER TABLE ... SET TBLPROPERTIES ('commit.retry.num-retries'='5') 增加重试次数。

复盘建议：在开发环境中，每次执行 DDL 后，使用 SELECT * FROM prod.db.sales.snapshots 查看快照历史，确认元数据版本正确生成。同时，养成在 CI/CD 流程中保存 DDL 脚本的习惯，因为 Iceberg 的元数据版本链使得回滚 DDL 变得简单——只需将 Catalog 指针指回旧版本即可。

最后，请记住 Iceberg DDL 的核心哲学：元数据与数据分离。你操作的是表的“定义层”，而数据文件始终躺在存储系统中等待被扫描。这种设计让 DDL 变得轻量、安全且可逆，但也要求你理解元数据版本的管理方式，才能真正用好 Iceberg 的表结构演进能力。