---
title: 表数据导入
description: 将 CSV、TSV、JSON 或 Excel 文件导入数据库表，并检查列映射和导入模式。
---

表数据导入用于把本地文件写入指定表。它适合一次性导入测试数据、业务数据补录、从表格工具迁移数据等场景。

## 支持的文件

| 格式  | 说明                                                  |
| ----- | ----------------------------------------------------- |
| CSV   | 逗号分隔文本，适合通用数据交换                        |
| TSV   | 制表符分隔文本，适合字段中包含逗号的场景              |
| JSON  | JSON 数组，适合从接口或脚本导出的数据                 |
| Excel | `.xlsx`、`.xlsm` 或 `.xls` 文件；DBX 读取第一个工作表 |

DBX 会在导入前预览前 50 行。CSV/TSV 中的空单元格会按 `NULL` 处理。JSON 可以是单个对象、对象数组或数组行；对象行和数组行混用会被拒绝。

## 导入流程

<Steps>
  <Step>
    ### 选择目标表

    在侧边栏中右键目标表，选择 **导入数据**。

  </Step>
  <Step>
    ### 选择文件

    选择要导入的 CSV、TSV、JSON 或 Excel 文件。

  </Step>
  <Step>
    ### 检查列映射

    DBX 会按列名尝试匹配文件字段和数据库字段。请检查主键、必填字段、日期字段和数值字段。

  </Step>
  <Step>
    ### 选择导入模式

    选择追加或清空后导入。清空模式会先删除目标表已有数据。

  </Step>
  <Step>
    ### 执行并检查结果

    导入完成后检查成功行数、失败原因和目标表数据。

  </Step>
</Steps>

## 导入模式

| 模式       | 行为                         | 适合场景                 |
| ---------- | ---------------------------- | ------------------------ |
| 追加       | 保留原有数据，继续插入新行   | 补充数据、追加样例数据   |
| 清空后导入 | 先清空目标表，再导入文件内容 | 重建测试表、替换临时数据 |

<Callout type="warn">清空后导入会删除目标表中的现有数据。生产环境使用前请确认备份和影响范围。</Callout>

导入会分批执行。默认批大小为 500 行，进度视图会显示已导入行数、总行数、错误和取消状态。

## 字段映射规则

- 先按字段名精确匹配
- 也会按规范化名称匹配，忽略大小写、空格、下划线和连字符差异
- 源字段可以跳过
- 同一个目标字段不能被重复映射
- 至少需要映射一个字段才能开始导入

## 数据库覆盖范围

表数据导入支持 MySQL、PostgreSQL、SQLite、DuckDB、ClickHouse、SQL Server、Oracle、Doris、StarRocks、Redshift、DM、GaussDB、KingBase、HighGo、Vastbase、GoldenDB 和 Access。

## 导入前检查

- 文件首行是否是列名
- 字符编码是否正确
- 日期、数字、布尔值格式是否符合目标数据库要求
- 非空字段是否都有值
- 唯一索引和主键是否会冲突
- 是否需要先导入父表，再导入带外键的子表

## 常见问题

| 现象           | 可能原因                                         |
| -------------- | ------------------------------------------------ |
| 部分列没有导入 | 文件列名和表字段名不匹配，或列被取消映射         |
| 导入失败       | 非空字段为空、类型不匹配、主键冲突或唯一约束冲突 |
| 中文乱码       | 文件编码和解析方式不一致                         |
| 日期错误       | 文件中的日期格式无法被目标数据库识别             |