DataBuddy SQL scripts support parameterization to meet the requirement of using the same SQL to retrieve different values in different runtime environments, such as using different database and table prefixes in development and production environments or dynamically filtering data by scheduling time. This section focuses on parameterized use of SQL scripts in Studio. For parameter management on workflows and tasks, see Parameter Management. Overview
Parameters in DataBuddy SQL are divided into the following categories and are uniformly referenced in the ${param_key} format:
Parameter Type | Definition Entry | Value priority |
File-level parameter | Parameter dialog box in the SQL file operation bar | Used during debugging |
Task-level parameter | Workflow Task Configuration | Highest priority during scheduling runtime |
Workflow-level parameter | Workflow General Configuration | Second priority during scheduling runtime |
System built-in parameter | Built into DataBuddy | Effective only in scheduling runtime scenarios |
Parameter priority (from high to low): Task > Workflow > File.
Prerequisites
You have Edit permission on the current SQL file.
In scheduled run scenarios, you need to create an SQL task in Workflow and reference this file.
Operation Steps
Step 1: Referencing Parameters in SQL
Use the ${param_key} placeholder in SQL:
SELECT *
FROM your_catalog.your_schema.orders
WHERE dt = '${dp_data_dt}'
LIMIT 100;
Step 2: Defining File-Level Parameters
1. Click the Parameters button in the operation bar.
2. In the dialog box, click + Add Parameter.
3. Enter:
Parameter name: Must be consistent with the identifier in ${...} in the SQL, such as dp_data_dt.
Parameter value: The value used during debugging, such as 2026-06-05.
4. Click Confirm to save.
Step 3: Debugging the Run
When you click Run or Run All, the system replaces the file-level parameter values in the SQL and executes it.
If an undefined parameter is referenced in the SQL, a dialog box prompts you to enter a value at runtime.
Step 4: Publishing to Workflow Scheduling
1. Click Quick Create Task in the operation bar and select the target workflow.
2. Go to the Workflow task configuration. Workflow and task parameters are identified according to the following rules:
Parameters in the ${...} format that are already used in the SQL are automatically identified as task parameter candidates.
You can provide actual values in the workflow parameters or task parameters, either as custom values or by referencing system built-in parameters.
3. Value resolution rule during scheduling: Task parameters > Workflow parameters > File parameters.
Step 5: Using System Built-in Parameters
You can assign system built-in parameters to custom parameters and then reference them in the SQL:
1. Define the parameter dp_data_dt = {{workflow.start_time.day}} in the workflow configuration.
2. Use WHERE dt = '${dp_data_dt}' in the SQL.
3. At scheduling runtime, ${dp_data_dt} is automatically replaced with the workflow instance data time.
Common system built-in parameters:
Parameter | Description |
{{workflow.id}}
| Workflow ID. |
{{workflow.name}}
| Workflow name |
{{workflow.run_id}}
| Workflow run ID |
{{workflow.start_time.year}} / month / day / hour / minute / second
| Components of instance data time |
{{workflow.start_time.iso_date}}
| Instance data time in ISO 8601 date format YYYY-MM-DD |
{{workflow.start_time.iso_datetime}}
| Instance data time in ISO 8601 datetime format |
{{workflow.start_time.is_weekday}}
| Whether it is a workday (true / false) |
{{workflow.trigger.time.day}}
| Day of scheduled time |
{{workspace.id}}
| Workspace ID |
{{task.name}}
| Task Name |
{{task.run_id}}
| Task run ID |
{{tasks.<upstream task name>.values.<parameter key>}}
| Parameters output by the upstream Notebook task through dlcutils.jobs.taskValues.set |
{{tasks.<upstream task name>.output.first_row}}
| First row of the upstream SQL task output |
{{tasks.<upstream task name>.output.first_row.<column name>}}
| Specified column in the first row of the upstream SQL task output |
{{tasks.<upstream task name>.output.rows}}
| All rows output by the upstream SQL task (JSON array) |
Parameter Description
Parameter Naming Conventions
Item | Specification |
Character Set | Chinese and English characters, digits, underscores _, and hyphens - |
Length | No more than 128 characters |
Case | Case Sensitivity |
Parameter Value Conventions
Item | Specification |
Length | No more than 2048 characters |
Type | String. In SQL, it is concatenated as a string. When a numeric value is required, manually add quotation marks or perform type conversion. |
Use Limits
Parameters support only the Key-Value format. Nested structures such as arrays and JSON objects are not supported.
File-level parameters are used only during Studio debugging. Scheduled runs use workflow and task parameters.
dlcutils.widgets.get cannot be used directly in SQL and is applicable only to Notebooks.
Parameter values are of the string type. When using them, note whether single quotes are required in the SQL, for example, for date fields.
FAQs
Q1: During debugging, ${dp_data_dt} is not replaced?
Check whether the parameter names are exactly the same, including case.
Check whether a parameter with the same name is defined in the file-level parameters.
During scheduled runs, if neither the workflow nor the task has a parameter with the same name, file-level parameters are used as a fallback. For scheduled scenarios, ensure that the parameter is defined at least in the workflow parameters.
Q2: How do I obtain the first day of the previous week in SQL?
We recommend that you define a custom parameter dp_start_dt in the workflow parameters and set its value by referencing a system built-in parameter with an offset:
dp_start_dt = {{workflow.start_time.iso_date}} -- Current day
For more complex date offsets, you can use the iso_date series of built-in parameters and the corresponding offset expressions in the workflow parameter values. For details, see System Built-in Parameters. Reference them in SQL through ${dp_start_dt}. Q3: What should I do if a parameter value contains single quotes or special characters?
We recommend that you avoid using special characters in parameter values. If special characters are required, escape them in SQL by using backslashes or concatenation functions such as concat.
References
SQL IDE Basic Operations