motherduck-query

查询 MotherDuck

前提条件

• 已建立 MotherDuck 连接（或已启动 MotherDuck MCP 服务）
• 已确定目标数据库和表

默认做法

• 当 MotherDuck MCP 可用，且查询旨在回答业务问题时，先调用 get_query_guide，再编写 SQL。只遍历相关主题，并根据实时架构验证 Guide 中的说法。
• 编写 DuckDB SQL，而不是 PostgreSQL SQL，即使使用 PG 端点也是如此。
• 优先使用完全限定的 "database"."schema"."table" 名称；附加了多个数据库或共享数据后，必须使用此类名称。
• 保留结果粒度，并在优化或物化查询前检查连接基数。
• 尽早筛选、尽早聚合；对于重复读取，优先使用服务表或汇总表。
• SQL 应清晰易懂，采用多行格式，并明确说明粒度、筛选条件和输出形态。
• 将 DDL、DML、ATTACH、DETACH、CREATE SNAPSHOT、ALTER DATABASE ... SET SNAPSHOT、UNDROP DATABASE 等恢复命令，以及 SHUTDOWN 等生命周期命令视为写操作。当用户的变更请求授权写入时，使用 MotherDuck MCP query_rw 工具。只有当操作具有破坏性、会对外产生可见影响或超出所述范围时，才请求确认。
• 当连接方式支持 custom_user_agent 时，为长期集成添加此标记；该标记会按查询显示在 Duckling Overview 和查询历史中。
• 对文本或图像进行分类、评分、路由或是非判断时，使用 prompt_jev()：它会返回带类型的概率和标签，只对输入令牌计费，并支持批量处理行。对于生成文本或使用 struct 或 json_schema 进行开放式提取，使用 prompt()。这两种调用都按行计费：先用较小的 LIMIT 测试，将结果存入表中，然后仅对 NULL 行重新运行。

工作流

1. 编写 SQL 前，确认实际的表、列和粒度。
2. 当 MCP 可用时，加载相关 Guide 上下文，但不要将其视为架构检查的替代品。
3. 先用 SQL 编写查询，只有在需要时才将其封装到 Python 或 TypeScript 中。
4. 如果 DuckDB 原生模式能简化查询，就使用这些模式；简单查询不需要 CTE 或物化。
5. 验证结果形态和关键聚合值。如果请求涉及性能，或执行时出现问题，请检查查询计划。
6. 在适当时，将昂贵且重复运行的查询物化到服务表或轻量视图中。

参考资料

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

• 阅读 references/QUERY_PLAYBOOK.md，了解 DuckDB 查询模式、数据探索 SQL、性能规则、常见分析形态和常见错误
• 当查询调用 prompt_jev()、prompt() 或 embedding() 时，阅读 references/AI_FUNCTIONS.md

相关技能

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

• motherduck-connect：用于会话设置
• motherduck-duckdb-sql：用于语法和函数参考
• motherduck-explore：用于在编写查询前了解源架构
• motherduck-manage-guides：用于读取或维护语义定义或可复用的查询规则