creating-data-lake-table
熱門使用 Amazon S3 Tables（s3tables API 命名空間）建立受管 Iceberg 資料表，具備自動壓縮與快照管理功能。設定資料表儲存桶、命名空間、資料表、結構描述、Glue 目錄註冊、分割區及 IAM 存取控制。觸發時機：建立資料表、資料湖資料表、分析資料表、結構化資料儲存、S3 Tables、Iceberg、Athena 資料表、分割策略、存取權限。請勿用於：匯入檔案（請使用 ingesting-into-data-lake）、向量儲存（請使用 storing-and-querying-vectors）、查詢現有資料表（請使用 querying-data-lake）、或尋找現有資料表（請使用 finding-data-lake-assets）。
Create managed Iceberg tables using Amazon S3 Tables (s3tables API namespace) with automatic compaction and snapshot management. Sets up table bucket, namespace, table, schema, Glue catalog registration, partitioning, IAM access control. Triggers on: create table, data lake table, analytics table, structured data storage, S3 Tables, Iceberg, Athena table, partitioning strategy, access permissions. Do NOT use for: importing files (use ingesting-into-data-lake), vector storage (use storing-and-querying-vectors), querying existing tables (use querying-data-lake), or locating existing table (use finding-data-lake-assets).
使用 Amazon S3 Tables 建立資料湖資料表
概述
Amazon S3 Tables 提供受管的 Iceberg 資料表，具備自動壓縮與快照管理功能。可透過 Athena 及相容 Iceberg 的引擎進行查詢。
常見任務
連線時您必須使用 AWS MCP 伺服器工具，這些工具提供指令驗證、沙箱執行與稽核記錄。若 MCP 無法使用，則改用 AWS CLI。
決策指南
建立前，您必須檢查現有資源：
當使用者提及資料庫時，您必須執行 aws glue get-tables --database-name <NAME>。
| 發現情況 | 處理方式 |
|---|---|
| 模糊的資料庫名稱（如「我們的分析資料庫」） | 您必須停止。交由 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技能。
限制條件：
- 您必須閱讀
references/best-practices.md以了解 Iceberg 型別對應、分割區與命名規則。 - 您必須事先詢問所有必要參數：資料表名稱、欄位、型別、分割策略。關於結構描述演進，請參閱
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 資料目錄整合
檢查 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 使用 s3tables:* IAM 命名空間（非 s3:*）。
查詢主體權限（儲存桶政策）：
s3tables:GetTableBucket、s3tables:GetNamespace、s3tables:GetTable、s3tables:GetTableMetadataLocation、s3tables:GetTableData
查詢主體權限（IAM 政策）：
glue:GetCatalog、glue:GetDatabase、glue:GetTable
您必須將範圍限定於正確的 ARN 模式。您必須閱讀 references/access-control.md 以取得確切的資源 ARN。
限制條件：
- 您必須詢問使用者查詢主體的 ARN
- 您不得授予超出必要的權限
- 您不得自動建立 IAM 角色，應驗證現有角色並引導使用者
7. 建立資料表
| 情境 | 路徑 |
|---|---|
| 預設（任何使用者） | S3 Tables API（如下） |
| 使用者明確要求 SQL DDL | Athena DDL（請參閱 references/athena-ddl-path.md） |
| Glue ETL 管線 | Spark DDL 透過 --conf 任務參數（非 spark.conf.set()）。您必須閱讀 references/table-creation-glue-etl.md 以取得 --conf 字串。 |
預設：S3 Tables API：
aws s3tables create-table \
--table-bucket-arn <ARN> \
--namespace <NAMESPACE> \
--name <TABLE_NAME> \
--format ICEBERG \
--metadata '<METADATA_JSON>'
Metadata 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），您必須使用
schemaV2並指定明確的欄位 ID。請參閱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 搭配 s3:* 政策 |
使用了 s3:* 而非 s3tables:* |
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技能
