migrating-hive-tables-to-s3-tables

将 Hive 表迁移到 S3 Tables

目录

• 概述
• 迁移前须知
• 适用场景
• 不适用场景（请使用其他技能）
• 范围和限制
• 6 个迁移 API
• 迁移生命周期
• 迁移前防护措施
• 迁移后防护措施
• 关键 API 结构
• 安全注意事项
• 参考资料

概述

此技能将引导 Agent 使用原生 S3 Tables 迁移 API，将一个 Glue Hive Parquet 表迁移到 S3 表 存储桶中。Amazon S3 Tables 会规划迁移、报告列和对象的兼容性、复制数据，并在你完成迁移之前 让目标端与源端保持同步。遵循此技能的编码 Agent 会运行迁移前检查、启动迁移、提交 迁移计划供审批、监控进度、完成迁移并验证结果。

如果 AWS MCP Server 可用，请使用它加载此技能及其参考资料 （使用 aws___retrieve_skill，并设置 file="references/<name>.md"），并执行 AWS 调用。

迁移前须知

Agent 指令： 在任何会更改表、数据、元数据或目录条目的步骤之前，以及进行任何 IAM、KMS 或 S3 存储桶更改之前（创建或编辑角色或策略、编辑密钥策略、创建报告存储桶），你都必须先 提交迁移计划，并获得用户的明确批准。先展示准确的 JSON 或命令。对于密钥策略，请使用 get-key-policy 读取，添加一条语句，绝不要替换整个策略。计划必须列出：

• 源表以及目标表存储桶、命名空间和表名；
• 将发生变化的写入路径（ETL 作业、流式处理或数据摄取、INSERT/MERGE、CDC）；
• 读取该表的查询引擎和下游使用方；
• 引用旧 Glue 表或 S3 前缀的数据集、已保存查询和权限。

用户请求中预先给出的批准（注明源、目标和迁移意图）仅涵盖只读检查，以及在审查计划后执行 Start。 批准计划、接受任何 setNull 或 drop 策略、执行 Complete，以及任何删除操作，始终都需要在对话过程中 获得明确批准。如果实际状态与已批准内容不同（架构、分区布局、行数或资源不同），请停止操作， 说明差异并再次征求批准。

请在制定计划时向用户确认以下限制：

• 所有写入目标端的程序都必须通过支持 Iceberg 的引擎写入（例如 Athena、 EMR 或支持 Iceberg 的 Glue）。直接将 Parquet 文件写入 S3 的程序无法正常工作。
• 所有读取程序都必须支持 Iceberg 和 S3 Tables 目录。
• 作业和查询必须从 Glue Hive 表切换到 S3 Tables 目录引用。
• 不得更改源端。在验证目标端之前，写入程序应继续写入源端。
• 在切换生产流量之前，请验证行数和样本值（references/validation.md）。

支持的源和限制的完整列表，请参阅将表迁移到 S3 Tables。

运行环境： 可在有或没有 AWS MCP Server 的情况下使用；步骤使用 AWS CLI 语法。建议使用 AWS MCP Server 进行沙箱化执行和审计日志记录。迁移命令属于 aws s3tables；如果较旧的 CLI 不包含这些命令，请参阅 references/api-setup.md。

适用场景

当源是 Glue Data Catalog Hive 表，且数据为 Parquet 格式 （TableType=EXTERNAL_TABLE，使用 Hive Parquet SerDe），目标是同一账户和区域中的 S3 表存储桶时，使用此技能：

• 使用原生迁移 API 将该表迁移到 S3 Tables，作为托管式 Iceberg 表。
• 在切换前，使迁移后的表与活动 Hive 源保持同步。

不适用场景（请使用其他技能）

以下名称指其他 Agent 技能。遇到这些请求时，请勿使用此技能，而应加载指定技能。当被问及哪些场景不适用时，请列出所有情况：

• 使用自运行的 CTAS、Glue ETL 或 EMR/Spark 将数据迁移到 Iceberg：使用 ingesting-into-data-lake 技能（此技能仅涵盖托管迁移 API）。
• 转换自托管或标准 Iceberg 表：使用 ingesting-into-data-lake 技能。
• 加载原始文件（没有 Glue 表的 Parquet、CSV、JSON）或其他来源（JDBC、Snowflake、BigQuery、DynamoDB）：使用 ingesting-into-data-lake 技能。
• 创建新的空 Iceberg 表：使用 creating-data-lake-table 技能。
• 运行或管理 Athena 查询：使用 querying-data-lake 技能。
• 查找表或资产：使用 finding-data-lake-assets 技能。审计目录：使用 exploring-data-catalog 技能。
• 设置 Glue 连接：使用 connecting-to-data-source 技能。
• 目标不是 S3 Tables 的任何场景。

提示词模式（触发表述）

