Scheduling parameters let you pass dynamic time values into node code at runtime. Each time a task runs, DataWorks replaces the parameter placeholders in your node code with computed values based on rules you configure in the Scheduling Parameters section of the Properties tab in Data Studio.
Core concepts
Two time concepts determine how scheduling parameters compute their values.
| Concept | Definition | Precision |
|---|---|---|
| Data timestamp | The day before the scheduling time. In offline computing, this represents the business date — the day on which source data was generated. | Day |
| Scheduling time | The time at which the task instance is scheduled to run. This may differ from the actual start time due to queue wait times and other factors. | Second |
Why the difference matters: In a typical ETL workflow, you process yesterday's data today. If a task runs at 2024-03-15 02:00:00, the data timestamp is 2024-03-14 — the business date of the data being processed. This one-day offset is the foundation of the ${...} format.
The value of a scheduling parameter is determined when the task instance is generated. It does not change regardless of when the instance actually runs.
Choose a parameter format
DataWorks provides two custom time parameter formats. Use this table to choose the right one:
| I want to... | Use | Example |
|---|---|---|
| Reference yesterday's date (data timestamp) | ${...} |
${yyyymmdd} |
| Add or subtract days, months, or years from the data timestamp | ${...} |
${yyyymmdd-7} |
| Reference the exact scheduling time (to the second) | $[...] |
$[yyyymmddhh24miss] |
| Add or subtract hours or minutes from the scheduling time | $[...] |
$[hh24miss-1/24] |
| Add or subtract months or years from the scheduling time | $[...] with add_months() |
$[add_months(yyyymmdd,-1)] |
${yyyymmdd}equals$[yyyymmdd-1]— both produce the data timestamp. The${...}format is day-precision only; use$[...]for hour- or minute-level precision.
${...} parameters (data timestamp based)
${...} parameters compute time relative to the data timestamp of the task. They support yyyy, yy, mm, and dd components, and support ±N arithmetic for days, months, and years.
Precision: Day only. Hour, minute, and second components are not supported.
Common formats
| Offset | Parameter |
|---|---|
| N days ago or later | ${yyyymmdd±N} |
| N weeks ago or later | ${yyyymmdd±7*N} |
| N months ago or later | ${yyyymm±N} |
| N years ago or later | ${yyyy±N} |
| N years ago or later (yy format) | ${yy±N} |
| Custom date separator | ${yyyy-mm-dd±N} |
| First day of month (string concat) | ${mm}01 |
To offset by months or years, use${yyyymm±N}or${yyyy±N}rather than$[...].
$[...] parameters (scheduling time based)
$[...] parameters compute time relative to the scheduling time of the task. They support all ${...} components plus hh24, hh, mi, and ss, and use fractional arithmetic to express hours and minutes.
Precision: Second. Use these parameters when you need hour- or minute-level accuracy.
Hour and minute notation
The $[...] format encodes time units as fractions of a day:
| Unit | Divisor | Meaning | Example |
|---|---|---|---|
| 1 hour | /24 |
1/24 of a day | $[hh24miss-1/24] — 1 hour ago |
| N hours | /24 |
N/24 of a day | $[hh24miss-3/24] — 3 hours ago |
| 1 minute | /24/60 |
1/(24x60) of a day | $[hh24miss-1/24/60] — 1 minute ago |
| N minutes | /24/60 |
N/(24x60) of a day | $[hh24miss-15/24/60] — 15 minutes ago |
Both hh24 (24-hour clock) and hh (12-hour clock) are supported for hour fields.
Common formats
| Offset | Parameter |
|---|---|
| Exact scheduling time | $[yyyymmddhh24miss] |
| N days ago or later | $[yyyymmdd±N] |
| N weeks ago or later | $[yyyymmdd±7*N] |
| N hours ago or later | $[hh24miss±N/24] or $[hh24±N/24] or $[Custom format±N/24] |
| N minutes ago or later | $[hh24miss±N/24/60] or $[yyyymmddhh24miss±N/24/60] or $[mi±N/24/60] |
| N months later | $[add_months(yyyymmdd,N)] |
| N months ago | $[add_months(yyyymmdd,-N)] |
| N years later | $[add_months(yyyymmdd,12*N)] |
| N years ago | $[add_months(yyyymmdd,-12*N)] |
| 1 hour ago on previous day | $[yyyymmdd-1-1/24] |
$[yyyy-N]and$[mm-N]are not supported for year and month offsets in$[...]. Use$[add_months(...)]instead.
Cross-day issues
When a task runs near midnight and uses hour- or minute-level parameters, the computed value may reference the wrong day's partition. For example, a task scheduled at 00:00 on March 15 that subtracts 1 hour produces 23:00 — but which day does the yyyymmdd component resolve to? For details and solutions, see I run an instance of a node at 00:00 on the current day to analyze the data in the partition that corresponds to 23:00 on the previous day. However, the data in the partition that corresponds to 23:00 on the current day is analyzed. What do I do?
Built-in parameters
DataWorks provides the following built-in parameters. For flexibility, use custom time parameters instead where possible.
| Parameter | Value format | Description |
|---|---|---|
$bizdate |
yyyymmdd |
Data timestamp. Same as ${yyyymmdd}. Default: scheduling time minus one day. |
$cyctime |
yyyymmddhh24miss |
Scheduling time. Same as $[yyyymmddhh24miss]. |
$gmtdate |
yyyymmdd |
Current date. When backfilling data, set to data timestamp + 1 day. |
$bizmonth |
yyyymm |
Month from the data timestamp. If the data timestamp is in the current month, returns one month earlier; otherwise returns the month of the data timestamp. |
$jobid |
— | ID of the workflow the task belongs to. |
$nodeid |
— | Node ID. |
$taskid |
— | ID of the task instance. |
Usage notes
-
Shell nodes: Scheduling parameters for Shell nodes use a different format —
$N, where N is an integer starting from 1. The${...}and$[...]formats do not apply. -
Constants: Assign a constant string to a scheduling parameter to pass the same value on every run.
-
`${bizdate}` in node code: The variable
${bizdate}in node code has no special built-in meaning — it is a custom variable name. Any variable you define in${Variable}format and map in the Scheduling Parameters section works the same way. -
Daylight saving time: DataWorks handles daylight saving time transitions without impact to task scheduling. If your tasks run in a region that observes daylight saving time, see Impacts exerted by the switching of daylight saving time on the running of tasks.
Appendix: Supported built-in scheduling parameters
The following built-in parameters are available in node code and can be referenced in scheduling configurations.
| Parameter | Description |
|---|---|
${projectId} |
ID of the MaxCompute project. |
${projectName} |
Name of the MaxCompute project. |
${nodeId} |
Node ID. |
${gmtdate} |
Date on which the instance is scheduled to run, in yyyy-MM-dd 00:00:00 format. |
${taskId} |
Task instance ID. |
${seq} |
Sequence number of the task instance among all instances scheduled on the same day. |
${cyctime} |
Time at which the instance is scheduled to run. |
${status} |
Status of the instance. Valid values: SUCCESS and FAILURE. |
${bizdate} |
Data timestamp. |
${finishTime} |
Time at which the instance finishes running. |
${taskType} |
Mode in which the instance runs. Valid values: NORMAL, MANUAL, PAUSE, SKIP, UNCHOOSE, and SKIP_CYCLE. |
${nodeName} |
Name of the node. |