dbx/docs/content/docs/data-grid.cn.mdx

---
title: 数据表格
description: 在 DBX 中浏览、筛选、编辑、校验、复制和导出查询结果或表数据。
---

数据表格用于显示查询结果和表数据。它同时覆盖只读分析和小范围数据修改：浏览大结果集、筛选排序、检查复杂值、批量复制，以及在 DBX 能可靠识别目标行时生成并预览 `INSERT`、`UPDATE` 或 `DELETE`。

<Callout type="info">Redis、MongoDB、向量数据库、HBase 等系统使用各自的专项数据界面。这里主要说明关系型和兼容 SQL 数据源的结果表格。</Callout>

## 浏览与布局

DBX 使用虚拟滚动，只渲染当前可视区域。常用浏览操作包括：

- 拖拽列边缘调整宽度，或双击按内容自适应
- 拖拽列头重排顺序，并按表或查询保存布局
- 冻结左侧或右侧列，横向滚动时保留关键字段
- 显示、隐藏和搜索列；搜索可以同时匹配列名和字段注释
- 调整表格字体、字号、行高和列宽密度
- 在标准视图与转置视图之间切换
- 查看连接名、结果来源、字段类型和字段注释

列宽、列顺序、冻结状态和多个显示选项可以跨会话保留。需要恢复时，在视图选项中重置当前表格布局。

## 过滤、搜索与排序

| 方式 | 执行位置 | 适合场景 |
| --- | --- | --- |
| 表格搜索 | 当前已加载结果 | 快速定位文本、字段值或字段注释 |
| 本地值过滤 | 当前已加载结果 | 临时勾选值、列表或范围，不重新查询数据库 |
| `WHERE` | 数据库 | 大表、精确条件、可使用索引的筛选 |
| `ORDER BY` | 数据库 | 跨页稳定排序和可复现结果 |
| 当前页排序 | 客户端当前页 | 临时比较已加载数据，不改变数据库查询 |

`WHERE` 和 `ORDER BY` 输入支持较长表达式、折叠/展开和基于字段元数据的条件补全。可以在设置中配置打开表时的默认排序。

<Callout type="info">面对大表时，优先使用数据库侧 `WHERE` 和 `ORDER BY`。客户端搜索、值过滤和当前页排序不会减少数据库实际返回的数据量。</Callout>

## 什么时候可以编辑

只有当 DBX 能识别目标表，并有足够的主键或行标识生成可审查 SQL 时，结果才可编辑。

| 结果类型 | 通常行为 |
| --- | --- |
| 从对象树直接打开的表数据 | 数据库和表支持时可编辑 |
| 简单 `SELECT` | 能解析单一目标表且有可靠行标识时可编辑 |
| Join、聚合、表达式、计算列 | 通常只读 |
| 没有主键或可靠唯一标识 | 通常只读，避免生成不安全条件 |
| 连接被标记为只读 | 所有可识别修改都被拒绝 |

只读单元格仍可以打开详情、复制和导出。需要了解无法编辑的原因时，查看数据表头和单元格详情中的只读说明。

## 编辑、新增与删除

- **修改单元格**：双击进入编辑，或在详情面板中处理长文本
- **新增行**：创建一行或多行待插入记录
- **批量粘贴**：把制表符分隔的数据直接粘贴到新增行区域
- **克隆行**：复制选中记录作为新行，并按需要排除主键
- **删除行**：把选中记录标记为待删除
- **设置 NULL**：明确写入数据库 `NULL`，与空字符串区分
- **使用默认值**：让新增字段使用数据库默认值（数据库和字段支持时）
- **生成值**：为选中单元格使用内置数据生成器填充测试值
- **按 `WHERE` 更新**：在 MySQL 表数据页中，将单个可写字段更新到所输入条件匹配的全部行，包括尚未加载的分页数据

日期时间、枚举、JSON 和其他类型会在可识别时使用专用编辑控件。批量编辑前应确认所选区域和目标字段类型一致。

## SQL 预览与保存

行级关系型数据修改先保存在本地待提交状态。点击保存时，DBX 会展示生成的 `INSERT`、`UPDATE` 和 `DELETE` SQL。

MySQL 按条件批量更新有所不同，因为条件匹配的数据可能并未全部加载到表格中。在批量修改对话框中，可直接使用当前表格筛选，或通过选择字段、运算符和值来设置匹配条件，并用 `AND` 或 `OR` 组合多条规则；自定义 `WHERE` 表达式保留为高级选项。继续前可预览预计影响行数，但它只是执行前快照，实际更新时可能因并发数据变化而不同。DBX 会在危险确认框中展示完整的 `UPDATE ... WHERE ...`，确认后立即执行。数据库按执行时的数据计算匹配范围，DBX 无法为未加载行生成可靠的回滚 SQL。

保存前重点检查：

