tencent cloud

大数据智能体工作台 DataBuddy

文档大数据智能体工作台 DataBuddy数据工程Workflow参数管理参数传递

参数传递

下载
聚焦模式
字号
最后更新时间： 2026-10-09 16:24:12
参数传递（Parameter Passing）允许下游任务引用上游任务的输出，实现任务之间的数据流转。目前支持 Notebook 和 SQL 任务之间的参数传递。

概述

DataBuddy 中的参数传递有三种典型场景：
场景
上游
下游
引用方式
Notebook → Notebook
Notebook
Notebook
dlcutils.jobs.taskValues.set/get
Notebook → SQL
Notebook
SQL
{{tasks.<name>.values.<key>}} 在任务参数中引用
SQL → Notebook
SQL
Notebook
{{tasks.<name>.output.rows / first_row / first_row.<col>}} 在任务参数中引用

前提条件

上游任务已在工作流中创建并配置了输出。
下游任务已配置上游依赖。否则下游运行时会报错「无法解析引用」。

操作场景

场景 1：Notebook 任务 → Notebook 任务

上游 Notebook 设置参数

my_value = "example_value"
dlcutils.jobs.taskValues.set(key='my_value', value=my_value)

下游 Notebook 获取参数

下游 Notebook 任务需要在工作流中将上游设为依赖。然后：
value = dlcutils.jobs.taskValues.get(
    taskKey='upstream_task_name',
    key='my_value',
    debugValue='debugValue'
)
print(value)
# 在 Studio 调试运行时输出 debugValue
# 在 Workflow 调度运行时输出 example_value
提示
dlcutils.jobs.taskValues.get 仅在 Workflow 调度运行场景下能取到上游 set 的值；Studio 调试运行返回 debugValue。

场景 2：Notebook → SQL 任务

上游 Notebook 设置参数

dlcutils.jobs.taskValues.set(key='favorite_food', value='apple')

下游 SQL 任务参数配置

在下游 SQL 任务的参数面板配置：
task_param = {{tasks.<上游 Notebook 任务名>.values.favorite_food}}

下游 SQL 中使用参数

SELECT '${task_param}' AS food;
-- 结果: apple

场景 3：SQL → Notebook 任务

上游 SQL 任务

SELECT 1 AS col_a, 2 AS col_b, 3 AS col_c
UNION
SELECT 4, 5, 6
UNION
SELECT 7, 8, 9;

下游任务参数配置

下游任务参数面板可以引用三种粒度：
引用
含义
示例返回
{{tasks.<name>.output.rows}}
全部行（JSON 数组）
[{"col_a":1,"col_b":2,"col_c":3}, ...]
{{tasks.<name>.output.first_row}}
第一行（JSON 对象）
{"col_a":1,"col_b":2,"col_c":3}
{{tasks.<name>.output.first_row.<col>}}
第一行指定列
1
提示
SQL 输出的限制：最多 1000 行，最大 48 KB。SQL 文件中存在多个 SELECT 语句时，仅第一个 SELECT 的结果作为 output。

下游 Notebook 中获取

param_value = dlcutils.widgets.get('task_param')
print(param_value)
# [{"col_a":1,"col_b":2,"col_c":3}, ...]

场景 4：For Each 中循环参数传递

For Each 节点的循环参数支持引用上游任务输出：
{{tasks.<上游 SQL>.output.rows}}
{{tasks.<上游 Notebook>.values.<key>}}

运行时校验

上游未运行时

如果只重跑或运行下游任务，没有同时选中上游任务 ，会发生：
阶段
行为
调度判断
直接失败。
错误信息
执行失败，失败原因展示：无法解析引用：由于任务"upstream_name"未在运行范围内，因此无法访问其输出。
错误码
获取上游传递参数失败。

重跑场景

重跑范围
行为
仅下游
使用上次成功运行结果中的参数。
包含上游
上游重新运行后，下游使用最新结果。

使用限制

dlcutils.jobs.taskValues 仅在 Notebook 任务中使用；SQL 任务通过 output.rows 输出。
SQL 任务的 output.rows 最多 1000 行 / 48 KB；超出部分被截断。
参数引用的上游必须是 直接或间接的上游 ，不能跨链路引用同级或下游任务。
不支持跨工作流参数传递，参数传递仅限于同一工作流内的任务。
单参数取值长度 ≤ 2048 字符；上游传递的引用值最大 48 KB（针对 SQL output）或 10 KB（针对 job parameters）。

常见问题

Q1：跨工作流能传递参数吗？ 不支持。参数传递仅限于同一工作流内的上下游任务之间。跨工作流（包括嵌套工作流/Run Job 场景）暂不支持参数传递。
Q2：上游 Notebook 中 dlcutils.jobs.taskValues.set 设置了参数，但下游报错获取不到？
检查上游是否在 Workflow 中而不是 Studio 中运行。Studio 调试时不会写入 taskValues。
检查下游是否将上游配置为依赖。
检查 dlcutils.jobs.taskValues.set 中 key 与下游引用的 key 大小写一致。
Q3：如何让上游 SQL 输出多行数据被下游 For Each 循环使用？ 配置 For Each 节点的「循环参数」为 {{tasks.<上游 SQL>.output.rows}}。SQL 任务输出的每一行作为一次循环。详见 For Each 循环任务。

相关文档

参数配置
参数使用
系统内置参数
嵌套工作流
For Each 循环任务
上一篇: 参数使用下一篇: 系统内置参数

帮助和支持

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

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

文档反馈

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