Supported formats for scheduling parameters - DataWorks - Alibaba Cloud Documentation Center

Scheduling parameters are the core mechanism in DataWorks for dynamic task and configuration management. They let you use variable placeholders in your code and inject dynamic values during scheduling. This solves the challenge of maintaining hardcoded dates in periodic tasks and separates configuration from code using a four-tier parameter hierarchy: workspace, workflow, node context, and node-local. This separation greatly enhances task flexibility, reusability, and adaptability across different environments.

Important

This article focuses on the assignment sources and expression syntax for scheduling parameters. Before reading this article, make sure that you are familiar with the basic configuration methods described in Configure and use scheduling parameters.

Scheduling parameter sources

Besides using parameters defined locally on a node, you can also use context, workflow, and workspace parameters. These sources are listed below in order of scope, from narrowest to broadest.

Node-local definition (current node)

Parameters defined in the Scheduling Parameters area of the Scheduling Configuration section apply only to the current node. They support a rich set of parameter expressions, as detailed below.
Context parameters (passed across nodes)

Use context parameters to receive output values from upstream nodes. This not only passes values but also establishes a dependency between the nodes. Use this method when a parameter's value must be dynamically determined by the result of an upstream task. You can quickly add a context parameter by clicking the icon in the parameter assignment area. For more information, see Configure and use node context parameters .
Workflow parameters (shared within a workflow)

Parameters defined at the workflow level are available to all nodes within that workflow. You can reference them directly using the format ${workflow.Parameter name}. The parameter expression rules described in this article also apply to workflow parameters.
Workspace parameters (shared within a workspace)

Workspace parameters are global parameters defined at the workspace level, making them available to all nodes within that workspace. Their most common use is to differentiate configurations between development and production environments. For example, you can define a parameter named db_name with a value of db_dev in the development environment and db_prod in the production environment. When setting a scheduling parameter's value, you can directly select Workspace Parameters . For details, see Use workspace parameters .

Parameter expressions

Scheduling parameters define assignment logic by specifying a parameter name and a parameter value. The parameter value supports multiple forms, including time parameters, built-in system parameters, and constants. After the parameters are defined, you can reference them in your code by using the ${parameter name} format.

Custom time parameters: Such as ${...} and $[...], which allow you to transform values based on two time references (business date and scheduled time). For details, see Time parameters.
Built-in system parameters: Such as $bizdate, $bizmonth, and $jobid, which can be used to retrieve the business date, business month, workflow ID, and more. They are not limited to time-related values. For details, see Built-in scheduling parameters.
Constants: Such as '123', 'abc', and so on.

Among these, time parameters are the primary use case for scheduling parameters. They are used to dynamically replace various time strings when tasks run.

Time parameters

Core concept: Time reference

All dynamic time parameters in DataWorks are based on the following two core time references.

Concept

Definition

Parameter value

Custom format

Time precision

Business date

Typically refers to the day before the scheduled run date of a task. In T+1 batch computing scenarios, it represents the date on which the business data was generated. For example, if you run a task today to calculate the previous day's revenue, the previous day — the date when the transactions occurred — is the business date.

${yyyymmdd}

${...}

Year, month, day

Scheduled time

Refers to the time configured in the Scheduling Settings section of a node via the cron expression. At task runtime, it is replaced with the day on which the task instance is scheduled to run. It is precise to the second and is independent of the actual execution time.

This time represents the expected execution time of the task, which may not exactly match the actual start time. The actual start time is affected by multiple factors.

$[yyyymmddhh24miss]

$[...]

Year, month, day, hour, minute, second

Summary:

Business date ≈ yesterday (the date of the data) = $bizdate = ${yyyymmdd}
Scheduled time ≈ today (the time the task runs) = $cyctime = $[yyyymmddhh24miss]

A typical T+1 task works as follows: at the early hours of today (scheduled time), a task is triggered to process yesterday's (business date) data.

The following shows the parameter definitions for $bizdate and ${yyyymmdd}, $cyctime and $[yyyymmddhh24miss], along with their preview results when the business date is 2025-10-16.

If the default return value of the base time parameter does not meet your requirements, you can customize time parameters by using ${...} and $[...]. Custom time parameters are derived by transforming the two base time references. The following methods are supported:

Important

When assigning values to scheduling parameters using custom expressions, make sure to distinguish between the two bracket formats: {...} and [...]. The two formats use different base time references and return entirely different values. Mixing them up may cause production data errors.

