概述
文件到表同步将半结构化文件（FTP / SFTP / COS / HDFS / REST API 等）按解析规则读取并写入 DataBuddy Catalog 下的目标表。本文介绍该链路的特有配置，通用步骤参见 批量创建单表同步任务。
适用场景
周期性接入业务伙伴上传到 FTP / SFTP / COS 的批量文件，落入数据湖仓供下游分析。
接入第三方 SaaS 系统通过 REST API 提供的数据。
增量同步对象存储中按日期分区的文件。
前提条件
在开始本操作前，请确保满足以下条件：
已开通 DataBuddy 服务并完成空间初始化。
当前账号在目标 Workspace 中拥有 数据接入相关角色 （详见 成员与权限管理）。
已创建用于数据接入的计算资源（数据接入型）。
已创建并测试通过来源端数据源连接（详见 添加数据源连接）。
目标 Catalog 与 Schema 已规划好；如目标表不存在，可由本任务一键建表（需要建表权限）。
使用限制
限制项 | 说明 |
来源端类型 | 半结构化数据源（FTP / SFTP / COS / HDFS / REST API 等） |
目标端类型 | DataBuddy Catalog 下的表（Iceberg 原生表） |
读取方式 | |
文件路径 | 路径下无文件或仅有空文件时任务正常运行成功，但目标端无新增数据 |
字段映射 | 来源端不读取字段元数据，需要用户手动添加字段并指定类型 |
操作步骤
步骤 1：进入任务创建页、填写基础信息
步骤 2：配置来源端
按所选数据源类型，来源端配置项略有差异。
通用字段（FTP / SFTP / COS / HDFS）
参数 | 说明 | 是否必填 |
数据源类型 | 选择来源数据源类型 | 是 |
源连接 | 选择已注册的数据源连接 | 是 |
文件路径 | 文件或文件夹路径；点击文件夹图标可弹出路径选择器逐层下钻；支持插入参数与正则； | 是 |
读取方式 | 是 | |
文件格式 | 数据同步模式下选择 Text/CSV/JSON/ORC/Parquet | 是 |
格式设置 | 按文件类型展示对应字段； | 视文件类型 |
高级设置 | 数据源专属扩展参数 | 否 |
REST API
参数 | 说明 | 是否必填 |
数据源类型 | REST API | 是 |
数据源连接 | 选择已注册的 API 数据源 | 是 |
读取方式 | 解析数据 ：解析结构化数据内容，按字段关系进行数据内容映射与同步; 原始文件 ：不做内容解析传输整个文件，可应用于非结构化数据同步 | 是 |
请求方式 | GET / POST | 是 |
数据路径 | 接口返回中数据所在 JSON 路径（如 data.list） | 否 |
返回结构 | 单条 JSON / 数组 JSON | 是 |
请求 Header | 自定义请求头 | 否 |
请求参数 | GET 查询参数或 POST 请求体参数 | 否 |
第一行作为字段 | 当返回为表格类结构时是否将首行作为字段名 | 否 |
高级设置 | 请求方式 ：单次请求 / 多次请求；参数 ：分页参数等 | 否 |
步骤 3：解析配置（按文件类型）
文件类型 | 关键配置 |
Text | 列分隔符（自定义 / ; / | / Tab）、行分隔符（自定义 / 回车 / 断行）、第一行作为字段行、转义字符（默认 \\） |
CSV | 列分隔符（自定义 / , / ; / Tab）、转义符（" / \\）、第一行作为字段名、行跨行 |
JSON | 将时间文本转换为时间类型、允许使用单引号、过滤注释、行跨行 当存在 JSON 嵌套时，嵌套的值会被解析为一个文本对象（不会自动展开为多列）。 |
ORC / Parquet | 无需额外配置（自描述格式） |
步骤 4：配置目标端
目标 Catalog / Schema / Table。
写入模式：append / overwrite / upsert。
步骤 5：配置字段映射
链路 | 来源端字段映射 | 目标端字段映射 |
文件（解析） → 表 | 可设置（需手动添加字段） | 可设置 |
文件类型的来源端不读取字段元数据 ，需要用户手动添加字段：
1. 点击 添加字段 ，输入字段索引值，如输入 0，表示读取出来的第一个元素，注意是从 0 开始检索的。
2. 选择字段类型（支持 STRING / INT / BIGINT / FLOAT / DOUBLE / DECIMAL / DATE / TIMESTAMP / BOOLEAN 等）。
3. 与目标端字段建立映射。
操作支持：清除、置顶已映射、刷新字段。
步骤 6：运行设置、调试、保存、发布
验证结果
任务保存并调试运行后，您可以通过以下方式确认：
1. 在数据接入任务列表中可以看到刚创建的任务。
2. 调试运行成功后，目标 Catalog 下对应表已包含解析后的数据；可在 数据目录 或 SQL 探索中查询验证。
3. 如需更细粒度的字段类型校验，可在 SQL 探索中运行
DESCRIBE 或简单查询观察实际写入字段。常见问题
Q：上传的 CSV 文件包含表头，但映射结果将表头当作了数据行？
A：来源端的 CSV / TXT 解析配置中需勾选 第一行作为字段名 。
Q：JSON 文件含嵌套对象，如何展开为多列？
A：当前 JSON 嵌套字段会整体解析为文本对象，不自动展开。如需展开，建议在 SQL 任务中使用
get_json_object / from_json 等函数后处理。Q：XML 行标签自动推断错误，如何手动指定？
A：在解析设置中，行标签字段输入正确的行标签名即可。例如
<root><record>...</record></root> 中行标签应为 record。Q：路径下没有文件，任务还会运行吗？
A：会，任务运行成功但目标端无新增数据 。
相关文档
本地上传到表（一次性手动上传场景）
