tencent cloud

Tencent Cloud DataBuddy

문서Tencent Cloud DataBuddyData EngineeringWorkflowParameter managementParameter Usage

Parameter Usage

다운로드
포커스 모드
폰트 크기
마지막 업데이트 시간: 2026-10-09 16:13:08
AI 번역
This document describes how to reference configured parameters in the code of Notebook and SQL tasks. For parameter configuration methods, see Parameter Configuration.

Overview

After parameters are configured, you need to reference parameter values in task code by using specific syntax. Different task types use different reference methods:
Task type
Reference Syntax
Description
Notebook
dlcutils.widgets.get('param_name')
Return the parameter value of the string type.
SQL
${param_name}
Replaced directly with the parameter value at runtime.

Using Parameters in Notebooks

Reference Syntax

value = dlcutils.widgets.get('param_name')
param_name: The parameter name, which corresponds to the Key defined in workflow parameters or task parameters.
The return value is of the string type. If a numeric type is required, explicitly convert it in the code.

Example

Referencing Workflow Parameters

Assume that the following parameter is defined in the workflow parameters: dp_data_dt = {{workflow.start_time.iso_date}}
# Obtain parameter values
dt = dlcutils.widgets.get('dp_data_dt')
print(dt)
# Output: 2026-06-11

# If numeric values are required, explicitly convert them.
batch_size = int(dlcutils.widgets.get('batch_size'))

Referencing Task Parameters

Assume that the following parameter is defined in the task parameters: task_param = {{tasks.upstream_sql.output.first_row.col_a}}
col_a_value = dlcutils.widgets.get('task_param')
print(col_a_value)
# Output: The value of col_a in the first row of the upstream SQL result.

Differences Between Debug Runs and Scheduled Runs

Scenario
Action
Studio debugging run
If a parameter is not defined, a dialog box prompts the user to manually enter the parameter value.
Workflow Scheduling Run
The system automatically parses parameter values, and undefined parameters are returned as empty strings.

Using Parameters in SQL

Reference Syntax

${param_name}
At runtime, ${param_name} is directly replaced with the parameter value (string replacement).

Example

Referencing Workflow Parameters

Assume that the following parameter is defined in the workflow parameters: dp_data_dt = {{workflow.start_time.iso_date}}
SELECT *
FROM my_table
WHERE dt = '${dp_data_dt}';
-- Replaced at runtime with: WHERE dt = '2026-06-11'

Referencing Task Parameters

Assume that the following parameter is defined in the task parameters: target_db = my_database
USE ${target_db};
SELECT COUNT(*) FROM orders;
-- Replaced at runtime with: USE my_database;

Combining Multiple Parameters

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

Differences Between Debug Runs and Scheduled Runs

Scenario
Action
Studio debugging run
If a parameter is not defined, a dialog box prompts the user to manually enter the parameter value.
Workflow Scheduling Run
The system automatically parses parameters. Undefined parameters are replaced with empty strings, which may cause SQL syntax errors.

Using Parameters in Other Task Types

Task type
Reference Syntax
Offline data ingestion
${param_name}
Conditional node
${param_name}
For Each loop
${param_name}
Nested workflow (Run Job)
${param_name}

Best Practices

1. Encapsulating System Built-in Parameters in Workflow Parameters

It is recommended to encapsulate system built-in parameters as business parameters with clear semantics, and reference only the business parameter names in the code.
# Workflow parameter definition
dp_data_dt = {{workflow.start_time.iso_date}}
-- Referencing in SQL (Recommended)
WHERE dt = '${dp_data_dt}'

-- Writing built-in parameters directly in code is not recommended.
# Referencing in Notebook (Recommended)
dt = dlcutils.widgets.get('dp_data_dt')
Benefits:
Parameter names have clear semantics, which improves code readability.
Manage them centrally in workflow parameters so that a change in one place takes effect immediately.
Parameter values in logs are traceable.

2. Calculating Offsets Based on trigger Time

