Duck-UI 核心功能全解:SQL 编辑器、笔记本、图表与仪表盘,一张界面导览图看懂
Duck-UI 核心功能全解:SQL 编辑器、笔记本、图表与仪表盘,一张界面导览图看懂
Duck-UI 是一款完全开源、运行在浏览器里的 DuckDB 工作台(Workbench):内置 SQL 编辑器、Notebook 笔记本、9 种图表与 Markdown 仪表盘,无需安装、无需注册、无需后端,你的数据全程不离开当前标签页。本文用一张界面导览图,带你快速看懂它的核心功能布局。
🧭 界面导览:一张图看懂工作区
打开 Duck-UI,整个界面从上到下、从左到右分为 5 个区域,先认路再干活:
| 区域 | 位置 | 作用 |
|---|---|---|
| 顶部导航 | 最上方 | 当前连接(如 WASM)、Home 主页、查询标签页、新建与分屏 |
| 左侧功能栏 | 最左窄条 | 五大入口:Query(工作区)、Library(仪表盘/已保存查询/历史)、Data(连接/扩展)、Share live(实时协作)、Settings |
| 数据浏览器 | 左侧面板 | 浏览 Schema 与表树、已挂载的本地文件夹(FILES),文件可直接拖进来导入 |
| SQL 编辑器 | 中部 | 写 SQL、一键运行、格式化、查看执行计划、调用 Duck Brain |
| 结果面板 | 下方 | Table / Charts / Stats / Schema 四种视图切换,右下角还有 Duck Brain、Pin、Compare、Add to dashboard 快捷操作 |
底部状态栏实时显示行数、列数与耗时(如 7 rows · 3 columns · 714ms),让你对查询性能心中有数。完整导览可参考 getting-started.md。
⚡ SQL 编辑器:自动补全与一键运行
编辑器基于 CodeMirror 6,对新手最实用的几点:
- 智能补全:补全来源不只是你的库目录,还包括 DuckDB 自身的能力,写
read_csv(、summarize时它都认得 - 方言格式化:一键 Format 使用 DuckDB 方言规则;
⌘K呼出命令面板可跳转任何页面、表和已保存查询 - 运行快捷键:
⌘Enter运行光标所在语句,⌘Shift+Enter运行整个标签页 - 错误定位:查询失败时,DuckDB 报告的位置会在编辑器中被精确下划线标出
- 执行计划:
EXPLAIN ANALYZE有专门的可视化查看器 - 查询参数:SQL 里写
$name占位符,上方会生成输入条,方便复用同一查询
编辑器实现见 SqlTab.svelte,补全逻辑在 sqlCompletion.ts。
📊 结果面板:表格、统计与多格式导出
查询跑完后,下方结果面板是"主战场":
- 虚拟滚动表格:百万行也不卡,支持排序、筛选、搜索、单元格框选复制
- 列统计:表尾一键为每列生成摘要——数字列出直方图,文本列出 Top 值,还有空值占比
- 导出:CSV、JSON、XLSX、Parquet 四种格式,直接下载或存入已挂载文件夹
- 全量排序:结果被行数上限截断时,排序和筛选是在 DuckDB 里对整个答案重跑,而不是只对屏幕上的行生效
- Pin + Compare:固定一份结果,再与后续运行的结果做差异对比(表结构、行数、变更单元格)
- 一键入仪表盘:右下角
Add to dashboard直接把当前查询和表格加入仪表盘
📓 笔记本 Notebook:SQL、Python 与 Markdown 混排
Duck-UI 的 Notebook 支持三种单元格,每个单元格有独立的结果和图表:
| 单元格 | 说明 |
|---|---|
| SQL | 在当前连接上执行,结果同查询标签页 |
| Python | 基于 Pyodide 在浏览器内运行,sql() 直接返回 pandas DataFrame,matplotlib 图会渲染成 PNG |
| Markdown | 写分析说明,适合把探索过程沉淀成文档 |
Python 内核按需启动——只有第一个 Python 单元格运行时才会下载 Pyodide(约 10 MB)。一个典型流程是:SQL 单元格取数 → Python 单元格用 pandas 做转换 → Markdown 单元格写结论,全程无后端。
实现见 NotebookTab.svelte。
📈 图表:从查询结果一键生成 9 种图表
任何查询结果切到 Charts 视图,选类型、选 X 列和值列即可,共 9 种:柱状、分组柱状、堆叠柱状、折线、面积、堆叠面积、饼图、环形图、散点图。
对新手友好的细节:
- 智能默认值:新建图表会自动挑选合适的类型、X 列和值列,跳过常量列
- 多序列:可同时选多个值列,点击图例可隐藏/显示对应序列
- 数据变换:Sum / Avg / Count / Min / Max 聚合、任意列排序、限制行数
- 主题跟随:明暗主题下配色自动适配,还能以 2 倍分辨率导出 PNG
- 地图:查询结果含 GEOMETRY 列时,结果面板会多出一个 Map 视图
图表文档见 charts.md,渲染组件在 ChartView.svelte。
🗂️ 仪表盘:Markdown 驱动的可视化报告
Duck-UI 的仪表盘不是拖拽面板,而是 Markdown 文档 + 内嵌实时 SQL:
- 在文档里用命名 SQL 代码块声明查询(如
```sql revenue) - 用组件标签绑定查询结果,如
<BarChart data={revenue} x=region y=total/> - 声明输入变量后,SQL 里用
${inputs.name.value}引用,得到 Grafana 式的交互筛选 - 设定自动刷新(30 秒到 1 小时),标签页隐藏时自动暂停
仪表盘自动保存到浏览器本地,可分享为一条链接——接收方打开即得可运行的完整分析,全程不经过服务器。
创建方式有三种:Dashboards 页面新建、从任意查询结果点 Add to dashboard、打开别人分享的链接。语法详解见 dashboards.md,组件实现见 DashboardTab.svelte。
🧠 Duck Brain:浏览器内的 AI 助手
编辑器右上角的 Duck Brain 是内置 AI 助手,主打两个动作:文本生成 SQL 和 一键修复报错。
- 多种 Provider 可选:WebLLM(完全在浏览器内运行,无需 API Key、可离线)、OpenAI、Anthropic,或任意 OpenAI 兼容端点(如 Ollama)
- 隐私优先:默认只发送你的表结构(Schema),绝不发送数据;可选的"解读结果"动作每次都会征询同意,且只发小样本行
- 理解你的表和列名,生成的 SQL 贴合实际 Schema
实现见 src/lib/duckBrain/index.ts。
🚀 快速上手:一条命令运行
推荐用 Docker,一条命令即可(无需配置任何数据库服务器,DuckDB 通过 WebAssembly 跑在浏览器里):
docker run -p 5522:5522 ghcr.io/caioricciuti/duck-ui:latest
浏览器打开 http://localhost:5522 就能用了。也可以从源码构建(需 Bun):
git clone https://gitcode.com/gh_mirrors/duc/duck-ui
cd duck-ui
bun install && bun run dev
📚 延伸阅读
| 资料 | 路径 |
|---|---|
| 项目总览与功能清单 | README.md |
| 安装与界面导览 | getting-started.md |
| 图表完整指南 | charts.md |
| 仪表盘语法详解 | dashboards.md |
| 可运行示例合集 | gallery.md |
| 执行架构说明 | execution.md |
Duck-UI 的全部前端代码均为 MIT 开源,基于 Svelte 5 + CodeMirror 6 构建,启动包仅约 350 kB。如果你想要一个可自托管、可嵌入、可离线、可看源码的 DuckDB 工作台,从上面的界面导览图出发,逐个点开五大区域,就是最快的上手路径。
