S3 Tables 托管迁移 Hive 到 Iceberg：迁移前先确认哪几类表结构与分区语义

如果只问一句“迁移前要先看什么”，答案是：先看源表是否属于这次托管迁移的适用范围，再看表结构能否落到你显式给出的目标 schema，最后看分区在 Hive 里是“目录约定”还是在 Iceberg 里变成“元数据语义”。前两项决定能不能迁，后一项决定迁完之后查询结果和写入行为是否还符合预期。

AWS 在 2026 年 11 月 4 日的公告中说明，S3 Tables 现在支持把 Amazon S3 上、注册在 AWS Glue Data Catalog 中的 Apache Hive 表托管迁移为 Apache Iceberg 表，整个过程由 API 驱动，不需要自建管道或预留计算，源表在生产写入继续的情况下可以多次同步（AWS 发布公告）。但公告没有展开逐项类型映射和分区转换规则，下面把“公告已确认的”和“需要你用兼容性报告核实的”分开说。

第一步：先划支持边界，不然表结构核对没有意义#

公告给出的范围很窄，先对照一遍：

• 元数据：表必须注册在 AWS Glue Data Catalog 中。其他 Hive Metastore 不在这次托管迁移的说明范围内。
• 文件格式：只支持 Parquet。ORC、Avro、文本格式的表，公告没有列为支持对象。
• 账号与区域：源表和目标表桶必须在同一个 AWS 账号、同一个 AWS Region。
• 区域：公告列出的可用区域包括美国东部（弗吉尼亚北部、俄亥俄）、美国西部（俄勒冈）、亚太（孟买、新加坡、悉尼、东京）和欧洲（法兰克福、爱尔兰、斯德哥尔摩）。其他区域是否可用，待核实。

如果源表目录里混有非 Parquet 文件、临时文件或 _SUCCESS 标记，是否会被纳入迁移范围，公告没有说明。公告只说迁移前会识别“范围内的每一个源对象”并生成兼容性报告，因此正确做法是先把对象清单和报告读一遍，而不是假设目录里只有数据文件。

表结构：四类要先核对#

1. 列类型与嵌套层级

公告确认迁移流程包含类型转换和兼容性检查，并提供 incompatibleValuesPolicy 策略。这句话的含义是：类型转换是迁移的一部分，但不等于所有类型都能无损落地。迁移前建议逐列核对以下几类：

• decimal：精度和小数位是否在目标类型可表示范围内，是否存在超出范围的值。
• timestamp：Hive 的 timestamp 不带时区，Iceberg 同时有带时区和不带时区的时间类型。映射到哪一种，会直接影响跨时区查询结果。
• char/varchar：Iceberg 没有等价的定长/变长字符类型，通常会落到 string，长度约束是否保留需要确认。
• 嵌套结构：array、map、struct 的层数和内部类型；Hive 的 uniontype 在 Iceberg 中没有直接对应类型，属于高风险项。
• map 的 key：Hive 对 map key 的约束比 Iceberg 宽松，key 为 null 或复杂类型的数据需要单独检查。

公告没有给出完整的 Hive→Iceberg 类型映射表，这一部分应以 S3 Tables 迁移文档和实际生成的表级兼容性报告为准。

2. 表定义之外的分区级 schema 差异

Hive 常被当作 schema-on-read 使用：Glue 里只有一份表定义，但不同分区目录可能是不同时期、用不同 schema 写进去的。Iceberg 表则是一份统一 schema 加演进历史。迁移时真正的风险不是“当前表定义能不能转”，而是“历史分区里有没有表定义没覆盖的列或类型”。

公告示例里的 unmatchedSourceFieldsPolicy 取值为 fail，说明源字段与目标 schema 不匹配时可以按策略处理。建议第一轮就用 fail，让报告把差异暴露出来，而不是先放宽策略、把问题留到查询阶段。

3. 字段名、大小写与重名

Hive 对列名大小写的处理相对宽松，而不同 Iceberg 引擎对大小写的处理并不完全一致。需要确认源表是否存在仅大小写不同的列名、保留字列名或含特殊字符的列名。这类问题在表定义层面看不出来，往往要等目标表建好后由引擎报错。公告未说明这部分是否在兼容性检查覆盖范围内，建议在报告和试查阶段各验证一次。

4. 目标 schema 是你给的，不是服务猜的

