motherduck-ducklake

在 MotherDuck 上使用 DuckLake

事实来源

• 优先查阅最新的 MotherDuck DuckLake 文档。
• 仅在需要澄清 MotherDuck 文档所引用的扩展级行为时，才查阅上游 DuckLake 和 DuckDB 扩展文档。
• 确保指导内容符合文档说明的产品定位：
  • 优先使用原生 MotherDuck
  • MotherDuck 的 DuckLake 文档定义了受支持的产品范围以及生命周期／兼容性限制；应核实当前的 DuckDB／DuckLake 版本矩阵，不要沿用提示词中上游版本或产品状态的描述
  • 全托管、BYOB 和自有计算是不同的模式
  • 维护和压缩是明确执行的操作，并非后台自动处理

默认原则

• 除非有明确的 DuckLake 需求，否则优先使用 MotherDuck 原生存储。
• 需要开放表格式语义、将对象存储作为事实来源、BYOB 或文件级维护时，再考虑 DuckLake。
• 不要仅仅因为工作负载“规模大”就推荐 DuckLake；MotherDuck 文档明确指出，原生存储通常读取速度更快。
• 有意选择运行模式：全托管最便于评估；BYOB 适合由客户拥有存储桶；只有在计算边界也很重要时，才选择自有计算。
• 如果 DuckLake 需求薄弱、未经核实，或仅涉及未来的可移植性，应说明回退到 MotherDuck 原生存储的方案。
• 对于数据内联、排序表、存储桶分区、删除向量或扩展行为，在保证语法可用前，应核实当前的 MotherDuck DuckLake 文档和 DuckDB／DuckLake 版本矩阵。
• 不要仅凭上游 DuckDB 发行说明推断 MotherDuck 客户端／运行时的支持情况；如果具体 DuckDB 版本很重要，应查阅 MotherDuck 生命周期文档。
• 应将 MotherDuck 产品范围与原始 DuckLake 扩展的假设区分开来。
• 细粒度共享（INCLUDE_PATTERN 以及用于行、列和数据屏蔽的安全视图）仅适用于全托管 DuckLake，不适用于拥有自身 DATA_PATH 的 BYOB 数据库。此类共享必须设为 UPDATE AUTOMATIC，且使用方无法使用时间旅行和 DuckLake 元数据函数。如果按受众划分访问控制很重要，应选择全托管模式而非 BYOB。持久化 Iceberg 目录无法共享。
• BYOB 存储桶可以位于与组织不同的区域或云环境：对 S3 密钥设置 REGION，对其他 S3 兼容存储设置 ENDPOINT；对 R2 设置 ACCOUNT_ID（如有数据驻留要求，还需设置司法管辖区端点）。应考虑更高的延迟和潜在的服务提供商数据传输费用。计算、元数据目录、统计信息和内联行仍保留在组织所在区域。
• 不要将原生存储／共享的 REFRESH DATABASE 假设应用于持久化 Iceberg 目录；其目录会独立推进。规定刷新操作前，应核实当前文档。

工作流

1. 确认原生 MotherDuck 存储为何无法满足需求。
2. 选择运行模式：全托管、由 MotherDuck 提供计算的 BYOB，或由自有计算的 BYOB。
3. 提出 BYOB 方案前，核实存储桶的可访问性、区域、数据传输成本和驻留要求，并确认设计是否需要细粒度共享（仅限全托管）。
4. 提前确定数据摄取和维护方案，包括数据内联、文件压缩和清理预期。
5. 最终确定架构前，确认谁将查询数据，以及使用哪种计算环境。

参考资料

仅阅读当前任务所需的参考资料部分。

• 阅读 references/DUCKLAKE_PLAYBOOK.md，了解模式选择矩阵、MotherDuck 专用 SQL 模式、BYOB 限制、数据内联行为、维护函数和常见的 DuckLake 错误

相关技能

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

• 当需要选择原生 DuckDB 还是 Postgres 端点访问路径时，使用 motherduck-connect
• 当实际问题在于数据摄取而非存储格式时，使用 motherduck-load-data
• 当用户在确定存储方案后仍需要设计分析表时，使用 motherduck-model-data
• 当 DuckLake 只是更广泛的数据摄取到服务工作流中的一环时，使用 motherduck-build-data-pipeline