tencent cloud

大数据智能体工作台 DataBuddy

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

参数使用

下载
聚焦模式
字号
最后更新时间： 2026-10-09 16:24:09
本文档介绍如何在 Notebook 和 SQL 任务的代码中引用已配置的参数。参数配置方法参考 参数配置。

概述

参数配置完成后，需要在任务代码中通过特定语法引用参数值。不同任务类型使用不同的引用方式：
任务类型
引用语法
说明
Notebook
dlcutils.widgets.get('param_name')
返回字符串类型的参数值
SQL
${param_name}
运行时直接替换为参数值

在 Notebook 中使用参数

引用语法

value = dlcutils.widgets.get('param_name')
param_name：参数名，对应工作流参数或任务参数中定义的 Key。
返回值为字符串类型。如需数值类型，请在代码中显式转换。

示例

引用工作流参数

假设在工作流参数中定义了：dp_data_dt = {{workflow.start_time.iso_date}}
# 获取参数值
dt = dlcutils.widgets.get('dp_data_dt')
print(dt)
# 输出: 2026-06-11

# 如需数值，显式转换
batch_size = int(dlcutils.widgets.get('batch_size'))

引用任务参数

假设在任务参数中定义了：task_param = {{tasks.upstream_sql.output.first_row.col_a}}
col_a_value = dlcutils.widgets.get('task_param')
print(col_a_value)
# 输出: 上游 SQL 第一行 col_a 的值

调试运行与调度运行的区别

场景
行为
Studio 调试运行
如果参数未定义，弹窗提示用户手动填写参数值。
Workflow 调度运行
系统自动解析参数值，未定义的参数返回空字符串。

在 SQL 中使用参数

引用语法

${param_name}
运行时 ${param_name} 会被直接替换为参数值（字符串替换）。

示例

引用工作流参数

假设在工作流参数中定义了：dp_data_dt = {{workflow.start_time.iso_date}}
SELECT *
FROM my_table
WHERE dt = '${dp_data_dt}';
-- 运行时替换为: WHERE dt = '2026-06-11'

引用任务参数

假设在任务参数中定义了：target_db = my_database
USE ${target_db};
SELECT COUNT(*) FROM orders;
-- 运行时替换为: USE my_database;

多参数组合

SELECT *
FROM ${target_db}.${target_table}
WHERE dt = '${dp_data_dt}'
  AND env = '${env}';

调试运行与调度运行的区别

场景
行为
Studio 调试运行
如果参数未定义，弹窗提示用户手动填写参数值。
Workflow 调度运行
系统自动解析；未定义的参数替换为空字符串，可能导致 SQL 语法错误。

在其他任务类型中使用参数

任务类型
引用语法
离线数据接入
${param_name}
条件节点
${param_name}
For Each 循环
${param_name}
嵌套工作流（Run Job）
${param_name}

最佳实践

1. 在工作流参数中封装系统内置参数

推荐将系统内置参数封装为语义明确的业务参数，代码中只引用业务参数名。
# 工作流参数定义
dp_data_dt = {{workflow.start_time.iso_date}}
-- SQL 中引用（推荐）
WHERE dt = '${dp_data_dt}'

-- 不推荐直接在代码中写内置参数
# Notebook 中引用（推荐）
dt = dlcutils.widgets.get('dp_data_dt')
好处：
参数名语义明确，代码可读性高。
统一在工作流参数中管理，修改一处即可生效。
日志中参数值可追溯。

2. 基于 trigger 时间做偏移计算

常见场景：需要用 trigger 时间 -1 天作为分区时间（T+1 场景）。
注意
系统内置参数 {{workflow.trigger.time.iso_date}} 不支持直接在模板语法中做偏移运算，需要在代码中自行计算。
前置步骤：在工作流参数中定义 trigger 日期
trigger_date = {{workflow.trigger.time.iso_date}}
方式一：在 SQL 中使用函数计算
-- 工作流参数已定义: trigger_date = {{workflow.trigger.time.iso_date}}
-- 使用 DATE_SUB 函数将 trigger 日期减 1 天作为分区时间
SELECT *
FROM dw.user_daily
WHERE dt = DATE_SUB('${trigger_date}', INTERVAL 1 DAY);
-- 如果 trigger 时间为 2026-06-12，则等价于: WHERE dt = '2026-06-11'
如果引擎不支持 DATE_SUB，也可以使用 DATE_ADD：
WHERE dt = DATE_ADD('${trigger_date}', INTERVAL -1 DAY);
方式二：在 Notebook 代码中计算偏移
from datetime import datetime, timedelta

# 获取工作流参数中的 trigger 日期
trigger_date = dlcutils.widgets.get('trigger_date')
# trigger_date 值示例: '2026-06-12'

# 计算前一天作为分区时间
dt_obj = datetime.strptime(trigger_date, '%Y-%m-%d')
partition_date = (dt_obj - timedelta(days=1)).strftime('%Y-%m-%d')
print(partition_date)
# 输出: 2026-06-11

# 后续使用 partition_date 进行数据读写
spark.sql(f"SELECT * FROM dw.user_daily WHERE dt = '{partition_date}'")

3. 注意字符串类型

参数值始终为字符串类型。在 SQL 中引用时需注意是否需要加引号：
-- 字符串类型字段：加引号
WHERE dt = '${dp_data_dt}'

-- 数值类型字段：不加引号（参数值本身是数字字符串）
WHERE id = ${target_id}
在 Notebook 中需显式类型转换：
# 字符串参数
env = dlcutils.widgets.get('env')

# 需要数值时
batch_size = int(dlcutils.widgets.get('batch_size'))
threshold = float(dlcutils.widgets.get('threshold'))

4. 设置合理的默认值

在开发调试阶段，建议为参数提供默认值，避免调试运行时反复手动输入：
import os

# 在 Notebook 中，可以先尝试获取参数，获取不到时使用默认值
dt = dlcutils.widgets.get('dp_data_dt')
if not dt:
    dt = '2026-06-11'  # 开发用默认值

使用限制

参数值始终为字符串类型，代码中如需其他类型请显式转换。
${param_name} 在 SQL 中是纯文本替换，不会自动加引号。
参数名区分大小写：dp_data_dt 和 DP_DATA_DT 是两个不同的参数。
未定义的参数在调度运行时替换为空字符串，可能导致 SQL 语法错误。

常见问题

Q1：Notebook 中 dlcutils.widgets.get 返回 None 或空字符串？
检查参数名是否拼写正确（区分大小写）。
检查是否在工作流参数或任务参数中定义了该参数。
如果是调试运行，检查是否在弹窗中填写了参数值。
Q2：SQL 中 ${param} 没有被替换？
确认参数名拼写正确。
确认该参数已在工作流参数或任务参数中定义。
如果是在 Studio 中调试，需在弹窗中填写参数值。
Q3：如何在 SQL 中引用上游任务的输出？
不能直接在 SQL 代码中使用 {{tasks.<name>.values.<key>}}。正确做法：
1. 在任务参数中定义：my_param = {{tasks.<name>.values.<key>}}
2. 在 SQL 中引用：${my_param}
详见 参数传递。

相关文档

参数配置
参数传递
系统内置参数
上一篇: 参数配置下一篇: 参数传递

帮助和支持

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

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

文档反馈

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