# 查询编辑器

> 使用 DBX 编写、理解、参数化、执行、分析和复用 SQL。

Source: https://dbxio.com/cn/docs/query-editor

Language: zh-CN

Relative links resolve against https://dbxio.com/cn/docs/query-editor.



查询编辑器是 DBX 的 SQL 工作区。它把方言感知的高亮与补全、语义诊断、参数输入、执行进度、多结果、执行计划、查询历史、SQL 库和 AI 助手放在同一个标签页中。

## Vim 配置

在桌面版的**编辑器设置**中启用 Vim 模式后，DBX 会读取 `~/.dbx/vimrc`。如文件不存在，请先创建；修改后重启 DBX 才会生效。空行及以 `"` 开头的注释行会被忽略。CodeMirror Vim 支持的命令会应用到每个 SQL 编辑器标签页，例如：

```vim
" DBX Vim 映射
imap jj <Esc>
nmap Y y$
set clipboard=unnamedplus
```

配置 `set clipboard=unnamedplus` 后，Vim 的复制和删除会写入系统剪贴板，普通模式下的 `p` 和 `P` 会从系统剪贴板读取。不支持的命令不会阻止编辑器启动。

## 基本工作流

### 选择连接上下文

新建查询时选择连接、数据库和 Schema。也可以从对象树、快速打开、SQL 库或 SQL 文件创建带上下文的查询标签。

### 编写并检查 SQL

使用补全、悬停信息、语义诊断、格式化和代码折叠理解 SQL。`Ctrl/Cmd+Click` 可以按设置跳转到表数据或对象位置。

### 明确执行范围

选中要执行的 SQL，或使用当前语句/全部内容。多语句时可以通过执行目标选择器确认范围。

### 查看结果或执行计划

结果区支持多个运行记录、横向标签或列表视图。需要分析性能时，使用执行计划入口读取树、摘要和标准表格。

### 保存和复用

把稳定查询保存到 SQL 库或外部 `.sql` 文件，并通过历史记录、快速打开或文件夹再次使用。

## 执行 SQL

| 操作      | macOS         | Windows / Linux |
| ------- | ------------- | --------------- |
| 执行当前范围  | `Cmd+Enter`   | `Ctrl+Enter`    |
| 在新结果中执行 | `Cmd+\`       | `Ctrl+\`        |
| 停止执行    | 点击执行按钮变成的停止按钮 | 点击执行按钮变成的停止按钮   |

有选中文本时，DBX 优先执行选中内容；没有选中时，根据当前语句和执行目标设置决定范围。快捷键可以在 [快捷键](/cn/docs/keyboard-shortcuts) 中修改。

普通执行会更新当前激活结果。**在新结果中执行**适合保留旧结果进行对比。结果可以平铺为横向标签，也可以切换为列表；多次执行还会保留运行记录，并可以固定重要结果。

多语句执行时，结果区显示当前语句、总语句数、完成状态和错误。驱动支持时，可以取消当前查询或后续语句。

查询取消取决于驱动和数据库能力。点击停止后，服务端可能仍需要时间中断正在执行的语句。

### 执行前预览变更

对 `UPDATE` / `INSERT` / `DELETE` 语句，编辑区工具栏会出现\*\*「预览变更」\*\*按钮（右键菜单里也可用）。DBX 会把该语句改写成一条等价的只读 `SELECT`，在新结果标签中展示影响到的数据。预览会重新求值被写入的表达式，带副作用的表达式（推进序列、volatile 函数）在预览中同样生效，非确定性函数（`uuid()`、`rand()`、`now()`）显示的值可能与实际执行不同：

* `UPDATE&#x60;：网格展示受影响行 + 每个被赋值列一列 &#x2A;*`列名 (new)`**（表达式按行内旧值求值，`SET a = a + 1` 也能算出真实新值）；
* `INSERT`：网格展示即将插入的行（列名来自目标列，`VALUES` 展开）；
* `DELETE`：网格展示将被删除的行。

无法安全改写的语句会提示 **Preview is not supported**，但仍可正常执行原语句。

## 执行范围与目标选择器

| 范围     | 如何确定            | 适合场景         |
| ------ | --------------- | ------------ |
| 选中 SQL | 执行前高亮文本         | 多语句草稿中最明确、安全 |
| 当前语句   | 光标位于语句内         | 快速执行脚本中的一条语句 |
| 全部内容   | 没有选择且按设置执行整个编辑器 | 单用途短脚本       |

执行目标选择器会在需要时标出可执行语句并展示预览。可以在设置中启用或关闭，但生产和复杂脚本建议保留。

大型 `.sql` 文件、需要逐语句进度或文件级统计的任务，应使用 [SQL 文件执行](/cn/docs/sql-file)。

## 自动补全与语义诊断

补全会结合当前数据库方言和元数据提供：

* SQL 关键字、函数、类型和数据库专属语法
* 数据库、Schema、表、视图、字段和字段注释
* 表别名、CTE、子查询作用域和可见字段
* 基于外键或关系元数据的 JOIN 条件
* MySQL、PostgreSQL、SQL Server、ClickHouse 等方言的函数和语法建议
* 用户配置的 [SQL 代码片段](/cn/docs/sql-snippets)

