migrating-hive-tables-to-s3-tables

Hive テーブルを S3 Tables に移行する

目次

• 概要
• 移行前に
• 使用する場面
• 使用しない場面（別のスキルを使用）
• 対象範囲と制約
• 6 つの移行 API
• 移行のライフサイクル
• 移行前のガードレール
• 移行後のガードレール
• 主要な API の形式
• セキュリティに関する考慮事項
• 参考資料

概要

このスキルでは、ネイティブの S3 Tables 移行 API を使用して、1 つの Glue Hive Parquet テーブルを S3 テーブルバケットに移行する手順をエージェントに案内します。Amazon S3 Tables は移行を計画し、列とオブジェクトの互換性を報告してデータをコピーし、移行を完了するまで移行先を移行元と同期させます。このスキルに従うコーディングエージェントは、事前チェックを実行し、移行を開始して、計画を提示して承認を得たうえで、進行状況を監視し、移行を完了して結果を検証します。

AWS MCP Server を利用できる場合は、このスキルとその参考資料（file="references/<name>.md" を指定した aws___retrieve_skill）を読み込み、AWS の呼び出しを実行するために使用します。

移行前に

エージェントへの指示： テーブル、データ、メタデータ、カタログエントリを変更する手順、および IAM、KMS、S3 バケットを変更する手順（ロールやポリシーの作成または編集、キーポリシーの編集、レポートバケットの作成）を実行する前に、必ず移行計画を提示し、ユーザーから明示的な承認を得てください。最初に正確な JSON またはコマンドを提示してください。キーポリシーについては、get-key-policy で読み取り、ステートメントを 1 つ追加してください。ポリシー全体を置き換えてはいけません。計画には、次の項目を必ず含めてください。

• 移行元テーブルと移行先のテーブルバケット、ネームスペース、テーブル名。
• 変更される書き込み先（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 サーバーの有無にかかわらず動作します。手順では AWS CLI の構文を使用します。サンドボックスでの実行と監査ログ記録には、AWS MCP サーバーの使用を推奨します。移行コマンドは aws s3tables の一部です。古い CLI にコマンドがない場合は、references/api-setup.mdを参照してください。

使用する場合

ソースが Parquet データを含む Glue Data Catalog の Hive テーブル（TableType=EXTERNAL_TABLE、Hive Parquet SerDe）で、移行先が同じアカウントおよびリージョンにある S3 テーブルバケットの場合に、このスキルを使用します。

• ネイティブ移行 API を使って、そのテーブルをマネージド Iceberg として S3 Tables に移行する場合。
• カットオーバー前に、移行したテーブルをアクティブな Hive ソースと同期させておく場合。

使用しない場合（別のスキルを使用）

以下は、ほかのエージェントスキルの名前です。これらの依頼にはこのスキルを使用せず、指定されたスキルを読み込んでください。このスキルを使用しない場合を尋ねられたときは、すべてのケースを列挙してください。

• 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 にインポートしてください。」
• 「CTAS や Glue/Spark ジョブを実行せずに、Parquet Hive テーブルを Iceberg に移行してください。」
• 「StartTableMigration を使って <tbl> を変換してください。」
• 「カットオーバー前に、移行したテーブルをソースと同期させておいてください」→ Sync。
• 「移行したテーブルを完了してください」→ Complete。
• 「移行 <id> のステータスまたは計画を確認してください」→ Get。
• 「テーブル移行の一覧を表示してください」→ List。

対象範囲と制約

• ソース： 移行先のテーブルバケットと同じアカウントおよびリージョンにある Glue Hive Parquet テーブル。
• 移行先： 既存の S3 テーブルバケットおよび名前空間。移行時にテーブルが作成されます。
• サポート対象外（最新の一覧は S3 Tables 移行ガイドで確認してください）： Lake Formation に登録されたテーブル、テーブルのロケーション外にあるパーティション、Parquet 以外の形式、Iceberg ソース、アカウント間の移行、SSE-C、アーカイブストレージクラス。これらを事前チェックで確認し、いずれかに該当する場合は中止してください。Lake Formation に登録されたテーブルの場合は、サポート対象外であることをユーザーに伝え、移行 ID を添えて AWS Support または担当のアカウントチームに問い合わせ、サポートを依頼するよう提案してください。Lake Formation の設定は変更しないでください。
• 互換性の問題は計画時に報告されます。承認する前に、必ず計画を確認してください。
• 全件成功または全件失敗のコピー： オブジェクトが1つでも失敗すると、移行全体が失敗します。succeeded の実行では、失敗したオブジェクトはありません。
• 指定した汎用バケットに、テーブル互換性、オブジェクト互換性、オブジェクト移行の3種類のレポートが書き込まれます。
• コストと所要時間： 移行ではデータのコピーがもう1つ作成されます。ソースを廃止するまで、ストレージ容量が概ね2倍になることを見込んでください。大規模なテーブルでは、数時間かかる場合があります。
• クォータ： 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	1つのテーブルバケットまたはテーブルの移行を一覧表示します。	検出

リクエストとレスポンスの形式は、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. 移行先の存在確認。 テーブルバケットと名前空間が存在すること。名前空間がない場合、開始時に NotFoundException で失敗します。
6. 移行ロールの信頼関係。 ステートメントは1つで、プリンシパルは 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 も許可する必要があります。許可されていない場合、テーブルの作成に失敗し、計画が完了しません（事前確認 §7 と IAM ロール を参照）。

移行後のガードレール（完了前に成功を検証）

詳細は references/validation.md を参照してください。

Complete の前に、succeeded 状態のテーブルでチェック1～7を実行してください。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 状態の移行のみ完了できます。2 回目の完了処理は 409 ConflictException または 400 BadRequestException を返します。どちらも「すでに完了済み」として扱ってください。
• Athena の参照形式："s3tablescatalog/<table-bucket>"."<namespace>"."<table>"。テーブルバケットを Glue Data Catalog と統合する必要があります。

セキュリティに関する考慮事項

• 説明のみで、同梱コードや依存関係はありません。
• 移行ロール： aws:SourceAccount および aws:SourceArn 条件を使用して migration.s3tables.amazonaws.com を信頼します。権限は、対象のソース、移行先、レポートリソースに限定します。
• 暗号化： 移行先のテーブルバケットとレポートバケットでは、TLS のみを許可するバケットポリシーとあわせて SSE-KMS を推奨します。移行先でカスタマーマネージドキーを使用する場合は、キーポリシーで 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 コードと修正方法