# 10 分钟上手教程

> 10 分钟上手 DuckLocal：打开样例 CSV 文件，编写 SQL 查询、画图并导出结果，再通过 CLI 查询同一个问题。

Source: https://ducklocal.app/docs/zh/tutorial

**[English](../tutorial.md)**

跟着本教程完成一次查询流程：打开一份小型销售数据文件，运行几个 SQL 查询，将结果画成图，再导出。本教程假设你已安装 DuckLocal；如果尚未安装，请先阅读[快速上手](getting-started.md)。

## 1. 获取样例文件 {#sample-file}

下载示例数据 [sales.csv](https://ducklocal.app/docs/samples/sales.csv)，其中包含两周共 224 行模拟订单数据。你也可以在终端中执行命令下载：

```bash
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 窗口。也可以点击 **打开文件…**；如果已经[添加了命令](getting-started.md#add-command)，还可以运行 `ducklocal sales.csv`。

会弹出通知 **已创建视图 sales**。侧栏的 **本地文件** 下出现了 `sales`，标着 224 行；展开可以看到各列及其类型。

## 3. 看看数据

在侧栏里，点击 `sales` 旁边的播放按钮。编辑器里会填入一条查询该视图的 `SELECT * … LIMIT 100`，按 **⌘↵** 运行。

编辑器下方的表格显示查询到的行。试试表格上方的过滤框：输入 `Store` 并回车，只留下包含 `Store` 的行。过滤只作用于已经加载的行，不会重新查询。

## 4. 提一个问题

把 SQL 换成下面这条，按 **⌘↵**：

```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 |

现在把结果面板从 **结果** 切到 **图表**。第一列是文本，所以每个渠道画成一根柱子，柱高取第一个数值列。

::: tip 自动补全
输入时，编辑器先提示侧栏里的表名和列名，然后才是 DuckDB 函数和 SQL 关键字。比如输入 `rev`，第一个候选就是 `revenue`。
:::

## 5. 画一条趋势

图表原样取查询返回的行来画，想画成什么样，就把结果整理成什么形状。每个渠道一列，就得到每个渠道一条线：

```sql
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 语法）。

第一列是日期时，**图表** 会画出随时间变化的面积图，每个数值列一条序列。规则和限制见[结果与图表](results-and-charts.md)。

## 6. 导出结果

**注意：如果文件已存在，导出会直接覆盖，不会询问。**趁趋势结果还在结果面板里，点击 **导出 CSV**。对话框默认填入 `~/Desktop/export.csv`；按需修改路径后确认。

导出会重新执行查询，所以文件里是完整结果，不只是表格里看得到的那部分。

## 7. 明天还能找到

打开侧栏的 **查询历史** 标签页：你运行过的每条查询都在这里，失败的也在。点击一条会替换编辑器里现有的内容——确认后点击，即可把那条查询放回编辑器。

退出 DuckLocal 再重新启动。`sales` 仍然在 **本地文件** 下：打开过的文件会按路径记下来，每次启动时重新读取，所以改过 CSV 之后，下次查询就能看到新内容。

## 8. 附加：在终端里问同一个问题

如果添加了 `ducklocal` 命令，CLI 不开窗口就能直接回答，写脚本或交给 AI agent 用都很方便：

```bash
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 指南](cli.md)和官方 agent skill（AI 智能体技能包，供 AI 编程助手调用）入手。

## 接下来

- 换成真实数据试试：通过 HTTPS 查询 350 万条出租车行程，见[示例：纽约出租车行程](example-nyc-taxi.md)
- 用 DuckLocal 打开自己的文件或文件夹，见[数据源](data-sources.md)
- 查询 S3 兼容存储里的文件，见 [S3 与 httpfs](s3.md)
- 用保存的查询搭一个仪表盘，见[仪表盘（Dashboard，.dash）](dashboards.md)