[其他] DuckDB 官方 skills 实测：Claude Code 自然语言查 SQL，记得核对日期口径

DuckDB 官方发布的 duckdb-skills 技能集，把 DuckDB CLI 直接接进 Claude Code、Codex 等工具，WorkBuddy 也能用。它覆盖文件读取、SQL 查询、格式转换、对象存储探索和空间分析。我用 DuckDB v1.5.5 跑了四类任务：200 条团购订单、CSV 格式转换、Overture Maps 的 S3 查询，以及上海 POI 查询。所有数字都带具体样本和版本边界；销售问题问的是“上个月”，但当时 SQL 没有日期筛选，因此这组结果不能直接当成上月统计。

项目地址：github.com/duckdb/duckdb-skills

01 自然语言查询怎么落到 SQL

duckdb-skills 不是新的数据库引擎，而是一组让 Claude Code 调用 DuckDB CLI 的技能。用户可以用自然语言描述数据问题，Claude Code 生成 SQL，DuckDB 执行；如果 SQL 用了不存在的字段，执行错误也能成为下一轮修正的依据。但这条链路能保证每次生成的 SQL 都符合业务口径吗？显然不能，结果仍要回到查询本身检查。

DuckDB 团队在 2026 年 9 月的官方博客里演示过出租车行程 Parquet 查询：第一次用了错误的 distance 字段，DuckDB 报错并给出候选字段 trip_distance，之后示例改用正确列名，结果是 184362。这是官方博客展示的例子，不是我这次复现的结果。它说明错误可以被发现和修正，不说明自然语言查询天然正确。

技能盘点：

• read-file：读任意数据文件：CSV / JSON / Parquet / Excel / Avro / SQLite / Jupyter，本地或 S3/GCS/HTTPS 远程
• query：写 SQL 或直接自然语言提问，自动接上会话状态
• attach-db：挂载 .duckdb 数据库文件，自动探索表结构并记住会话
• convert-file：任意格式互转：CSV ↔ Parquet ↔ Excel ↔ GeoJSON…
• spatial：地理分析：找“附近的店”、算距离、看热力分布
• s3-explore：不下载直接浏览 S3 / R2 / GCS / MinIO 里的数据
• duckdb-docs：全文搜索官方文档，SQL 报错时自动查解法
• read-memories：用 SQL 搜索 Claude Code 的历史会话记录，找回旧上下文
• install-duckdb：安装 / 更新 DuckDB 扩展和 CLI

02 团购订单：有结果，也要核对日期口径

我用一份含 200 条团购订单的 sales_2026.csv 查询商品总金额 Top 5。当时使用的 SQL 是：

SELECT 商品, count(*) AS 订单数, sum(金额) AS 总金额
FROM 'sales_2026.csv'
GROUP BY 商品
ORDER BY 总金额 DESC
LIMIT 5;

这条 SQL 按商品汇总了整份 CSV，没有日期条件。虽然当时的问题写的是“上个月销售额最高的 5 个商品”，但如果文件里不止上个月的数据，这个结果就不是上月 Top 5。我没有记录 CSV 的日期列名和覆盖范围，因此保留实际跑出的排序，但不把它解释为已验证的上月统计：

商品	订单数	总金额
垃圾袋	16	5407.7
猪肉铺	17	4919.2
海盐芝士饼干	17	4679.2
四川爱媛果冻橙	15	4249.8
阳光玫瑰葡萄	17	3979.8

我还用同一份样本按渠道统计金额：到店 19016.5，占 35.6%；小程序 17531.1，占 32.8%；微信接龙 16866.5，占 31.6%。要用于业务复盘，应先确认 CSV 的日期范围和日期字段，再把相应筛选条件写进 SQL。

03 格式转换：同一 CSV 的三个文件大小

用 convert-file 转换同一份样本：

/duckdb-skills:convert-file sales_2026.csv sales_2026.parquet
/duckdb-skills:convert-file sales_2026.csv sales_2026.xlsx

我记录的文件大小是：CSV 12,612 bytes，Parquet 5,130 bytes，XLSX 12,109 bytes。这是这个 CSV 的一次转换结果；数据类型、内容和压缩设置都会影响输出体积，不能把它当成 Parquet 对任意文件都能缩小约 60% 的保证。

