把 Hive 表迁到 Iceberg 之前：分区语义与表结构的核对清单

把 Hive 表迁到 Iceberg，真正决定成败的往往不是搬迁工具本身，而是搬迁之前就能查清的三件事：分区值从哪里来、列的标识与类型怎么对齐、切换窗口里还有谁在写。这三件事工具替你搬不动，只能由表的主人先定下来。下面按这个顺序整理一份可逐项打勾的清单。

先说明本文的事实边界：关于 S3 Tables 托管迁移的能力描述，均来自 AWS 的发布说明；文中所有命令片段都取自该说明的示例，本文未实际执行，其中的账号、ARN、桶名均为占位值。发布说明未覆盖的部分，本文明确标注为待核实，不做推测性断言。

先划范围：哪些表在这次的覆盖之内#

按发布说明，该托管迁移在发布时支持的是：存储在 Amazon S3、已注册在 AWS Glue Data Catalog、格式为 Parquet 的 Hive 表，且与目标 S3 Tables 表桶位于同一 AWS 账号、同一区域。可用区域为美国东部（弗吉尼亚北部、俄亥俄）、美国西部（俄勒冈）、亚太地区（孟买、新加坡、悉尼、东京）以及欧洲（法兰克福、爱尔兰、斯德哥尔摩）。

所以核对清单的第一项不是分区，而是格式与位置：ORC、Avro、文本格式的表，以及跨账号、跨区域的表，都不在这条路径上。这一项不通过，后面的检查没有意义。

分区语义：Hive 的分区在路径里，Iceberg 的分区在规范里#

这是 Hive 侧的一般行为：分区是目录结构的一部分。一张按 dt、region 分区的表，文件路径通常形如 .../dt=2026-11-09/region=cn/part-00000.parquet。分区列的值从路径字符串解析得到，其“类型”并不存在于数据文件里，而是读取时由元数据定义套上去的。这带来两个后果：值以字符串形式存在，能否无损还原取决于当初写路径的那一方；分区列的物理表示与普通列完全不同。

Iceberg 则把分区写进表规范：分区由 partition spec 的 transform 定义（identity、bucket、truncate、按时间粒度等），分区值记录在清单文件中，查询时不需要在 WHERE 里显式写出分区列——这正是发布说明提到的 hidden partitioning。分区从“路径约定”变成了“表定义的一部分”。

分区相关的核对项

• 分区键的名字、顺序与大小写：元数据里登记的分区列，与实际路径中的键是否一一对应；路径里是否存在 URL 编码字符（例如 %3A 代表冒号）或空格，解码后会变成什么。
• 分区值能否无损还原：dt=2026-11-09 与 dt=20261109 混用是很常见的历史遗留。前导零（hour=09）在转成整数时会丢失，在保持字符串时又未必与下游断言一致。
• 默认分区与空值：Hive 习惯用 __HIVE_DEFAULT_PARTITION__ 表示空分区。目标侧是把它转成 NULL，还是保留为字面量字符串，会直接影响按分区过滤的结果。此项待核实，应以兼容性报告与文档为准。
• 分区列的源类型：Hive 里分区列一律按字符串处理。若目标 Iceberg 里希望它成为 date 或 int，就需要一次显式转换；转换失败时如何处理，取决于你设置的迁移策略（见下节）。
• 非常规路径：外部表、LOCATION 指向自定义目录、大小写混合目录、多级嵌套目录，都可能让“范围内对象”的识别结果与预期不同。发布说明称迁移在拷贝任何数据之前会枚举范围内每个源对象并生成兼容性报告，这类表正应该先看 objectCompatibilityReport 再动手。
• 分区粒度与文件数量：迁移配置里可以指定 icebergCompaction.targetFileSizeMB（示例为 512）与 binpack 策略。分区切得太碎，首次压缩的工作量与之后的元数据规模都会随之上升。

容易忽略的一点：分区列也是列

在 Iceberg 中，分区字段需要是表结构里的字段，分区值由 spec 对该字段做变换得出。因此“分区列要不要保留在列定义里、用什么类型保留”必须在迁移前定下来，而不是交给工具去猜。发布说明只说明迁移包含类型转换并会生成兼容性报告，没有给出分区列的具体映射规则，这一项属于待核实范围，建议以 tableCompatibilityReport 的实际输出为依据。

表结构：字段标识、类型、可空性#

字段标识

Iceberg 用数字 id 标识字段，改名不改变 id；Hive 只有列名，没有 id 概念。迁移时 id 由谁分配、源表历史上的改名列怎么处理，发布说明未涉及，待核实。示例中的请求体是显式给出 schema 的（含 id、required、doc 和 identifierFieldIds），这说明至少在这个 API 层面，字段定义可以由调用方指定——这本身就是一件需要提前设计的事，而不是默认值。

类型映射

