Hive 数据集转 Iceberg：分区与元数据核对该落在哪些字段上

把 Hive 表迁到 Iceberg，真正费时间的往往不是搬数据，而是搬之前说不清"目标表长什么样"。Amazon S3 Tables 提供的托管迁移把这件事压缩成一条 API 流程：先用兼容性报告把源表范围内的对象列清楚，再复制、增量追平、最后切换。按本次材料，能做的是 Start、Sync、Complete 三类调用；不能直接做的，是把"分区怎么落"当成一个请求参数填进去——本次材料没有给出 Hive 分区键到 Iceberg 分区规范的映射说明，这一项必须靠报告和官方文档补核。下文把能核对的元数据面、分区这一项的缺口、以及操作顺序分开讲。

一、迁移前真正能核对的元数据面#

按 AWS 新闻博客的说明，这项能力面向存放在 Amazon S3 中、注册在 AWS Glue Data Catalog 里的 Parquet 表，发布时限定同一 AWS 账号、同一区域（来源：AWS News Blog，2026-11-04）。同一篇材料强调，在复制任何数据之前，S3 Tables 会识别范围内的每个源对象并生成兼容性报告——这是核对工作的主要抓手，而不是事后去比对两个目录。

目标表这一侧，请求里可显式给出的元数据大致分四组：

• Schema：字段的 id、name、type、required、doc，以及 identifierFieldIds。字段 id 是 Iceberg 里跨版本追踪列的依据，改写字段名时它保持不变。
• 排序：icebergSortOrder，示例中给了一个 identity、asc、nulls-first 的字段。
• 表属性：writeFormat、icebergFormatVersion、compressionCodec、dictionaryEncoding。
• 维护设置：icebergCompaction 的目标文件大小与策略（示例为 512 MB、binpack），以及 icebergSnapshotManagement 的快照保留条数与最长保留小时数。

这四组里，schema 与排序决定了"迁完之后查询读到什么"，维护设置决定了"迁完之后文件长什么样"。核对顺序建议反过来：先看源表结构，再定 schema，最后才谈压缩与文件大小。

二、分区：材料说到哪、没说到哪#

需要先把一个容易混淆的点说清楚：示例请求里的 icebergSortOrder 是排序，不是分区。排序影响写入时数据文件的排列，分区决定数据落到哪些目录（在 Iceberg 里由 partition spec 描述）。两者在 Iceberg 中是独立的两份元数据，拿 sort order 去核对分区，会得出错误结论。

本次材料对分区的全部信息只有一句：Iceberg 具备 schema evolution、hidden partitioning、time travel 等特性。至于迁移过程中 Hive 的分区键会不会被自动识别、映射成哪种 transform、能否在请求中显式覆盖，材料没有说明。这是缺口，不是"官方没有这项能力"，两者要分开。

在这个缺口下，分区核对只能落成三个动作：

1. 先跑一次不复制数据的兼容性检查（示例中 reviewMigrationPlan 字段存在，但材料未解释其确切语义，属待核实项），把兼容性报告读出来，看报告是否覆盖了分区相关信息。
2. 目标表建好、数据开始复制后，用任何兼容 Iceberg REST API 的工具读取目标表的元数据，直接看 partition spec 的实际内容——材料提到可通过 Iceberg REST API 兼容工具查询表，但未给出具体的元数据查询方式，需查官方迁移文档。
3. 把源端 Hive 的目录层级（Hive 分区的常见表现形式）与目标 partition spec 逐项对照，差异项写进迁移记录，而不是留在口头约定里。

边界提醒：上面的第 2、3 步依赖的是"读目标表元数据"这一通用能力，本次材料只确认了查询接口的存在，没有确认元数据读取的具体路径与权限要求，落地前需另行核实。

三、先定失败策略，再点开始#

