ingesting-into-data-lake

データレイクへの取り込み

ソースからデータをデータレイク内のクエリ可能なテーブルに移動します。このスキルでは、ソース接続が必要な場合、すでに作成されていることを前提とします。Glue 接続のセットアップやトラブルシューティングについては、connecting-to-data-source に委任してください。

基本方針

環境から別の指示がない限り、S3 Tables をデフォルトとして使用してください。 S3 Tables は、新しいデータレイクの作業で推奨されるターゲットです。ユーザーのカタログインベントリで S3 Tables がまだ採用されていないことが確認できた場合は、方針の変更を無理に求めるのではなく、既存の汎用バケット上の標準的な Iceberg を推奨してください。

よくあるタスク

接続時は、コマンドを必ず AWS MCP サーバーツールを使って実行してください。これらのツールは、検証、サンドボックスでの実行、監査ログを提供します。MCP が利用できない場合に限り、AWS CLI に切り替えてください。実行前に各手順を必ず説明してください。

ワークフロー

1. 依存関係とコンテキストを確認する

• AWS MCP ツールまたは AWS CLI が利用可能か必ず確認し、利用できない場合はユーザーに伝えてください
• ターゲットの AWS リージョンを必ず確認し、aws sts get-caller-identity を実行して認証情報を検証してください
• SageMaker Unified Studio のプロジェクトロールでは、ターゲットテーブルと接続がプロジェクトのスコープ内にある場合があります。querying-data-lake の呼び出し元 ARN の検出パターンを参照してください。

2. ソースを分類する

ユーザーの発言...	ソースタイプ	参照先
「ファイルをアップロードしたい」「ローカル CSV」「S3 に移動」	ローカルファイル	local-upload.md
「S3 から読み込む」「s3:// から CSV／JSON／Parquet をインポート」	S3 ファイル	s3-files.md
「Oracle／Postgres／MySQL／SQL Server／Redshift／RDS／Aurora からインポート」	JDBC	jdbc-ingest.md
「Snowflake から取得」「Snowflake テーブルを S3 に移動」	Snowflake	snowflake-ingest.md
「BigQuery からインポート」「GCP の分析データを S3 に移動」	BigQuery	bigquery-ingest.md
「DynamoDB をエクスポート」「DynamoDB をデータレイクに移動」	DynamoDB	dynamodb-ingest.md
「Glue テーブルを移行」「Hive を Iceberg に変換」	カタログ移行	catalog-migration.md

ユーザーが Salesforce、ServiceNow、SAP、MongoDB、Kafka、またはその他の SaaS／ストリーミングソースを指定した場合は、今回はサポート対象外のため対応できない旨を伝えてください。

ソーステーブルが曖昧な名前や業務上の名前で指定されている場合（「注文テーブルを移行したい」「営業データウェアハウスから取得したい」など）は、先に finding-data-lake-assets に委任して特定してください。

3. 接続の有無を確認する（該当する場合）

JDBC、Snowflake、BigQuery のソースでは、Glue 接続が必要です。次のコマンドで確認してください。

aws glue get-connection --name <CONNECTION_NAME> --region <REGION>

接続が存在しない場合は作業を中断し、接続を作成してテストするため connecting-to-data-source に委任してください。接続が検証されるまで、取り込みを進めないでください。

ローカルファイル、S3 ファイル、DynamoDB、カタログ移行では Glue 接続は不要です。

4. ターゲットを確認する

テーブルを作成または書き込む前に、必ずユーザーに確認するか、カタログの内容をもとに提案してください。

• データベース／名前空間：特定のターゲットデータベースは存在しますか？それとも新規作成しますか？
• テーブル：既存のテーブル（追加／マージ）ですか、新規テーブル（creating-data-lake-table に委任）ですか？
• 形式：S3 Tables（デフォルト）、標準の Iceberg、または生の Parquet ですか？

インベントリに応じたデフォルト設定：

すでに exploring-data-catalog を実行している場合、またはすぐに確認できる場合は、既存の内容を利用してください。

• アカウントに s3tablescatalog フェデレーテッドカタログとアクティブなテーブルバケットがある場合：S3 Tables を推奨します
• アカウントに Iceberg テーブルを含む汎用バケットがあり、S3 Tables の使用実績がない場合：既存のバケットで標準の Iceberg を推奨します
• アカウントが Iceberg メタデータなしで S3 上の Parquet／ORC を使用している場合：今すぐ Iceberg を採用するか（推奨）、生ファイルを使い続けるかを確認します

S3 Tables をまだ採用していないお客様に、S3 Tables を強制しないでください。iceberg-catalog-config-and-usage.md を参照してください。

このステップからの委任先：

• ターゲットテーブルが存在しない場合 → creating-data-lake-table
• ターゲットデータベース名が曖昧な用語で指定されている場合 → finding-data-lake-assets
• ユーザーが既存の内容を把握していない場合 → exploring-data-catalog

5. ソースのワークフローを実行する

ソース固有のリファレンスを読み、そのフェーズに従ってください。それぞれにジョブテンプレート、注意点、トラブルシューティングがまとめられています。

• ローカル／S3／JDBC／Snowflake／BigQuery／DynamoDB／カタログの移行：ソースごとにリファレンスがあります

Glue 5.1 以降の共通ジョブ設定と PySpark テンプレートは、glue-job-config.md および glue-job-scripts.md にまとめられています。