Custom time parameters

DataWorks supports using ${...} and $[...] to retrieve the business date and scheduled time, respectively. The following transformation types allow you to flexibly modify time values to meet your business requirements. The following examples assume a daily schedule with a scheduled time of 02:30:45 and a business date of 20251031. The base time references are:

Business date: ${yyyymmdd}, for example, 20251031.
Scheduled time: $[yyyymmddhh24miss], for example, 20251101023045.

Important
The scheduled time is the preset scheduling time, which is fixed when the task instance is generated. If a task instance is delayed due to resource constraints or upstream node status, the scheduled time does not change with the actual run time of the instance.

`${...}` vs. `$[...]` key differences

First, understand the key differences between the two. ${...} and $[...] differ fundamentally in their time references and calculation capabilities. Mixing these two formats may cause data errors.

Dimension	`${...}` (based on business date)	`$[...]` (based on scheduled time)
Time reference	Business date (T-1)	Scheduled time (T)
Time precision	Day (year, month, day)	Second (year, month, day, hour, minute, second)
Offset calculation capability	Supports offset calculations for year, month, week, and day.	Supports offset calculations for day, hour, and minute.
Key limitation	Does not support formatting or offset calculations for smaller time units such as hour, minute, and second.	Does not support using the `$[yyyy±N]` or `$[mm±N]` syntax to directly offset years or months. Use the `add_months` function instead.
Default equivalent	`${yyyymmdd}` is equivalent to `$bizdate`	`$[yyyymmddhh24miss]` is equivalent to `$cyctime`

Time formatting

Use curly braces ${...} or square brackets $[...], combined with yyyy, yy, mm, and dd in custom combinations to generate time parameters that retrieve dates a certain number of years, months, or days before or after the business date.

Code	Description	`${...}` (based on business date)		`$[...]` (based on scheduled time)
Code	Description	Assignment	Result	Assignment	Result
`yyyy`	4-digit year	`${yyyy}`	`2025`	`$[yyyy]`	`2025`
`mm`	2-digit month	`${mm}`	`10`	`$[mm]`	`11`
`dd`	2-digit day	`${dd}`	`31`	`$[dd]`	`01`
`hh24`	Hour in 24-hour format	Not supported (day-level precision)	-	`$[hh24]`	`02`
`hh` / `hh12`	Hour in 12-hour format		-	`$[hh]`	`02`
`mi`	Minute		-	`$[mi]`	`30`
`ss`	Second		-	`$[ss]`	`45`
`yyyymm`	Year and month	`${yyyymm}`	`202510`	`$[yyyymm]`	`202511`
`yyyy-mm-dd`	Formatted with hyphens as delimiters	`${yyyy-mm-dd}`	`2025-10-31`	`$[yyyy-mm-dd]`	`2025-11-01`
`yyyy-mm-dd hh24:mi:ss`	Formatted with hyphens, including hours, minutes, and seconds	Not supported (day-level precision)	-	For the supported method, see String concatenation: Method 2.

Offset calculation

Offset calculation is the core of dynamic parameters. You can add or subtract values from the business date or scheduled time to retrieve dates and times N years, months, days, hours, or minutes before or after the base time (hours and minutes are supported only for the scheduled time). ${...} and $[...] support different ranges due to the different precision of their base time references.

${...} offset calculation

Core capability: Supports integer offset for year, month, week, and day.

Important
Does not support hour or minute offset calculations. Expressions such as ${yyyy-mm-dd-1/24} are not supported.

Syntax: ${<time format><±N>}, where N corresponds to the smallest unit in the time format. For example, if the format is yyyymm, N is in months. If the format is yyyymmdd, N is in days.

Date offset period	Offset unit	Syntax	Example
N years before/after	Year	`${yyyy±N}` or `${yy±N}`	Get the previous year: `${yyyy-1}`
N months before/after	Month	${yyyymm±N}	Get the previous month: `${yyyymm-1}`
N weeks before/after	Week	${yyyymmdd±7*N}	Get the previous week: `${yyyymmdd-7*1}`
N days before/after	Day	${yyyymmdd±N}	Get the day before yesterday: `${yyyymmdd-1}`

$[...] offset calculation

Core capability: Supports fractional offset for day, hour, and minute.

