大数据智能体工作台 DataBuddy 参数化实现

一、概述

DataBuddy SQL 中的参数分为以下几类，统一以 ${param_key} 形式引用：

参数优先级（从高到低）：任务 > 工作流 > 文件 。

二、前提条件

·你具备当前 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。

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} 自动替换为工作流的实例数据时间。

常用系统内置参数：

完整内置参数清单详见 系统内置参数。

八、参数命名规范

九、参数取值规范

十、使用限制

·参数仅支持 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、魔法命令）