1. 课程导入
欢迎进入《Iceberg Schema与Partition演进实战》。在数据湖仓一体化的今天，Apache Iceberg 之所以能成为事实标准，核心不在于它“又造了一张表格式”，而在于它把表结构变更与分区布局调整这两件过去代价极高、甚至需要停机重写全量数据的事情，变成了元数据层面的轻量操作。本课程要解决的，正是这两个最容易被低估、却最容易在生产环境踩坑的能力。
一、为什么值得专门学：核心价值
传统 Hive 表做一次加列、改类型或换分区字段，往往意味着重跑历史数据、重刷分区、下游任务大面积失败。Iceberg 通过三层元数据（metadata file → manifest list → manifest file）把“数据文件”和“表定义”解耦，使得 Schema 演进和 Partition 演进都只改元数据指针，历史数据文件原地不动。这带来三个直接价值：
- 零重写成本：加列、删列、改列类型、重命名列，不触碰任何 Parquet/ORC 数据文件。
- 查询正确性：演进后新旧数据用同一套逻辑读取，靠 field-id 而非列名对齐，避免“改名即错位”。
- 分区可进化：从按天分区升级到按小时，或从 identity 分区改为 bucket 分区，无需重刷历史分区。
一句话概括本课程的核心命题：让表结构变化和分区策略变化，像改配置一样安全、可回滚、可审计。
二、整体课程框架与实战路线图
全课程共 30 章，按“原理 → 单点能力 → 组合演进 → 生产治理”四段递进。下面的路线图展示了从认知到落地的完整路径，也是你学习时判断自己进度的坐标。
三、核心原理速览：Schema 演进与 Partition 演进各自在改什么
理解演进，先要理解 Iceberg 的“字段身份”机制。每个列在创建时被分配一个全局唯一的 field-id，数据文件里的列按 id 存储，而不是按名字。因此重命名列只是改元数据里的 name 映射，读取时仍按 id 找到同一份数据。这是 Schema 演进安全性的根基。
分区演进则依赖 partition spec 的版本化。每次修改分区字段，Iceberg 会生成一个新的 spec-id，新写入的数据按新 spec 组织，旧数据仍按旧 spec 读取。查询时引擎根据每个数据文件携带的 spec-id 做分区裁剪，因此新旧分区布局可以共存。
-- 查看当前表的 schema 与 field-id
DESCRIBE TABLE prod.db.orders;
-- 查看分区演进历史（spec 版本）
SELECT * FROM prod.db.orders.partitions;
-- 查看元数据文件中的 schema 版本
SELECT * FROM prod.db.orders.metadata_log_entries;四、典型场景与误区复盘
下面这张清单对比了“正确做法”与“常见误区”，建议在动手前先过一遍，能省下大量返工时间。
| 场景 | 正确做法 | 常见误区 |
|---|---|---|
| 新增列 | 直接 ADD COLUMN，历史数据读为 null | 重刷全量数据“补齐”新列 |
| 修改列类型 | 仅允许 int→long、float→double 等安全提升 | 强行 string→int，导致读取失败 |
| 重命名列 | 改元数据 name，field-id 不变 | 删列再建列，丢失历史数据映射 |
| 调整分区 | 新增 spec，新旧分区共存 | 直接改 spec 后重写全部历史分区 |
| 删除分区字段 | 保留旧 spec 供历史数据读取 | 删除后旧数据无法被正确裁剪 |
高频误区：把“Schema 演进”理解成“改表结构 DDL”。Iceberg 的演进是元数据版本推进，不是数据重写。一旦你开始重写数据文件，就说明用错了方式，成本和风险都会成倍上升。
学习建议：每学完一个演进操作，立刻在本地用 Spark 或 Flink 建一张小表验证：改完之后旧数据还能不能读、新数据写进去分区对不对、时间旅行能不能回到改之前。这三问能覆盖 80% 的生产问题。
本课程后续每一章都会围绕一个具体演进动作展开，配合可复制的 SQL、配置和排障日志。你现在只需要记住一件事：Iceberg 演进的目标不是“改得动”，而是“改得安全、改得可回滚、改得下游无感”。带着这个标准进入后面的实战，你会对每一个操作背后的元数据变化有更清晰的判断。