tencent cloud

大数据智能体工作台 DataBuddy

文档大数据智能体工作台 DataBuddy数据工程Workflow配置任务For Each 循环任务

For Each 循环任务

下载
聚焦模式
字号
最后更新时间： 2026-10-09 16:23:56
For Each 循环任务用于按数据集（数组或对象数组）循环执行内部任务，常用于按分区并行处理、多库多表同步、大规模批处理等场景。

概述

For Each 节点由 外部循环节点 和 内部循环节点 组成：
外部节点 ：定义循环参数与并发数，决定循环次数与并行度。
内部节点 ：实际执行的任务，每次循环按不同的输入参数执行一次。
典型应用场景：
场景
描述
按分区并行处理
上游查询出多个日期分区，并行启动多个补数据任务。
多库多表同步
从元数据库读取表清单，动态生成多个同步任务。
大规模模型推理
将海量数据切分为多个 Batch，并行启动多个推理节点。
通用配置（任务名称、上游依赖、运行条件、参数、监控指标、告警、失败与超时策略）请参考 任务通用配置。

前提条件

已是工作流所有者或具备「管理」权限。
已准备好循环参数（数组、对象数组）或可从上游任务的输出引用。

操作步骤

步骤 1：创建 For Each 节点

1. 在工作流画布单击 + 添加任务 。
2. 任务类型选择 For Each 。

步骤 2：配置外部 For Each 节点

参数
说明
是否必填
任务名称
同工作流内唯一。
是
任务类型
For Each（不可改）。
是
循环参数
循环依赖的数组或对象数组。最长 5000 字符。
是
最大并发数
同时运行的循环次数，1–100 之间正整数。
否（默认 1）

循环参数支持的来源

来源
写法
静态数组
["Beijing", "Shanghai", "Guangzhou"]
静态对象数组
[{"db": "inventory", "region": "shanghai"}, {"db": "orders", "region": "beijing"}]
上游 Notebook
{{tasks.<name>.values.<key>}}（上游通过 dlcutils.jobs.taskValues.set 设置）
上游 SQL
{{tasks.<name>.output.rows}}

上游依赖与运行条件

监控指标、告警

参考 工作流与任务的告警。For Each 任务支持运行时长、等待时长、完成时间监控。

步骤 3：添加内部循环节点

1. 配置完外部节点后单击 添加循环节点 。
2. 进入内部循环节点的配置面板。
3. 选择内部任务类型：Notebook / Python File / SQL / 离线数据接入、嵌套工作流、数据质量任务 。
4. 内部节点的配置项与对应任务类型一致，参数中可使用循环变量。

循环变量（仅在内部节点使用）

变量
说明
示例
{{loopDataArray}}
整个循环参数数组，每次循环都返回完整数据。
[{...}, {...}]
{{loopDataCurrent}}
本次循环对应的元素。
{"db": "inventory", "region": "shanghai"}
{{loopDataCurrent.<key>}}
本次循环元素中指定 key 的值。
shanghai
{{loopTimes}}
当前是第几次循环（从 1 开始）。
1
如内部节点配置参数时未引用循环变量，参数下方提示：
您可以通过配置参数值为 {{loopDataCurrent}} 获取每次迭代的输入数据。

步骤 4：保存

单击 创建任务 或 保存任务 。保存后画布上 For Each 节点呈双层框结构：
外框 ：For Each 节点本身。
内框 ：内部循环节点。

画布交互

操作
说明
单击外框
选中 For Each 节点并打开外部配置面板。
单击内框
选中内部循环节点并打开其配置面板。
拖拽外框
整体移动 For Each 节点（含内部节点）。
与其他节点连线
仅外框可连线，内部循环节点不能与外部节点直接连接。

运行行为

整体状态

场景
状态
所有循环成功
For Each 节点状态：成功
部分循环失败
For Each 节点状态：失败（共 N 次循环，X 次失败）
至少一次循环正在运行
状态：运行中（共 N 次循环，X 次失败）
循环参数为空
状态：成功；运行详情提示「无循环执行」。
循环参数格式不正确
状态：失败；运行详情提示「输入字段格式不正确。循环参数必须是 JSON 格式的基础类型数组或对象数组。」

查看循环执行详情

运行结束后，单击 For Each 节点进入运行详情页，可以：
1. 查看循环执行列表 ：每次循环独立一行，展示循环次数、运行状态、运行时长、参数值等信息。
2. 筛选失败循环 ：勾选「仅展示失败循环」快速定位失败项。
3. 跳转到单次循环详情 ：单击某次循环的运行 ID，进入内部节点运行详情页，查看具体的执行日志和参数。
4. 查看循环配置 ：右侧信息栏展示循环参数原始值和最大并发数。
说明：
重跑策略配置在内部循环节点上，重跑时仅重跑该次循环中失败的内部节点。

使用限制

For Each 仅支持配置 一个 内部循环节点；如需多步骤，请将多步骤封装为嵌套工作流后引用。
内部循环节点不能与外部其他任务连线。
循环参数（常量）最长 5000 字符；上游传递的引用值（变量）最大 48 KB，超出后任务运行失败。
最大循环次数由循环参数的数组长度决定，无独立上限配置。
单 For Each 最大并发数 100。
循环中有任意一次失败，For Each 节点整体状态为失败。

常见问题

Q1：循环参数从 SQL 任务的 output.rows 引用，循环行为是什么？ SQL 输出的每一行作为一次循环。例如：
{{tasks.test_sql_up.output.rows}}
返回 [{"id": 1, "name": "alice"}, {"id": 2, "name": "bob"}]，则会执行 2 次循环。{{loopDataCurrent.name}} 分别为 alice 和 bob。
Q2：某次循环失败了如何重跑？ 重跑策略配置在内部循环节点上。重跑时只会重跑该次循环中失败的内部节点，不会重跑已成功的循环。
Q3：循环参数是空数组 [] 时会发生什么？ For Each 节点视为「无循环执行」，状态置为成功；下游任务按运行条件继续执行。
Q4：循环参数格式校验在何时？ 在运行时校验。配置时不强制校验，建议保存后通过调试运行验证格式合法性。

相关文档

参数传递
系统内置参数
嵌套工作流
上一篇: IF ELSE 条件任务下一篇: 嵌套工作流任务

帮助和支持

本页内容是否解决了您的问题？

填写满意度调查问卷，共创更好文档体验。

文档反馈

搜索
    请输入关键词搜索文档