ETL：源、转换、目标与增量

适用版本：1.0.0。任务 → 新增/编辑 → 插件 ETL。

入口与准备

使用 ADMIN 创建、配置和保存任务；ADMIN 或 OPERATOR 可以执行已发布定义，详细日志和输入输出变量由 ADMIN 查看。资源必须启用并可被执行节点访问。任务公共超时、重试和版本规则见任务，角色动作见权限矩阵。

按配置目标定位

来源 / 类型与资源 · 来源 / 数据库 · 来源 / 文件与格式 · 来源 / 消息队列 · 目标 / 数据库写入 · 目标 / 文件输出 · 数据库增量 · 文件增量 · 消息摄入 · 执行限制 · 映射 · 重试

字段说明

“默认值”指 1.0.0 新建表单的初始值；空表示尚未填写，不表示必填项可以省略。显示条件决定当前分支中是否出现字段。“条件必填”只在对应分支启用时要求填写。转换/校验规则的示例值用于解释填写方式，不能当作运行时缺省值。

来源 / 类型与资源

• 来源类型：选择 DATABASE、FILE、KAFKA 或 RABBITMQ，并决定后续来源字段。
• 资源：引用与来源类型匹配的已配置资源，连接和认证来自该资源。

来源 / 数据库

• 查询 SQL：定义数据库查询或文件暂存后的 SQL 查询；值参数使用命名绑定。
• 查询提取批量：范围 1–100000
• 查询参数（JSON）：提供命名 SQL 参数的 JSON 值；单一变量占位符可保留值类型。
• 前置 SQL 数组（JSON）：在来源数据库读取前依次执行准备 SQL。

来源 / 文件与格式

• 文件路径：在文件资源范围内指定读取路径。
• 文件格式：选择文件解析格式，并决定可用读取方式。
• 读取方式：直接读取文件记录，或先暂存后执行 SQL。
• 字符编码：指定文本文件解码字符集。
• 分隔符：指定 CSV/TXT 字段分隔符。
• 引号：指定带分隔符等特殊内容的字段引号。
• 转义符：指定引号内特殊字符的转义字符。
• 首行为表头：控制是否从表头取得字段名称。
• 跳过行数：范围 0–2147483647
• 表头行号：范围 0–2147483647
• 起始行号：范围 0–2147483647
• 工作表名称：按名称选择单个 Excel 工作表。
• 工作表序号：范围 0–2147483647
• 正则读取模式：选择逐行匹配或按块读取后匹配。
• 内容正则：从文本行或文本块中提取匹配组。
• 块起始正则：标识一个待解析文本块的起始位置。
• 块结束正则：标识一个待解析文本块的结束位置。
• 每块最大行数：范围 1–1000000
• 每块最大字符数：范围 1–67108864
• 正则字段映射（JSON）：将正则匹配组映射为记录字段，可设置未匹配默认值。
• 暂存表名：指定文件 SQL 读取使用的暂存表名称。
• 暂存列名：显式指定暂存列名称；未填写时按文件解析结果取得。
• 多工作表配置（JSON）：为多个 Excel 工作表分别指定工作表选择、表头与暂存表。

来源 / 消息队列

• Topic（主题）：读取消息的 Kafka 主题。
• 消费组：用于保存 Kafka 消费进度的消费组。
• 队列名称：读取消息的 RabbitMQ 队列。
• 首次消费位置：仅在消费组没有已提交位置时选择起始位置。
• 预取数量（条）：范围 1–1000

目标 / 数据库写入

• 目标类型：选择写入数据库或文件；消息来源仅允许数据库目标。
• 资源：引用目标数据库或文件资源。
• Schema（可选）：指定目标表所在的 Schema。
• 目标表：指定写入的目标表。
• 写入方式：选择追加、插入、更新、合并或 SCD2 写入语义。
• 逻辑键：填写用于识别目标记录的目标列名。
• 字段映射方式：选择自动同名映射或手工字段映射。
• 排除来源字段（可选）：在自动映射中排除指定来源字段。
• 事务范围：控制按整次运行或按写入批次提交事务。
• 空值策略：设置来源空值保留或覆盖目标值的默认策略。
• 按列空值策略（JSON）：按目标列覆盖默认空值策略。
• 记录保护（JSON）：按目标记录中的字段和值配置写入保护。
• SCD2 配置（JSON）：配置业务键、变化比较和历史有效期字段。
• 前置 SQL 数组（JSON）：在目标写入前执行准备 SQL；消息和文件增量有额外限制。
• 后置 SQL 数组（JSON）：在目标写入后执行收尾 SQL；消息和文件增量有额外限制。