公告的 CLI 示例里，目标表请求显式携带 schema、identifierFieldIds、icebergSortOrder、icebergFormatVersion 和压缩参数。这意味着迁移前就要把目标表结构定下来。两个容易忽略的点：

• identifierFieldIds 用于行级更新/删除语义。普通 Hive 表没有主键约束，是否声明、声明哪一列，需要结合下游是否要做 upsert 来决定。
• icebergSortOrder 影响写入布局和查询裁剪，和 Hive 的 SORTED BY 不是同一套语义，不能直接照搬。

分区语义：从目录布局变成元数据#

这是迁移前后行为差异最容易被低估的一块。Hive 的分区主要是路径约定，Iceberg 的分区是表元数据里的 transform。迁移时要逐项确认：

迁移窗口：读公告时容易漏掉的两句#

公告说明目标表在迁移期间是只读的，完成迁移后才提升为可读写；同步可以执行多次，每次只复制变化，除 cutover 期间的几分钟外不需要停止源表写入。这带来两个实际约束：

• 依赖目标表可写的下游任务，不能在建表后立刻切过去。
• cutover 需要源端写入方配合暂停。先确认源表有没有长事务或持续写入作业，再定停写窗口。

另外，公告提到过去自建迁移需要自己做回滚能力，但没有说明这次托管迁移在失败或 cutover 后如何回滚。这一点应在上线前向官方文档或支持渠道确认，不能默认“源表不动就等于可回滚”。

一个未执行的调用骨架#

下面示例按公告中的请求结构做了删减，账号、桶名、库表名均为占位符，未实际执行，仅用于说明哪些字段需要在迁移前定好：

{
  "roleARN": "arn:aws:iam::111122223333:role/YOUR_MIGRATION_ROLE",
  "destinationTable": {
    "tableBucketARN": "arn:aws:s3tables:us-east-1:111122223333:bucket/YOUR_BUCKET",
    "namespace": "YOUR_NAMESPACE",
    "name": "YOUR_TABLE",
    "properties": {
      "icebergFormatVersion": 2,
      "compressionCodec": "zstd"
    },
    "schema": {
      "type": "struct",
      "schemaId": 0,
      "fields": [
        { "id": 1, "name": "id", "type": "long", "required": true },
        { "id": 2, "name": "payload", "type": "string", "required": false }
      ]
    },
    "icebergSortOrder": {
      "orderId": 1,
      "fields": [
        { "sourceId": 1, "transform": "identity", "direction": "asc", "nullOrder": "nulls-first" }
      ]
    }
  },
  "sourceType": "glueTable",
  "source": {
    "glueTable": {
      "catalogId": "111122223333",
      "databaseName": "YOUR_DB",
      "tableName": "YOUR_HIVE_TABLE"
    }
  },
  "dataMigration": {
    "migrationPolicies": {
      "unmatchedSourceFieldsPolicy": "fail",
      "incompatibleValuesPolicy": "fail"
    }
  }
}

对应的命令是 aws s3tables start-table-migration --cli-input-json file:///tmp/start-migration.json，之后按需调用 sync-table-migration，最后 complete。公告还提到可以通过 S3 控制台、AWS SDK 和 Agent Toolkit for AWS 完成同一流程。

迁移前检查清单#

1. 确认源表在 Glue 中注册、数据为 Parquet、与目标同账号同区域。
2. 拉取源表 location 下的对象清单，标出非 Parquet 文件、临时文件和大小写混合路径。
3. 逐列比对 Hive 表定义与目标 schema，重点看 decimal、timestamp、char/varchar、union 和嵌套结构。
4. 抽查历史分区，确认是否存在表定义未覆盖的列或类型。
5. 确认分区列的路径编码、NULL 表示、层级顺序，以及分区列是否被重复写入文件。
6. 确认原表的分桶、排序信息在新表中如何处理。
7. 先用 fail 策略跑一次迁移计划，阅读表级和对象级兼容性报告，再决定是否开始复制。
8. 和源端写入方约定 cutover 停写窗口，并确认回滚方式。

结论可以压缩成一句：这次托管迁移把基础设施工作接了过去，但“表结构怎么定、分区语义要不要变”仍然是使用方的决策。公告能确认的是范围和流程；类型映射明细、分桶处理、空分区值转换和回滚语义，都需要以迁移文档、兼容性报告和实际试查结果为准。