Hive 表迁 Iceberg 的托管迁移：表结构、分区与元数据先核哪几项

先核三组：源表资格与 Glue 目录元数据；表结构中的字段 ID、类型、必填与空值；分区、排序和文件布局。顺序不宜反过来：如果源表不在托管迁移的支持范围内，后面核分区就没有意义。AWS 在 2026 年 11 月 4 日的公告中称，S3 Tables 支持把 S3 中注册在 AWS Glue Data Catalog 的 Apache Hive 表托管迁移为 Iceberg 表；迁移包含数据校验、兼容性检查、类型转换、文件重压缩和 compaction（合并压缩），并在复制数据前识别范围内每个源对象、生成兼容性报告（AWS News Blog 公告）。这给出了核对范围，却没有给出 Hive 分区到 Iceberg 分区规范的逐项映射；这是后文单独标出的未知项。

先确认托管迁移的边界#

公告说，迁移无需构建管道或预置计算，生产负载可继续运行，但 cutover（切换）期间有几分钟停机窗口。启动时支持同一 AWS 账号、同一 AWS 区域内、注册在 Glue Data Catalog 的 Hive 表，源文件格式为 Parquet。可用区域包括美国东部（弗吉尼亚北部、俄亥俄）、美国西部（俄勒冈）、亚太（孟买、新加坡、悉尼、东京）和欧洲（法兰克福、爱尔兰、斯德哥尔摩）（公告）。对开发者的含义是：跨账号、跨区域、非 Glue 注册或非 Parquet 的 Hive 表，不能按这篇公告的托管路径直接假设可用；是否需要另建管道或等待支持范围变化，待核实。

第一组：源表资格与 Glue 目录元数据#

先对齐请求里的 catalogId、databaseName、tableName 与 Glue 中的实际登记项。公告说迁移前会识别范围内每个源对象并生成兼容性报告；请求示例把报告分成表兼容性、对象兼容性和对象迁移三类输出前缀。建议先看对象兼容性报告，按源分区路径检查是否有对象遗漏，再看表兼容性报告。这里的“建议”是核对方法，不是公告规定的强制顺序。

• 目标侧要核 tableBucketARN、命名空间、表名、加密方式、存储类、标签和维护设置；示例使用 aws:kms 与 INTELLIGENT_TIERING，实际值需按环境确认。公告说目标表按推荐默认设置创建，但具体默认值材料未列出，待核实。
• 权限要核 roleARN 能否读源表、写目标表、写报告桶并使用 AWS KMS（密钥管理服务）密钥。公告提到 Agent Toolkit 的迁移 skill 可以分析现有 IAM 策略并推荐目标策略；这是公告描述，本次未执行验证。
• 成本口径要核：公告称只对复制的数据收费，Hive 到 Iceberg 的转换不收费；源对象在 S3 Intelligent-Tiering 中保持当前访问层。具体金额待核实，不要用示例字段估算账单。

第二组：表结构先看字段 ID、类型和空值策略#

Iceberg schema 用字段 ID 跟踪列，示例显式给出 id 和 payload 的字段 ID，并把 id 标为 required、放入 identifierFieldIds。迁移前建议先固定源列到目标字段 ID 的映射，不要只按列名对齐；新增列、重命名列和嵌套字段尤其容易在这里出错。

公告说迁移会做类型转换，但没有列出 Hive 到 Iceberg 的类型映射表。因此 decimal 精度、timestamp 时区、char/varchar、array/map/struct 等类型是否支持、如何转换，应以兼容性报告和迁移文档为准，当前材料不足以断言。示例请求显式提供 schema；如果不提供 schema 是否会自动推导，材料未说明，待核实。

空值和必填性也容易漏。示例中 id 为必填、payload 可空；迁移前应统计源列的 null、空串和默认值，确认目标 required 约束不会阻断迁移。示例还把 unmatchedSourceFieldsPolicy 和 incompatibleValuesPolicy 设为 fail。首次演练采用 fail 是保守做法，可以让未匹配字段和不兼容值先暴露出来；放宽策略前，应确认报告中的每类问题都已处理。这是示例配置，不是唯一推荐值。

第三组：分区、排序与文件布局不要混为一谈#

