表数据导入

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

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

两种目标方式

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

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

支持的文件

格式	说明
CSV	默认逗号分隔，也可以调整标题行、数据范围和编码
TSV	使用制表符分隔
分隔文本	`.txt` 等文本文件，可自定义分隔符
JSON	支持单个对象、对象数组或数组行；可以指定对象或数组结构
Excel	支持 `.xlsx`、`.xlsm` 和 `.xls`，可选择工作表

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

导入向导

选择文件和目标方式

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

调整解析选项

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

检查字段映射

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

复核执行计划

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

执行并检查结果

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

解析选项

文本编码

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

行范围

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

值处理

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

字段映射和建表

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

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

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

导入模式和批次

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

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

数据库覆盖范围

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

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

失败和取消

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