# 数据导入

导入任务按数据形态提供非结构化、结构化文件和结构化数据库三条流程：非结构化文件写入卷，结构化文件和数据库对象写入表。先选择数据形态，再选择对应的数据来源和目标对象。

| 导入类型 | 数据来源 | 写入 Catalog 的对象 |
| --- | --- | --- |
| 非结构化 | 本地文件，或 OSS、S3、HDFS 连接器中的文件 | 卷 |
| 结构化文件 | 本地 `CSV`、`XLS`、`XLSX`，或 OSS、S3、HDFS 连接器中的同类文件 | 表 |
| 结构化数据库 | 已启用且可用的数据库连接器中的表或集合 | 表 |

## 创建非结构化导入任务

非结构化导入适用于文档、图片、音视频等文件。文件会写入 Catalog 的卷。

1. 进入 **数据连接 > 导入任务**，选择 **非结构化**。
2. 选择 **连接器数据源** 或 **本地上传**。
3. 如果使用连接器，选择一个用途包含 **导入** 的 OSS、S3 或 HDFS 连接器。
4. 选择 Catalog 中的目标卷。没有合适的卷时，可在选择器中创建。
5. 配置文件处理规则。
6. 选择要导入的文件，或上传本地文件或文件夹。
7. 点击 **创建并开始导入**。

### 配置文件处理规则

| 配置项 | 说明 |
| --- | --- |
| 导入周期 | 使用连接器时，可以选择一次性或周期导入；本地上传为一次性操作。 |
| 解压策略 | 当前可选 **忽略目录结构**。保留目录结构的选项当前不可用。 |
| 去重规则 | 可按文件名、MD5 或两者判断重复文件；检测到重复文件后可跳过或覆盖。 |
| 处理范围 | 按文件类型和路径正则筛选需要处理的文件。文件类型默认全选，可按文档、音频、视频、图片、网页、邮件、CAD 等类别调整。 |

使用连接器并选择周期导入时，只能选择文件夹，不能单独选择文件。

本地上传最多选择 20 个文件，每个文件不能超过 200 MB。可以使用 **选择文件夹** 上传目录中的文件。

## 创建结构化文件导入任务

结构化文件导入适用于 `CSV`、`XLS` 和 `XLSX` 文件。每次创建任务选择一个源文件，解析后写入一个或多个 Catalog 表。

1. 进入 **数据连接 > 导入任务**，选择 **结构化**，并保持 **文件** 导入类型。
2. 选择 **连接器数据源** 或 **本地上传**。
3. 选择或上传一个 `CSV`、`XLS` 或 `XLSX` 文件。
4. 在 **导入目标** 中，为文件或选中的 Excel 工作表选择 **已有表** 或 **新建表**。
5. 确认文件解析和列配置。
6. 点击 **创建并开始导入**。

本地结构化文件一次只能上传一个文件，单个文件不能超过 200 MB。

### 配置文件解析

选择文件后，系统会显示预览和解析配置。

- 对 `CSV` 文件，可配置列分隔符、文本定界符和转义；
- 可设置是否使用列名、列名所在行和开始导入的行；
- 对 Excel 文件，可选择一个或多个工作表。每个选中的工作表分别设置目标表；
- 写入新表时，确认表名、描述、列名、数据类型、主键、默认值和列描述；
- 写入已有表时，选择按顺序或按名称映射源列和目标列，并选择初次导入时追加数据或清空已有数据后追加；
- 如果目标表存在主键，可选择遇到冲突时报错、跳过或替换冲突行。

## 创建结构化数据库导入任务

结构化数据库导入将外部数据库中的表或 MongoDB 集合写入 Catalog 表。只有当前工作区启用该入口，并且存在可用连接器时，才能选择 **数据库**。如果 **数据库** 按钮不可选，当前工作区未启用结构化数据库导入。

1. 进入 **数据连接 > 导入任务**，选择 **结构化**，再选择 **数据库**。
2. 选择连接器、数据库，以及页面要求的 Schema。
3. 选择源表或集合。
4. 选择已有目标表，或选择目标数据库并新建表。
5. 检查源字段、目标字段和数据类型映射。
6. 选择一次导入或周期导入。
7. 周期导入时，选择增量同步或全量覆盖，并补全调度配置。
8. 设置初次导入规则和主键冲突处理方式。
9. 点击 **创建并开始导入**。

选择新建目标表时，不需要清空已有数据。选择已有目标表后，才可以选择 **清空已有数据后追加**。只有保留至少一个主键映射时，才能选择替换冲突行。

## 查看和管理导入任务

进入 **数据连接 > 导入任务**。列表会显示任务类型、来源、目标、运行方式、状态、失败原因和时间信息。打开任务 ID 可查看任务详情。

| 操作 | 适用情况 |
| --- | --- |
| 暂停 | 运行中的任务。 |
| 恢复 | 已暂停的任务。 |
| 编辑 | 已暂停且页面允许编辑的任务。 |
| 重试失败文件 | 任务详情显示失败文件时。点击 **重试**，选择失败文件后确认。 |
| 删除 | 非运行中的任务。 |

周期结构化数据库导入任务支持暂停和恢复；一次导入的结构化数据库任务不显示这两个控制。

创建成功只表示任务已提交。请在任务列表或详情中查看状态；任务进入 **已完成** 后，再到 Catalog 确认目标表或卷中的数据。

## 导入失败时检查

| 现象 | 下一步 |
| --- | --- |
| 连接或认证失败 | 打开所用[连接器](connectors.md)，检查参数后重新执行 **测试连接**。 |
| 找不到源文件、源表或集合 | 检查连接器、路径、数据库、Schema 和对象选择。 |
| 文件解析或列映射失败 | 查看任务详情中的失败原因，检查文件格式、解析设置和目标列映射。 |
| 目标写入失败 | 检查目标卷或表的权限、表名和初次导入规则。 |