04 S3：查看 Overture 文件，再执行远程查询

我用 DuckDB v1.5.5 查看 Overture Maps 的 2026-08-19 版数据。那次列出 S3 文件清单用时 3.5 秒；其中一个 Parquet 文件为 551 MB，元数据有 12,800 个 row groups、共 232,935,000 行。随后按 subtype = 'country' 做计数，23 秒返回 219。

查询使用的 SQL 是：

SELECT count(*)
FROM read_parquet('s3://overturemaps-us-west-2/...')
WHERE subtype = 'country';

这里用 ... 代替了具体对象路径，因此代码不能直接复制运行。耗时也只代表那次测试的网络、区域和请求条件；我没有保留运行日志或下载量记录，不能据此断言完全没有下载、数据全程留在本机，或同样查询在其他环境也能在 23 秒完成。

05 空间查询：南京西路咖啡店与静安寺最近邻

spatial 技能可以把地点问题组织成 DuckDB 空间查询。我用 Overture Maps 2026-08-19 POI 数据查询上海南京西路一带的咖啡店，结果为 157 家；还查询了距离静安寺最近的 5 家咖啡店。我没有记录后一项查询的门店名称或距离，所以不补写这些结果。

157 这个数量依赖当时的数据版本、南京西路周边范围和 POI 分类方式。换一份数据、边界框或类别条件，结果都可能变化。把“附近”改成可复查的分析时，应确认坐标系、空间范围、类别过滤和距离算法。

06 主要能力与安装

DuckDB 官方博客介绍了九类能力：read-file 读取数据文件，query 执行 SQL 或自然语言查询，attach-db 挂载 DuckDB 数据库，convert-file 转换格式，s3-explore 探索对象存储，spatial 做地理查询，duckdb-docs 搜索文档，read-memories 搜索 Claude Code 历史会话，install-duckdb 安装或更新 CLI 与扩展。

截至 2026 年 10 月 8 日，我查看的 GitHub README 只列出六项：attach-db、query、read-file、duckdb-docs、read-memories 和 install-duckdb。convert-file、s3-explore、spatial 出现在官方博客的能力清单中，但没有出现在那份 README 清单里。两份官方资料的快照并不一致，安装时应以实际插件版本提供的技能为准。

安装可以走 Claude Code 官方插件市场：

/plugin install duckdb-skills@claude-plugins-official

也可以添加 GitHub 仓库市场后安装：

/plugin marketplace add duckdb/duckdb-skills
/plugin install duckdb-skills@duckdb-skills

插件需要 DuckDB CLI。官方仓库说明 macOS 和 Linux 已测试，Windows 尚未完全支持；仓库也说技能在缺少 CLI 时可以提示安装。实际使用前，先确认目标系统上的 CLI 可运行，再用非敏感文件检查 SQL、输出和错误处理。

07 state.sql 可能保存凭据

技能之间共享 state.sql，可用于恢复数据库连接、USE、扩展加载和宏等会话状态。官方 README 提到它可能包含 secrets，并支持放在项目目录 .duckdb-skills/state.sql 或用户目录 ~/.duckdb-skills/<project>/state.sql。项目级文件应检查 .gitignore 和具体内容，避免把凭据提交到仓库；用户级文件也要按敏感配置管理。

本地 CLI 的存在不等于整个数据链路都在本机。S3 查询会访问远程对象存储，Claude Code 也参与处理自然语言请求与查询结果。涉及敏感数据时，要按实际连接方式、凭据权限和团队数据政策评估。

如果工作主要是快速探索 CSV、Parquet、Excel，做临时 SQL，或围绕 DuckDB 数据库追问，duckdb-skills 提供了一个直接入口。正式报表或业务决策前，仍需核对文件、字段、日期范围、过滤条件和统计口径；尤其是“上个月”这类时间问题，不能只看自然语言提问，还要确认 SQL 里真的有对应日期筛选。

参考资料

• DuckDB 团队博客《DuckDB Skills for Claude Code》（2026-09-16）：duckdb.org
• DuckDB 官方插件仓库：github.com/duckdb/duckdb-skills