Hive 表托管迁移到 Iceberg：Schema、分区与回滚的顺序怎么排

如果只看操作顺序，这次托管迁移的主线很短：先 Start，按需 Sync 若干次，最后 Complete。但真正决定迁移能不能平稳落地的，是三个前置判断——Schema 能不能对上、分区布局怎么落、出问题时按什么顺序退回去。AWS 在 2026 年 11 月 4 日的公告中把这条路做成了托管 API 操作，同时明确了若干限制；分区映射与回滚语义则没有在公告里展开，需要单独核实。

先把事实基线固定下来#

根据 AWS News Blog 的公告，S3 Tables 的托管迁移面向存储在 Amazon S3、注册在 AWS Glue Data Catalog 中的 Parquet 格式 Hive 表。托管范围包括数据校验、兼容性检查、类型转换、文件重压缩和 compaction；迁移前会先识别范围内的全部源对象并生成兼容性报告，再开始复制数据。计费上，只为复制的数据付费，Hive 到 Iceberg 的转换不单独收费。

公告写明的边界值得先记住：启动时仅支持同一 AWS 账号、同一 AWS 区域内的 Glue 表；可用区域为美国东部（弗吉尼亚北部、俄亥俄）、美国西部（俄勒冈）、亚太（孟买、新加坡、悉尼、东京）和欧洲（法兰克福、爱尔兰、斯德哥尔摩）。跨账号、跨区域或非 Parquet 表不在本次能力范围内。

另一个容易被忽略的状态约束是：目标表在整个迁移期间是只读的，只有 complete 之后才被提升为读写。这意味着迁移期不能靠"双写 + 比对"来验证正确性，校验只能依赖源侧读取、兼容性报告和迁移报告。这一点会直接影响后面的回滚设计。

Schema 演进：先过兼容性报告这道闸门#

两个 policy 决定迁移是继续还是失败

公告给出的启动参数里，dataMigration.migrationPolicies 有两个键：unmatchedSourceFieldsPolicy 与 incompatibleValuesPolicy，示例值都是 fail。字面含义是：源表出现目标 schema 里没有的字段，或出现无法按目标类型转换的值时，迁移失败而不是静默跳过。这是保守但可解释的默认值——失败比悄悄丢列更容易排查。不过公告没有说明这两个键还接受哪些取值，也没说明失败是发生在校验阶段还是复制阶段，这部分待核实。

由此可以推出一条操作顺序：先把兼容性报告跑出来读完，再决定改源表还是改目标 schema。报告分表级和对象级两类，示例中通过 migrationOutput.prefixes.tableCompatibilityReport 与 objectCompatibilityReport 指定输出位置。表级报告回答"结构能不能对上"，对象级报告回答"具体哪些文件有问题"，后者才是决定要修多少数据的依据。

Schema 变更尽量前置，不要在迁移中途改

公告把 Iceberg 的 schema evolution 列为 Iceberg 的既有能力，但没有说明迁移任务本身会如何处理迁移期间的源表 DDL 变更。在这一点上，稳妥的做法（属于建议，不是公告承诺）是：在正式 Start 之前冻结源表结构，把加列、放宽类型这类变更排到迁移完成之后，用 Iceberg 自身的 schema evolution 在目标表上做。这样 Sync 阶段的"只复制变化"才不会掺进结构变化，排查问题时变量更少。

如果确实必须让源表继续演进，那么每次 Sync 之后重新检查一遍兼容性报告，比等到 Complete 时才发现字段对不上要划算。

目标 schema 的写法

下面这段来自公告示例，本次未执行，仅用于说明字段结构，不能当作可直接运行的配置：

{
  "schema": {
    "type": "struct",
    "schemaId": 0,
    "identifierFieldIds": [1],
    "fields": [
      { "id": 1, "name": "id", "type": "long", "required": true, "doc": "primary key" },
      { "id": 2, "name": "payload", "type": "string", "required": false }
    ]
  }
}

注意 identifierFieldIds 指向字段 id 1，配合 icebergFormatVersion: 2 使用；字段 id 一旦分配就不应复用，这是 Iceberg 的通用约束，超出本次公告范围，属于需要另行确认的通用知识。示例中的 KMS 密钥、账号和桶名都是占位值。