• “将我的 Glue Hive 表 <db>.<tbl> 迁移到我的表存储桶 <name>。”
• “使用原生迁移 API 将现有 Hive 表导入 S3 Tables。”
• “将我的 Parquet Hive 表迁移到 Iceberg，不运行 CTAS 或 Glue/Spark 作业。”
• “使用 StartTableMigration 转换 <tbl>。”
• “在切换前使迁移后的表与源保持同步” → 同步。
• “完成迁移后的表” → 完成。
• “检查迁移 <id> 的状态或计划” → 获取。
• “列出我的表迁移” → 列出。

范围和限制

• 源： 与目标表存储桶位于同一账户和区域的 Glue Hive Parquet 表。
• 目标： 现有的 S3 表存储桶和命名空间；迁移过程会创建表。
• 不支持（请在 S3 Tables 迁移指南中确认当前列表）： Lake Formation 注册表、位于表位置之外的分区、非 Parquet 格式、Iceberg 源、跨账户、SSE-C 和归档存储类别。请在预检时检查这些情况，若有任何一项适用，则停止操作。对于 Lake Formation 注册表，请告知用户当前不支持，并建议其联系 AWS Support 或其客户团队，提供迁移 ID 以申请支持。切勿更改 Lake Formation 设置。
• 兼容性问题会在规划期间报告。批准前务必检查计划。
• 全有或全无的复制： 如果单个对象失败，整个迁移都会失败。运行状态为 succeeded 时，没有失败的对象。
• 三份报告会写入你提供的通用存储桶：表兼容性、对象兼容性和对象迁移报告。
• 成本和耗时： 迁移会写入第二份数据副本；源数据退役前，请按存储量约翻倍做好规划。大型表可能需要数小时。
• 配额： 请参阅 S3 Tables 配额。
• 迁移策略： 默认情况下，不兼容的列会导致运行失败。incompatibleValuesPolicy: setNull 和 unmatchedSourceFieldsPolicy: drop 会应用于整个列，且运行仍会报告 succeeded。任何 setNull 或 dropped 列都应视为数据丢失，必须获得明确批准。

6 个迁移 API

API	用途	阶段
StartTableMigration	规划并启动迁移。使用 --review-migration-plan 时，会在 pendingReview 状态暂停。	启动
GetTableMigration	返回 state、hasValidPlan、planningStats、migrationStats、migrationOutput、failureReason。	跟踪、审核
UpdateTableMigration	批准（--requested-state queued）或取消。	批准
SyncTableMigration	应用自上次规划以来的源更改；重复执行，直到同步到最新状态。	同步
CompleteTableMigration	将目标提升为可读写状态。需要 --table-arn。返回空响应体；迁移状态保持为 succeeded。使用 get-table 确认（managedByService 为 null）。	完成
ListTableMigrations	列出某个表存储桶或表的迁移。	发现

请求和响应结构见 references/lifecycle.md。

迁移生命周期（阶段）

1. 预检 → references/preflight.md、references/iam-roles.md
2. 启动并规划： start-table-migration --review-migration-plan；planning → pendingReview。
3. 审核： get-table-migration；阅读兼容性报告，并提交迁移计划以供批准。
4. 批准并迁移： update-table-migration --requested-state queued；轮询状态，直到从 migrating 变为 succeeded。
5. 同步（可选）： sync-table-migration；重复执行，直到同步到最新状态。
6. 验证： 在 succeeded 状态的表上、完成迁移之前，在 Athena 中查询目标并与源进行比较 → references/validation.md。每次迁移都必须验证：除非用户选择退出，否则无需询问就运行行数和样本检查。如果计数不足，使用 sync-table-migration 进行协调（完成迁移后无法执行）。
7. 完成： 确认数据一致且用户批准后，执行 complete-table-migration --table-arn ...，然后确认 get-table 显示 managedByService 为 null。

第 2 至 7 阶段详见 references/lifecycle.md。

迁移前防护检查（每次启动前都要运行）

在所有检查通过之前，不要调用 start-table-migration。命令见 references/preflight.md 和 references/iam-roles.md。

