10 分钟上手教程
跟着本教程完成一次查询流程：打开一份小型销售数据文件，运行几个 SQL 查询，将结果画成图，再导出。本教程假设你已安装 DuckLocal；如果尚未安装，请先阅读快速上手。
1. 获取样例文件
下载示例数据 sales.csv，其中包含两周共 224 行模拟订单数据。你也可以在终端中执行命令下载：
curl -LO https://ducklocal.app/docs/samples/sales.csv它有五列：
| 列 | 类型 | 示例 |
|---|---|---|
date | DATE | 2026-09-01 |
channel | VARCHAR | Web、Mobile app、Store、Phone |
region | VARCHAR | North、South、East、West |
orders | BIGINT | 72 |
revenue | DOUBLE | 4181.04 |
这些都不用告诉 DuckLocal：DuckDB 会读取表头，自行推断类型。
2. 打开文件
将 sales.csv 拖入 DuckLocal 窗口。也可以点击 打开文件…；如果已经添加了命令，还可以运行 ducklocal sales.csv。
会弹出通知 已创建视图 sales。侧栏的 本地文件 下出现了 sales，标着 224 行；展开可以看到各列及其类型。
3. 看看数据
在侧栏里，点击 sales 旁边的播放按钮。编辑器里会填入一条查询该视图的 SELECT * … LIMIT 100，按 ⌘↵ 运行。
编辑器下方的表格显示查询到的行。试试表格上方的过滤框：输入 Store 并回车，只留下包含 Store 的行。过滤只作用于已经加载的行，不会重新查询。
4. 提一个问题
把 SQL 换成下面这条，按 ⌘↵：
SELECT channel, round(sum(revenue), 2) AS revenue
FROM sales
GROUP BY channel
ORDER BY revenue DESC;| channel | revenue |
|---|---|
| Mobile app | 290549.76 |
| Web | 289544.8 |
| Store | 240067.6 |
| Phone | 82511.2 |
现在把结果面板从 结果 切到 图表。第一列是文本，所以每个渠道画成一根柱子，柱高取第一个数值列。
自动补全
输入时，编辑器先提示侧栏里的表名和列名，然后才是 DuckDB 函数和 SQL 关键字。比如输入 rev，第一个候选就是 revenue。
5. 画一条趋势
图表原样取查询返回的行来画，想画成什么样，就把结果整理成什么形状。每个渠道一列，就得到每个渠道一条线：
SELECT
date,
round(sum(revenue) FILTER (WHERE channel = 'Web'), 2) AS web,
round(sum(revenue) FILTER (WHERE channel = 'Mobile app'), 2) AS mobile,
round(sum(revenue) FILTER (WHERE channel = 'Store'), 2) AS store
FROM sales
GROUP BY date
ORDER BY date;FILTER (WHERE …) 只对满足条件的行做聚合（DuckDB 语法）。
第一列是日期时，图表 会画出随时间变化的面积图，每个数值列一条序列。规则和限制见结果与图表。
6. 导出结果
**注意：如果文件已存在，导出会直接覆盖，不会询问。**趁趋势结果还在结果面板里，点击 导出 CSV。对话框默认填入 ~/Desktop/export.csv；按需修改路径后确认。
导出会重新执行查询，所以文件里是完整结果，不只是表格里看得到的那部分。
7. 明天还能找到
打开侧栏的 查询历史 标签页：你运行过的每条查询都在这里，失败的也在。点击一条会替换编辑器里现有的内容——确认后点击，即可把那条查询放回编辑器。
退出 DuckLocal 再重新启动。sales 仍然在 本地文件 下：打开过的文件会按路径记下来，每次启动时重新读取，所以改过 CSV 之后，下次查询就能看到新内容。
8. 附加：在终端里问同一个问题
如果添加了 ducklocal 命令，CLI 不开窗口就能直接回答，写脚本或交给 AI agent 用都很方便：
ducklocal query --format md --sql "
SELECT channel, round(sum(revenue), 2) AS revenue
FROM 'sales.csv' GROUP BY channel ORDER BY revenue DESC"去掉 --format md 就会输出结构化的 JSON。想进一步了解，从 CLI 指南和官方 agent skill（AI 智能体技能包，供 AI 编程助手调用）入手。
接下来
- 换成真实数据试试：通过 HTTPS 查询 350 万条出租车行程，见示例：纽约出租车行程
- 用 DuckLocal 打开自己的文件或文件夹，见数据源
- 查询 S3 兼容存储里的文件，见 S3 与 httpfs
- 用保存的查询搭一个仪表盘，见仪表盘（Dashboard，.dash）