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）。
使用 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）。
使用 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技能