公告提到 Iceberg 的隐藏分区（hidden partitioning）是迁移后的能力之一，但请求示例中出现的是 icebergSortOrder，不是分区规范。排序定义数据顺序，分区决定数据裁剪和文件组织；不要把示例里的 identity 排序当成 Hive 分区键的映射。

先核源表在 Glue 中的分区键：字段名、类型、层级、分区值格式和分区数量；再核对象兼容性报告是否覆盖所有分区路径。就本次材料所及的公告正文而言，未给出 Hive 分区到 Iceberg 分区规范的逐项映射：是否保留同名分区、是否转换分区字段类型、分区演进如何处理，都需要以兼容性报告和迁移文档核实（待核实）。

文件布局也要一起看。公告说迁移会做重压缩和压缩；示例设置 targetFileSizeMB: 512、strategy: binpack、compressionCodec: zstd，并保留 3 个快照、最大快照年龄 168 小时。这些是示例值，不是性能承诺；分区多、小文件多的表，应结合对象报告和迁移报告决定维护设置。切换阶段，公告称目标表在迁移期间只读，完成迁移后提升为读写；可以多次调用同步，每次只复制变化，cutover 只需几分钟停机。写入频繁的表应预留切换窗口，并在 complete 前核对同步后的行数和分区覆盖；公告未给出规模上限或耗时数据。

把核对结果落到一次迁移演练#

1. 确认源表在支持范围内：同账号、同区域、Glue 注册、Parquet。
2. 在 Glue 侧记录源 schema、分区键、对象前缀和表属性，形成核对基线。
3. 创建目标表并显式给出 schema；首次演练把未匹配字段和不兼容值策略设为 fail。
4. 启动迁移，先读表兼容性和对象兼容性报告，再决定是否同步或调整。
5. 多次同步后核对行数、分区覆盖和报告中的对象迁移结果，最后 complete 并验证读写。

这个顺序不是公告强制的 API 顺序，而是把“先核结构、分区与元数据”落实到可检查的动作。公告的 API 顺序是 start、sync、complete；示例中的请求字段可以帮助你把核对项映射到配置。

示例：请求字段与核对项的对应关系#

下面的 JSON 和 CLI 依据公告示例整理，替换了账号、ARN 等占位符并省略了部分字段；未在本次写作中执行，不能直接用于生产。实际字段、权限和区域端点以官方文档为准。

{
  "roleARN": "arn:aws:iam::YOUR_ACCOUNT_ID:role/S3TablesMigrationRole",
  "destinationTable": {
    "tableBucketARN": "arn:aws:s3tables:us-east-1:YOUR_ACCOUNT_ID:bucket/my-destination-bucket",
    "namespace": "mynamespace",
    "name": "my_destination_table",
    "properties": {
      "writeFormat": "parquet",
      "icebergFormatVersion": 2,
      "compressionCodec": "zstd"
    },
    "schema": {
      "type": "struct",
      "schemaId": 0,
      "identifierFieldIds": [1],
      "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": "YOUR_ACCOUNT_ID",
      "databaseName": "my_glue_database",
      "tableName": "my_source_table"
    }
  },
  "dataMigration": {
    "migrationPolicies": {
      "unmatchedSourceFieldsPolicy": "fail",
      "incompatibleValuesPolicy": "fail"
    }
  },
  "migrationOutput": {
    "bucket": "arn:aws:s3:::my-report-bucket",
    "prefixes": {
      "tableCompatibilityReport": "reports/table-compatibility/",
      "objectCompatibilityReport": "reports/object-compatibility/",
      "objectMigrationReport": "reports/object-migration/"
    }
  }
}

aws s3tables start-table-migration \
  --cli-input-json file:///tmp/start-migration.json

这段示例只覆盖启动请求的一部分：它没有给出分区规范的字段，也没有展示 KMS 加密和完整维护设置。因此它适合对照 schema、排序、策略和报告前缀，不适合作为分区映射的依据。

核对表#

结论#

先核资格与目录元数据，再核 schema，最后核分区与文件布局。公告明确了托管流程、报告机制、支持范围和计费口径，但没有给出 Hive 分区到 Iceberg 分区规范的逐项映射、类型映射表或性能数字。把这些未知项写进演练清单，逐项用兼容性报告和迁移文档确认，比照着示例字段猜分区行为更稳妥。