0. 计划已获批准。 已展示并批准迁移前准备中的计划。
1. 凭证和区域。 sts get-caller-identity 执行成功；源和目标位于同一账户和区域。
2. 源表为 Glue Hive Parquet。 TableType=EXTERNAL_TABLE，使用 Hive Parquet 格式和 SerDe；不是 Iceberg，不是 ACID/事务表，也没有存储处理程序。记录 catalogId。
3. 分区位置。 每个分区位置都在表位置之下；位于表位置之外的分区会导致规划失败，并返回 UNSUPPORTED_PARTITIONS。检查分区投影和 skip.header.line.count。
4. Lake Formation。 如果源表或其位置已在 Lake Formation 中注册，请停止：暂不支持（请在迁移指南中确认当前支持情况）。不要更改 Lake Formation 设置。
5. 目标已存在。 表存储桶和命名空间均已存在。命名空间缺失会导致 Start 返回 NotFoundException。
6. 迁移角色信任关系。 一个语句，主体为 migration.s3tables.amazonaws.com，条件为 aws:SourceAccount 和 aws:SourceArn。
7. 迁移角色权限。 按范围授予源 S3 和 Glue 读取权限、目标写入权限以及报告存储桶写入权限。调用方还需要对该角色拥有 iam:PassRole 权限，并将 iam:PassedToService 条件设为 migration.s3tables.amazonaws.com。
8. KMS。 如果数据使用客户管理的密钥加密，请授予 kms:Decrypt 和 kms:GenerateDataKey 权限。对于 SSE-KMS 目标，密钥策略还必须允许 maintenance.s3tables.amazonaws.com，否则表创建会失败，规划也无法完成（参见 preflight §7 和 IAM roles）。

迁移后防护检查（Complete 前验证成功）

详情见 references/validation.md。

在 succeeded 状态的表上运行检查 1 至 7，再执行 Complete，因为 Complete 后会拒绝 Sync。Complete 后，只需确认 get-table 显示 managedByService 为 null。

1. 终止状态： state: succeeded，failureReason 为 null。
2. 对象核算： objectsFailedMigration 为 0，且 objectsMigrated 与计划的对象数量一致。如果数量不一致，请检查源对象数量（较早一次同步留下的额外文件属于正常情况），并通过行数一致性确认后再判定为失败。
3. 行数一致性： 目标表的 count(*) 等于源表。
4. 分区一致性： 每个分区的行数相符（适用于分区表）。
5. 抽样检查行： 抽样值相符，包括时间戳等经过转换的列。
6. 架构审查： 计划中已接受每列的类型标签（Lossless、Widened、Converted）；没有任何列标记为 Incompatible 或 Unsupported。
7. 目录命名： 按 "s3tablescatalog/<table-bucket>"."<namespace>"."<table>" 查询。

关键 API 结构

• sourceType = glueTable（顶层），source = {"glueTable":{"catalogId":"<acct>","databaseName":"<db>","tableName":"<tbl>"}}。catalogId 为必填项。角色成员为 roleARN。
• --destination-table = {"tableBucketARN":"<arn>","namespace":"<ns>","name":"<tbl>"}。
• migrationOutput 为必填项：{bucket, prefixes}，其中 bucket 是通用存储桶 ARN，prefixes 可选，用于设置 tableCompatibilityReport、objectCompatibilityReport、objectMigrationReport。
• 可选的 dataMigration.migrationPolicies：unmatchedSourceFieldsPolicy（fail | drop）、incompatibleValuesPolicy（fail | setNull）。两者默认值均为 fail。
• 不要向信任策略添加 sts:ExternalId；Amazon S3 Tables 不会发送此项。
• 状态：new → planning → pendingReview → queued → migrating → succeeded，另有 failed、cancelling、cancelled。
• 取消或失败时，目标表会保留。如果 hasValidPlan 为 true，则使用 sync-table-migration 恢复；否则删除该表并重新开始。规则见 references/lifecycle.md。
• 仅当迁移状态为 succeeded 时才可完成。重复完成会返回 409 ConflictException 或 400 BadRequestException；两者均视为“已完成”。
• Athena 参考格式："s3tablescatalog/<table-bucket>"."<namespace>"."<table>"。要求表存储桶已与 Glue Data Catalog 集成。

安全注意事项

• 仅包含说明；不提供随附代码或依赖项。
• **迁移角色：**信任 migration.s3tables.amazonaws.com，并带有 aws:SourceAccount 和 aws:SourceArn 条件；权限限定于确切的源、目标和报告资源。
• **加密：**建议对目标表存储桶和报告存储桶使用 SSE-KMS，并采用仅允许 TLS 的存储桶策略。客户管理的目标密钥必须在其密钥策略中允许 maintenance.s3tables.amazonaws.com。
• **日志记录：**为迁移 API 和角色承担操作启用 CloudTrail；为涉及的存储桶启用 S3 数据事件或服务器访问日志记录，并针对失败设置 CloudWatch 警报。加密日志目标。
• 生成的命令、报告或状态文件中不得包含机密信息。

参考资料

文件	主题
references/api-setup.md	确认迁移命令已包含在 aws s3tables CLI 中
references/preflight.md	凭证、源检查、分区位置、Lake Formation、目标
references/iam-roles.md	调用方策略以及迁移角色的信任关系和权限
references/lifecycle.md	状态机和各阶段调用：启动、审核、批准、同步、完成
references/validation.md	Athena 行数、聚合和抽样检查；目录命名
references/troubleshooting.md	failureReason 代码和修复方法