motherduck-load-data

将数据加载到 MotherDuck

可信来源

• 优先查阅最新的 MotherDuck 加载、云存储和 Postgres 端点加载文档。
• 对于受保护对象存储的工作流，请使用 CREATE SECRET 和云存储文档。
• 如果源是现有的本地 .duckdb、.ddb 或已附加的 DuckDB 数据库，请使用 DuckDB 数据库上传文档。
• 加载建议应符合 MotherDuck 文档所述的做法：
  • 批量加载优于流式加载
  • 如果格式由你控制，优先使用 Parquet，而非 CSV
  • 优先使用 DataFrame、COPY、CTAS 或 INSERT ... SELECT，而非逐行插入
  • 优先使用 MotherDuck 原生存储，除非明确要求使用 DuckLake

默认做法

• 首先判断数据源类型：对象存储或 HTTPS、本地文件或本地 DuckDB、内存中的行，或外部数据库。
• 首次加载优先使用 CREATE TABLE AS SELECT，追加数据优先使用 INSERT INTO ... SELECT。
• 对于整个 DuckDB 数据库，使用 CREATE OR REPLACE DATABASE remote_name FROM CURRENT_DATABASE()、已附加的本地数据库、原生客户端提供的本地文件路径，或远程 .duckdb 文件 URL（例如 S3）。远程和本地文件导入会将数据实际复制到 MotherDuck；数据库或共享克隆源则为零复制。
• 只要源格式由你控制，持久化批量传输就使用 Parquet。
• 将 Postgres 端点视为用于服务器端远程读取的轻量客户端路径，而非用于本地文件或依赖扩展的摄取方式。
• 如果摄取工具不会自动创建目标数据库，请先在 MotherDuck 中初始化该数据库。
• 原始落地数据应尽量少做转换；类型转换、去重和业务逻辑应放在暂存或建模步骤中处理。
• 如果存储位置由你控制，应让源存储靠近 MotherDuck 所在区域。

工作流

1. 确认源数据的实际存放位置。
2. 选择加载路径：
   • 对象存储或 HTTPS：远程读取数据并加载到 MotherDuck
   • 本地文件或本地 DuckDB：使用 DuckDB 客户端路径
   • 远程 DuckDB 数据库文件：使用 CREATE DATABASE ... FROM '<cloud-url>'，并提供所需的云密钥
   • 内存中的行：优先使用 Arrow 或 DataFrame 批量加载；仅在备用情况下使用分批插入
   • 外部数据库：在支持 DuckDB 的环境中使用相应的扫描或复制路径
3. 将数据以最少转换的方式写入原始表或暂存表。
4. 加载完成后立即验证行数、类型以及一些业务汇总指标。
5. 仅当请求包含转换时，才将数据提升到建模表；验证目标数据后，加载请求即告完成。

对于回答、审查或规划请求，给出加载路径建议，不要修改数据。对于加载或实施请求，执行所请求范围内的写入和验证；在进行破坏性替换或范围更广的外部写入之前，应先征求确认。

参考资料

仅阅读当前任务所需的参考章节。

• 阅读 references/INGESTION_PATTERNS.md，了解特定格式的选项、云存储密钥、Postgres 端点加载的权衡、Python DataFrame 路径以及高级摄取模式。

相关技能

仅在缺少相应能力时加载相关技能；复用已有上下文。

• motherduck-connect：选择 Postgres 端点还是 DuckDB 客户端路径
• motherduck-explore：检查目标数据库并验证已落地的表
• motherduck-query：编写 CTAS、追加和验证 SQL
• motherduck-model-data：将已落地的数据提升到暂存表和分析表
• motherduck-ducklake：仅在明确要求使用对象存储支持的湖仓存储时使用
• motherduck-cli：当基于 Shell 的加载需要将结构化输出流式写入文件时使用