SQL 编辑器

English

每个查询标签页都有独立的编辑器缓冲区。编辑器使用 tree-sitter 实现 SQL 语法高亮，采用 2 个空格缩进，并显示行号。

标签页

控件	作用
+ 或 ⌘T	在末尾新建一个查询标签页并切换过去
单击某个标签页	切换到该标签页
Ctrl+Tab / Ctrl+Shift+Tab	下一个 / 上一个标签页
⌘1 … ⌘8、⌘9	第一到第八个标签页；⌘9 是最后一个
拖动标签页	调整它在标签栏里的位置
×、⌘W 或鼠标中键单击	关闭一个标签页。最后一个标签页关不掉：不显示 ×，⌘W 也不起作用。有未保存修改的仪表盘（dashboard）会先询问
右键单击标签页	关闭标签页、关闭其他标签页、关闭右侧标签页。有未保存修改的仪表盘会保持打开，并提示有几个
双击某个标签页	就地编辑标题。按 Enter 或点别处保留新标题，按 Escape 保留原标题；标题为空时回退为 查询 N

打开的标签页下次启动会按原来的顺序回来：查询标签页连同标题和编辑器里的 SQL（不论运行过没有），以及仪表盘标签页。查询结果不保留，重新运行即可。新开的查询标签页以 SELECT '你好，DuckLocal' AS greeting; 开头。

工具栏

编辑器上方从左到右依次是：

按钮	作用
运行	运行编辑器里的 SQL，见运行 SQL
停止	只在查询或性能分析运行期间出现，用来中断它
格式化	重新排版 SQL，见格式化
执行计划	显示 DuckDB 打算怎么执行，不真正运行语句
性能分析	运行查询，并显示每个算子花了多少时间

执行计划 和 性能分析 的说明见执行计划与性能分析。

运行 SQL

编辑器获得焦点时按 ⌘↵（Cmd+Enter），或使用 运行 按钮。

查询运行期间，再按运行没有反应（执行计划和性能分析也一样），运行按钮旁会出现 停止 按钮。点停止或按 ⌘. 可以中断查询：查询以 DuckDB 的 Interrupted 错误结束，和其他失败一样记入历史。没有超时：不点停止，查询会一直跑到 DuckDB 算完为止，其他数据库操作都在后面排队。

查询结果从 DuckDB 流式读取。表格达到行数上限后，扫描会停止，文件剩余部分不再读取。有些查询必须读取所有行才能返回第一行结果，例如 ORDER BY、GROUP BY、聚合和窗口函数，这类查询仍会完整计算。

每个标签页有自己的结果。切换标签页后才返回的结果，会回到发起查询的那个标签页。

语句怎么处理，看它开头的关键字。SELECT、WITH、SHOW、DESCRIBE、EXPLAIN、PRAGMA、SUMMARIZE、VALUES、FROM、TABLE、PIVOT 和 CALL 会产生结果集。其他语句（DDL（数据定义）和 DML（数据操作）语句）不显示结果表格，只报告 完成：N 行受影响，耗时 …。判断时会跳过开头的 -- 注释，但不跳过块注释。

脚本

编辑器里可以写多条语句。运行 会像 DuckDB 命令行读文件那样按顺序全部执行，遇到第一个失败就停下：ATTACH 失败后再跑 SELECT，只会多出一个误导人的错误。结果上方有一条步骤栏，列出每条语句，标着行数、完成、失败或未执行；点哪一条就看哪一条的结果。出错时下划线标在失败的那条语句上，而不是整个脚本。

DuckDB 命令行的几个点命令也能用，每个单独占一行：

命令	显示
.tables ?PATTERN?	表和视图，可以用 ILIKE 模式过滤，比如 stat%
.schema ?PATTERN?	表和视图的 CREATE 语句，可以过滤
.databases	已挂载的数据库
.help	这张列表

其他点命令（.mode、.read 等）会报错，并列出能用的那几个。

错误

语句执行失败时会弹出提示框，标题为 查询失败，里面原样显示 DuckDB 的报错信息。这条信息来自引擎，不管界面是什么语言，都是英文。结果表格里什么也不写，但这次执行仍会记入查询历史，并标为失败。

报错里指明了位置时（解析错误和绑定错误都会带一行 LINE n: 和一个 ^），编辑器会在该处画一条红色波浪线：单个 ^ 标出所指的词，一串 ^ 标出覆盖的范围。编辑代码时标记会跟着移动，下次运行时清除。运行期错误不带位置，所以不画标记。

格式化

格式化 会用 sqlformat 处理缓冲区内容：缩进 2 个空格、关键字转为大写，然后替换整个缓冲区。缓冲区为空时什么也不做。

执行计划与性能分析

