Duck-UI 核心功能全解:SQL 编辑器、笔记本、图表与仪表盘,一张界面导览图看懂

原创2026-11-07 21:19:221,824 阅读

Duck-UI 核心功能全解:SQL 编辑器、笔记本、图表与仪表盘,一张界面导览图看懂

Duck-UI 是一款完全开源、运行在浏览器里的 DuckDB 工作台(Workbench):内置 SQL 编辑器、Notebook 笔记本、9 种图表与 Markdown 仪表盘,无需安装、无需注册、无需后端,你的数据全程不离开当前标签页。本文用一张界面导览图,带你快速看懂它的核心功能布局。

Duck-UI 界面导览图:SQL 编辑器、数据浏览器、结果表格与图表视图

🧭 界面导览:一张图看懂工作区

打开 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:

  1. 在文档里用命名 SQL 代码块声明查询(如 ```sql revenue)
  2. 用组件标签绑定查询结果,如 <BarChart data={revenue} x=region y=total/>
  3. 声明输入变量后,SQL 里用 ${inputs.name.value} 引用,得到 Grafana 式的交互筛选
  4. 设定自动刷新(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 工作台,从上面的界面导览图出发,逐个点开五大区域,就是最快的上手路径。

登录后查看全文
duck-ui