语义诊断会标出部分无法解析的表、字段、别名和 SQL 结构。它用于提前发现问题，不代表数据库一定会拒绝或接受语句；厂商扩展语法仍以服务端结果为准。

刚创建或修改对象后，先刷新连接元数据。DBX 会缓存并按需加载表结构，以减少大型 Schema 的重复请求。

## 表和对象导航

* `Ctrl/Cmd+Click` 表名可以按设置打开表数据或定位对象
* 从光标位置可以在侧边栏定位当前引用的表
* 快速打开支持搜索连接、数据库、表、SQL 文件和 SQL 库
* 对象源码视图支持搜索，并可以把 SQL 打开到编辑器继续修改

导航依赖 SQL 解析和当前元数据。动态 SQL、同名对象或缺少 Schema 的引用可能需要手动确认目标。

## SQL 参数与变量

执行前，DBX 可以识别常见占位符并打开参数输入对话框：

| 语法            | 示例                   |
| ------------- | -------------------- |
| 位置参数          | `?`                  |
| 命名参数          | `:user_id`           |
| Shell 风格      | `${user_id}`         |
| MyBatis 风格    | `#{user_id}`         |
| SQL Server 风格 | `@user_id`           |
| 脚本变量          | `@set user_id = 42;` |

参数可以按字符串、数字、布尔、`NULL` 或原始 SQL 值输入。每种数据库可以在设置中关闭会与原生语法冲突的占位符形式。

“原始 SQL”参数不会自动加引号。只应填入经过审查的 SQL 片段，不要直接拼接不可信输入。

## 格式化、压缩与折叠

* **格式化 SQL**统一缩进、换行和关键字风格
* **压缩 SQL**移除不必要的空白，适合复制或排查生成 SQL
* **代码折叠**收起长查询、子查询或过程块；折叠快捷键可以配置
* 格式化选项和变量语法见 [SQL 格式化](/cn/docs/sql-formatter)

格式化和压缩只修改编辑器文本，不会执行 SQL。

## 执行计划

执行计划入口只接受可安全分析的查询类 SQL，例如 `SELECT`、`WITH`、`TABLE` 或 `VALUES`。支持的数据库会返回：

* 标准结果表格
* 可展开的计划树
* 节点、成本、预估行数、表和索引摘要
* 数据库返回的原始详情

不同数据库的 `EXPLAIN` 语义不同，部分引擎只提供表格或文本结果。执行计划反映优化器估算，不等于真实生产性能；需要结合数据量、统计信息、索引和实际耗时判断。

## 查询历史

在 **设置 → 数据 → 查询历史保留条数** 中，可选择 **200**、**1000**（默认）、**5000**、**10000** 或 **不限**。上限由所有连接及执行来源（包括 MCP）共用。调小后，下次记录历史时才会删除超出上限的旧记录；提高上限不会恢复已删除的记录。历史分页大小保持不变。

查询历史按连接保存已执行 SQL，并记录时间和相关上下文。可以：

* 按日期范围过滤
* 搜索并重新填入编辑器
* 区分普通执行和 AI 辅助来源
* 从历史 SQL 恢复或对比之前的排查过程
* 在字段血缘中把历史 SQL 作为可能引用关系

查询历史可能包含业务字段、表名、筛选条件或数据字面量。共享日志、截图或配置备份前先检查敏感信息。

## SQL 库与 SQL 文件

| 方式        | 适合场景                       | 平台边界                         |
| --------- | -------------------------- | ---------------------------- |
| SQL 库     | 在 DBX 中按文件夹保存和搜索常用查询       | 桌面版支持完整本地 SQL 库管理；同步范围见云同步设置 |
| 外部 SQL 文件 | 与项目仓库、脚本目录或编辑器共享 `.sql` 文件 | 本地文件打开、保存和文件树属于桌面端能力         |
| 查询标签      | 临时分析和未完成草稿                 | 可按设置恢复全部、仅固定标签或不恢复           |

保存 SQL 时可以搜索或创建文件夹。快速打开会同时索引 SQL 库和 SQL 文件。

## 安全与边界

* 只读连接会在核心执行路径拒绝可识别写入
* 生产环境保护会对写入逐次显示明确确认
* 危险 SQL 确认和 Redis 命令安全是额外保护层
* `USE` 或数据库切换会更新查询上下文，但仍应检查当前连接和目标数据库
* 自动补全、语义诊断和执行计划都依赖当前驱动与元数据能力

完整规则见 [生产环境与写入安全](/cn/docs/production-safety)。

### [查看结果](/cn/docs/data-grid)

了解数据表格、复制、导出和安全编辑。

### [使用 SQL 文件](/cn/docs/sql-file)

执行大型脚本并查看文件和语句级进度。

### [配置代码片段](/cn/docs/sql-snippets)

创建可通过补全展开的个人 SQL 模板。

### [使用 AI](/cn/docs/ai-assistant)

生成、解释、优化 SQL，并把结果放回编辑器审查。