6. 検証する

次の 3 項目すべてを実行してください。省略しないでください。

1. 行数が想定どおりであること（ソースとターゲットを比較）
2. 重要な列に対する NULL チェック
3. 3～5 件のサンプル行を抜き取り確認

data-quality-validation.md を参照してください。

7. スケジュールを設定する（定期実行の場合）

定期実行するパイプラインでは、cron スケジュールを指定した Glue トリガーを作成します。testing-and-scheduling.md を参照してください。単一ステップのシンプルなパイプラインには Glue トリガーを使用し、分岐を含む複数ステップのパイプラインには MWAA を使用します。

引数の振り分け

• S3 パスのみ：一度限りのロードと推定し、S3 ファイルを使ってステップ 2 から開始します
• 接続名：指定された接続を使ってステップ 3 から開始します
• テーブル名：ステップ 4 から開始し、ソースかターゲットかを確認します
• --target フラグ：ステップ 4 のターゲット形式を事前入力します
• 引数なし：対話形式で順に進めます

注意点

• S3 Tables には Glue 5.1 以降と --datalake-formats iceberg ジョブ引数が必要です
• すべての spark.sql.catalog.* 設定は、必ず --conf ジョブ引数に指定し、spark.conf.set() には指定しないでください。そうしないと Glue 5.x で AnalysisException: Cannot modify the value of a static config が発生します。正しいカタログ設定については、iceberg-catalog-config-and-usage.md を参照してください。
• S3 Tables のカタログ設定では warehouse パラメーターが必須です。指定しないと、Spark で「Cannot derive default warehouse location」というエラーが発生します。
• S3 Tables のテーブル名と列名は、すべて小文字にする必要があります
• overwritePartitions() が置き換えるのは DataFrame に含まれるパーティションのみです。削除を含む全件更新には createOrReplace() を使用してください
• 標準の Iceberg ターゲットには LOCATION 句が必須です。S3 Tables では指定してはいけません
• DynamoDB には Glue 接続は不要です。作成しようとしないでください
• 取り込み中の接続エラーは connecting-to-data-source に委任してください。このスキル内でネットワークや認証情報をデバッグしないでください
• SageMaker Unified Studio プロジェクトのターゲットテーブルについては、Glue ジョブの実行前に、プロジェクトロールがターゲット名前空間への書き込みアクセス権を持っていることを確認してください

トラブルシューティング

エラー	考えられる原因	対処方法
S3 でアクセス拒否	IAM 権限が不足しています	Glue ロールに s3:GetObject、s3:PutObject があることを確認します
S3 Tables でアクセス拒否	s3tables:* 権限が不足しています	S3 Tables のインラインポリシーを Glue ロールに追加します
CTAS のタイムアウト	データセットが Athena で処理するには大きすぎます	Glue ETL に切り替えるか、WHERE フィルターを使ってバッチ処理します
JDBC 接続のタイムアウト／認証エラー	接続レベルの問題です	connecting-to-data-source に委任します
スループット超過（DynamoDB）	読み取り率が高すぎます	read.percent を下げるか、ネイティブエクスポートを使用します

一覧については、error-handling.md を参照してください。

リファレンス

データソース別

• local-upload.md -- ローカルファイル
• s3-files.md -- S3 ファイル（CSV、JSON、Parquet、Avro、ORC）
• jdbc-ingest.md -- Oracle、SQL Server、PostgreSQL、MySQL、RDS、Aurora、Redshift
• snowflake-ingest.md -- Snowflake
• bigquery-ingest.md -- BigQuery
• dynamodb-ingest.md -- DynamoDB（エクスポートと Glue の直接読み取り）
• catalog-migration.md -- 既存の Glue カタログテーブル（Hive、セルフマネージド Iceberg）

横断的な項目

• iceberg-catalog-config-and-usage.md -- S3 Tables、標準 Iceberg、raw ファイル：カタログ設定、エンジンのアクセスパターン
• glue-job-config.md -- ジョブのサイズ設定、モニタリング、再試行
• glue-job-scripts.md -- PySpark テンプレート（追加、アップサート、カスタム SQL、全件更新）
• incremental-loading.md -- ウォーターマーク戦略
• testing-and-scheduling.md -- Glue Triggers、MWAA
• data-quality-validation.md -- 行数、NULL チェック、Glue Data Quality
• schema-evolution.md -- ALTER TABLE ADD COLUMNS、ネストされた JSON
• type-transformations.md -- 型の競合の解決
• format-specific-loading.md -- CSV／JSON／Parquet／Avro／ORC 固有の項目
• athena-loading.md -- シンプルな読み込みの代替手段としての Athena INSERT INTO
• error-handling.md -- 取り込みエラー（接続エラーは connecting-to-data-source に委任）
• upload-options.md -- aws s3 cp と sync、マルチパート

移行関連

• ctas-patterns.md -- Athena CTAS の構文とパーティション変換
• glue-etl-migration.md -- Glue 5.1 以降の PySpark による大規模テーブルの移行
• migration-validation.md -- 検証チェックリスト全体
• migration-troubleshooting.md -- CTAS の失敗、可視性、パーティション

JDBC 関連

• jdbc-schema-discovery.md -- クローラー、直接調査、カスタム SQL
• jdbc-performance.md -- 並列読み取り、パーティション分割