creating-data-lake-table

使用 Amazon S3 Tables 创建数据湖表

概述

Amazon S3 Tables 提供托管式 Iceberg 表，并自动进行压缩和快照管理。可通过 Athena 和兼容 Iceberg 的引擎查询。

常见任务

连接后，MUST 使用 AWS MCP 服务工具，它们可提供命令验证、沙盒执行和审计日志记录。如果 MCP 不可用，则回退到 AWS CLI。

决策指南

创建前，MUST 检查现有内容：

用户提到数据库时，MUST 运行 aws glue get-tables --database-name <NAME>。

查找结果	操作
数据库名称模糊（“我们的分析数据库”）	MUST 停止。委托给 finding-data-lake-assets 进行确认。
存在名称匹配的非 S3 Tables 表	MUST 停止。委托给 finding-data-lake-assets。在用户确认前，MUST NOT 创建。
存在名称匹配的 S3 Tables 表	MUST 检查架构是否匹配。兼容时重复使用；仅在用户确认后重新创建。
没有匹配的表	继续创建（步骤 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. 验证依赖项

限制：

• MUST 检查 AWS MCP 服务工具或 AWS CLI 是否可用，并在缺少时告知用户
• MUST 确认目标 AWS 区域，并使用 aws sts get-caller-identity 验证凭证

2. 了解架构

• 明确的架构：验证 Iceberg 类型。
• 宽泛的描述：询问列、类型和粒度。提出方案并确认。
• 已有 S3 数据：仅根据文件标头推断架构。先创建空表，然后使用 ingesting-into-data-lake 技能。

限制：

• MUST 阅读 references/best-practices.md，了解 Iceberg 类型映射、分区和命名规范。
• MUST 一次性询问所有必需参数：表名、列、类型和分区策略。有关架构演进，请参阅 references/athena-ddl-path.md。
• MUST 使用全小写名称——Glue 遇到大小写混用时会返回 GENERIC_INTERNAL_ERROR。命名空间和表名 MUST NOT 包含连字符。
• SHOULD 根据访问模式建议分区列。

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。

限制：

• MUST 使用 aws s3tables list-table-buckets 检查现有存储桶，并询问用户是选择现有存储桶还是创建新的存储桶。
• 如果使用 SSE-KMS，KMS 密钥策略 MUST 允许 S3 Tables 维护服务主体读取数据。搜索 AWS 文档 "S3 Tables KMS key policy"，了解所需策略。
• 如果存储桶创建失败，请参阅 references/best-practices.md 了解常见错误。

4. 创建命名空间

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

限制：

• MUST 先列出现有命名空间，并在相关时建议重复使用
• MUST 使用不含连字符的小写名称

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 使用 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 管道	通过 --conf 作业参数使用 Spark DDL（而非 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>'

元数据 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 执行 DESCRIBE <table_name> 确认表可查询，使用 --query-execution-context '{"Catalog":"s3tablescatalog/<BUCKET_NAME>","Database":"<NAMESPACE>"}'。不要在 SQL 中指定目录。提供摘要：存储桶 ARN、命名空间、表、架构、分区。

故障排除

错误	原因	修复方法
"Table location can not be specified"	CREATE TABLE 中包含 LOCATION	删除 LOCATION 子句。S3 Tables 会自动管理存储。
使用 s3:* 策略时出现 AccessDeniedException	使用了 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 技能