Important
$[...] cannot use the $[yyyy-N] or $[mm-N] time format to retrieve dates N years or N months ago. To perform year or month offset calculations, use the add_months function.

Syntax: $[<time format><±N>], where N/24 is used for hour offsets and N/24/60 is used for minute offsets. N is the number of hours or minutes to offset.

Requirement	Offset unit	Syntax	Example
N years before/after	Year	`$[add_months(yyyymmdd,12N)]` (N years after) `$[add_months(yyyymmdd,-12N)]` (N years before)	Get the previous year: `$[add_months(yyyymmdd,-12)]`
N months before/after	Month	`$[add_months(yyyymmdd,N)]` (N months after) `$[add_months(yyyymmdd,-N)]` (N months before)	Get the previous month: `$[add_months(yyyymmdd,-1)]`
N weeks before/after	Week	`$[yyyymmdd±7*N]`	Get the previous week: `$[yyyymmdd±7*1]`
N days before/after	Day	`$[yyyymmdd±N]`	Get yesterday: `$[yyyymmdd-1]`
N hours before/after	Hour	You can retrieve this time data using the following methods: `$[hh24miss±N/24]`, `$[hh24±N/24]` `$[custom time format±N/24]`	Get the previous hour using different time formats: Get month: `$[mm-1/24]`. Get year: `$[yyyy-1/24]`. Get year and month: `$[yyyymm-1/24]`. Get year, month, and day: `$[yyyymmdd-1/24]`. Get the previous day and previous hour: `$[yyyymmdd-1-1/24]`
N minutes before/after	Minute	You can retrieve this time data using the following methods: `$[hh24miss±N/24/60]` `$[yyyymmddhh24miss±N/24/60]` `$[mi±N/24/60]` `$[custom time format±N/24/60]`	Get 15 minutes before the scheduled time using different time formats: `$[yyyy-15/24/60]` `$[yyyymm-15/24/60]` `$[yyyymmdd-15/24/60]` `$[hh24-15/24/60]` `$[mi-15/24/60]`
Complex combined offset	Day + Hour	`$[yyyymmdd±N±M/24]`, where N is the day offset and M is the hour offset.	Example: Get one day before and one hour before → `$[yyyymmdd-1-1/24]`

Note

When performing hour or minute offset calculations, day boundary crossing may occur. For information about how parameters handle day boundary crossing, see Handle day boundary crossing in time parameters.
When performing a month offset calculation on an end-of-month date, if the target month does not have the corresponding day, the result is automatically adjusted to the last day of that month. For example, if the current date is 2025-03-31 and a 1-month backward offset is applied, the result is 2025-02-28 because February does not have a 31st day.

Secondary transformation using engine functions

When the built-in formatting and offset of scheduling parameters cannot directly produce the desired value (such as the last day of the previous month), you can use functions built into the compute engine of the target node or use an assignment node to perform secondary transformations on time parameters when calling them.

For more information, see Perform secondary transformation using engine functions.

String concatenation

Use this method to construct date strings with patterns that the built-in syntax does not support. It combines the date portion generated by scheduling parameters with fixed constant strings.

Example 1: Dynamically get the first day of each month.

Scenario: Regardless of the day the task runs, you need a string representing the first day of the current month in the format yyyymm01.
Implementation:
1. Extract the year and month: Use ${yyyymm} to get the year and month of the current business date (for example, if the business date is 20231027, the result is 202310).
2. Concatenate the constant: Concatenate the extracted year and month with the string '01'.
3. Parameter call: first_day_of_month=${yyyymm}01
Result: When the task runs, ${first_day_of_month} is replaced with 20231001.

Example 2: Get the time in yyyy-mm-dd hh24:mi:ss format.

Scenario: Get a time string in yyyy-mm-dd hh24:mi:ss format, such as 2023-11-01 02:30:45.
Implementation:
1. Define two parameters: datetime1 and datetime2, and assign them as datetime1=$[yyyy-mm-dd] and datetime2=$[hh24:mi:ss-1/24/60].
2. Concatenate the parameters: Concatenate datetime1 and datetime2 with a space.
3. Parameter call: pt=${datetime1} ${datetime2}.
Result: When the task runs, ${datetime1} ${datetime2} is replaced with 2023-11-01 02:30:45.

Built-in scheduling parameters

DataWorks supports the following built-in system parameters, which can be used as scheduling parameter values. However, this approach is less flexible because the time format is fixed. We recommend that you use custom time parameters, which support flexible transformations.

