creating-data-lake-table

Amazon S3 Tables でデータレイクテーブルを作成する

概要

Amazon S3 Tables は、自動コンパクションとスナップショット管理機能を備えたマネージド Iceberg テーブルを提供します。Athena および Iceberg 互換エンジンからクエリできます。

一般的なタスク

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

判断ガイド

作成する前に、必ず既存のものを確認してください。

ユーザーがデータベースに言及した場合は、必ず aws glue get-tables --database-name <NAME> を実行してください。

確認できた内容	対応
あいまいなデータベース名（「当社の分析用 DB」など）	必ず停止してください。finding-data-lake-assets に委任して特定してください。
一致する名前の S3 Tables 以外のテーブル	必ず停止してください。finding-data-lake-assets に委任してください。ユーザーが確認するまで、テーブルを作成してはいけません。
一致する名前の既存 S3 Tables テーブル	スキーマが一致するか必ず確認してください。互換性がある場合は再利用し、再作成するのはユーザーが確認した場合に限ります。
一致するテーブルがない	作成に進みます（ステップ 1～8）。
ユーザーが新しい S3 Tables テーブルを明示的に要求	確認を省略し、作成に進みます。

作成方法：

• S3 に既存データがある場合：空のテーブルを作成し（ステップ 1～8）、その後 ingesting-into-data-lake スキルを使用します。
• Glue ETL パイプラインの場合：まず references/table-creation-glue-etl.md を読み、その後ステップ 1～6 に進みます。
• Lake Formation のアクセス制御の場合：AWS ドキュメントで "S3 Tables integration with Lake Formation" を検索します。

1. 依存関係を確認する

制約：

• AWS MCP サーバーのツールまたは AWS CLI が利用可能か必ず確認し、利用できない場合はユーザーに伝えてください。
• 対象の AWS リージョンを必ず確認し、aws sts get-caller-identity で認証情報を検証してください。

2. スキーマを把握する

• 明示的なスキーマ：Iceberg の型を検証します。
• 概要のみの場合：列、型、粒度を確認してください。案を提示し、ユーザーの確認を得てください。
• 既存の S3 データ：ファイルヘッダーのみからスキーマを推測します。まず空のテーブルを作成し、その後 ingesting-into-data-lake スキルを使用します。

制約：

• Iceberg の型のマッピング、パーティション、命名規則について、必ず references/best-practices.md を読んでください。
• 必須パラメーター（テーブル名、列、型、パーティション戦略）はすべて、必ず事前に確認してください。スキーマの進化については、references/athena-ddl-path.md を参照してください。
• 名前はすべて小文字にしてください。Glue は大文字と小文字が混在する名前を GENERIC_INTERNAL_ERROR で拒否します。名前空間とテーブル名にハイフンを含めてはいけません。
• アクセスパターンに基づいてパーティション列を提案することを推奨します。

3. テーブルバケットを作成する

名前：3～63 文字、小文字、数字、ハイフンを使用します。

aws s3tables create-table-bucket --name <BUCKET_NAME> --region <REGION>

table-bucket-arn を取得します。暗号化（SSE-S3 がデフォルト、SSE-KMS）とストレージクラス（STANDARD、INTELLIGENT_TIERING）は作成時に設定します。references/best-practices.md を参照してください。

制約：

• aws s3tables list-table-buckets で既存のバケットを必ず確認し、既存のものを選択するか、新規作成するかをユーザーに尋ねてください。
• SSE-KMS を使用する場合、KMS キーポリシーで S3 Tables のメンテナンスサービスプリンシパルにデータの読み取りを許可する必要があります。必要なポリシーについて、AWS ドキュメントで "S3 Tables KMS key policy" を検索してください。
• バケットの作成に失敗した場合は、よくあるエラーについて references/best-practices.md を参照してください。

4. 名前空間を作成する

aws s3tables create-namespace --table-bucket-arn <ARN> --namespace <NAMESPACE>

制約：

• 既存の名前空間を必ず先に一覧表示し、関連するものがあれば再利用を提案してください。
• ハイフンを含まない小文字の名前を必ず使用してください。

5. Glue Data Catalog 統合を作成する

s3tablescatalog が存在するか確認します（アカウントごと、リージョンごとに一度作成します）。

aws glue get-catalog --catalog-id s3tablescatalog

見つからない場合は作成します（glue:CreateCatalog、glue:passConnection が必要です）。