Common scenario: You need to use the trigger time - 1 day as the partition time (T+1 scenario).
Note:
The system built-in parameter {{workflow.trigger.time.iso_date}} does not support offset operations directly in template syntax. You need to calculate it in your code.
Prerequisite: Define the trigger date in the workflow parameters.
trigger_date = {{workflow.trigger.time.iso_date}}
Method 1: Use functions in SQL for calculation.
-- Workflow parameter defined: trigger_date = {{workflow.trigger.time.iso_date}}.
-- Use the DATE_SUB function to subtract 1 day from the trigger date as the partition time.
SELECT *
FROM dw.user_daily
WHERE dt = DATE_SUB('${trigger_date}', INTERVAL 1 DAY);
-- If the trigger time is 2026-06-12, it is equivalent to: WHERE dt = '2026-06-11'.
If the engine does not support DATE_SUB, you can use DATE_ADD instead:
WHERE dt = DATE_ADD('${trigger_date}', INTERVAL -1 DAY);
Method 2: Calculate the offset in Notebook code
from datetime import datetime, timedelta

# Obtain the trigger date from the workflow parameters.
trigger_date = dlcutils.widgets.get('trigger_date')
# Example of the trigger_date value: '2026-06-12'.

# Calculate the previous day as the partition time.
dt_obj = datetime.strptime(trigger_date, '%Y-%m-%d')
partition_date = (dt_obj - timedelta(days=1)).strftime('%Y-%m-%d')
print(partition_date)
# Output: 2026-06-11.

# Use partition_date for subsequent data reads and writes.
spark.sql(f"SELECT * FROM dw.user_daily WHERE dt = '{partition_date}'")

3. Note the String Type

Parameter values are always of the string type. When referencing them in SQL, note whether quotes are required:
-- String type fields: Add quotes.
WHERE dt = '${dp_data_dt}'

-- Numeric type fields: Do not add quotes (the parameter value itself is a numeric string).
WHERE id = ${target_id}
In Notebook, explicit type conversion is required:
# String parameters
env = dlcutils.widgets.get('env')

# When numeric values are required
batch_size = int(dlcutils.widgets.get('batch_size'))
threshold = float(dlcutils.widgets.get('threshold'))

4. Setting Reasonable Default Values

During development and debugging, provide default values for parameters to avoid repeated manual input during debugging runs:
import os

# In Notebook, you can try to obtain the parameter first, and use the default value if it cannot be obtained.
dt = dlcutils.widgets.get('dp_data_dt')
if not dt:
    dt = '2026-06-11'  # Default value for development

Use Limits

Parameter values are always of the string type. If other types are required in the code, perform an explicit conversion.
${param_name} is a plain text substitution in SQL and is not automatically quoted.
Parameter names are case-sensitive: dp_data_dt and DP_DATA_DT are two different parameters.
Undefined parameters are replaced with empty strings during scheduling runs, which may cause SQL syntax errors.

FAQs

Q1: In Notebook, does dlcutils.widgets.get return None or an empty string?
Check whether the parameter names are spelled correctly (case-sensitive).
Check whether this parameter is defined in the workflow parameters or task parameters.
For debugging runs, check whether parameter values are filled in the pop-up window.
Q2: In SQL, is ${param} not replaced?
Confirm that the parameter names are spelled correctly.
Confirm that this parameter is defined in the workflow parameters or task parameters.
When debugging in Studio, fill in the parameter values in the pop-up window.
Q3: How do I reference the output of an upstream task in SQL?
You cannot use {{tasks.<name>.values.<key>}} directly in SQL code. The correct approach is as follows:
1. Define the following in the task parameters: my_param = {{tasks.<name>.values.<key>}}
2. Reference in SQL: ${my_param}
For details, see Parameter Passing.

References

Parameter Configuration
Parameter Passing
System Built-in Parameters
이전 주제: Parameter Configuration다음 주제: Parameter Transfer

도움말 및 지원

문제 해결에 도움이 되었나요?

피드백

키워드로 검색
    Enter keywords to search documentation