Built-in parameter	Definition
$bizdate	The business date, in the format `yyyymmdd`. Its value is the same as the custom parameter `${yyyymmdd}`. This parameter is widely used. In daily scheduling, the business date defaults to the day before the expected task run date.
$cyctime	The scheduled time of the task, in the format `yyyymmddhh24miss`. Its value is the same as the custom parameter `$[yyyymmddhh24miss]`.
$gmtdate	The current date, in the format `yyyymmdd`. This parameter defaults to the current date. When you backfill data, the input date is `business date + 1`.
$bizmonth	The business month, in the format `yyyymm`. If the month of the business date is the same as the current month, then `$bizmonth = business date month - 1`. If the month of the business date is different from the current month, then `$bizmonth = business date month`.
$jobid	The ID of the workflow to which the task belongs.
$nodeid	The node ID.
$taskid	The instance ID generated by the node.

Appendix

Parameter replacement during data backfill

After a task is submitted to Operation Center, you can backfill data to batch-generate and run historical task instances within a specified date range for data repair, backfilling, or retrospective analysis.

Business date ($bizdate): During data backfill, the business date you select is consistent with the replacement result of $bizdate. If the scheduling parameter uses the ${...} custom format, the base time is the selected date, which is then transformed according to the specified time expression.
Scheduled time ($cyctime): During data backfill, the replacement result of $cyctime is the selected business date + 1 day.

For example, if the business date selected for data backfill is 20250315, then during data backfill, the replacement result of the $cyctime parameter is 20250316000000. If the scheduling parameter uses the $[...] format, the base time is the selected business date + 1, which is then transformed according to the specified time expression.

Relationship between scheduling parameters, business date, scheduled time, and actual run time

Relationship type	Description and example
Relationship between scheduling parameters and actual run time.	The replacement values of scheduling parameters are determined when instances are generated. Therefore, the replacement values do not change with the actual run time of the instance.
Relationship between scheduling parameters and scheduled time.	When a scheduling parameter is set to `$[]`, the replacement value is determined by the scheduled time of the instance, which is based on the scheduling time configured in the node's schedule settings. For example, if the current node is an hourly scheduled node with a scheduled time range of `00:00` to `23:59` and runs once every hour, then: The scheduled time of the first hourly instance is `0` o'clock, and the hour parameter value is `00`. The scheduled time of the second hourly instance is `1` o'clock, and the hour parameter value is `01`.
Relationship between scheduling parameters, business date, and scheduled time.

Daylight saving time notes

DataWorks ensures that tasks run correctly on the days when daylight saving time (DST) begins and ends. For details about how the product handles DST transitions, see Daylight saving time. To avoid additional complexity caused by DST transitions on your task execution, we recommend that you review this document if your region observes DST.

Value comparison of custom parameters

This section uses an ODPS SQL node as an example. Assuming the task's scheduled time is July 20, 2025 10:30:00, the following table shows the time value configurations for ${…} and $[…] parameters.

