motherduck-explore

探索 MotherDuck 数据

前提条件

• 已建立 MotherDuck 连接（或已启动 MotherDuck MCP 服务）

默认做法

• 从已知的目录对象开始；仅在目标未知时才扩展到数据库或共享。
• 优先使用完全限定的 "database"."schema"."table" 名称；连接了多个数据库或共享后，必须使用这种名称。
• 在判定数据不可用之前，先检查共享数据库。带有安全视图的共享可能会隐藏列和行：已连接的共享中缺少某列，可能是策略所致，而非架构发生变化。
• 如果有可用的 MotherDuck MCP 工具（list_databases、list_tables、list_views、list_columns、list_macros、search_catalog），请优先使用它们，因为它们返回结构化结果的速度比临时 SQL 更快。重新实现逻辑之前，请先检查 list_macros；表宏和标量宏通常包含受治理的定义。
• 通过 MCP 探索业务语义之前，先调用 get_query_guide，然后只阅读相关的根级指南和主题分支。如果目录工具返回的 relatedGuides 适用于当前范围内的对象，请遵循这些指南。
• 记录共享是否经过筛选，以及现有 Dive 处于 Draft、Ready、Endorsed 还是 Archived 状态；这些属性会影响下游 Agent 应信任或预期看到的内容。
• 在开始建模或处理仪表板之前，简要提供架构映射，说明表的粒度、连接键、日期列和可能的度量。

工作流

1. 列出范围内的数据库。
2. 加载相关指南上下文，然后列出目标数据库中的表和视图。
3. 编写查询之前，先检查列、类型、可空性和注释。
4. 如果范围、基数或空值率会影响答案，请使用定向分析或 SUMMARIZE；查询目录时避免进行大范围扫描。
5. 使用 SELECT * ... LIMIT n 或 USING SAMPLE 预览行；对于宽表，这些操作只会读取所需的行组。记录粒度和连接假设，然后再进行分析型 SQL 查询或建模。

参考资料

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

• 阅读 references/EXPLORATION_PLAYBOOK.md，了解完整 SQL 工作流、共享发现模式、MCP 工具指南和常见探索错误

相关技能

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

• motherduck-connect：用于会话设置和身份验证
• motherduck-query：用于了解架构后的分析型 SQL
• motherduck-duckdb-sql：用于探索过程中参考 DuckDB 语法模式
• motherduck-share-data：当共享数据集成为工作流的一部分时，用于创建和使用共享
• motherduck-manage-guides：用于阅读或维护附加到已发现对象的上下文