ingesting-into-data-lake

导入到数据湖

将数据从源位置移入数据湖中的可查询表。此技能假设源连接（如果需要）已存在。有关 Glue 连接的设置或故障排查，请委托给 connecting-to-data-source。

理念

除非环境另有要求，否则默认使用 S3 Tables。 对于新的数据湖工作，S3 Tables 是推荐的目标。如果用户的目录清单显示他们尚未采用 S3 Tables，请推荐在其现有的通用存储桶上使用标准 Iceberg，而不是强行要求他们改变现状。

常见任务

连接后，你 MUST 使用 AWS MCP 服务工具执行命令——这些工具可提供验证、沙盒执行和审计日志记录。只有在 MCP 不可用时，才使用 AWS CLI。你 MUST 在执行每个步骤前向用户说明。

工作流

1. 验证依赖项和上下文

• 你 MUST 检查 AWS MCP 工具或 AWS CLI 是否可用，并在缺少时告知用户
• 你 MUST 确认目标 AWS 区域，并使用 aws sts get-caller-identity 验证凭证
• 对于 SageMaker Unified Studio 项目角色，请注意目标表和连接的作用域可能限定在项目内。请参阅 querying-data-lake 中的调用者 ARN 检测模式。

2. 对源进行分类

用户表述……	源类型	参考
“上传我的文件”、“本地 CSV”、“移至 S3”	本地文件	local-upload.md
“从 S3 加载”、“从 s3:// 导入 CSV/JSON/Parquet”	S3 文件	s3-files.md
“从 Oracle/Postgres/MySQL/SQL Server/Redshift/RDS/Aurora 导入”	JDBC	jdbc-ingest.md
“从 Snowflake 拉取”、“将 Snowflake 表移至 S3”	Snowflake	snowflake-ingest.md
“从 BigQuery 导入”、“将 GCP 分析数据移至 S3”	BigQuery	bigquery-ingest.md
“导出 DynamoDB”、“将 DynamoDB 数据移入数据湖”	DynamoDB	dynamodb-ingest.md
“迁移 Glue 表”、“将 Hive 转换为 Iceberg”	目录迁移	catalog-migration.md

如果用户提到 Salesforce、ServiceNow、SAP、MongoDB、Kafka 或其他 SaaS/流式数据源，请拒绝——当前版本不支持这些数据源。

如果源表是通过模糊名称或业务名称提及的（“迁移我们的订单表”、“从销售数据仓库拉取”），请委托给 finding-data-lake-assets 解析后再继续。

3. 确认连接存在（如适用）

对于 JDBC、Snowflake 和 BigQuery 源，需要 Glue 连接。检查：

aws glue get-connection --name <CONNECTION_NAME> --region <REGION>

如果连接不存在，请停止并委托给 connecting-to-data-source 创建并测试连接。验证连接之前，不要继续导入。

本地文件、S3 文件、DynamoDB 和目录迁移不需要 Glue 连接。

4. 明确目标

在创建或写入任何表之前，必须询问用户（或根据目录清单提出建议）：

• 数据库/命名空间：是否已有特定的目标数据库？还是需要创建一个？
• 表：使用现有表（追加/合并），还是创建新表（委派给 creating-data-lake-table）？
• 格式：S3 Tables（默认）、标准 Iceberg，还是原始 Parquet？

基于清单的默认建议：

如果你已经运行过 exploring-data-catalog，或者可以快速检查，则根据现有资源进行选择：

• 账户有一个 s3tablescatalog 联合目录和活动表存储桶：建议使用 S3 Tables
• 账户有通用存储桶，其中包含 Iceberg 表，且未使用 S3 Tables：建议在其现有存储桶上使用标准 Iceberg
• 账户在 S3 上使用 Parquet/ORC，但没有 Iceberg 元数据：询问是否现在采用 Iceberg（建议采用），或继续使用原始文件

不要强迫尚未采用 S3 Tables 的客户使用它。请参阅 iceberg-catalog-config-and-usage.md。

此步骤的委派：

• 目标表不存在 -> creating-data-lake-table
• 目标数据库由模糊名称指定 -> finding-data-lake-assets
• 用户不知道现有资源 -> exploring-data-catalog

5. 执行源工作流

阅读特定于源的参考文档，并按其阶段操作。每份文档均包含完整的作业模板、注意事项和故障排除说明：

• 本地文件 / S3 / JDBC / Snowflake / BigQuery / DynamoDB / 目录迁移——每种源都有一份参考文档

通用的 Glue 5.1 或更高版本作业配置和 PySpark 模板见 glue-job-config.md 和 glue-job-scripts.md。

6. 验证

以下三项都要执行，不得跳过：

