query

query 技能概览

query 技能能做什么

query 技能可以帮助你对已挂载的工作数据库，或你直接指定的文件运行 DuckDB 查询。它面向的是想尽快把问题变成结果的人：临时 SQL、自然语言数据提问，或者用 DuckDB Friendly SQL 做简单的基于文件分析。

最适合谁使用

如果你的数据已经在 DuckDB、项目状态文件里，或者在 CSV/Parquet 之类的本地文件中，并且你想不搭完整流水线就立刻拿到答案，那么 query 技能就很适合做 Data Analysis。它尤其适合需要快速、反复查看数据的分析师、工程师和 AI agent。

这个技能的不同之处

query 的核心差异在于模式选择。只要存在之前的 DuckDB 状态，它就可以在 session mode 下工作；如果输入引用了文件，或者当前没有可用状态，它就会切到 ad-hoc mode。这样能减少猜测，让 query skill 同时适用于持久化工作流和一次性工作流。

如何使用 query 技能

安装与基础调用

使用 npx skills add duckdb/duckdb-skills --skill query 安装 query 技能。然后你可以直接传 SQL 或问题，例如：query "show daily revenue by country" 或 query "select count(*) from 'events.csv'"。query usage 这种用法在请求足够具体、能自然收敛成一条明确查询时效果最好。

query 技能如何选择 session 或 ad-hoc 模式

query 技能会先检查 .duckdb-skills/state.sql 或 ~/.duckdb-skills/<project-id>/state.sql 中是否存在已有的 DuckDB state file。如果找到了，而且已挂载的数据库仍然可用，它就会使用 session mode。若你传了 --file、在提示词里引用了文件路径，或者没有可用状态，它就会切换到 ad-hoc mode，直接查询文件；必要时则使用 :memory:。这是 query guide 里最关键的一点，因为你的输入应该和你真正想要的模式一致。

先读仓库里的哪些内容

先看 SKILL.md，因为这里写明了执行流程、模式规则和 fallback 行为。对于安装决策来说，通常看这一份就够了。如果你要把这个技能改造成自己的工作流，也可以继续查看仓库树里被引用的其他文件，尤其是定义 state 处理或 prompt 约束的内容。这个仓库里没有额外的 rules/、resources/ 或辅助脚本需要额外学习。

如何写出更好的提示来得到更好的查询

给技能最少但足够的上下文，让它生成正确的查询：目标文件或表、指标、粒度、过滤条件和时间范围。好的输入像 query "For orders.csv, show revenue by month for 2024 and exclude refunds"；差的输入像 query "analyze the sales data"。前者能明确告诉技能该用基于文件的访问方式、该怎么汇总，以及哪些边界情况需要处理。

query 技能常见问题

query 技能只适合 SQL 专家吗？

不适合。query 技能既接受原始 SQL，也接受自然语言问题，所以初学者也能用它做比较直接的分析。不过，当你需要精确的 join、过滤或聚合规则时，SQL 仍然更有帮助。

什么时候不该用 query 技能？

如果你的任务需要多步转换逻辑，而这些逻辑更适合放在 notebook、ETL job 或应用代码里，就不要用它。它优化的是提出和回答数据问题，而不是构建完整的数据产品。

它和普通 prompt 相比有什么不同？

普通 prompt 也许能生成一条看起来合理的查询，但 query 技能额外加入了运行层规则：它会检查 DuckDB state、选择 session vs ad-hoc mode、验证 DuckDB 是否可用，并在挂载失败时安全回退。这让它在安装时评估和重复 query usage 时都更可靠。

它适合文件和本地分析吗？

适合。如果你想对本地 CSV、Parquet 或其他 DuckDB 可读文件做 query for Data Analysis，这个技能非常合适，因为它在没有 session state，或者 session state 不合适时，本来就是为直接查询文件而设计的。

如何改进 query 技能

提供准确的数据形状

最有效的改进来自把数据源和输出形状说清楚。把表名、文件名、你关心的列，以及希望返回的粒度都写出来。例如：query "from sessions.parquet, group by user_id and return avg session length for paid users only" 就能给技能足够的结构，避免结果过宽或含糊。

在第一次运行前先消除歧义

常见失败模式是只说想要“insights”，却没有说明应该统计什么、比较什么或过滤什么。如果你知道指标、日期窗口或分群规则，最好一开始就写进去。这样可以减少来回追问，也能让第一次答案更有用。

尽早检查与模式相关的限制

如果你预期会走 session mode，先确认项目 state 已存在，而且已挂载的数据库还能正常打开。如果你预期会走 file mode，就在提示词里直接引用文件，或者传 --file。这一点很重要，因为 query 技能会根据能否复用现有状态，或必须临时处理，表现出不同的行为。

通过逐步收紧目标来迭代

拿到第一版结果后，下一轮提示词每次只加一个约束：更窄的时间范围、更好的 join key、不同的分组层级，或者必须排除的条件。这样可以让 query skill 继续朝着可决策的结果推进，而不是停留在模糊总结。