DuckLocal 文档

简体中文

English

简体中文

English

外观

快速上手 ​

English

DuckLocal 是一个桌面应用，让你直接用 SQL 查询本机上的数据文件。不用运行服务器，不用配置连接，也不用注册账号，选好文件就能开始查询。本页带你从下载走到第一条查询结果，大约五分钟。

1. 安装 ​

DuckLocal 支持 macOS、Windows 和 Linux。点击下方链接可从 dl.ducklocal.app 获取最新版本；安装文件与发布说明也可在 GitHub 查看。

本文档已按 v0.4.0 发布版本更新（2026 年 11 月 4 日）。这个版本新增了 Agent 工作流：受限 SQL、可确认结果的窗口交接、仪表盘修改提议、分析记录和可移动的项目。仪表盘里的折线图和散点图改为按实际时间定位，gzip 压缩的 JSON 和 CSV 也能直接当数据打开。如果你是从 0.3.0 之前的版本更新，请重新安装扩展，因为 0.3.0 把 DuckLocal 升级到了 DuckDB 2.0。

Mac ​

需要 macOS 12 及以上、Apple silicon 芯片（M1 或更新）。

  1. 下载 ducklocal-macos-arm64.dmg。
  2. 打开磁盘映像，把 DuckLocal 拖到“应用程序”上。
  3. 从“应用程序”或聚焦搜索启动 DuckLocal。

磁盘映像已经过 Apple 签名和公证，打开时不需要任何绕过 Gatekeeper 的操作。

Windows ​

需要 64 位 Windows 10 及以上。

  1. 下载 ducklocal-windows-x86_64.zip 并解压。
  2. 运行解压出的文件夹里的 ducklocal.exe。这个版本暂未进行代码签名，首次启动时可能出现 Windows 已保护你的电脑——点击 更多信息，再点击 仍要运行。

Linux ​

需要 x86_64 系统、glibc 2.35 或更新（Ubuntu 22.04、Debian 12、Fedora 36 及以上），以及支持 Vulkan 的显卡驱动。

bash
curl -LO https://dl.ducklocal.app/latest/ducklocal-linux-x86_64.tar.gz
tar -xzf ducklocal-linux-x86_64.tar.gz
./ducklocal-linux-x86_64/ducklocal
改为从源码构建

需要 Rust stable 1.85.1 或更新版本，以及 C++ 工具链（Xcode Command Line Tools）。DuckDB 由内置源码编译，首次构建需要几分钟，并占用几 GB 磁盘空间。

bash
git clone https://github.com/JetSquirrel/DuckLocal
cd DuckLocal
cargo build --release
./target/release/ducklocal

可执行文件是 ./target/release/ducklocal，本指南中写 ducklocal 的地方都可以用它代替。打包 .app 的方法见开发指南。

2. 添加 ducklocal 命令（可选） ​

应用里的功能都用不着终端。如果还想从命令行打开数据，或者让 AI 助手通过 CLI 分析数据，在应用里添加命令即可：

  1. 点击标题栏的机器人按钮，或在菜单栏选择 DuckLocal → 命令行与 AI…。
  2. 点击 安装命令。在 Mac 上，系统会请你输入密码，以写入 /usr/local/bin。
  3. 打开新的终端，确认一下：ducklocal --version。

这个命令是指向应用的链接，所以更新 DuckLocal 后，命令也随之更新。要更新，点状态栏最右边的版本号：新版本会下载好，重启时安装（见检查更新）。Mac 上装在 /usr/local/bin，Linux 上装在 ~/.local/bin；Windows 上会把应用所在文件夹加入 Path。

在同一个对话框里，添加到 Claude Code 会安装 DuckLocal 的 AI 智能体技能包（agent skill），让 Claude Code 知道怎样查询你的文件；复制说明 会复制一段简短说明，粘贴给任何其他 AI 助手即可。详见 AI CLI 与官方技能包。

手动添加
bash
sudo mkdir -p /usr/local/bin
sudo ln -sf /Applications/DuckLocal.app/Contents/MacOS/ducklocal /usr/local/bin/ducklocal

删除命令：sudo rm /usr/local/bin/ducklocal。在 Linux 上，把解压出的可执行文件链接到 ~/.local/bin；在 Windows 上，把解压出的文件夹加入 Path。

3. 打开数据 ​

首次启动时，会先出现一段由小鸭子带路的简短引导：接入 AI 助手、打开数据、侧边栏、运行查询、查看结果。任何一步都可以点 跳过。想再看一遍，Mac 上在 DuckLocal 菜单里选 显示新手引导，或者在状态栏右端版本号的右键菜单里选。

引导后面是标题为 把数据拖进来 的界面。以下任意一种方式都能导入数据：

  • 把 CSV、TSV、Parquet、JSON、Excel 文件或整个文件夹拖到窗口上。

  • 点击 打开文件 或 打开文件夹。

  • 在 Mac 上，在访达里双击 .parquet 或 .duckdb 文件；CSV、JSON 和 Excel 文件则在 打开方式 里选 DuckLocal。见从访达打开。

  • 在终端里写出路径：

    bash
    ducklocal ./sales.csv         # 单个文件
ducklocal ./logs/             # 递归打开文件夹下的所有数据文件
ducklocal './data/*.parquet'  # 通配符——加引号，避免被 shell 提前展开
ducklocal warehouse.duckdb    # 已有的 DuckDB 数据库

每个文件都会变成一个以文件名命名的视图（sales.csv 变成 sales），出现在侧栏的 本地文件 下，并列出各列和行数。DuckLocal 在原位置读取文件，不复制，也不上传。

打开过的文件会记下来，下次启动还是同一个工作区。格式、文件夹、通配符和数据库的细节见数据源。

在 Mac 上，打开文件之前还可以先瞄一眼：在访达里选中它，按空格键。DuckLocal 的快速查看预览会显示 Parquet、DuckDB、CSV、TSV 和 JSON Lines 文件的列和前几行。

手头没有数据？

10 分钟上手教程会用一个小样例文件一步步带你走一遍。

4. 运行查询 ​

点击 新建查询（打开数据后，编辑器也会自动出现）。输入 SQL，按 ⌘↵（Cmd+Enter；Windows 和 Linux 上是 Ctrl+Enter）：

sql
SELECT * FROM sales LIMIT 20;

把 sales 换成你侧栏里的任意视图名。

结果出现在编辑器下方的面板里。切换到 图表 可以快速看个大概，也可以导出为 CSV 或 Parquet。编辑器上方的工具栏有 运行、格式化 和 EXPLAIN。

还有个捷径：在侧栏点表旁边的播放按钮，会生成现成的 SELECT * … LIMIT 100；点列名则只查询这一列。

接下来 ​

基于 Apache-2.0 许可开源发布。