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>。

发现情况	操作
模糊的数据库名称（如“我们的分析数据库”）	您必须停止。委托给 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>'

元数据 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 使用 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 自动管理存储。
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 技能