这两个按钮都作用于编辑器里的全部文本，而且都只接受恰好一条语句。有两条或更多语句，或者有点命令（dot command）时，会拒绝执行并提示 一次只能对一条语句执行计划或分析：把要看的那条单独放进一个标签页。 末尾的 ; 和末尾的注释没有影响。

运行、执行计划、性能分析三者中有一个在忙时，另外两个按了没有反应。执行计划和性能分析都不会记入查询历史。它们的输出会替换 结果 标签页里的表格，当时开着别的标签页也会切回来；出错时和运行失败一样，显示 查询失败 提示框。

执行计划

执行计划 执行 EXPLAIN <你的语句>，用等宽纯文本显示 DuckDB 的查询计划和耗时。它只做规划，不执行语句，所以对 INSERT、UPDATE、DELETE 查看执行计划也是安全的。

性能分析

性能分析 用 EXPLAIN (ANALYZE, FORMAT JSON) 运行语句，把实际执行的计划画成一棵树：每个算子自身的耗时及其占比、产出的行数与优化器的预估（相差超过 10 倍时标出），以及它的过滤条件、连接键和投影列。最耗时的算子会在顶部点名，并用红色显示。怎么看这棵树，见执行计划与性能分析的输出。

性能分析会真正执行语句，算子的耗时就是这样测出来的。所以它只接受单条只读查询：

• 接受：SELECT、WITH … SELECT、FROM …、VALUES、TABLE、SHOW、DESCRIBE、SUMMARIZE。
• **拒绝：**任何写入数据的语句（INSERT、UPDATE、DELETE、CREATE 等）、CALL、PRAGMA、COPY、EXPLAIN 本身、藏在 WITH 后面的写入（WITH s AS (…) INSERT …），以及没有显式写出 IN (…) 列表的 PIVOT。

被拒绝的语句会提示 只能分析读取数据的语句（SELECT、WITH、FROM 等）：分析会真正执行语句。 判断由 DuckDB 自己的解析器在执行任何东西之前做出，而不是看开头的关键字。

性能分析的耗时和查询本身差不多，外加测量的开销。和运行一样，可以用 停止（或 ⌘.）中断。

自动补全

补全菜单会参考 catalog 中的对象。候选项依次为：

1. schema（表结构）中的表和列（最多 35 项）
2. DuckDB 函数名
3. SQL 关键字

最多列出 50 个候选项。匹配对象是光标左边紧挨着的标识符，按前缀匹配，不区分大小写：sel 能补全为 SELECT，elect 则什么也补不出来。选中函数会插入函数名和左括号；包含空格或特殊字符的标识符会加上双引号再插入。

关键字和函数列表只收录了挑选过的一部分，并非所有 DuckDB 函数都会出现。

键盘快捷键

在 Windows 和 Linux 上，下文的 ⌘ 一律换成 Ctrl。

DuckLocal 自己的快捷键，全部列在菜单栏里：

快捷键	操作
⌘↵	运行查询
⌘.	停止正在运行的查询
⌘T	新建查询标签页
⌘W	关闭当前标签页
Ctrl+Tab / Ctrl+Shift+Tab	下一个 / 上一个标签页（Mac 上也是 Ctrl）
⌘1 … ⌘9	跳到对应位置的标签页；⌘9 是最后一个
⌘O	打开数据
⌘S	在仪表盘的源码视图中保存
⌘B	收起或展开侧栏
⌘+ / ⌘− / ⌘0	放大 / 缩小 / 复原界面大小——见界面大小
⌘Q	退出

编辑器自带的快捷键，和普通文本框一样：

快捷键	操作
⌘F / ⇧⌘F	在编辑器中查找 / 替换
⌘Z / ⇧⌘Z	撤销 / 重做
⌘A	全选
⌘C / ⌘X / ⌘V	复制 / 剪切 / 粘贴
⌥⌘↑ / ⌥⌘↓	在上方 / 下方添加光标
⌘← / ⌘→ / ⌥← / ⌥→	按行 / 按词移动
⌘↑ / ⌘↓	移动到文档开头 / 结尾
⌘⌫ / ⌥⌫	删除到行首 / 删除前一个词

菜单

菜单栏列出了窗口里的所有命令和对应的快捷键：

菜单	命令
DuckLocal	命令行与 AI、检查更新…、启动时检查更新、显示新手引导、打开日志文件夹、退出 DuckLocal
文件	新建查询、打开数据、保存、关闭标签页、下一个标签页、上一个标签页
编辑	撤销、重做、剪切、拷贝、粘贴、全选
查询	运行、停止
显示	显示或隐藏侧边栏、放大界面、缩小界面、默认大小、在线底图（OpenStreetMap）

Windows 和 Linux 没有菜单栏，显示新手引导 和 打开日志文件夹 在状态栏右端版本号的右键菜单里。

在线底图（OpenStreetMap） 是一个勾选项，见图表。表结构侧栏里的行也有右键菜单，见Schema 浏览与历史。没有命令面板。