S3 Tables 托管迁移 Hive 到 Iceberg：迁移前后该核对哪些元数据

如果只用一句话回答：这次托管迁移要核对的元数据，一半在迁移前，包括源表在 Glue 里的定义、S3 上的对象范围，以及目标表请求体里的 schema 与表属性；另一半在迁移后，即目标 Iceberg 表的 schema、排序、快照与维护设置是否按声明真正生效。迁移过程中生成的三类报告，是把这两半对上的依据。

先划边界：这次迁移覆盖什么#

AWS 在 2026 年 11 月 4 日的公告中说明，S3 Tables 现在支持把 Amazon S3 中注册在 AWS Glue Data Catalog 的 Parquet Hive 表迁移为托管 Iceberg 表。启动时的硬边界是：同一 AWS 账户、同一 AWS 区域、Parquet 格式、Glue 注册。可用区域包括美国东部（弗吉尼亚北部、俄亥俄）、美国西部（俄勒冈）、亚太（孟买、新加坡、悉尼、东京）和欧洲（法兰克福、爱尔兰、斯德哥尔摩）。

迁移期间目标表只读，完成后提升为读写；同步可以多次执行，每次只复制变更，源表写入不需要停止，只有 cutover 期间有几分钟中断。计费上只按复制的数据量收费，Hive 到 Iceberg 的转换不另收费，源对象若在 S3 Intelligent-Tiering 会保持当前访问层。

迁移前：把源端和目标端写成两张可对照的清单#

源端：表身份、schema 与对象范围

• 表身份：catalogId、databaseName、tableName 要与 Glue Data Catalog 中的实际条目一致。示例请求体把这三项分开写，写错就会指向另一张表。
• 源 schema：字段名、类型、是否 required、注释。公告说 S3 Tables 会处理类型转换，但 Hive 类型到 Iceberg 类型的完整映射规则，本次材料没有给出，需要查迁移文档。不要把“支持类型转换”理解成“任意类型都能无损转换”。
• 分区键：源表按什么分区，决定 S3 上的前缀结构。示例请求体里没有显式的 Iceberg 分区规范字段，源分区如何映射到 Iceberg 的隐藏分区，材料未展开，待核实。
• 对象范围：复制前 S3 Tables 会识别范围内每个源对象并生成兼容性报告。迁移前可以先按前缀统计对象数量、大小和格式，迁移后用对象级兼容性报告对照，确认没有漏对象。

目标端：请求体里哪些字段属于元数据

控制台路径会用推荐默认设置创建目标表；API 路径则要在 start-table-migration 请求体里显式写出目标表定义。以下字段属于迁移后要复核的元数据，不是一次性的配置：

• schema.fields：字段 id、name、type、required、doc。id 是 Iceberg 内部标识，排序定义和 identifierFieldIds 都引用 id，不是字段名；字段 id 一旦定下，后续演进要沿用。
• identifierFieldIds：示例把 id 字段设为 required 并列入 [1]。这项要与业务主键一致，迁移前先确认。
• icebergSortOrder：orderId、sourceId、transform、direction、nullOrder。sourceId 指向 schema 字段 id，字段 id 变动会让排序定义失效。
• properties：writeFormat（示例 parquet）、icebergFormatVersion（示例 2）、compressionCodec（示例 zstd）、dictionaryEncoding（示例 true）。建议核对下游查询引擎对格式版本和压缩编码的支持范围；材料没有列出各引擎的支持情况。
• encryptionConfiguration：示例为 aws:kms 加 KMS key ARN。它是否在兼容性报告中体现，材料未说明，迁移前应单独确认。
• maintenanceSettings：icebergCompaction 的 targetFileSizeMB（示例 512）与 strategy（示例 binpack）；icebergSnapshotManagement 的 minSnapshotsToKeep（示例 3）与 maxSnapshotAgeHours（示例 168）。这些是迁移后持续生效的表维护参数，不是迁移完成就结束。
• migrationPolicies：unmatchedSourceFieldsPolicy 与 incompatibleValuesPolicy，示例均为 fail。含义是遇到源字段未匹配或不兼容值时让迁移失败，而不是静默跳过。其他取值材料未列出，待核实。
• migrationOutput：报告桶与三个前缀（表级兼容性、对象级兼容性、对象迁移报告）。先确认这个位置可写可读，否则迁移过程中拿不到核对依据。

权限与计划复核

