tencent cloud

大数据智能体工作台 DataBuddy

文档大数据智能体工作台 DataBuddy数据工程Studio SQL 开发参数化实现

参数化实现

下载
聚焦模式
字号
最后更新时间： 2026-10-09 16:22:53
DataBuddy SQL 脚本支持通过参数化实现「同一段 SQL 在不同运行环境取不同值」的需求，例如开发与生产环境使用不同的库表前缀、按调度时间动态过滤数据等。本节聚焦 Studio 中 SQL 脚本的参数化使用，工作流和任务上的参数管理请参考 参数管理。

概述

DataBuddy SQL 中的参数分为以下几类，统一以 ${param_key} 形式引用：
参数类型
定义入口
取值优先级
文件级参数
SQL 文件操作栏的 参数 弹窗
调试运行时使用
任务级参数
Workflow 任务配置
调度运行时优先级最高
工作流级参数
Workflow 通用配置
调度运行时次优先
系统内置参数
DataBuddy 自带
仅在调度运行场景生效
参数优先级（从高到低）：任务 > 工作流 > 文件 。

前提条件

您具备当前 SQL 文件的「编辑」权限。
调度运行场景下，需在 Workflow 中创建 SQL 任务并引用本文件。

操作步骤

步骤 1：在 SQL 中引用参数

在 SQL 中使用 ${param_key} 占位符：
SELECT *
FROM your_catalog.your_schema.orders
WHERE dt = '${dp_data_dt}'
LIMIT 100;

步骤 2：定义文件级参数

1. 单击操作栏 参数 按钮。
2. 在弹窗中单击 + 添加参数 。
3. 填写：
参数名 ：与 SQL 中 ${...} 内的标识符一致，如 dp_data_dt。
参数值 ：调试运行时使用的值，如 2026-06-05。
4. 单击 确定 保存。

步骤 3：调试运行

单击 运行、全部运行 时，系统将文件级参数值替换到 SQL 中执行。
如果 SQL 中引用了未定义的参数，运行时弹窗提示填写。

步骤 4：发布到 Workflow 调度

1. 单击操作栏 快速创建任务 ，选择目标工作流。
2. 进入 Workflow 任务配置，工作流和任务参数会按以下规则识别：
SQL 中已使用的 ${...} 参数会自动识别为任务参数候选项。
您可在工作流参数、任务参数中给出实际取值（自定义值或引用系统内置参数）。
3. 调度运行时取值规则：任务参数 > 工作流参数 > 文件参数 。

步骤 5：使用系统内置参数

可将系统内置参数赋给自定义参数，再在 SQL 中引用：
1. 在工作流配置中定义参数 dp_data_dt = {{workflow.start_time.day}}。
2. SQL 中使用 WHERE dt = '${dp_data_dt}'。
3. 调度运行时 ${dp_data_dt} 自动替换为工作流的实例数据时间。
常用系统内置参数：
参数
含义
{{workflow.id}}
工作流 ID
{{workflow.name}}
工作流名称
{{workflow.run_id}}
工作流运行 ID
{{workflow.start_time.year}} / month / day / hour / minute / second
实例数据时间各分量
{{workflow.start_time.iso_date}}
实例数据时间 ISO 8601 日期格式 YYYY-MM-DD
{{workflow.start_time.iso_datetime}}
实例数据时间 ISO 8601 日期时间格式
{{workflow.start_time.is_weekday}}
是否工作日（true / false）
{{workflow.trigger.time.day}}
计划调度时间日
{{workspace.id}}
工作空间 ID
{{task.name}}
任务名称
{{task.run_id}}
任务运行 ID
{{tasks.<上游任务名>.values.<参数 key>}}
上游 Notebook 任务通过 dlcutils.jobs.taskValues.set 输出的参数
{{tasks.<上游任务名>.output.first_row}}
上游 SQL 任务输出的第一行
{{tasks.<上游任务名>.output.first_row.<列名>}}
上游 SQL 任务输出第一行指定列
{{tasks.<上游任务名>.output.rows}}
上游 SQL 任务输出全部行（JSON 数组）
完整内置参数清单详见 系统内置参数。

参数说明

参数命名规范

项目
规范
字符集
中英文、数字、下划线 _、短横线 -
长度
不超过 128 字符
大小写
区分大小写

参数取值规范

项目
规范
长度
不超过 2048 字符
类型
字符串。SQL 中按字符串拼接到位，需要数值时手动加引号或类型转换。

使用限制

参数仅支持 Key-Value 形式；不支持嵌套结构（数组、JSON 对象）。
文件级参数仅在 Studio 调试运行时使用；调度运行以工作流和任务参数为准。
dlcutils.widgets.get 不能直接在 SQL 中使用，仅适用于 Notebook。
参数值为字符串类型，使用时请注意 SQL 中是否需要单引号包裹（如日期字段）。

常见问题

Q1：调试运行时 ${dp_data_dt} 没有被替换？
检查参数名是否完全一致，包括大小写。
检查文件级参数中是否定义了同名参数。
调度运行时如果工作流和任务都没有同名参数，会按文件级参数兜底；调度场景请确保至少在工作流参数中定义。
Q2：如何在 SQL 中获取「上一周第一天」？ 推荐在工作流参数中定义自定义参数 dp_start_dt，取值引用系统内置参数并做偏移：
dp_start_dt = {{workflow.start_time.iso_date}}   -- 当天
如需更复杂的日期偏移，可在工作流参数取值中使用 iso_date 系列内置参数与配套偏移表达式（详见 系统内置参数），SQL 中通过 ${dp_start_dt} 引用。
Q3：参数值包含单引号或特殊字符怎么办？ 建议在参数值中避免使用特殊字符。如需特殊字符，请在 SQL 中使用反斜杠或拼接函数（如 concat）转义。

相关文档

SQL IDE 基础操作
SQL 脚本运行
辅助工具（DLCUtils、魔法命令）
上一篇: SQL 脚本运行（数据源、资源组配置、运行日志处理、结果查看）下一篇: Python IDE 基础操作

帮助和支持

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

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

文档反馈

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