分区布局：材料能支持到哪一步#

公告在介绍 Iceberg 时提到了 hidden partitioning，但在目标表定义示例里，只出现了 icebergSortOrder，没有出现分区规格字段。这里需要克制两种相反的推断：既不能说迁移会原样保留 Hive 的分区目录结构，也不能说 API 不支持指定分区——示例完全可能省略了字段。

可以确认的只有：icebergSortOrder 用来控制目标表的排序，示例里是 sourceId: 1、transform: identity、direction: asc、nullOrder: nulls-first；maintenanceSettings.icebergCompaction 用 targetFileSizeMB: 512 和 binpack 策略控制后续 compaction，icebergSnapshotManagement 则用 minSnapshotsToKeep: 3 与 maxSnapshotAgeHours: 168 控制快照保留。这三个值都是示例值，不是推荐基线。

因此分区这块的实际顺序应该是：先确认映射规则，再谈调优。Hive 的分区列在 Iceberg 里是继续作为分区字段、还是降级为普通列由查询侧过滤，公告没有写，属于必须查迁移文档确认的事项。在确认之前，不建议围绕分区裁剪去设计新的查询模式。

一个可操作的做法是：迁移完成后先看目标表实际的 manifest 与文件分布，再决定是否调整排序和 compaction 参数。排序键影响的是文件内的 min/max 统计质量，进而影响跳读效率；分区则影响目录级裁剪。这两者不是一回事，混在一起调很难判断收益来自哪里。

回滚顺序：没有回滚 API，就自己留退路#

公告描述的最后一步是把目标表提升为读写，但没有提到任何回滚接口，也没有说明 Complete 之后源 Hive 表会被如何处理。所以回滚不能指望"一键撤回"，只能按下面这个顺序预先布好：

1. Complete 之前：确认源表在迁移完成后仍然保留，且保留时长覆盖你的观察窗口。如果所在团队的清理策略会在目标表可写后删除源表，先在策略层面拦住。
2. Complete 之前：用最后一次 Sync 后的对象迁移报告做完整性核对，把"复制了多少对象、失败了多少"作为 cutover 的放行条件，而不是凭感觉放行。
3. cutover 窗口内：公告说源表写入只在 cutover 期间停几分钟。这个窗口越短越好，暂停写入的动作应该提前演练过，不要在现场临时找停机脚本。
4. Complete 之后：目标表可写，此时才具备回滚的实际选择权——查询侧切回源表，或留在目标表上修问题。切回的前提是源表还在、且 cutover 后的增量写入没有只落在目标表上；如果已经只写目标表，切回就意味着丢一段增量，这个损失要在切换前就评估清楚。

快照保留设置在这里会间接影响回滚粒度。minSnapshotsToKeep: 3 和 maxSnapshotAgeHours: 168 是示例值，它决定了你能往回翻多久的 Iceberg 快照。如果你的观察窗口比这个更长，就要相应调整；具体取值没有材料支持，需按业务容忍度自定。

把顺序串起来#

1. 确认前置条件：同账号同区域、Glue 注册、Parquet 格式、区域在支持列表内。
2. Start，生成兼容性报告；读表级报告判断结构，读对象级报告判断数据。
3. 根据报告决定改源还是改目标 schema，然后冻结源表结构。
4. 反复 Sync 追增量，每次之后复查报告。
5. 确认分区映射规则（待核实），必要时调整 sort order 与 compaction 示例参数。
6. 确认源表保留策略与快照保留窗口，再执行 cutover。
7. Complete，目标表转为读写，进入观察期。

公告还提到 Agent Toolkit for AWS 中有 migrating-hive-tables-to-s3-tables skill，可以做 IAM 策略等价性分析、迁移计划校验、执行 Start → Sync → Complete 以及进度监控。公告给出了 GitHub README 的说法，但本次材料未提供具体地址，需要自行检索确认。Complete 对应的具体命令名，公告也没有写出，同样待核实。

本文涉及的自建迁移方案、其他引擎的迁移工具与性能对比不在本次材料范围内，未作比较；文中出现的账号、角色、KMS 密钥与桶名均为公告示例中的占位值，不构成可直接使用的配置。