Time value	${…} parameter	$[…] parameter
Get year: 2025	Scheduling parameter assignment: `datetime=${yyyy}` Code reference: `pt=${datetime}` Parameter replacement result: `pt=2025`	Scheduling parameter assignment: `datetime=$[yyyy]` Code reference: `pt=${datetime}` Parameter replacement result: `pt=2025`
Get year: 25	Scheduling parameter assignment: `datetime=${yy}` Code reference: `pt=${datetime}` Parameter replacement result: `pt=25`	Scheduling parameter assignment: `datetime=$[yy]` Code reference: `pt=${datetime}` Parameter replacement result: `pt=25`
Get year: 2024	Scheduling parameter assignment: `datetime=${yyyy-1}` Code reference: `pt=${datetime}` Parameter replacement result: `pt=2024`	Scheduling parameter assignment: `datetime=$[add_months(yyyymmdd,-12)]` Code reference: `pt=${datetime}` Parameter replacement result: `pt=2024`
Get month: 07	Scheduling parameter assignment: `datetime=${mm}` Code reference: `pt=${datetime}` Parameter replacement result: `pt=07`	Scheduling parameter assignment: `datetime=$[mm]` Code reference: `pt=${datetime}` Parameter replacement result: `pt=07`
Get day: 20	Scheduling parameter assignment: `datetime=${dd}` Code reference: `pt=${datetime}` Parameter replacement result: `pt=20`	Scheduling parameter assignment: `datetime=$[dd]` Code reference: `pt=${datetime}` Parameter replacement result: `pt=20`
Get date: June 20, 2025	Scheduling parameter assignment: `datetime=${yyyy-mm-dd-29}` Code reference: `pt=${datetime}` Parameter replacement result: `pt=2025-06-20` Important This approach requires consideration of the number of days in each month and is not recommended. We recommend that you use the `$[]` format to get the same date of the previous month.	Scheduling parameter assignment: `datetime=$[add_months(yyyymmdd,-1)]` Code reference: `pt=${datetime}` Parameter replacement result: `pt=2025-06-20`
Get date: July 19, 2025	Scheduling parameter assignment: `datetime=${yyyy-mm-dd}` Code reference: `pt=${datetime}` Parameter replacement result: `pt=2025-07-19`	Scheduling parameter assignment: `datetime=$[yyyy-mm-dd-1]` Code reference: `pt=${datetime}` Parameter replacement result: `pt=2025-07-19`
Get date: July 20, 2024	Scheduling parameter assignment: `datetime=${yyyy-mm-dd-364}` Code reference: `pt=${datetime}` Parameter replacement result: `pt=2024-07-20` Important This approach requires consideration of leap years and is not recommended. We recommend that you use the `$[]` format to get the same date of the previous year.	Scheduling parameter assignment: `datetime=$[add_months(yyyymmdd,-12)]` Code reference: `pt=${datetime}` Parameter replacement result: `pt=2024-07-20`
Get time: 10:30:00	Not supported	Scheduling parameter assignment: `datetime=$[hh24:mi:ss]` Code reference: `pt=${datetime}` Parameter replacement result: `pt=10:30:00`
Get time: 2025-07-20 10:30:00	Not supported	Scheduling parameter assignment: `datetime1=$[yyyy-mm-dd] datetime2=$[hh24:mi:ss]` Note You need to define two parameters, datetime1 and datetime2, separated by a space. Code reference: `pt=${datetime1} ${datetime2}` Parameter replacement result: `datetime1=$[yyyy-mm-dd]=2025-07-20` `datetime2=$[hh24:mi:ss]=10:30:00` `pt=2025-07-20 10:30:00`
Get time: 2025-07-20 10:29:00	Not supported	Scheduling parameter assignment: `datetime1=$[yyyy-mm-dd] datetime2=$[hh24:mi:ss-1/24/60]` Note You need to define two parameters, datetime1 and datetime2, separated by a space. Code reference: `pt=${datetime1} ${datetime2}` Parameter replacement result: `datetime1=$[yyyy-mm-dd]=2025-07-20` `datetime2=$[hh24:mi:ss-1/24/60]=10:29:00` `pt=2025-07-20 10:29:00`
Get time: 2025-07-20 09:30:00	Not supported	Scheduling parameter assignment: `datetime1=$[yyyy-mm-dd] datetime2=$[hh24:mi:ss-1/24]` Note You need to define two parameters, datetime1 and datetime2, separated by a space. Code reference: `pt=${datetime1} ${datetime2}` Parameter replacement result: `datetime1=$[yyyy-mm-dd]=2025-07-20` `datetime2=$[hh24:mi:ss-1/24]=09:30:00` `pt=2025-07-20 09:30:00`
Get the previous day's time, precise to seconds, with no space between date and time: 2025071910:30:00	Not supported	Scheduling parameter assignment: `datetime=$[yyyymmddhh24miss-1]` Code reference: `pt=${datetime}` Parameter replacement result: `datetime=$[yyyymmddhh24miss-1]=2025071910:30:00` `pt=2025071910:30:00`
Get the previous day's time, precise to seconds, with a space between date and time: 20250719 10:30:00	Not supported	Scheduling parameter assignment: `datetime1=$[yyyymmdd-1] datetime2=$[hh24:mi:ss]` Note You need to define two parameters, datetime1 and datetime2, separated by a space. Code reference: `pt=${datetime1} ${datetime2}` Parameter replacement result: `datetime1=$[yyyymmdd-1]=20250719` `datetime2=$[hh24:mi:ss]=10:30:00` `pt=20250719 10:30:00`

DataWorks:Scheduling parameter sources and expressions

Scheduling parameter sources

Parameter expressions