概述
表到 Volume 同步将结构化数据源（如 MySQL、PostgreSQL、Oracle、SQL Server 等）的表数据按指定文件格式写入 DataBuddy Volume，常用于将加工后的数据导出为 .ok / .ctl 文件给下游系统消费。本文介绍该链路的特有配置，通用步骤参见 创建单表同步任务。
适用场景
周期性导出加工结果文件给短信、营销、外部系统等下游业务（如 .txt / .csv / .json）。
数据交付：将湖仓数据按约定格式导出到指定 Volume 路径。
文件归档：将业务库数据按时间分区落盘到 Volume，方便长期存储。
前提条件
在开始本操作前，请确保满足以下条件：
已开通 DataBuddy 服务并完成空间初始化。
当前账号在目标 Workspace 中拥有 数据接入相关角色 （详见 成员与权限管理）。
已创建用于数据接入的计算资源（平台集群型）。
已创建并测试通过来源端数据源连接（详见 添加数据源连接）。
目标 Catalog 下已存在 Volume 类型的 Schema，或当前账号有权限创建。
使用限制
限制项 | 说明 |
来源端类型 | |
目标端类型 | DataBuddy Catalog 下的 Volume 类型 Catalog |
字段映射 | 来源端可设置；目标端不可设置（Volume 不感知字段结构） |
文件类型 | 仅支持 txt / csv / json |
.ok 与 .ctl | 不同文件类型支持的标记文件不同 |
操作步骤
步骤 1：进入任务创建页
步骤 2：填写基础信息、来源端
步骤 3：配置目标端
当目标端选择为 Volume 类型 Catalog 时，配置项如下：
参数 | 说明 | 是否必填 | 默认值 |
Catalog | 选择有权限的 Volume 类型 Catalog | 是 | — |
Schema | Catalog 下的 Schema | 是 | — |
Volume | 选择已存在的 Volume；不存在时可在 Catalog 中创建 | 是 | — |
Volume 目录 | 文件写入的 Volume 子路径；可选择、可输入、可插入正则、可插入参数；不建议你把根路径「/」作为子路径 | 是 | — |
文件名称 | 写入的文件名；可输入、可插入正则、可插入参数 | 是 | — |
文件格式 | txt / csv / json；不同类型对应的解析配置不同 | 是 | — |
格式设置 | 是 | — | |
写入模式 | Append / Overwrite / Truncate / NonConflict | 是 | Append |
标记完成文件 | 当文件写入完成后生成.ok 文件 | 是 | 不生成 |
ctl 文件 | 当文件写入完成后生成.ctl 文件 | 视文件类型 | 不生成 |
步骤 4：格式设置
点击「格式设置」弹出弹窗，按所选文件类型配置写入规则：
TXT / CSV
配置项 | 说明 |
压缩格式 | gzip / 无压缩等 |
列分隔符 | 字段分隔符（如 , ; ` |
行分隔符 | 行结束符（如 \\n \\r\\n 自定义） |
编码 | UTF-8 / GBK 等 |
控制转换 | 是否对特殊字符做转义 |
Quote Character | 字符串包裹符（如 " '） |
包含表头 | 是否在第一行记录写入字段名 |
JSON
配置项 | 说明 |
压缩格式 | gzip / 无压缩等 |
编码 | UTF-8 / GBK 等 |
空值转换 | 是否将 null 转换为指定字符串 |
包含表头 | 是否在第一行记录写入字段名 |
步骤 5：字段映射
链路 | 来源端字段映射 | 目标端字段映射 |
结构化数据源 → Volume | 可设置 | 不可设置 |
如果你不希望某个字段被写入 Volume，可以通过删除字段映射行来实现。
添加字段映射行时，字段类型必须为「字段」，否则会报错。
步骤 6：运行设置、调试、保存、发布
文件类型与标记文件支持
文件类型 | .ok 文件 | .ctl 文件 |
Text | 有 | 有 |
CSV | 有 | 有 |
JSON | 有 | 无 |
提示
.ok 文件用于通知下游「数据已写入完成」；.ctl 文件用于记录数据描述（如行数、文件清单）。验证结果
任务保存并调试运行后，您可以通过以下方式确认：
1. 在 数据目录 中进入目标 Volume，看到已写入的文件（如
output_20260101.txt 与 output_20260101.ok）。2. 下载、预览文件内容，确认字段顺序、分隔符、编码与配置一致。
3. 在 离线同步任务运维监控 中查看任务日志确认无错误。
常见问题
Q：目标端 Volume 路径或文件名支持哪些参数？
A：支持系统时间参数（如
${yyyyMMdd}）和工作流调度参数。手动调试运行时如未设置参数值，系统使用默认、缺省值；建议在「运行参数」中提前定义，确保调试可重复。Q：写入模式选择 Overwrite 时，目标 Volume 路径下的旧文件会被删除吗？
A：Overwrite 仅覆盖同名文件，不会删除路径下的其他文件；Append 在同名文件后追加内容（取决于文件类型）；
Q：JSON 文件的「空值转换」如何配置？
A：开启后，所有 NULL 字段会被转换为指定字符串（如空字符串
"" 或字面量 NULL）。关闭时按 JSON 标准输出 null 字面量。Q：是否支持 .parquet / .avro 等列式格式？
A：当前仅支持 TEXT / CSV / JSON 三种格式。
