178 lines
7.7 KiB
Plaintext
178 lines
7.7 KiB
Plaintext
---
|
||
title: 查询编辑器
|
||
description: 使用 DBX 编写、理解、参数化、执行、分析和复用 SQL。
|
||
---
|
||
|
||
查询编辑器是 DBX 的 SQL 工作区。它把方言感知的高亮与补全、语义诊断、参数输入、执行进度、多结果、执行计划、查询历史、SQL 库和 AI 助手放在同一个标签页中。
|
||
|
||
## 基本工作流
|
||
|
||
<Steps>
|
||
<Step>
|
||
### 选择连接上下文
|
||
|
||
新建查询时选择连接、数据库和 Schema。也可以从对象树、快速打开、SQL 库或 SQL 文件创建带上下文的查询标签。
|
||
|
||
</Step>
|
||
<Step>
|
||
### 编写并检查 SQL
|
||
|
||
使用补全、悬停信息、语义诊断、格式化和代码折叠理解 SQL。`Ctrl/Cmd+Click` 可以按设置跳转到表数据或对象位置。
|
||
|
||
</Step>
|
||
<Step>
|
||
### 明确执行范围
|
||
|
||
选中要执行的 SQL，或使用当前语句/全部内容。多语句时可以通过执行目标选择器确认范围。
|
||
|
||
</Step>
|
||
<Step>
|
||
### 查看结果或执行计划
|
||
|
||
结果区支持多个运行记录、横向标签或列表视图。需要分析性能时，使用执行计划入口读取树、摘要和标准表格。
|
||
|
||
</Step>
|
||
<Step>
|
||
### 保存和复用
|
||
|
||
把稳定查询保存到 SQL 库或外部 `.sql` 文件，并通过历史记录、快速打开或文件夹再次使用。
|
||
|
||
</Step>
|
||
</Steps>
|
||
|
||
## 执行 SQL
|
||
|
||
| 操作 | macOS | Windows / Linux |
|
||
| --- | --- | --- |
|
||
| 执行当前范围 | `Cmd+Enter` | `Ctrl+Enter` |
|
||
| 在新结果中执行 | `Cmd+\` | `Ctrl+\` |
|
||
| 停止执行 | 点击执行按钮变成的停止按钮 | 点击执行按钮变成的停止按钮 |
|
||
|
||
有选中文本时，DBX 优先执行选中内容；没有选中时，根据当前语句和执行目标设置决定范围。快捷键可以在 [快捷键](/cn/docs/keyboard-shortcuts) 中修改。
|
||
|
||
普通执行会更新当前激活结果。**在新结果中执行**适合保留旧结果进行对比。结果可以平铺为横向标签，也可以切换为列表；多次执行还会保留运行记录，并可以固定重要结果。
|
||
|
||
多语句执行时，结果区显示当前语句、总语句数、完成状态和错误。驱动支持时，可以取消当前查询或后续语句。
|
||
|
||
<Callout type="warn">查询取消取决于驱动和数据库能力。点击停止后，服务端可能仍需要时间中断正在执行的语句。</Callout>
|
||
|
||
## 执行范围与目标选择器
|
||
|
||
| 范围 | 如何确定 | 适合场景 |
|
||
| --- | --- | --- |
|
||
| 选中 SQL | 执行前高亮文本 | 多语句草稿中最明确、安全 |
|
||
| 当前语句 | 光标位于语句内 | 快速执行脚本中的一条语句 |
|
||
| 全部内容 | 没有选择且按设置执行整个编辑器 | 单用途短脚本 |
|
||
|
||
执行目标选择器会在需要时标出可执行语句并展示预览。可以在设置中启用或关闭，但生产和复杂脚本建议保留。
|
||
|
||
大型 `.sql` 文件、需要逐语句进度或文件级统计的任务，应使用 [SQL 文件执行](/cn/docs/sql-file)。
|
||
|
||
## 自动补全与语义诊断
|
||
|
||
补全会结合当前数据库方言和元数据提供：
|
||
|
||
- SQL 关键字、函数、类型和数据库专属语法
|
||
- 数据库、Schema、表、视图、字段和字段注释
|
||
- 表别名、CTE、子查询作用域和可见字段
|
||
- 基于外键或关系元数据的 JOIN 条件
|
||
- MySQL、PostgreSQL、SQL Server、ClickHouse 等方言的函数和语法建议
|
||
- 用户配置的 [SQL 代码片段](/cn/docs/sql-snippets)
|
||
|
||
语义诊断会标出部分无法解析的表、字段、别名和 SQL 结构。它用于提前发现问题，不代表数据库一定会拒绝或接受语句；厂商扩展语法仍以服务端结果为准。
|
||
|
||
<Callout type="info">刚创建或修改对象后，先刷新连接元数据。DBX 会缓存并按需加载表结构，以减少大型 Schema 的重复请求。</Callout>
|
||
|
||
## 表和对象导航
|
||
|
||
- `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 值输入。每种数据库可以在设置中关闭会与原生语法冲突的占位符形式。
|
||
|
||
<Callout type="warn">“原始 SQL”参数不会自动加引号。只应填入经过审查的 SQL 片段，不要直接拼接不可信输入。</Callout>
|
||
|
||
## 格式化、压缩与折叠
|
||
|
||
- **格式化 SQL**统一缩进、换行和关键字风格
|
||
- **压缩 SQL**移除不必要的空白，适合复制或排查生成 SQL
|
||
- **代码折叠**收起长查询、子查询或过程块；折叠快捷键可以配置
|
||
- 格式化选项和变量语法见 [SQL 格式化](/cn/docs/sql-formatter)
|
||
|
||
格式化和压缩只修改编辑器文本，不会执行 SQL。
|
||
|
||
## 执行计划
|
||
|
||
执行计划入口只接受可安全分析的查询类 SQL，例如 `SELECT`、`WITH`、`TABLE` 或 `VALUES`。支持的数据库会返回：
|
||
|
||
- 标准结果表格
|
||
- 可展开的计划树
|
||
- 节点、成本、预估行数、表和索引摘要
|
||
- 数据库返回的原始详情
|
||
|
||
不同数据库的 `EXPLAIN` 语义不同，部分引擎只提供表格或文本结果。执行计划反映优化器估算，不等于真实生产性能；需要结合数据量、统计信息、索引和实际耗时判断。
|
||
|
||
## 查询历史
|
||
|
||
查询历史按连接保存已执行 SQL，并记录时间和相关上下文。可以：
|
||
|
||
- 按日期范围过滤
|
||
- 搜索并重新填入编辑器
|
||
- 区分普通执行和 AI 辅助来源
|
||
- 从历史 SQL 恢复或对比之前的排查过程
|
||
- 在字段血缘中把历史 SQL 作为可能引用关系
|
||
|
||
<Callout type="warn">查询历史可能包含业务字段、表名、筛选条件或数据字面量。共享日志、截图或配置备份前先检查敏感信息。</Callout>
|
||
|
||
## SQL 库与 SQL 文件
|
||
|
||
| 方式 | 适合场景 | 平台边界 |
|
||
| --- | --- | --- |
|
||
| SQL 库 | 在 DBX 中按文件夹保存和搜索常用查询 | 桌面版支持完整本地 SQL 库管理；同步范围见云同步设置 |
|
||
| 外部 SQL 文件 | 与项目仓库、脚本目录或编辑器共享 `.sql` 文件 | 本地文件打开、保存和文件树属于桌面端能力 |
|
||
| 查询标签 | 临时分析和未完成草稿 | 可按设置恢复全部、仅固定标签或不恢复 |
|
||
|
||
保存 SQL 时可以搜索或创建文件夹。快速打开会同时索引 SQL 库和 SQL 文件。
|
||
|
||
## 安全与边界
|
||
|
||
- 只读连接会在核心执行路径拒绝可识别写入
|
||
- 生产环境保护会对写入逐次显示明确确认
|
||
- 危险 SQL 确认和 Redis 命令安全是额外保护层
|
||
- `USE` 或数据库切换会更新查询上下文，但仍应检查当前连接和目标数据库
|
||
- 自动补全、语义诊断和执行计划都依赖当前驱动与元数据能力
|
||
|
||
完整规则见 [生产环境与写入安全](/cn/docs/production-safety)。
|
||
|
||
<Cards>
|
||
<Card title="查看结果" href="/cn/docs/data-grid">
|
||
了解数据表格、复制、导出和安全编辑。
|
||
</Card>
|
||
<Card title="使用 SQL 文件" href="/cn/docs/sql-file">
|
||
执行大型脚本并查看文件和语句级进度。
|
||
</Card>
|
||
<Card title="配置代码片段" href="/cn/docs/sql-snippets">
|
||
创建可通过补全展开的个人 SQL 模板。
|
||
</Card>
|
||
<Card title="使用 AI" href="/cn/docs/ai-assistant">
|
||
生成、解释、优化 SQL，并把结果放回编辑器审查。
|
||
</Card>
|
||
</Cards>
|