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.ordersWHERE dt = '${dp_data_dt}'LIMIT 100;
步骤 2：定义文件级参数
1. 单击操作栏 参数 按钮。
2. 在弹窗中单击 + 添加参数 。
3. 填写：
参数名 ：与 SQL 中
${...} 内的标识符一致，如 dp_data_dt。参数值 ：调试运行时使用的值，如
2026-06-05。1. 单击 确定 保存。
步骤 3：调试运行
单击 运行、全部运行 时，系统将文件级参数值替换到 SQL 中执行。
如果 SQL 中引用了未定义的参数，运行时弹窗提示填写。
步骤 4：发布到 Workflow 调度
1. 单击操作栏 快速创建任务 ，选择目标工作流。
2. 进入 Workflow 任务配置，工作流和任务参数会按以下规则识别：
SQL 中已使用的
${...} 参数会自动识别为任务参数候选项。您可在工作流参数、任务参数中给出实际取值（自定义值或引用系统内置参数）。
1. 调度运行时取值规则：任务参数 > 工作流参数 > 文件参数 。
步骤 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}} -- 当天
Q3：参数值包含单引号或特殊字符怎么办？
建议在参数值中避免使用特殊字符。如需特殊字符，请在 SQL 中使用反斜杠或拼接函数（如
concat）转义。相关文档
SQL IDE 基础操作