roleARN 指向的角色要能读源表与源对象、写目标 table bucket、写报告桶。公告提到 Agent Toolkit for AWS 中的 migrating-hive-tables-to-s3-tables skill 可以分析现有 IAM 策略并推荐等价的目标策略、在开始前验证迁移计划、执行 Start→Sync→Complete 并监控进度。是否使用它属于工具选择，但权限等价性本身仍要核对。示例中 reviewMigrationPlan 为 false；设为 true 时的具体行为，材料未说明。

迁移中：三类报告是核对主依据#

启动迁移后，S3 Tables 先验证源表、生成兼容性报告，再开始复制；复制期间目标表只读。报告按 migrationOutput 的前缀分三类：

• 表级兼容性报告：确认源表定义与目标声明之间是否存在字段不匹配、类型不兼容等问题。
• 对象级兼容性报告：对应复制前识别出的每个源对象，确认哪些对象可以迁移、哪些有问题。
• 对象迁移报告：确认实际复制了哪些对象。

策略设为 fail 时，报告是定位失败点的入口：先看表级报告判断是不是 schema 问题，再看对象级报告判断是不是个别文件问题。同步阶段调用 sync-table-migration，每次只复制变更，可以多次执行直到准备 cutover。材料只给出 API 名称，没有给出同步命令的完整参数，需查文档。

迁移后：目标表元数据与一次查询验证#

完成迁移后目标表从只读提升为读写，核对对象从“请求体”变成“实际表元数据”：

• schema：字段 id、类型、required 是否与请求体一致；类型转换后的实际类型是否被下游引擎识别。
• 排序与标识：排序的 sourceId 是否仍指向正确字段；identifierFieldIds 是否与业务主键一致。
• 表属性：格式版本、压缩编码、字典编码是否按声明生效。
• 维护设置：compaction 目标文件大小、快照保留数量与时长是否按配置生效。快照保留是策略，不代表迁移后立刻有多少快照，实际快照数要查询表元数据。
• 查询验证：用 Amazon Athena、Amazon SageMaker Unified Studio，或任何兼容 Iceberg REST API 的工具查询目标表，至少跑一次计数和按排序键过滤，确认结果符合预期。
• 源表处置：迁移完成后源表是否保留或自动删除，本次材料没有说明，需按文档确认后再清理，避免在验证完成前丢数据。

一段可对照的请求示例（未执行）#

下面这段 JSON 依据 AWS 公告中的 start-table-migration 示例整理，省略了 encryptionConfiguration、tags、storageClassConfiguration、reviewMigrationPlan 等字段；账号、ARN、桶名均为占位，未实际执行。放这里的目的是把迁移前要核对的元数据落到字段上。

{
  "roleARN": "arn:aws:iam::123456789012:role/S3TablesMigrationRole",
  "destinationTable": {
    "tableBucketARN": "arn:aws:s3tables:us-east-1:123456789012:bucket/my-destination-bucket",
    "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" }
      ]
    }
  },
  "sourceType": "glueTable",
  "source": {
    "glueTable": {
      "catalogId": "123456789012",
      "databaseName": "my_glue_database",
      "tableName": "my_source_table"
    }
  },
  "dataMigration": {
    "maintenanceSettings": {
      "icebergCompaction": { "targetFileSizeMB": 512, "strategy": "binpack" },
      "icebergSnapshotManagement": { "minSnapshotsToKeep": 3, "maxSnapshotAgeHours": 168 }
    },
    "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

这段命令同样未执行，--cli-input-json 指向本地文件，路径是占位。公告在 skill 描述中提到 Start→Sync→Complete 三步调用，但只给出了 start 的完整命令形式，完成迁移那一步的参数需查文档。

本次材料没有回答的部分#

• Hive 类型到 Iceberg 类型的完整映射规则。
• 源分区键如何映射到 Iceberg 分区规范；示例请求体没有分区规范字段。
• 控制台“推荐默认设置”与 API 请求体字段的对应关系。
• migrationPolicies 除 fail 以外的取值。
• reviewMigrationPlan 设为 true 时的行为。
• 迁移完成后源表的处置方式。
• 各查询引擎对 icebergFormatVersion 2 与 zstd 压缩的支持范围。

这些项不应靠推测补全。迁移前查对应版本的迁移文档，或先用小表跑一次 Start→Sync→Complete，把三类报告和输出前缀下的文件作为核对样本，再扩大到生产表。

把迁移当成一次元数据对照，而不是一次点击：迁移前把源 schema、目标 schema、排序、表属性、维护参数和报告位置写成清单；迁移中用三类报告逐项对上；迁移后用查询引擎验证。这样即使控制台默认值或类型转换结果与预期不同，也能在 cutover 前发现，而不是等到业务查询报错时才发现。