---
title: "纯文本文件形式的本地 SQL 仪表盘 | DuckLocal"
description: "把 DuckDB 仪表盘写成纯文本 .dash 文件：SQL 查询、图表、指标卡、地图和交叉筛选在你自己的电脑上运行，可以在 git 里审阅，AI 智能体也能编辑和校验。"
image: https://ducklocal.app/og-image.jpg?v=2
language: zh-CN
---

# 能阅读、能 diff、能审阅的 SQL 仪表盘

DuckLocal 仪表盘是一个纯文本 `.dash` 文件：数据源、DuckDB SQL 查询，以及绘制结果的图表。它在你的电脑上针对本地文件运行，像代码一样放在 git 里，你和 AI 智能体都能编写。

无需 BI 服务器，无需账户，无需上传数据。免费开源，支持 macOS、Windows 和 Linux。

- 纯文本 .dash 文件
- 图表、指标卡、地图、表格
- 点击即可跨图表筛选
- 用 ducklocal check 校验

## 一个仪表盘就是一个短文件

`source` 块指定数据文件，`query` 块存放 SQL，`plot` 块说明如何绘制每个结果。`filter` 块让你点击一个图表时筛选其他图表。没有函数或模板要学，只有 SQL 和几个属性。

路径相对于 `.dash` 文件，所以把规格文件和数据放在一个文件夹里，复制到哪里都能用。

[所有块和属性](https://ducklocal.app/docs/zh/dashboards#blocks)

```hcl
source "orders" {
  path = "orders.csv"
}

query "revenue" {
  sql = <<SQL
    SELECT channel, sum(amount) AS total
    FROM orders
    GROUP BY channel
    ORDER BY total DESC
  SQL
}

plot "revenue" {
  type  = "bar"
  query = query.revenue
  x     = channel
  y     = total
}
```

## 仪表盘需要的图表

常用图表、数字和地图，排布在 12 列网格上。

- **line · area**时间序列，每个图表最多 12 个序列
- **bar · stacked_bar**排名和构成，附带合计
- **scatter · histogram**相关关系与分布
- **heatmap**星期 × 小时、地区 × 月份
- **map**按经纬度绘制的点，可设大小和颜色
- **timeline**按真实时间间隔分道排列的事件
- **card**一个数字，附带变化，好坏一目了然
- **table · text**可排序的行、标题和说明
[图表类型与选项 →](https://ducklocal.app/docs/zh/dashboards#plot-types)

## 像审阅文档一样审阅仪表盘

把鼠标悬停在图表上，点击气泡图标，写下需要改的地方，例如*“按大小排序，最大的渠道在前”*。讨论串可以回复、可以标记为已解决，有未解决讨论的图表会显示数量。

AI 智能体用 `ducklocal comments` 读取同样的讨论串。每个讨论串都标明了它的图表，以及该图表的块在文件中的行号。智能体修改规格文件、校验后回复。打开的窗口在一秒内重绘，并显示标记为**智能体**的回复。

[用评论审阅](https://ducklocal.app/docs/zh/dashboards#review-with-comments) · [Claude Dashboards 给 DuckLocal 的启发](https://ducklocal.app/zh/blog/claude-dashboards-ducklocal/)

```bash
ducklocal comments sales.dash
{"open":1, "threads":[{"id":"c1",
  "plot":"revenue_by_channel",
  "plot_lines":[68,75], ...}]}

ducklocal check sales.dash
ducklocal comments sales.dash --reply c1 \
  --text "Sorted by revenue, descending" --resolve
```

## 在任何人打开之前先校验

`ducklocal check` 会解析文件、解析每一个引用，并以只读方式运行每一条查询。然后确认每个图表用到的列确实存在于真实结果中，这样拼写错误、失败的类型转换或匹配不到文件的通配符，都会在终端里被发现，而不是在会议上。

所有问题一次性列出，每条一行 `file:line: message`，退出码可供脚本或 CI 任务使用。

[校验仪表盘](https://ducklocal.app/docs/zh/dashboards#validate-a-dashboard)

- 检查语法、名称和引用
- 每条查询的 SQL 都经 DuckDB 运行
- 对照真实结果检查图表的列
- 在选中值的情况下检查筛选器
- 标出没有返回任何行的查询

## 数据留在本地，文件随处可带

查询在 DuckLocal 内置的 DuckDB 引擎中运行，针对你磁盘上的文件或 DuckDB 数据库。把文件夹发给别人，他们就能在自己那份数据上看到同样的仪表盘，无需发布，也无需共享工作区。

> **从一条查询开始？** SQL 编辑器里的任何结果都可以当场画成图表。等一组图表值得保留时，再写一个 `.dash` 文件。 [结果与图表 →](https://ducklocal.app/docs/zh/results-and-charts)

## 关于 SQL 仪表盘

**.dash 文件是什么？** 一个以块的形式声明仪表盘的纯文本文件：`source` 指定数据文件，`query` 存放一条 DuckDB SQL 语句，`plot` 绘制一个结果，`filter` 让点击一个图表时筛选其他图表。不需要写代码。

**仪表盘需要服务器或 BI 账户吗？** 不需要。DuckLocal 打开文件，用应用内的 DuckDB 引擎在你的电脑上运行其中的查询。数据文件留在原处。

**有哪些图表可用？** 折线图、柱状图、堆叠柱状图、面积图、散点图、饼图、热力图、直方图、地图和时间线，另外还有表格、带变化指示的数字卡片和文本面板，排布在 12 列网格上。

**AI 智能体能创建或修改仪表盘吗？** 能。智能体编写或编辑 .dash 文件，运行 `ducklocal check` 确认每条查询都能运行、每个图表的列都存在，并用 `ducklocal comments` 回复审阅评论。打开的窗口会在一秒内重绘。

**仪表盘能放进 git 吗？** 能。.dash 文件是简短的纯文本，可以像代码一样 diff 和审阅。审阅评论保存在单独的 `NAME.dash.comments.json` 文件里，你可以不把它纳入版本控制。

相关页面：[面向 AI 智能体的 SQL](https://ducklocal.app/zh/use-cases/ai-agent-sql/) · [本地数据分析](https://ducklocal.app/zh/use-cases/local-data-analysis/) · [DuckDB GUI](https://ducklocal.app/zh/use-cases/duckdb-gui/) · [用 SQL 查询 CSV](https://ducklocal.app/zh/use-cases/query-csv-with-sql/)

## 打开示例仪表盘

下载 DuckLocal，把教程里的 `sales.csv` 和 `sales.dash` 存在同一个文件夹，然后把仪表盘拖到窗口上。

## 链接

- [下载 DuckLocal](https://github.com/JetSquirrel/DuckLocal/releases/latest)
- [阅读仪表盘指南](https://ducklocal.app/docs/zh/dashboards)
- [查看完整示例](https://ducklocal.app/docs/zh/dashboards#a-complete-example)

Source: https://ducklocal.app/zh/use-cases/sql-dashboards/
