{"id":50827810,"url":"https://github.com/Chenkeliang/duckdb-query","last_synced_at":"2026-06-15T19:00:16.310Z","repository":{"id":321763465,"uuid":"1049748685","full_name":"Chenkeliang/duckdb-query","owner":"Chenkeliang","description":"DuckDB 可视化 SQL 工作台。无需 ETL，直接分析本地 CSV/Excel 和远程数据库 支持跨数据源关联 · The Visual SQL Workbench for DuckDB (No-ETL, Local-First, Cross-Source JOINs).","archived":false,"fork":false,"pushed_at":"2026-05-31T06:08:11.000Z","size":40943,"stargazers_count":2,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-31T08:07:34.249Z","etag":null,"topics":["data-visualization","duckdb","duckdb-query","duckdb-ui","etl-tool","pandas","python","visual-analytics"],"latest_commit_sha":null,"homepage":"https://chenkeliang.github.io/duckdb-query/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Chenkeliang.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-09-03T12:47:26.000Z","updated_at":"2026-05-31T06:08:19.000Z","dependencies_parsed_at":"2025-11-22T11:03:08.493Z","dependency_job_id":null,"html_url":"https://github.com/Chenkeliang/duckdb-query","commit_stats":null,"previous_names":["chenkeliang/duckdb-query"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/Chenkeliang/duckdb-query","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Chenkeliang%2Fduckdb-query","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Chenkeliang%2Fduckdb-query/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Chenkeliang%2Fduckdb-query/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Chenkeliang%2Fduckdb-query/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Chenkeliang","download_url":"https://codeload.github.com/Chenkeliang/duckdb-query/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Chenkeliang%2Fduckdb-query/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34376125,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-15T02:00:07.085Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["data-visualization","duckdb","duckdb-query","duckdb-ui","etl-tool","pandas","python","visual-analytics"],"created_at":"2026-06-13T21:00:14.186Z","updated_at":"2026-06-15T19:00:16.283Z","avatar_url":"https://github.com/Chenkeliang.png","language":"TypeScript","funding_links":[],"categories":["DuckDB Clients and UIs"],"sub_categories":["Web Clients (WebAssembly)"],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"frontend/src/assets/duckq-logo.svg\" alt=\"DuckQuery\" height=\"80\"\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eDuckQuery\u003c/h1\u003e\n\n  \u003cb\u003e文件与数据库的 AI 可视化 SQL 工作台。\u003c/b\u003e\u003cbr\u003e\n  \u003cb\u003e用大白话提问或直接写 SQL，跨本地文件（Excel/CSV/JSON）与远程数据库（MySQL/PG）一站式分析 —— 跨源、免 ETL。\u003c/b\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003csub\u003e写给在本地文件与在线数据库之间来回折腾的分析师和工程师 —— 不建仓、不写脚本。\u003c/sub\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://chenkeliang.github.io/duckdb-query/\"\u003e在线 Demo\u003c/a\u003e •\n  \u003ca href=\"#快速开始\"\u003e快速开始\u003c/a\u003e •\n  \u003ca href=\"#你能做什么\"\u003e你能做什么\u003c/a\u003e •\n  \u003ca href=\"#部署方式\"\u003e部署方式\u003c/a\u003e •\n  \u003ca href=\"README_en.md\"\u003eEnglish\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://chenkeliang.github.io/duckdb-query/\"\u003e\u003cimg src=\"https://img.shields.io/badge/在线_Demo-浏览器内试用-F4B43C?logo=duckdb\u0026logoColor=white\" alt=\"Live Demo\"\u003e\u003c/a\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Python-3.12+-3776AB.svg?logo=python\u0026logoColor=white\" alt=\"Python\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/React-18-61DAFB.svg?logo=react\u0026logoColor=black\" alt=\"React\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/DuckDB-Powered-FFBF00.svg?logo=duckdb\u0026logoColor=white\" alt=\"DuckDB\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/License-MIT-green.svg\" alt=\"MIT\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/assets/og-cover.png\" alt=\"DuckQuery —— 一条 SQL 同时查本地文件与远程数据库\" width=\"840\"\u003e\n\u003c/p\u003e\n\n---\n\n## 快速开始\n\n### 浏览器内试用（免安装）\n\n对示例表跑真 SQL,或拖入你自己的 CSV / Parquet / JSON —— 全程在浏览器内、基于 **DuckDB-Wasm**。\n\n👉 **[打开在线 Demo](https://chenkeliang.github.io/duckdb-query/)**\n\n\u003e 连接 MySQL / Postgres 与 AI 功能跑在后端,需要下面的自托管版。\n\n### 自托管（完整功能）\n\n启动全栈版本（Python 后端 + React 前端）—— 直接读写本地文件、连接持久化的 MySQL/Postgres、以及 AI。\n\n**前置依赖：** 需要安装 Docker 和 Docker Compose\n\n```bash\ngit clone https://github.com/Chenkeliang/duckdb-query.git \u0026\u0026 cd duckdb-query \u0026\u0026 ./quick-start.sh\n```\n\n打开 **http://localhost:3000** 即可开始查询。\n\n---\n\n## 演示\n\n### 数据源上传\n![数据源上传](docs/assets/cn_source.gif)\n\n### 查询工作台\n![查询工作台](docs/assets/cn_query.gif)\n\n---\n\n## 你能做什么\n\n| 功能 | 操作方式 |\n|------|---------|\n| 🧠 **用大白话提问（问数 Text-to-SQL）** | 和数据对话，AI 起草 SQL，你确认后再执行 —— **绝不自动运行**。 |\n| 🩺 **AI 报错医生** | 查询报错时，给出中文诊断 + 修正后的 SQL（懂你的表结构，含联邦表）。 |\n| 📈 **AI 图表推荐** | 一键把结果集变成合适的图表 —— 柱 / 折线 / 饼 / 大数字。 |\n| 📥 **从任意处粘贴CSV/TSV** | 复制单元格，直接粘贴创建新表。 |\n| 📂 **查询任意文件** | 拖拽 CSV/Excel/Parquet/JSON 到浏览器，即刻生成表。 |\n| 🗄️ **连接外部数据库** | 添加 MySQL/PostgreSQL 连接，与本地文件一起查询。 |\n| 🔗 **跨数据源 JOIN** | `SELECT * FROM 本地表 JOIN mysql_db.users ON ...` |\n| 📊 **透视 / JOIN / 集合** | SQL 编辑器 + JOIN 工作台 + 透视表 + 集合运算（无独立「可视化构建器」Tab）。 |\n| 🌐 **从 URL 导入** | 输入 CSV/Parquet/JSON 链接，自动导入 DuckDB。 |\n| 🌙 **深色模式 \u0026 多语言** | 一键切换主题和语言（中文/English）。 |\n\n---\n\n## 工作原理\n\n```\n┌─────────────────┐      ┌─────────────────┐      ┌─────────────────┐\n│  你的文件        │      │   DuckQuery     │      │  你的数据库      │\n│  CSV/Excel/...  │ ───► │  (DuckDB 引擎)  │ ◄─── │  MySQL/Postgres │\n└─────────────────┘      └────────┬────────┘      └─────────────────┘\n                                  │\n                                  ▼\n                         ┌─────────────────┐\n                         │  SQL + 可视化    │\n                         │    查询结果      │\n                         └─────────────────┘\n```\n\n文件被导入为 **DuckDB 原生表**，查询速度极快。外部数据库通过 DuckDB 的 `ATTACH` 机制连接。\n\n---\n\n## 为什么选 DuckQuery？\n\n多数工具让你二选一：**数据库 GUI**（DBeaver、TablePlus）碰不了本地 CSV；**BI 工具**（Metabase、Superset）又要先建仓库、跑 ETL。DuckQuery 补上中间这块 —— 同时对着文件和数据库、一条 SQL 跨源 JOIN，还能让 AI 帮你写 SQL。\n\n| | **DuckQuery** | DBeaver / TablePlus | Metabase / Superset |\n|---|:---:|:---:|:---:|\n| 查询本地 CSV / Excel / Parquet | ✅ 原生 | ⚠️ 需先导入 | ❌ |\n| 一条 SQL JOIN 文件 ↔ MySQL/PG | ✅ | ❌ | ❌ |\n| 自然语言生成 SQL（AI） | ✅ 内置 | ❌ | ⚠️ 付费/受限 |\n| 免 ETL / 免数仓 | ✅ | ✅ | ❌ |\n| 完全本地 / 可自托管 | ✅ | ✅ | ⚠️ 需服务端 |\n| 上手到第一条查询 | 几秒 | 几分钟 | 几小时 |\n\n基于 **DuckDB** 进程内分析引擎 —— 1 GB 的 CSV 与远程表毫秒级 JOIN，无需维护任何数据管道。\n\n---\n\n## 部署方式\n\n### Docker 启动（推荐）\n\n```bash\ngit clone https://github.com/Chenkeliang/duckdb-query.git\ncd duckdb-query\n./quick-start.sh\n```\n\n| 服务 | 地址 |\n|------|------|\n| 前端界面 | http://localhost:3000 |\n| API 文档 | http://localhost:8001/docs |\n\n**数据位置**：表与连接配置在宿主机 **`./data`**（Docker 卷绑定）。`./quick-start.sh` 重建容器时**不会**删除 `./data`；日志里的 `Removed` 一般指旧容器被替换，不是删库。\n\n**国内拉取镜像超时**（`node:24-alpine` 连接 docker.io 失败时）：\n\n- 脚本默认使用 DaoCloud 镜像；首次运行会自动从 `.env.docker.cn.example` 生成 `.env`。\n- 也可手动：`cp .env.docker.cn.example .env` 后执行 `docker compose up -d --build`。\n- 能稳定访问 Docker Hub 时：`USE_DOCKER_HUB=1 ./quick-start.sh`。\n\n**仅重建前端**（保留 `./data`）：\n\n```bash\ndocker compose up -d --build frontend\n```\n\n**完全停止服务**（仍保留 `./data`）：`docker compose down`（请勿随意使用 `down -v`）。\n\n### 本地开发\n\n```bash\n# 后端（默认 http://localhost:8000 ，文档 /docs）\ncd api \u0026\u0026 pip install -r requirements.txt \u0026\u0026 uvicorn main:app --reload\n\n# 前端（默认 http://localhost:5173 ，/api 由 Vite 代理到后端）\ncd frontend \u0026\u0026 npm install \u0026\u0026 npm run dev\n```\n\n本地查询走 `POST /api/duckdb/execute`（本地表）与 `POST /api/duckdb/federated-query`（外部库 ATTACH），勿使用旧版 `POST /api/execute_sql`。端点清单见 [`docs/API_CONTRACT_FE_BE.md`](docs/API_CONTRACT_FE_BE.md)，执行流程见 [`docs/frontend/QUERY_EXECUTION_FLOW.md`](docs/frontend/QUERY_EXECUTION_FLOW.md)。\n\n---\n\n## 配置说明\n\nDuckQuery 开箱即用。如需高级配置，编辑 `config/app-config.json`：\n\n| 配置项 | 默认值 | 作用 |\n|--------|--------|------|\n| `duckdb_memory_limit` | `8GB` | DuckDB 最大内存 |\n| `server_data_mounts` | `[]` | 挂载宿主机目录用于直接读取文件 |\n| `cors_origins` | `3000`、`5173` | 允许的前端访问源 |\n\n👉 **[完整配置参考 →](docs/CONFIGURATION_ZH.md)**\n\n---\n\n## 常见问题\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eDocker 如何不上传文件直接查询？\u003c/b\u003e\u003c/summary\u003e\n\n在 `docker-compose.yml` 中挂载目录：\n```yaml\nvolumes:\n  - /你的数据路径:/app/server_mounts\n```\n然后在 `config/app-config.json` 添加：\n```json\n\"server_data_mounts\": [{\"label\": \"我的数据\", \"path\": \"/app/server_mounts\"}]\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e本地开发如何不上传文件直接查询？\u003c/b\u003e\u003c/summary\u003e\n\n在 `config/app-config.json` 中配置本地文件夹：\n```json\n\"server_data_mounts\": [{\"label\": \"我的数据\", \"path\": \"/Users/你的用户名/数据目录\"}]\n```\n重启后端服务后，在数据源页面的\"服务器目录\"标签页可直接浏览和导入文件。\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eDocker 如何修改默认端口？\u003c/b\u003e\u003c/summary\u003e\n\n编辑 `docker-compose.yml`：\n```yaml\nservices:\n  backend:\n    ports: [\"9000:8000\"]  # 后端改为 9000\n  frontend:\n    ports: [\"8080:80\"]    # 前端改为 8080\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e本地开发如何修改默认端口？\u003c/b\u003e\u003c/summary\u003e\n\n**后端端口**（默认 8000）：\n```bash\ncd api \u0026\u0026 uvicorn main:app --reload --port 9000\n```\n\n**前端端口**（默认 5173）：\n在 `frontend/vite.config.js` 的 `server` 块中添加 `port`：\n```javascript\nserver: {\n  port: 3000,  // 添加这一行\n  proxy: {\n    // ... 现有配置\n  },\n},\n```\n或启动时指定：\n```bash\ncd frontend \u0026\u0026 npm run dev -- --port 3000\n```\n\n**注意跨域配置**：默认允许 `localhost:3000` 和 `localhost:5173`。如使用其他端口，需在 `config/app-config.json` 添加：\n```json\n\"cors_origins\": [\"http://localhost:3000\", \"http://localhost:5173\", \"http://localhost:你的端口\"]\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eDocker 重新部署会删掉我的表吗？\u003c/b\u003e\u003c/summary\u003e\n\n不会。DuckDB 文件在宿主机 **`./data`**，`docker compose up -d --build` 只替换容器。`docker compose down` 停止容器，也**不删** `./data`。请勿对生产数据执行 `docker compose down -v`（若将来引入命名卷）。WAL 异常时可参考 `./scripts/repair-duckdb-wal.sh`。\n\u003c/details\u003e\n\n---\n\n## 喜欢的话\n\n如果 DuckQuery 帮你省了一段弯路，点个 star 能让更多人找到它。\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/Chenkeliang/duckdb-query\"\u003e⭐ 在 GitHub 上 Star\u003c/a\u003e \u0026nbsp;·\u0026nbsp;\n  \u003ca href=\"https://chenkeliang.github.io/duckdb-query/\"\u003e🚀 试用在线 Demo\u003c/a\u003e \u0026nbsp;·\u0026nbsp;\n  \u003ca href=\"https://github.com/Chenkeliang/duckdb-query/issues\"\u003e🛠 提 issue / 参与贡献\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n## 许可证\n\n本项目采用 MIT 许可证开源，详见 [LICENSE](LICENSE) 文件。\n\nMIT © [Chenkeliang](https://github.com/Chenkeliang)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FChenkeliang%2Fduckdb-query","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FChenkeliang%2Fduckdb-query","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FChenkeliang%2Fduckdb-query/lists"}