参数传递（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_cUNIONSELECT 4, 5, 6UNIONSELECT 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 循环任务。
