# 表数据导入

> 通过向导将 CSV、TSV、文本、JSON、Excel、SQL 或 DuckDB Parquet 数据导入现有表，或按文件批量创建新表。

Source: https://dbxio.com/cn/docs/table-import

Language: zh-CN

Relative links resolve against https://dbxio.com/cn/docs/table-import.



表数据导入用于把文件数据写入数据库表。DBX 会先解析和预览文件，再让你确认解析选项、目标表、字段映射和执行方式，而不是选中文件后立即写入。

MongoDB Collection 不走这条关系型导入流程。请在 Collection 文档页使用 CSV/JSON 导入，参见 [MongoDB 工作区](/cn/docs/mongodb)。

导入会真实写入数据库。连接的只读保护会阻止导入，但数据库权限仍是最终边界。生产环境使用前请确认目标连接、目标表和备份方案。

## 两种目标方式

| 目标方式  | 行为                                 | 适合场景                    |
| ----- | ---------------------------------- | ----------------------- |
| 导入现有表 | 读取目标字段并建立源字段映射，可选择追加或清空后导入         | 数据补录、测试数据恢复、批量更新样例数据    |
| 创建新表  | 根据预览数据推断字段类型，你可以修改表名、字段名和类型后创建表并导入 | 从文件快速建表、迁移表格数据、一次导入多个文件 |

创建新表时可以一次选择多个文件。Excel 文件会按工作表拆成独立任务；DBX 为每个文件或工作表生成一个建议表名，并要求最终表名唯一。批量任务按顺序执行，每个任务保留自己的预览、映射和类型设置。

## 支持的文件

| 格式      | 说明                                                     |
| ------- | ------------------------------------------------------ |
| CSV     | 默认逗号分隔，也可以调整标题行、数据范围和编码                                |
| TSV     | 使用制表符分隔                                                |
| 分隔文本    | `.txt` 等文本文件，可自定义分隔符                                   |
| JSON    | 支持单个对象、对象数组或数组行；可以指定对象或数组结构                            |
| Excel   | 支持 `.xlsx`、`.xlsm` 和 `.xls`，可选择工作表                     |
| SQL     | 包含字面量 `INSERT INTO ... VALUES` 语句的 `.sql` 脚本，每个文件对应一张表 |
| Parquet | `.parquet` 文件，仅在目标连接为 DuckDB 时提供                       |

SQL 导入只接受字面量 `INSERT INTO ... VALUES` 行；表达式、`REPLACE`、`INSERT IGNORE`、`INSERT ... SELECT` 等无法无损改写的内容会被拒绝，以保留数据和语句语义。

SQL 导入按分块流式读取脚本，不把整个文件读进内存，因此没有文件体积上限，超大文件的内存占用也保持平稳。总行数要等脚本扫描到结尾才能确定，所以导入过程中的进度按已读取字节数显示，总行数在导入完成后给出。脚本是边扫描边写入的，中途某条语句失败时，已经写入的行会保留在目标表里；预览步骤会先完整解析一遍脚本，所以格式有问题的脚本通常会在写入前就被拦下。`TO_DATE`、`TO_TIMESTAMP` 等日期函数的值会按第一个参数的文本导入，目标字段必须能解析该格式。

Desktop 直接读取所选本地文件；Docker/Web 会先把浏览器选择的文件上传到服务器临时目录，预览和导入结束后释放临时源文件。

Parquet 导入使用所选 DuckDB 连接的原生 Parquet 读取能力，仍然沿用预览、字段映射、新建表、追加和清空后导入流程；其他数据库类型不会提供 Parquet 导入格式。大型 Parquet 文件按有界批次读取，嵌套值仍受目标字段类型和 DuckDB 类型转换规则约束。

## 导入向导

### 选择文件和目标方式

从表的右键菜单打开导入时，目标表会自动带入；也可以切换到创建新表并选择一个或多个文件。

### 调整解析选项

检查编码、标题行、数据起始行、最后一行、工作表、JSON 结构、空字符串和前后空白处理。

### 检查字段映射

导入现有表时把源字段映射到目标字段；创建新表时确认字段名和推断类型。右侧预览用于核对实际值。

### 复核执行计划

确认目标连接、数据库、Schema、表名、导入模式、映射数量、预计行数和批大小。

### 执行并检查结果

进度页显示读取、写入、完成状态、已导入行数、字节进度、耗时、错误和取消结果。

## 解析选项

### 文本编码

CSV、TSV、分隔文本和 SQL 脚本支持自动检测、UTF-8、GBK、UTF-16 LE 和 UTF-16 BE。自动检测不正确时，请手动选择编码后重新检查预览。

### 行范围

* **标题行**：指定哪一行作为字段名
* **数据起始行**：跳过文件前部的说明或空行
* **最后一行**：只导入指定范围；`0` 表示读取到文件末尾
* **预览行数**：控制映射页显示多少行，不等于最终导入行数

### 值处理

* **去除前后空白**：对文本值执行 trim
* **空字符串按 NULL**：默认开启；关闭后会保留空字符串
* **JSON 结构**：自动识别，也可以强制按对象行或数组行解析
* **工作表**：Excel 可以切换工作表；批量建表会为各工作表建立独立任务

## 字段映射和建表

导入现有表时，DBX 先按字段名精确匹配，再按规范化名称匹配，规范化会忽略大小写、空格、下划线和连字符差异。

* 源字段可以跳过
* 同一个目标字段不能被重复映射
* 至少需要映射一个字段
* 未映射的必填字段必须有默认值、自增/生成规则或允许为空

创建新表时，源字段默认映射为同名目标字段，并根据预览值推荐数据库类型。类型建议只是起点；日期、精度、长文本、JSON、二进制和数据库特有类型应在执行前人工确认。

## 导入模式和批次

| 选项    | 行为                    |
| ----- | --------------------- |
| 追加    | 保留目标表现有数据并插入新行        |
| 清空后导入 | 在支持的路径中先清空目标表，再写入文件数据 |
| 批大小   | 控制每次写入的行数，默认 500      |

创建新表和多文件批量导入固定使用追加模式，因为目标表由当前任务创建。清空后导入具有破坏性；不同数据库的事务和 `TRUNCATE` 语义不同，失败时不能假设所有已执行操作都会自动回滚。

## 数据库覆盖范围

DBX 根据驱动能力清单决定是否显示表导入。原生 SQL 驱动中只有实现了字段读取、建表/写入和类型转换的连接才会启用；Redis、MongoDB、搜索、向量、消息队列和配置中心等专用工作区不使用这个关系型表导入入口。

不要把“能够连接”理解为“支持表导入”。如果菜单未出现，应先检查当前数据库类型、驱动模式和版本，而不是直接假设权限问题。

## 失败和取消

* 解析失败通常发生在编码、分隔符、标题行、JSON 结构或 Excel 工作表设置不正确时
* 写入失败通常来自类型不匹配、非空约束、主键/唯一键冲突、权限或目标表结构
* 取消会阻止后续批次继续写入，但已经提交的批次不保证回滚
* 批量创建新表时，任务按顺序执行；某个任务失败后会保留失败表和错误信息，不应假设前面已完成的表会被撤销

## 相关功能

### [数据传输](/cn/docs/data-transfer)

在两个连接、数据库或引擎之间复制表数据。

### [数据库导出](/cn/docs/database-export)

把结构、数据和对象导出为 SQL 文件。

### [生产环境安全](/cn/docs/production-safety)

了解只读保护、生产保护和数据库权限的边界。