目标 / 文件输出

• 文件路径：在目标文件资源范围内指定输出路径。
• 字符编码：指定输出文本文件的字符集。
• 分隔符：指定输出文件的字段分隔符。
• 引号：指定输出字段的引号字符。
• 首行为表头：控制输出文件是否包含表头。
• 文件已存在时：目标文件已存在时选择失败、覆盖或跳过。
• 空数据输出：无数据时选择带表头文件、空文件或不创建文件。

数据库增量

• 启用增量：开启基于数据库水位或文件标记的增量处理；不用于消息源。
• 检查点键：标识需要持续复用的增量检查点。
• 标记类型：选择比较数据库水位或文件标记的类型。
• 初始标记：尚无检查点时使用的起始水位。
• 标记字段：来源结果中用于推进数据库检查点的字段。
• 上界查询 SQL：在本次读取前查询稳定的水位上界。
• 同值排序字段：按顺序指定相同水位值下的稳定排序字段。
• 排序初始值（JSON 数组）：提供与同值排序字段一一对应的初始值。
• 允许越过无效记录推进：允许检查点越过被过滤的无效记录，可能使其不再自动重读。

文件增量

• 标记位置：从文件名或相对路径中提取增量标记。
• 匹配方式：选择模板或正则表达式匹配标记。
• 匹配表达式：匹配文件并提取标记；模板使用 {mark}。
• 源标记格式（可选）：指定日期或时间戳标记在源文件中的格式。
• 解析时区：解析日期时间标记时使用的时区。
• 选择方式：选择严格推进、回看窗口或指定下界。
• 回看范围：配置需要重新考虑的标记回看范围。
• 指定下界：显式设置文件标记选择下界。
• 上界（可选）：可选限制本次处理的文件标记上界。
• 已完成文件内容变更时：已完成文件内容变化时选择失败或重新处理。
• 递归扫描目录：开启后在限制范围内递归查找文件。
• 最大扫描深度：范围 0–32
• 最大扫描条目数：范围 1–100000
• 单次最大文件数：范围 1–10000
• 文件总量上限（字节）：范围 1–107374182400
• 稳定时间（秒）：范围 0–604800
• 完成标识后缀（可选）：仅处理具有对应完成标识文件的源文件。

消息摄入

• 单次消息数（条）：范围 1–10000000
• 接收窗口（秒）：范围 1–3600
• 连续空闲等待（秒）：范围 1–300
• 处理批量（条）：范围 1–1000
• 不满批提交间隔（毫秒）：范围 100–10000
• 单条消息上限（字节）：范围 1024–16777216
• 解压后上限（字节）：范围 1024–67108864
• 累计载荷上限（字节）：范围 1024–107374182400
• 接收缓冲上限（字节）：范围 1024–268435456
• JSON 嵌套深度上限：范围 1–100

执行限制

• 读取批量：范围 1–100000
• 写入批量：范围 1–100000
• 查询超时（秒）：范围 1–86400
• 最大记录数：范围 1–9223372036854775807
• 单文件上限（字节）：范围 1–9223372036854775807
• 展开文本字符上限：范围 1–9223372036854775807
• Excel 单元格上限：范围 1–9223372036854775807
• 暂存单元格上限：范围 1–9223372036854775807
• 每条记录字段上限：范围 1–10000
• 单字段字符上限：范围 1–16777216
• Excel 工作表上限：范围 1–10000

映射

• 字段映射：技术配置为目标列→来源字段；逻辑键填写目标列。

重试

• 允许非幂等写入重试：显式允许追加写入等非幂等操作重试。

转换 / 字段映射

规则填写示例（请按业务数据修改）：

示例是新增规则时的预填内容，不是运行时缺省；请替换为实际业务字段。

转换 / 默认值

规则填写示例（请按业务数据修改）：

示例是新增规则时的预填内容；按字段需要配置实际默认值。

转换 / 去除首尾空白

规则填写示例（请按业务数据修改）：

转换 / 值替换

规则填写示例（请按业务数据修改）：

转换 / 日期格式转换

规则填写示例（请按业务数据修改）：

转换 / 类型转换

规则填写示例（请按业务数据修改）：

转换 / 数值计算与精度

规则填写示例（请按业务数据修改）：