aws glue create-catalog --name "s3tablescatalog" --catalog-input '{
  "FederatedCatalog": {
    "Identifier": "arn:aws:s3tables:<REGION>:<ACCOUNT_ID>:bucket/*",
    "ConnectionName": "aws:s3tables"
  },
  "CreateDatabaseDefaultPermissions": [{"Principal": {"DataLakePrincipalIdentifier": "IAM_ALLOWED_PRINCIPALS"}, "Permissions": ["ALL"]}],
  "CreateTableDefaultPermissions": [{"Principal": {"DataLakePrincipalIdentifier": "IAM_ALLOWED_PRINCIPALS"}, "Permissions": ["ALL"]}],
  "AllowFullTableExternalDataAccess": "True"
}'

aws glue get-catalogs --parent-catalog-id s3tablescatalog で検証します。

6. アクセス制御を設定する

S3 Tables では s3:* ではなく、s3tables:* IAM 名前空間を使用します。

クエリ実行主体の権限（バケットポリシー）：

• s3tables:GetTableBucket、s3tables:GetNamespace、s3tables:GetTable、s3tables:GetTableMetadataLocation、s3tables:GetTableData

クエリ実行主体の権限（IAM ポリシー）：

• glue:GetCatalog、glue:GetDatabase、glue:GetTable

正しい ARN パターンに必ずスコープを設定してください。正確なリソース ARN については、必ず references/access-control.md を読んでください。

制約：

• クエリ実行主体の ARN を必ずユーザーに尋ねてください
• 必要以上に広い権限を付与してはいけません
• IAM ロールを自動作成してはいけません。既存のロールを確認し、ユーザーを案内してください

7. テーブルを作成する

コンテキスト	パス
デフォルト（すべてのユーザー）	S3 Tables API（以下を参照）
ユーザーが SQL DDL を明示的に希望する場合	Athena DDL（references/athena-ddl-path.md を参照）
Glue ETL パイプライン	--conf ジョブ引数による Spark DDL（spark.conf.set() は使用しないでください）。--conf 文字列については、必ず references/table-creation-glue-etl.md を読んでください。

デフォルト：S3 Tables API：

aws s3tables create-table \
  --table-bucket-arn <ARN> \
  --namespace <NAMESPACE> \
  --name <TABLE_NAME> \
  --format ICEBERG \
  --metadata '<METADATA_JSON>'

メタデータ JSON は必ず "iceberg" キーの下にネストしてください：

{"iceberg":{"schema":{"fields":[
  {"name":"order_date","type":"date","required":true},
  {"name":"customer_id","type":"string","required":true},
  {"name":"amount","type":"double","required":false}
]},
"partitionSpec":{"fields":[
  {"sourceId":1,"fieldId":1000,"transform":"month","name":"order_date_month"}
]}}}

制約：

• partitionSpec.sourceId は、有効なスキーマフィールド ID を必ず参照してください
• 作成後にスキーマを変更する場合は、Athena DDL を使用してください。references/athena-ddl-path.md を参照してください
• 複合型（list、map、struct）には、明示的なフィールド ID を指定した schemaV2 を必ず使用してください。references/best-practices.md を参照してください。
• サポートされているパーティション変換を確認するには、AWS ドキュメントで "IcebergPartitionField S3 Tables" を検索することを推奨します

8. 検証して確認する

aws s3tables get-table を使用して必ず検証し、Athena 経由で --query-execution-context '{"Catalog":"s3tablescatalog/<BUCKET_NAME>","Database":"<NAMESPACE>"}' を指定した DESCRIBE <table_name> によりクエリ可能であることを確認してください。SQL にカタログを指定してはいけません。バケット ARN、名前空間、テーブル、スキーマ、パーティションの概要を提示してください。

トラブルシューティング

エラー	原因	解決方法
"Table location can not be specified"	CREATE TABLE 内の LOCATION	LOCATION 句を削除してください。S3 Tables がストレージを自動的に管理します。
AccessDeniedException with s3:* policy	s3tables:* ではなく s3:* を使用している	S3 Tables は s3tables:* 名前空間を使用します。IAM ポリシーを更新してください。

追加リソース

• access-control.md -- IAM 権限、ARN パターン、権限エラー
• best-practices.md -- Iceberg の型、パーティション、命名、よくあるエラー
• athena-ddl-path.md -- Athena DDL、スキーマの変更
• table-creation-glue-etl.md -- Glue ETL 経由の Spark DDL
• データの読み込み：ingesting-into-data-lake スキル