📚 课程目录第3章 Iceberg Schema基础

3. Iceberg Schema基础

在Iceberg中，Schema不是“建表时写一次就束之高阁”的附属信息，而是表元数据的一等公民。它决定了数据如何被解释、写入时如何校验、查询时如何裁剪，以及后续演进时哪些变更安全、哪些变更危险。理解Schema的定义方式、字段类型体系、嵌套结构表达、演进规则与元数据存储机制，是掌握Iceberg表管理能力的基础。

一、核心原理：Schema是带ID的字段树

Iceberg Schema的本质是一棵字段树，每个字段拥有全局唯一的整数ID。这个ID一旦分配，在表生命周期内不会因重命名、移动位置或类型提升而改变。正是这种“ID稳定、名称可变”的设计，使得Iceberg能够在不重写数据文件的前提下完成Schema演进。

Schema由若干顶层字段组成，每个字段包含：字段ID、名称、类型、是否必填（required/optional）、文档说明，以及可选的初始默认值。嵌套结构（struct、list、map）中的子字段同样拥有独立ID，形成层级化的ID空间。

关键认知：Iceberg通过字段ID而非字段名来追踪列。重命名列只是修改元数据中的名称映射，历史数据文件中的列ID不变，因此无需重写数据。

Schema在元数据中以JSON形式序列化，并带有schema-id。每次Schema变更都会生成新的schema-id，同时保留历史Schema列表，用于时间旅行和快照读取时的正确解析。

二、字段类型与嵌套结构

Iceberg支持丰富的基础类型和三种嵌套类型，能够表达复杂的数据模型。

类别	类型	说明
基础类型	boolean, int, long, float, double	数值与布尔
基础类型	decimal(P,S), date, time, timestamp, timestamptz	精度数值与时间
基础类型	string, uuid, fixed(L), binary	文本与二进制
嵌套类型	struct	命名字段集合，类似对象
嵌套类型	list	有序元素集合，元素可为任意类型
嵌套类型	map	键值对集合，键必须为必填基础类型

嵌套结构可以任意组合，例如struct<id: long, tags: list<string>, attrs: map<string, string>>。每个子字段都有独立ID，这使得Iceberg可以只演进嵌套结构中的某个子字段，而不影响其他部分。

{
  "type": "struct",
  "fields": [
    {"id": 1, "name": "order_id", "type": "long", "required": true},
    {"id": 2, "name": "customer", "type": {
      "type": "struct",
      "fields": [
        {"id": 3, "name": "name", "type": "string", "required": false},
        {"id": 4, "name": "level", "type": "int", "required": false}
      ]
    }, "required": false},
    {"id": 5, "name": "items", "type": {
      "type": "list",
      "element-id": 6,
      "element": "string",
      "element-required": false
    }, "required": false}
  ]
}

三、演进规则与兼容性约束

Iceberg的Schema演进遵循“安全变更自动允许、危险变更明确拒绝”的原则。核心判断依据是：变更是否会导致已有数据无法正确读取。

允许的操作：新增可选字段、删除任意字段、重命名字段、调整字段顺序、提升类型（int→long、float→double、decimal精度提升）。
禁止的操作：将可选字段改为必填、将必填字段改为可选（部分引擎允许但需谨慎）、类型降级、改变嵌套结构的基本形态。
需谨慎的操作：删除字段后历史快照仍可读取，但新写入数据不再包含该字段；重命名后旧查询需使用新名称。

类型提升只允许“向上兼容”方向：int→long、float→double、decimal(P,S)→decimal(P',S)且P'>P。反向操作会破坏已有数据解析，Iceberg会直接拒绝。

兼容性约束的底层逻辑是：读取时，Iceberg根据数据文件中的字段ID与当前Schema进行匹配。如果文件中的字段ID在当前Schema中不存在，则忽略；如果当前Schema新增了字段而文件中没有，则填充默认值或null。这种基于ID的解析机制，使得Schema演进与数据文件解耦。

四、元数据存储机制与实战场景

Schema信息存储在Iceberg表的元数据层，具体位置包括：表级metadata.json中的schemas列表、当前schema-id，以及每个快照（snapshot）关联的schema-id。这种设计使得读取历史快照时，能够使用当时的Schema正确解析数据。

-- 查看当前Schema
DESCRIBE TABLE prod.orders;

-- 查看Schema历史
SELECT * FROM prod.orders.schemas;

-- 新增字段
ALTER TABLE prod.orders ADD COLUMN discount DECIMAL(10,2);

-- 重命名字段
ALTER TABLE prod.orders RENAME COLUMN discount TO discount_amount;

-- 提升类型
ALTER TABLE prod.orders ALTER COLUMN quantity TYPE bigint;

在实际场景中，Schema演进常用于以下情况：业务新增维度字段、上游数据类型扩展、字段命名规范化、废弃字段清理。由于Iceberg不重写历史数据，这些操作通常秒级完成，仅修改元数据。

最佳实践：新增字段时始终设为optional并指定默认值，避免下游查询因null处理不当而报错。删除字段前先确认没有下游任务依赖该字段名。

五、常见误区与复盘

误区一：重命名等于修改数据。实际上重命名只改元数据，历史数据文件中的字段ID不变，读取时按ID匹配，名称仅用于展示。
误区二：删除字段后数据立即消失。删除字段后，新写入数据不再包含该字段，但历史快照仍可读取该字段，直到快照过期。
误区三：类型可以随意转换。Iceberg只允许向上兼容的类型提升，string与int之间不能互转，否则会破坏已有数据解析。
误区四：嵌套字段不能单独演进。实际上嵌套结构中的子字段拥有独立ID，可以单独新增、删除或重命名，不影响同级其他字段。

复盘要点：Schema演进的安全性建立在字段ID稳定和类型兼容规则之上。每次变更前，应确认变更方向是否在允许列表内，并评估下游查询对新增null值或字段消失的容忍度。理解元数据中schema-id与快照的关联关系，是排查“历史数据读取异常”类问题的关键。