DuckLocalducklocal schema ./data/发现关系
在写 SQL 之前，列出文件、表、视图及其列。
先探索，再查询
官方工作流让智能体不去猜列名，也不会把一部分预览当成完整的数据集。
摸清表结构
运行
ducklocal schema ./data/，得到关系、可直接使用的FROM表达式、列和类型。目录很大时，会返回概要和进一步深入的提示。在边界内预览
用一条 SQL 语句和较小的
--limit查看有代表性的行。检查命令的退出状态和 JSON 中的truncated字段。在 SQL 里算出答案
过滤、连接和聚合都在 DuckDB 中完成，而不是在智能体上下文里对截断的预览求和。只返回答案需要的证据。
一条命令，一条 SQL
每次调用都会创建独立的 DuckDB 连接，校验输入恰好是一条语句，并把机器可读的结果写到 stdout。出错时以 JSON 写到 stderr，并返回非零退出码。
$ ducklocal query --sql \ "SELECT channel, round(sum(revenue), 2) AS revenue FROM 'sales.csv' GROUP BY channel ORDER BY revenue DESC" {"columns":[...], "rows":[["Mobile app",290549.76],...], "row_count":4, "truncated":false, "elapsed_ms":14}
小而明确的接口
ducklocal schema sales.csv --stats剖析单个关系
获得准确的空值数、不同值数、取值范围、中位数和日期覆盖范围。
ducklocal query --sql "…"执行一条语句
默认得到带类型的 JSON，加 --format md 则输出 Markdown 表格。
ducklocal open --title "…" --run --sql "…"把工作交给人
当结果需要人来审阅或进一步探索时，在桌面应用中打开这条查询。
输出会告诉智能体结果是否完整
默认最多返回 1,000 行，另有 2,000,000 个单元格的上限。DuckLocal 会多读一行来判断响应是否被截断，并通过 truncated 字段告知。
GROUP BY、ORDER BY 和聚合这类查询，仍然会在完整输入上计算，然后才返回有边界的结果。
- 稳定的 JSON 结构，带类型的列和行
- 明确的
row_count、truncated和elapsed_ms - 参数无效时退出码为 2，执行失败时为 1
- 错误以 JSON 写到 stderr，stdout 保持为空
- Markdown 输出，便于生成给人看的报告
教会工作流，而不只是命令
开源的 DuckLocal 技能教智能体先看表结构、预览有边界的样本、在 SQL 中聚合、核对是否截断，并根据返回的数值作答。可以在应用里为 Claude Code 一键安装，也可以把同样的说明复制给其他编程智能体。
一个本地 CLI——不是隐藏的云服务，也不是沙箱
DuckLocal 不会把本地文件上传到任何 DuckLocal 服务，但它也不假装任意 SQL 都无害。只读数据库模式并不是文件系统或网络沙箱：COPY、安装扩展或显式的外部访问等 SQL 都可能产生副作用。
- 输出路径、覆盖写入和数据库修改需要授权
- 安装扩展和外部访问需要授权
- 写入失败后重试前，先检查目标位置
- 只在确实要修改数据库时才使用
--read-write - 依赖某个命令之前，先查看
ducklocal --help
更想要可视化的工作流？了解桌面应用中的本地数据分析 →
关于 AI agent SQL
- AI 智能体如何用 DuckLocal 查询本地数据？
- 智能体先运行
ducklocal schema找出关系和列，再用ducklocal query执行一条 SQL。命令默认返回结构化 JSON，不会打开桌面窗口，也不会启动服务器。 - CLI 默认会返回全部数据吗？
- 不会。查询输出有意设了边界：默认最多返回 1,000 行，并且还有 2,000,000 个单元格的上限。JSON 响应会说明结果是否被截断。完整的聚合应该在 SQL 中计算。
- DuckLocal 能替智能体执行 SQL 脚本吗？
- 每次调用
ducklocal query只接受一条 SQL 语句。多语句脚本会被直接拒绝，而不是部分执行，这让每一次工具调用都更容易检查。 - DuckLocal 是 MCP 服务器或安全沙箱吗？
- 不是。DuckLocal 提供的是命令行工具和一个可选的智能体技能，不是 MCP 服务器，也不是安全沙箱。可能的写入、安装扩展和外部访问仍然需要正常授权。