示例请求里有两条策略值得单独拿出来：unmatchedSourceFieldsPolicy 与 incompatibleValuesPolicy，取值都是 fail。按字面理解，前者处理"源表有、目标 schema 没有"的字段，后者处理类型转换后无法表示的值。这是保守起点：宁可让迁移在报告阶段停下来，也不要先复制出一批需要回滚的数据。

材料只给出了这两个字段名和示例取值，没有列出全部可选值，也没有说明非 fail 取值下的具体行为。因此"能不能改成跳过"这类问题，属于待核实范围。实践上的建议是：第一次迁移固定用 fail，把报告读完，再讨论是否放宽。

四、三类报告分别对应什么#

请求中的 migrationOutput 指定了一个 S3 桶和三个前缀。字段名本身说明了产物类型，但具体报告包含哪些列，材料未展开：

三类报告放在同一个桶的不同前缀下，好处是审计时不必去翻控制台历史。建议在迁移前就把这个桶的保留策略、访问权限和生命周期定下来，否则报告会在迁移结束后成为无人认领的临时数据。

五、操作顺序与只读窗口#

按材料，流程是三段：Start 校验源表、生成兼容性报告并开始复制；Sync 追平源表变化，可调用多次，每次只复制变化部分；Complete 完成迁移。迁移期间目标表只读，完成后提升为读写；源表除切换的几分钟外可以继续写入。

这意味着核对窗口其实有两段：第一段在 Start 之后、复制进行中，看报告和 schema；第二段在 Complete 之前，确认最后一次 Sync 之后源端没有再产生未被覆盖的变更。第二段的时间点比第一段更关键，因为一旦 Complete，切换窗口只有几分钟，出问题就没有缓冲。

下面这段请求片段依据官方博客示例整理，省略了账号、ARN、KMS 密钥等占位信息，未在本次写作中执行，仅用于对照字段位置：

{
  "destinationTable": {
    "namespace": "mynamespace",
    "name": "my_destination_table",
    "properties": {
      "writeFormat": "parquet",
      "icebergFormatVersion": 2,
      "compressionCodec": "zstd",
      "dictionaryEncoding": true
    },
    "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 }
      ]
    },
    "icebergSortOrder": {
      "orderId": 1,
      "fields": [ { "sourceId": 1, "transform": "identity", "direction": "asc", "nullOrder": "nulls-first" } ]
    }
  },
  "source": {
    "glueTable": { "databaseName": "my_glue_database", "tableName": "my_source_table" }
  },
  "dataMigration": {
    "migrationPolicies": {
      "unmatchedSourceFieldsPolicy": "fail",
      "incompatibleValuesPolicy": "fail"
    }
  }
}

注意 schema.fields[].id 与 icebergSortOrder.fields[].sourceId 的对应关系：排序里引用的是字段 id，不是字段名。改字段名的时候这一层不会断，改 id 才会。

六、能力边界与费用口径#

发布时可用区域包括美国东部（弗吉尼亚北部、俄亥俄）、美国西部（俄勒冈）、亚太（孟买、新加坡、悉尼、东京）以及欧洲（法兰克福、爱尔兰、斯德哥尔摩）。限制条件为：AWS Glue 注册、Parquet 格式、同账号同区域。

费用方面，材料给出的口径是只按复制的数据量计费，Hive 到 Iceberg 的转换不另行收费，源对象若在 S3 Intelligent-Tiering 中则保持当前访问层。区域名单与计费口径均以发布说明为准，具体单价需查阅官方定价页，本次材料未提供。

把核对清单压缩成三类#

第一类是可确认项：源表位置与格式、目标 schema、字段 id、排序、表属性、维护设置、三类报告的落地位置。第二类是需查文档补足项：reviewMigrationPlan 的语义、两条策略字段的可选值、报告的具体列结构、目标表元数据的读取路径。第三类是本次材料未覆盖项：Hive 分区到 Iceberg 分区规范的映射规则。开发者的落地顺序应当遵循这个分类——前两类可以先写进迁移脚本和检查单，第三类在拿到官方文档或第一份兼容性报告之前，不要假设它会自动对齐。