- `UPDATE` 和 `DELETE` 的主键或条件是否只命中目标行
- 新增行是否遗漏必填字段
- `NULL`、空字符串、默认值和自动生成值是否符合预期
- 批量操作是否包含了未注意到的行
- 当前连接和数据库是否正确

生产环境保护启用后，保存仍会进入统一的生产写入确认。完整规则见 [生产环境与写入安全](/cn/docs/production-safety)。

<Callout type="warn">SQL 预览是最后检查点，不是事务审批系统。重要生产变更仍应使用最小权限账号、备份和团队变更流程。</Callout>

## 单元格详情与复杂值预览

单元格详情用于表格内不适合直接显示或编辑的值：

- 长文本、多行文本、SQL 和带语法高亮的 JSON
- JSON 格式化、压缩和路径查看
- 二进制值的十六进制与 ASCII 查看
- 图片 URL、图片二进制或可识别图像数据预览
- 日期、时间和带时区值的专用编辑与格式化
- 几何/空间数据的文本、坐标和地图预览，包括可识别的 SRID
- 被截断值、只读值和字段元数据说明

详情面板中的格式化和预览通常只影响显示；真正修改值时，仍会进入待保存状态并生成 SQL。

## 转置视图

转置视图交换行列，适合：

- 单行但字段很多的记录
- 并排查看字段类型、注释、默认值和可空状态
- 对比少量记录的大字段

转置视图支持选择、复制、详情、编辑和导航。排序与数据库侧过滤仍以原始结果方向为准。

## 列格式化器

列格式化器只改变显示，不修改底层数据。常见选项包括：

- 全局或列级日期/时间格式
- JSON 路径提取
- 值掩码
- 自定义显示模板
- 数字、布尔值和数据库类型对应的显示方式

如果需要恢复原始值，清除当前列格式化器即可。

## 选择、复制与导航

表格支持单元格、矩形区域、整行和多行选择。选择后可以：

- 查看数量、求和等选择摘要（适用于可计算值）
- 复制为 TSV、CSV、JSON、Markdown、SQL `INSERT` 或 `UPDATE`
- 复制单元格、选中区域、整行或带表头结果
- 选择列名引用方式，包括数据库标识符引号
- 使用字段注释作为复制列名（适合面向业务的表格）
- 为多行生成单条批量 `INSERT`，或逐行 `INSERT`
- 排除主键后复制为新记录模板

当字段存在可识别外键关系时，可以从单元格跳转到被引用记录。这个入口依赖元数据和目标连接权限。

## 导出

| 格式 | 适合场景 |
| --- | --- |
| CSV / TSV | 电子表格、脚本和文本交换 |
| JSON | API 调试和程序处理 |
| Markdown | Issue、PR、文档和聊天 |
| XLSX | Excel 交付；超出单工作表上限时会拆分工作表 |
| SQL | 复用选中数据生成 `INSERT` 或 `UPDATE` |

导出查询结果时，DBX 会按当前结果和选择范围处理。导出前确认当前页面、筛选、排序和选择区域，避免把“当前可见数据”误认为完整表。

## 自动刷新、分页与大结果集

- 打开表时的分页大小可以配置并持久化
- 自动刷新适合监控变化较快的小结果集
- 查询执行结果可以保留多个运行记录或固定需要对比的结果
- 大结果集只在可视区域渲染，但数据库查询和传输成本仍取决于实际返回行数
- 排序、过滤或自动刷新会重新获取数据，未保存编辑可能阻止或影响刷新

<Callout type="warn">自动刷新不适合正在编辑的数据，也不能替代监控系统。大表请先缩小查询范围，再提高刷新频率。</Callout>

## 常见问题

| 现象 | 检查项 |
| --- | --- |
| 结果只能查看不能编辑 | 是否为 Join/聚合；是否有主键；连接是否只读；驱动是否支持编辑 |
| 过滤后行数没有减少 | 使用的是客户端搜索/过滤，而不是数据库侧 `WHERE` |
| 排序只影响当前页 | 当前使用了本地排序；需要跨页稳定排序时改用 `ORDER BY` |
| 粘贴后列错位 | 剪贴板列数、当前选中起始列、隐藏列和字段顺序 |
| 图片或空间数据没有预览 | 值格式、MIME/二进制类型、几何编码或 SRID 无法识别 |
| 导出数量和预期不同 | 当前页、选择区域、客户端过滤和数据库查询范围 |

<Cards>
  <Card title="编写查询" href="/cn/docs/query-editor">
    使用补全、执行目标、多结果和查询历史生成数据表格。
  </Card>
  <Card title="批量导入" href="/cn/docs/table-import">
    从 CSV、TSV、JSON 或 Excel 导入大量数据。
  </Card>
  <Card title="跨库传输" href="/cn/docs/data-transfer">
    在不同连接或数据库引擎之间复制表数据。
  </Card>
  <Card title="保护生产写入" href="/cn/docs/production-safety">
    配置只读连接、生产确认和 MCP 权限。
  </Card>
</Cards>