Hive 的一些类型在 Iceberg 里没有一一对应物：varchar(n)、char(n) 通常落到 string，长度约束随之消失；不带时区的 timestamp 与 timestamptz 的取舍会改变下游的时间语义；decimal(p,s) 需要精度与标度都能对上。核对方式是逐一列出源表类型，写出目标类型，并标出下游依赖该类型的断言（长度校验、时间窗口计算、金额四舍五入）。

可空性与迁移策略

Hive 的列默认可空，Iceberg 的字段可以是 required。示例里 id 被标为 required: true。由此可以推断：如果源数据中该列存在 NULL，迁移会在校验阶段暴露出来——实际行为应以兼容性报告为准，这属于基于示例的推断而非发布说明的明确表述。

示例中的 migrationPolicies 有两个开关：unmatchedSourceFieldsPolicy 与 incompatibleValuesPolicy，取值均为 "fail"。按字段命名的字面含义推断，前者处理“源表有、目标 schema 没有”的列，后者处理“值转换不了”的情况，设为 fail 意味着宁可中断也不静默丢弃。这是偏保守的默认选择，但两个字段的确切语义与可选值仍需以文档为准。

表属性与排序

writeFormat、icebergFormatVersion、compressionCodec、dictionaryEncoding 决定的是迁移后写入文件的形态，影响读性能与存储成本，不影响迁移能否成功——但事后再改比迁移时一次定下来麻烦得多。icebergSortOrder 与分区是两件不同的事：它描述文件内与文件间的排序，用于跳过不相关的数据，不改变分区语义。

迁移过程中的写入与切换#

流程是三段式：启动（start）→ 同步（sync，可重复多次，每次只拷贝变化的部分）→ 完成（complete）。发布说明明确：目标表在迁移期间为只读，完成之后才被提升为可读写；源表在同步阶段可以继续写入，只有切换时会有一个短暂停写窗口。因此清单里必须包含：谁在写源表、这些写入方能否在该窗口内暂停、暂停期间上游数据如何缓冲、下游读取如何从旧表切到新表。

关于回滚：发布说明把“自建回滚能力”列为自建方案的复杂度来源，但没有说明托管迁移本身提供回滚。因此不应把回滚当作已有能力，较稳妥的做法是切换完成后保留源表与源路径一段时间，并记录切换时间点与最后一次同步覆盖的范围。

计费方面，发布说明的表述是只为拷贝的数据付费、Hive 到 Iceberg 的转换不额外收费、位于 S3 Intelligent-Tiering 的源对象保持当前访问层。由于同步可以多次执行，多次同步带来的重复拷贝会如何计入，属于推断范畴——成本随同步次数与变更量增长，建议在计划阶段就把同步次数当作成本变量控制。

一份可以逐行打勾的核对表#

命令骨架：只保留与核对项相关的字段#

以下片段取自发布说明示例并做了删减，本文未执行；ARN、账号、桶名均为占位。适用环境为已配置 AWS CLI 且有权调用 S3 Tables API 的终端。完整字段与取值请以发布说明和文档为准。

{
  "roleARN": "arn:aws:iam::123456789012:role/YOUR_MIGRATION_ROLE",
  "destinationTable": {
    "tableBucketARN": "arn:aws:s3tables:us-east-1:123456789012:bucket/YOUR_BUCKET",
    "namespace": "YOUR_NAMESPACE",
    "name": "YOUR_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 },
        { "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": "YOUR_GLUE_DB",
      "tableName": "YOUR_SOURCE_TABLE"
    }
  },
  "dataMigration": {
    "migrationPolicies": {
      "unmatchedSourceFieldsPolicy": "fail",
      "incompatibleValuesPolicy": "fail"
    }
  },
  "migrationOutput": {
    "bucket": "arn:aws:s3:::YOUR_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

示例中的 schema 只含两列，迁移正式表时需要按上表核对结果完整写出。migrationOutput 指定的三类报告，正好对应本清单里的分区解析、对象枚举与最终结果核验；把它们的输出目录提前规划好，比迁移完再回头找现场要省事。reviewMigrationPlan 字段在示例中出现，暗示存在“先审阅计划再执行”的模式，其具体语义待核实。

仍然待核实的地方#

• 分区列的映射规则：Hive 分区键在目标表中是继续作为分区字段，还是降为普通列再由 transform 生成分区，发布说明未给出。
• 嵌套类型：struct、array、map 的处理方式，发布说明未涉及。
• 两个 policy 字段的可选值与语义细节：示例只展示了 fail，其他取值与降级行为不明。
• 回滚能力：不能假设存在。
• 计费细节：多次同步是否叠加计费，需要以官方计费文档为准。

回到最初的问题：这份清单要产出的不是一堆勾，而是一份决定——分区键在目标表里怎么表达、哪些列必须保持可空、切换窗口定在哪一刻。这三件事在启动迁移之前写完，托管迁移的自动化才有意义；写不完，工具只会把不确定性原样搬到新的表里。