把文件、数据库和 AI，放进同一个 SQL 工作台。
用 Excel 核对业务库，用一条 SQL 关联多个数据源，或让智能体先查数据再回答。
下载桌面版 · 安装指南 · 功能 · 文档 · 浏览器演示 · English
DuckQuery 是独立开发、基于 DuckDB 的本地优先数据工作台，适合临时对账、跨源核查和数据探索。文件导入、数据库连接、SQL、可视化查询、图表和导出都在一个界面里完成，不需要为一次分析搭建数仓。
不用 AI，也能完整使用查询与分析功能。 启用 AI 时，由你选择模型服务并提供自己的 API Key。
最新发布版本为 v2.2.0。本文功能说明以该发布版为准；对应源码见 v2.2.0 标签。
从 GitHub Releases 选择与你的电脑匹配的安装包：
| 系统 | 标准包 | 离线包 |
|---|---|---|
| Windows 10 / 11 · x64 | *_x64-setup.exe |
*_x64-offline-setup.exe |
| macOS · Apple 芯片 | *_aarch64.dmg |
*_aarch64-offline.dmg |
| macOS · Intel | *_x64.dmg |
*_x64-offline.dmg |
联网环境用标准包；首次使用部分外部数据库时会下载 DuckDB 扩展。无法在线下载扩展时选择离线包，内置相关扩展，Windows 离线包还包含 WebView2 安装器。暂不提供 Linux 桌面安装包，可使用 Docker。
.sig、.app.tar.gz 和 latest.json 用于应用内更新，无需单独下载。安装包未使用 Apple Developer ID 或 Microsoft 发布证书，首次运行可能出现系统提示；处理方式见桌面版使用手册。
先安装 Docker 与 Docker Compose，然后运行：
git clone --branch v2.2.0 --depth 1 https://github.com/Chenkeliang/duckdb-query.git
cd duckdb-query
./quick-start.sh- 工作台：http://localhost:48000
- API 文档：http://localhost:48001/docs
- 数据库和上传数据保存在宿主机
./data；配置与密钥在./config。备份或迁移时应一并保留。
脚本支持配置构建镜像源，详见配置参考。默认仅监听本机 127.0.0.1；需要共享访问时应使用带认证的反向代理，应用本身没有多用户鉴权。
在线体验使用独立 DuckDB-Wasm，在浏览器内解析 CSV / TSV / Parquet / JSON，不上传文件到应用服务器。Excel、外部数据库连接、AI 和扩展管理请使用桌面版或 Docker。演示引擎与桌面 / Docker 后端独立。
| 你的任务 | DuckQuery 提供的能力 |
|---|---|
| 把散落的文件变成可查询的数据 | CSV / Excel / Parquet / JSON / JSONL 导入、表格粘贴、URL 导入、服务器目录读取 |
| 核对文件与业务库 | 本地表与 MySQL / PostgreSQL / SQLite / DuckDB 跨源关联，支持符合条件的远端筛选优化 |
| 使用远程 DuckDB 计算 | 独立 Quack 服务连接、远程表与字段浏览、绑定服务的只读 SQL 标签；支持取消、转后台、导出与保存到本地 |
| 反复调整一条查询 | 多标签 SQL 编辑器、表与字段补全、错误位置提示、查询历史、SQL 收藏夹 |
| 少写 SQL 完成分析 | 可视化关联查询、集合运算与透视表；支持不加分组字段直接统计，可查看生成的 SQL |
| 让长查询继续跑 | 异步任务、执行中转后台、任务搜索、取消、重试与结果查看；转后台继续同一次查询，不重新执行 |
| 看清结果并交付 | 虚拟滚动表格、列来源、JSON 查看、按结果结构推荐图表、显式重算与下钻；默认直接展示当前 SQL 结果 |
| 把结果带走 | CSV / Excel / JSON / Parquet 导出，或保存为 DuckDB 本地表 |
| 让 AI 辅助查数 | 限定问数范围、查看结构与真实取值、只读查询、SQL 解释与优化、报错修复、图表建议 |
| 接入 AI 编程工具 | MCP 服务，供 Claude Code、Codex、Cursor 等客户端使用，提供三种权限模式 |
工作台支持中文 / English、深色 / 浅色主题、命令面板和可自定义快捷键。
在数据源管理页或左侧「Quack 服务」分组添加已有服务的地址和 Token。查询由远端 DuckDB 执行，连接从运行 DuckQuery 后端的机器发起。服务器可以暴露 CSV / Parquet 视图、DuckDB 表及其他已配置数据；客户端浏览服务器实际提供的目录，不在这里配置远端 MySQL / PostgreSQL。
当前 Quack 入口仅提供只读 SQL 标签，尚不接入可视化 JOIN、集合、透视、数据探索、远端 SQL 的 AI 问数/修复或 SQL 收藏。保存为表会写入本地 DuckDB，不会写入远端。浏览器内 Wasm Demo 不支持 Quack。首次显式测试连接会按需安装官方 httpfs / quack；当前离线包未预置 quack，受限网络需先安装匹配引擎与平台的扩展。详见 Quack 使用指南。
DuckDB 本地表、原有数据库连接表和 Quack 表均可通过箭头展开字段与类型；双击表名或右键选择「打开预览 SQL（100 行）」只填入 SQL，不自动执行。同一服务的相同 Quack SQL 已打开时会切回已有页，已编辑的草稿不会被覆盖；显式新建查询仍创建独立标签。
图表默认按当前 SQL 返回的行展示，不再因为结果截断而自动重跑或再次汇总。按字段类型和当前结果推荐可用图表；需要分组统计时，选择计算方式与范围，再显式预览。日期排序、重复日期、无效日期和显示点数限制会影响画面，界面会说明对应情况；图形坐标使用近似数值，提示值保留后端提供的原始精度。
AI 推荐只在点击后请求你配置的模型，发送当前 SQL、字段、当前结果的分布摘要与最多 5 行限量样本。建议先展示依据，由你选择预览，不自动应用或执行 SQL。
- 接入数据。 拖入 CSV、Excel、Parquet 或 JSON，粘贴表格，或连接 MySQL、PostgreSQL、SQLite、DuckDB。
- 查询或提问。 手写 SQL；用可视化界面构建关联、集合运算或透视表；也可以打开智能体，限定数据源与表后直接提问。
- 检查与交付。 查看表格、图表和列来源，核对 SQL，把结果导出或保存为本地表。执行中的只读查询可以转到后台，保持后端运行即可稍后从任务面板取回结果。
示例：用一条 SQL 关联本地文件与 MySQL
把本地订单与 MySQL 客户资料关联，找出已完成订单的客户和金额：
SELECT
o.order_id,
c.customer_name,
c.segment,
o.amount
FROM readme_demo_orders AS o
JOIN mysql_readme_demo_mysql.customers AS c
ON o.customer_id = c.customer_id
WHERE o.status = 'completed'
ORDER BY o.amount DESC;这里的表名与连接别名来自演示数据，使用时替换为你自己的来源。一个查询可以同时使用本地表与已连接的外部数据库。
以下动图录制于 v1.1.4，仅用于说明跨源查询流程，不代表当前界面。
在查询工作台打开 AI 面板，选择它可以访问的数据源与表，然后描述问题。输入 @ 可以加入表；输入区支持多行，Enter 发送，Shift+Enter 换行。
- 问数据： 智能体查看结构、核对取值，并执行有行数限制的只读查询后给出回答，附可复用 SQL。统计由数据库执行；你仍应核对查询口径和结果。
- 解释或优化 SQL： 快捷按钮先填入可编辑的问题草稿，由你确认发送。
- 使用返回的 SQL： 先查看修改前后的差异，再选择应用；应用只更新编辑器，不自动执行。你在等待期间修改了 SQL 时，预览会提示冲突。
文件与本地表保存在运行 DuckQuery 的电脑或自托管服务器上，外部数据库仍位于原来的服务中。使用 AI 时，所选范围内的结构、问题和限量查询结果可能发送给你配置的模型服务；请按数据要求选择本地或远程模型。
先启动 DuckQuery 桌面版或 Docker，再运行：
uvx duckquery-mcpClaude Code 可直接添加：
claude mcp add duckquery -- uvx duckquery-mcp| 权限模式 | 行为 |
|---|---|
read-only |
不开放修改工具，阻止变更请求 |
normal（默认） |
修改工具可用，变更必须显式确认 |
full |
跳过 MCP 的确认门控，后端限制仍有效 |
客户端配置、后端自动发现与具体工具见 MCP 文档。MCP 包版本与应用版本独立发布；当前配套版本仍为 0.4.1，安装来源与更新方式见 MCP 文档。
最新发布的 应用版本为 v2.2.0，新增 Quack 远程只读 SQL，统一表结构浏览与预览交互，并更新图表及 AI 推荐。保留 v2.1.3 的 Windows 覆盖升级修复，以及原有数据探索、JSON 提取、安全 MySQL 下推和扩展管理，详见 v2.2.0 发布说明。
应用版本与 DuckDB 引擎版本分别维护。v2.2.0 继续使用 DuckDB 2.0 正式版（duckdb==2.0.0，engine v2.0.0）；v2.1.1 仍是 1.6.0.dev379 / v2.0.0-alpha39998。新库继续使用 v2.0.0 存储格式；旧库不会自动迁移，扩展须匹配正式版引擎和运行平台。
“数据探索”按实际字段类型推荐统计方式，确认 SQL 后显示指标卡片；也可采样发现 JSON/VARIANT/文本列中的路径，选择输出类型并提取为列。路径发现先应用当前筛选，最多采样 100 行，不代表完整结构；统计使用完整筛选范围。默认文本提取保留大整数精度，缺失路径或转换失败返回 NULL。此入口用于桌面和服务器版，浏览器内 Wasm Demo 暂不提供。
MySQL 查询支持安全的时间/数值条件及关联键候选下推；可等价转换的单表 COUNT 在源库完成，SUM/AVG 继续由 DuckDB 精确计算。执行前后显示采用的方式；无法证明安全的表达式保留本地执行，原生 remote_pushdown 未全局开启。
扩展页支持名称/用途搜索和安装状态筛选，SQL 示例按需展开。Avro 已加入官方精选安装目录，可通过 SQL 读取；文件导入选择器未新增 Avro 格式。
从 DuckQuery 2.0.x 升级不新增存储迁移。从 1.x 升级前，请备份 main.db、system.db 及对应 .wal，再阅读 2.0 大版本说明。旧库不会在启动时静默迁移；显式迁移到新存储格式后，应通过升级前备份恢复旧版本。
历史发布说明：v2.1.3 · v2.1.2 · v2.1.1 · v2.1.0 · v2.0.1 · v2.0.0。
“设置 → DuckDB 数据库存储”可查看资源预算、检查最近备份和查看恢复指引。扩展按引擎版本隔离；详细兼容范围见引擎升级方案。
文档索引 · 配置参考 · 使用手册 · 参与贡献 · 行为准则
遇到问题或有功能建议，欢迎提交 Issue，说明你的场景、应用版本和复现步骤。觉得有用，也欢迎点亮 Star。
感谢 LINUX DO 对开源项目的支持。DuckQuery 使用 MIT License。