1. 行数符合预期（源与目标对比）
2. 检查关键列是否存在空值
3. 抽查 3-5 行样本数据

请参阅 data-quality-validation.md。

7. 安排计划（如需定期运行）

对于定期运行的管道，请创建带有 cron 计划的 Glue Trigger。请参阅 testing-and-scheduling.md。简单的单步骤管道使用 Glue Triggers；包含分支的多步骤管道使用 MWAA。

参数路由

• 仅提供 S3 路径：推断为一次性加载，从步骤 2 开始处理 S3 文件
• 连接名称：从步骤 3 开始，使用指定的连接
• 表名：从步骤 4 开始，询问这是源表还是目标表
• --target 标志：在步骤 4 中预先填入目标格式
• 无参数：通过交互逐步引导

注意事项

• S3 Tables 要求使用 Glue 5.1 或更高版本，并在作业参数中设置 --datalake-formats iceberg
• 所有 spark.sql.catalog.* 配置都必须放在 --conf 作业参数中，绝不能放在 spark.conf.set() 中。否则 Glue 5.x 会抛出 AnalysisException: Cannot modify the value of a static config。正确的目录配置见 iceberg-catalog-config-and-usage.md。
• S3 Tables 目录配置中必须指定 warehouse 参数。未指定时，Spark 会因 “Cannot derive default warehouse location” 而失败。
• S3 Tables 中的表名和列名必须全部使用小写字母
• overwritePartitions() 只会替换 DataFrame 中包含的分区；如需在完整刷新时删除数据，请使用 createOrReplace()
• 标准 Iceberg 目标必须包含 LOCATION 子句；S3 Tables 则绝不能包含
• DynamoDB 不需要 Glue 连接——不要尝试创建连接
• 数据摄取期间发生连接故障时，应委派回 connecting-to-data-source；不要在此技能中排查网络/凭证问题
• 对于 SageMaker Unified Studio 项目中的目标表，请确保项目角色在 Glue 作业运行前拥有对目标命名空间的写入权限

故障排查

错误	可能原因	处理方法
S3 访问被拒绝	缺少 IAM 权限	检查 Glue 角色是否具有 s3:GetObject、s3:PutObject 权限
S3 Tables 访问被拒绝	缺少 s3tables:* 权限	将 S3 Tables 内联策略添加到 Glue 角色
CTAS 超时	数据集对于 Athena 来说过大	改用 Glue ETL，或使用 WHERE 筛选条件进行分批处理
JDBC 连接超时／身份验证失败	连接级问题	委托给 connecting-to-data-source
吞吐量超限（DynamoDB）	读取百分比过高	调低 read.percent，或使用原生导出

完整目录请参阅 error-handling.md。

参考资料

特定数据源

• local-upload.md -- 本地文件
• s3-files.md -- S3 文件（CSV、JSON、Parquet、Avro、ORC）
• jdbc-ingest.md -- Oracle、SQL Server、PostgreSQL、MySQL、RDS、Aurora、Redshift
• snowflake-ingest.md -- Snowflake
• bigquery-ingest.md -- BigQuery
• dynamodb-ingest.md -- DynamoDB（导出和 Glue 直接读取）
• catalog-migration.md -- 现有 Glue catalog 表（Hive、自托管 Iceberg）

通用主题

• iceberg-catalog-config-and-usage.md -- S3 Tables、标准 Iceberg、原始文件：目录配置、引擎访问模式
• glue-job-config.md -- 作业规格、监控、重试
• glue-job-scripts.md -- PySpark 模板（追加、更新插入、自定义 SQL、完整刷新）
• incremental-loading.md -- 水位线策略
• testing-and-scheduling.md -- Glue Triggers、MWAA
• data-quality-validation.md -- 行数、空值检查、Glue Data Quality
• schema-evolution.md -- ALTER TABLE ADD COLUMNS、嵌套 JSON
• type-transformations.md -- 类型冲突解决
• format-specific-loading.md -- CSV/JSON/Parquet/Avro/ORC 特定内容
• athena-loading.md -- 将 Athena INSERT INTO 作为简单加载的备用方案
• error-handling.md -- 数据摄取错误（连接错误委托给 connecting-to-data-source）
• upload-options.md -- aws s3 cp 与 sync、多段上传

特定迁移

• ctas-patterns.md -- Athena CTAS 语法和分区转换
• glue-etl-migration.md -- 通过 Glue 5.1 或更高版本的 PySpark 迁移大表
• migration-validation.md -- 完整验证清单
• migration-troubleshooting.md -- CTAS 失败、可见性、分区

特定 JDBC

• jdbc-schema-discovery.md -- 爬网程序、直接检查、自定义 SQL
• jdbc-performance.md -- 并行读取、分区