可选数值留空表示不配置，不填写null。除数不能为0；scale须为-1至1000的整数。

转换 / 表达式

规则填写示例（请按业务数据修改）：

转换 / 数据库查找

规则填写示例（请按业务数据修改）：

选择自己的已启用查询资源并准备lookup_table的code/name列。查询使用:keys。这里的“消息提交批量”实际控制查询键批量（1–2000）；查询超时1–86400秒，二者可留空。

转换 / 去重

规则填写示例（请按业务数据修改）：

校验 / 必填校验

规则填写示例（请按业务数据修改）：

校验 / 正则校验

规则填写示例（请按业务数据修改）：

校验 / 范围校验

规则填写示例（请按业务数据修改）：

min/max至少填写一项；没有上界或下界时省略对应项，不填null。

校验 / 枚举校验

规则填写示例（请按业务数据修改）：

校验 / 条件校验

规则填写示例（请按业务数据修改）：

校验 / SQL 校验

规则填写示例（请按业务数据修改）：

选择自己的已启用查询资源，并准备orders.id。FIELD模式必须填写处理字段，查询必须含:keys；GLOBAL模式不填处理字段。查询批量1–2000、超时1–86400秒；可留空，不填null。

校验 / 外键存在校验

规则填写示例（请按业务数据修改）：

选择自己的已启用查询资源，准备customers.id，并让来源记录包含customer_id。查询必须含:keys。查询批量1–2000、超时1–86400秒；可留空，不填null。

目标高级 / 记录保护

• 保护字段：目标表中用于判定记录是否受保护的列。
• 受保护值列表：该列命中任一列表值时将记录判定为受保护。
• 遇到保护记录时：遇到受保护记录时跳过或使任务失败。

目标高级 / SCD2 历史版本

• 业务键（目标列）：用于识别同一业务实体的目标列。
• 比较字段（目标列）：用于判断业务内容是否变化的目标列；界面要求至少一项。
• 生效时间来源字段：提供新历史版本生效时间的来源记录字段。
• 有效期起始列：存储历史版本生效时间的目标列。
• 有效期结束列：存储历史版本失效时间的目标列。
• 当前版本标记列：可选目标列，用于标记当前和历史版本。
• 当前版本值：写入当前版本标记列的值。
• 历史版本值：写入历史版本标记列的值。
• 时间粒度：选择按天或时间戳比较和保存有效期。

使用边界

• 文件源 SQLITE/MDB 只能 SQL 读取；REGEX 只能 DIRECT；EXCEL 多工作表配置不能与单工作表名称/序号同时配置。
• 数据库增量 SQL 必须有 :etlLastWatermark、:etlUpperWatermark；启用排序字段后绑定 :etlLastTie1 等。必须保持查询排序与水位/同值排序一致。
• 消息源使用 broker 进度，不使用普通增量；只允许 DATABASE 目标，UPSERT/INSERT_ONLY，BATCH 事务；禁止前后 SQL、DEDUPLICATE 和 FILTER 校验策略。
• 文件增量不支持 DEDUPLICATE 和目标前后 SQL；检查点提交与目标副作用存在边界。
• 目标手工映射至少一项，逻辑键为目标列；AUTO 排除字段不能同时出现在自定义映射。
• SCD2 需业务键、比较字段、生效值来源、有效期始末列；当前标记列可选。
• ETL 的消息配置内部格式版本为 2，不等于产品发布版本，产品仍为 1.0.0。
• 在界面中配置SCD2时，比较字段至少填写一项。

表单初始值与兼容补值

下面的后端值仅用于解释导入或旧配置缺少该键时的补值。按教程新建任务时，请明确选择表单值，不能把兼容补值当作推荐配置。

典型配置：三行订单 UPSERT 到独立目标

按下表填写界面，资源名称需替换为自己的已启用资源。这是配置说明，不是可直接导入的 JSON。完整数据准备与执行步骤见本节末尾教程。

先按教程创建两个数据库连接；来源orders为三行、金额600，目标已建同结构空表并保留id主键。

查询 SQL：

SELECT id,amount,updated_at FROM orders ORDER BY id

预期结果： 目标表 3 行、金额总和 600，重复执行不增加行数。

跟做完整教程。保存定义后再手动执行；实例状态与业务结果分别核对。

真实界面

技术字段对照

以下键名用于导入配置、接口或排障。规则中的 [] 表示集合元素；不需要把这些键名填入界面标签。

相关页面

任务与版本 · 参数与表达式 · 场景教程