motherduck-duckdb-sql

MotherDuck 的 DuckDB SQL 参考

信息来源

• 语言功能和函数语义优先参考当前 DuckDB SQL 文档。
• 对于 shares、secrets、snapshots 和 Dive 操作等仅限 MotherDuck 的命令，请使用当前 MotherDuck SQL 文档。
• 为了兼容客户端，MotherDuck 可能会滞后于上游 DuckDB 版本；在承诺支持新发布的 DuckDB 语法或类型之前，请先查看 MotherDuck 版本生命周期文档。
• 如果连接路径会影响结果，请先根据当前 Postgres 端点文档确认行为，再承诺支持服务器模式。

默认原则

• 使用 DuckDB SQL，而不是 PostgreSQL SQL，即使客户端通过 Postgres 端点连接也是如此。
• 优先使用完全限定的 "database"."schema"."table" 名称；附加多个数据库或 share 后，必须使用这类名称。
• 如果 DuckDB 原生构造能简化查询，请优先使用，例如 GROUP BY ALL、QUALIFY、UNION BY NAME、arg_max、EXCLUDE 和 REPLACE。
• 从其他引擎迁移 SQL 时，应明确转换函数、日期运算、标识符引号和类型转换，不要假设它们兼容。
• 依赖近期发布的上游 DuckDB 功能（例如 VARIANT、原生 GEOMETRY、MERGE INTO 或 date_trunc 返回类型变更）之前，请确认 MotherDuck 当前是否支持。
• 在声称某条语句可在 MotherDuck 中运行之前，请检查它是否依赖本地文件、扩展安装/加载、临时表行为或其他仅限客户端的功能。
• 将快照、恢复和 UNDROP DATABASE 语句视为具有依套餐而异的保留行为的运维 SQL，而不是普通分析语法。
• 将 INCLUDE_PATTERN 视为 Share 上针对整个表/视图的筛选功能。行筛选、隐藏列和遮蔽使用 share 安全视图（WITH SECURE VIEW ... REPLACES <table> AS (SELECT ...)、ALTER SHARE ... ADD|DROP SECURE VIEW），与 DuckDB 的 CREATE SECURE VIEW 优化器屏障无关。
• 区分物理导入（CREATE DATABASE ... FROM '<file-url>'，包括云存储中的 DuckDB 文件，例如 's3://bucket/app.db'）和零拷贝克隆源。拒绝将经过筛选的 share 和包含安全视图的 share 用作克隆源；应改用 COPY FROM DATABASE。
• 使用角色/授权 SQL 管理受治理的访问，并通过 SHOW ... 语句进行审计；不要再将 ACCESS ORGANIZATION 作为首选 RBAC 模式。
• 将 MotherDuck SQL 视为 DuckDB SQL 之上的扩展，而不是对它的替代。
• MotherDuck 添加了 SQL AI 函数：prompt() 用于生成文本或结构化文本，embedding() 用于生成向量，prompt_jev() 用于类型化分类、评分、是/否概率和图像边界框。用法和费用规则请参阅 motherduck-query。

工作流

1. 确认连接路径，以及问题涉及的是语法、功能支持还是特定错误。
2. 首先使用 DuckDB SQL 编写或修复语句。
3. 根据当前文档确认任何仅限 MotherDuck 的命令或服务器模式限制。
4. 如果用户需要精确的语法或函数详情，请打开 references/SYNTAX_REFERENCE.md。

参考资料

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

• 有关 DuckDB 数据类型、易用 SQL 功能、函数、复杂类型和常见的 MotherDuck 特定注意事项，请阅读 references/SYNTAX_REFERENCE.md。

相关技能

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

• motherduck-query：针对实时 MotherDuck 数据编写和验证分析 SQL
• motherduck-connect：当语法支持取决于 PG 端点还是原生 DuckDB 行为时使用
• motherduck-explore：当问题实际源于缺少架构上下文，而非缺少语法知识时使用