调度参数

最近更新时间:2026-03-27 14:38:12

我的收藏
适用场景:已创建调度任务的开发者,在任务代码中使用系统参数实现动态时间取值。
调度系统支持系统内置参数,帮助用户在代码中动态引用时间和任务上下文信息。系统内置参数分为时间参数非时间参数,下文将详细介绍各参数的含义和使用方式。

速查卡(Quick Reference)

语法速查:
${yyyyMMdd} → 实例数据时间(推荐用于分区值)
$(yyyyMMdd) → 计划调度时间(推荐用于海外时区场景)
$[yyyyMMdd] → 实例执行时间(适用于日志/审计)

偏移速查:
${yyyyMMdd-1d} → 前 1
${yyyyMMdd+3M} → 后 3 个月
${yyyyMMdd+2w} → 后 2
${yyyyMMddHHmmss-2H}→ 前 2 小时

特殊偏移速查:
${yyyyMMdd+ME} → 当月月末
${yyyyMMdd+MS} → 当月月初
${yyyyMMdd+PME} → 上月月末
${yyyyMMdd+YE} → 当年年末

时区速查:
${UTC+0_yyyyMMdd} → UTC+0 时区
${UTC+7_yyyyMMdd} → UTC+7 时区
不加时区前缀 → 默认 UTC+8

一、系统内置时间参数

1.1 三类时间参数总览

系统支持三类内置时间参数,核心区别如下:
参数类型
语法标记
含义
稳定性
推荐场景
实例数据时间
${ }
业务数据的基准时间,按任务粒度截断
周期运行 / 补录 / 重跑均不变
分区值、业务时间字段
计划调度时间
$( )
调度配置中设定的起调时间
固定不变
海外时区场景、保留完整调度时刻
实例执行时间
$[ ]
实例实际开始运行的时间
每次执行都变
日志记录、审计追踪
说明:
关键区别:对于一个天任务(每天 02:00 执行),2026-03-22 正常执行时:
参数
正常周期运行
补录 2026-03-20
重跑 2026-03-22
${yyyyMMddHHmmss}
20260322000000
20260320000000
20260322000000
$(yyyyMMddHHmmss)
20260322020000
20260320020000
20260322020000
$[yyyyMMddHHmmss]
20260322020015
20260325103022
20260326140512
实例数据时间${}):始终是业务日期,截断到天为 00:00:00,补录/重跑不变
计划调度时间$()):保留了具体的调度时刻 02:00:00,补录/重跑不变
实例执行时间$[]):取决于实际何时开始运行,每次都不同

1.2 实例数据时间${}

参数定义:处理业务数据的基准时间。同一实例的数据时间在周期运行、补录、重跑中始终相同
数据时间截断规则
任务类型
计划调度时间(示例)
实例数据时间
截断说明
分钟任务
2026-03-22 14:30:00
2026-03-22 14:30:00
保留到分钟
小时任务
2026-03-22 14:30:00
2026-03-22 14:00:00
截断到整小时
天任务
2026-03-22 02:00:00
2026-03-22 00:00:00
截断到天
周任务
2026-03-22 02:00:00
2026-03-22 00:00:00
截断到天
月任务
2026-03-22 02:00:00
2026-03-22 00:00:00
截断到天
年任务
2026-03-22 02:00:00
2026-03-22 00:00:00
截断到天
测试运行:数据时间为提交执行的时间。
参数格式:使用 ${} 包裹格式串,如 ${yyyyMMddHHmmss}

1.3 计划调度时间$()

参数定义:在任务调度配置中设置的调度时间,也是周期实例生成的时间。比如天任务每天 2 点执行,则计划调度时间为每天 02:00:00
与实例数据时间的关系:计划调度时间保留了完整的调度时刻(如 02:00:00),而实例数据时间会按任务粒度截断(天任务截断为 00:00:00)。对于分钟任务,两者相同。
参数格式:使用 $() 包裹格式串,如 $(yyyyMMddHHmmss)

1.4 实例执行时间$[]

参数定义:实例真实执行的开始时间,是动态变化的。同一个实例在周期执行和补录/重跑时,实例执行时间一定不同
参数格式:使用 $[] 包裹格式串,如 $[yyyyMMddHHmmss]

1.5 通用语法规则

说明:
以下规则三种时间参数通用,仅需替换括号标记:${} / $() / $[]
下文以实例数据时间 ${} 为例进行说明。

1.5.1 时间格式化

支持按需调整参数格式,自由组合年、月、日、时、分、秒:
格式串
描述
示例(数据时间为 2026-03-22 14:30:45
${yyyy}
4 位年份
2026
${MM}
2 位月份
03
${dd}
2 位日期
22
${HH}
2 位小时(24h)
14
${mm}
2 位分钟
30
${ss}
2 位秒
45
${yyyyMMdd}
紧凑日期
20260322
${yyyy-MM-dd}
格式化日期,用 - 拼接
2026-03-22
${HH:mm:ss}
格式化时间,用 : 拼接
14:30:45
${yyyy-MM-dd HH:mm:ss}
完整日期时间
2026-03-22 14:30:45
${yyyyMMddHHmmss}
紧凑完整时间
20260322143045
说明:
计划调度时间使用 $():如 $(yyyy-MM-dd)
实例执行时间使用 $[]:如 $[yyyy-MM-dd]

1.5.2 时间偏移计算

支持按需进行偏移计算,语法为 ${<格式串><±N><单位>}
偏移方向
语法
说明
后 N 年
${yyyyMMdd+Ny}
${yyyyMMdd+2y} → 后 2 年
前 N 年
${yyyyMMdd-Ny}
${yyyyMMdd-1y} → 前 1 年
后 N 月
${yyyyMMdd+NM}
${yyyyMMdd+3M} → 后 3 个月
前 N 月
${yyyyMMdd-NM}
${yyyyMMdd-1M} → 前 1 个月
后 N 周
${yyyyMMdd+Nw}
${yyyyMMdd+1w} → 后 1 周
前 N 周
${yyyyMMdd-Nw}
${yyyyMMdd-2w} → 前 2 周
后 N 天
${yyyyMMdd+Nd}
${yyyyMMdd+7d} → 后 7 天
前 N 天
${yyyyMMdd-Nd}
${yyyyMMdd-1d} → 前 1 天
后 N 小时
${yyyyMMddHHmmss+NH}
${yyyyMMddHHmmss+6H} → 后 6 小时
前 N 小时
${yyyyMMddHHmmss-NH}
${yyyyMMddHHmmss-2H} → 前 2 小时
后 N 分钟
${yyyyMMddHHmmss+Nm}
${yyyyMMddHHmmss+30m} → 后 30 分钟
前 N 分钟
${yyyyMMddHHmmss-Nm}
${yyyyMMddHHmmss-15m} → 前 15 分钟
时间戳(秒)
${timestamp}
10 位 Unix 时间戳
时间戳(毫秒)
${timestamp_ms}
13 位 Unix 时间戳
注意:
偏移语法本身不要求时区前缀。${yyyyMMdd-1d}${UTC+0_yyyyMMdd-1d} 都是有效写法,区别仅在于时区,详情请参见 1.5.4 时区配置

1.5.3 特殊偏移

支持计算当前时间对应的月末、季末、年末等特殊时间点:
偏移标识
全称
说明
示例(数据时间为 2026-03-22
+TE
TENDAY END
当旬旬末
20260331(3月下旬末)
+ME
MONTH END
当月月末
20260331
+QE
QUARTER END
当季季末
20260331(Q1 末)
+HYE
HALF YEAR END
当半年末
20260630
+YE
YEAR END
当年年末
20261231
+TS
TENDAY START
当旬旬初
20260321(3月下旬初)
+MS
MONTH START
当月月初
20260301
+HYS
HALFYEAR START
当半年初
20260101
+YS
YEAR START
当年年初
20260101
+PME
PRI MONTH END
上月月末
20260228
+PYE
PRI YEAR END
上年年末
20251231
语法示例
${yyyyMMdd+ME} :实例数据时间对应的当月月末
$(yyyyMMdd+PME) :计划调度时间对应的上月月末
$[yyyyMMdd+YE] :实例执行时间对应的当年年末

1.5.4 时区配置

支持对时间参数做时区转化,语法为在格式串前添加 UTC+N_ 前缀:
${UTC+0_yyyyMMdd} → 实例数据时间的 UTC+0 时间
$(UTC+7_yyyyMMdd) → 计划调度时间的 UTC+7 时间
$[UTC+9_yyyyMMdd] → 实例执行时间的 UTC+9 时间
默认行为:若未添加时区前缀,默认为 UTC+8(北京时间)。
时区 + 偏移组合:可以同时使用时区和偏移,如 ${UTC+0_yyyyMMdd-1d} 表示 UTC+0 时区下前一天的日期。

1.5.5 完整语法规则

参数语法:
实例数据时间: ${[UTC+N_]<format>[±N<unit>][+<special>]}
计划调度时间: $([UTC+N_]<format>[±N<unit>][+<special>])
实例执行时间: $[[UTC+N_]<format>[±N<unit>][+<special>]]

其中:
[UTC+N_] 可选,时区前缀,N 为整数,默认 UTC+8
<format> yyyy, MM, dd, HH, mm, ss 及其自由组合(支持分隔符)
[±N<unit>] 可选,偏移量
<unit> y(), M(), w(), d(), H(小时), m(分钟)
[+<special>] 可选,特殊偏移标识
TE, ME, QE, HYE, YE, TS, MS, HYS, YS, PME, PYE

1.6 使用建议

推荐使用方式

分区值 / 业务时间字段 → 使用实例数据时间 ${}
实例数据时间是基准时间,在周期执行、补录、重跑场景下值相同,保证数据始终写入正确的时间分区。
海外 / 非 UTC+8 场景 → 使用计划调度时间 $() + 时区前缀
如海外客户以 UTC+0 定义调度时间,建议使用 $(UTC+0_yyyyMMdd)。若使用实例数据时间,在极端跨周期场景下可能存在时间错误。
日志 / 审计 → 使用实例执行时间 $[]
当需要记录"这条数据是什么时候跑出来的"时使用。
全局 T+1 模式 → 在项目管理-参数设置中定义全局参数
参数值设为 ${yyyyMMdd-1d}(当天的前一天),该参数在项目下所有任务中均生效。




使用示例

场景 1:T+1 分区写入(最常见)
今天跑的任务,数据写入昨天的分区:
-- 天任务,2026-03-22 执行,写入 dt='20260321' 分区
INSERT OVERWRITE TABLE dw.user_daily PARTITION(dt='${yyyyMMdd-1d}')
SELECT * FROM ods.user_log
WHERE dt = '${yyyyMMdd-1d}';
场景 2:当天分区写入
业务数据写在分区表中,每天的数据写入当天对应分区:
-- 天任务,2026-03-22 执行
-- ${yyyy-MM-dd} 解析为 '2026-03-22'
SELECT ${yyyy-MM-dd} AS p_date, user_id, action
FROM ods.user_events
WHERE dt = '${yyyyMMdd}';



场景 3:跨月汇总(月初跑上月数据)
-- 每月 1 号跑任务,统计上月全月数据
-- ${yyyyMMdd+PME} → 上月月末, ${yyyyMMdd+MS} → 当月月初(用于定位上月范围)
SELECT COUNT(*) AS order_cnt
FROM dw.order_detail
WHERE dt >= '${yyyyMMdd+PME}' AND dt < '${yyyyMMdd+MS}';
场景 4:Shell 脚本中使用参数
#!/bin/bash
# 时间参数在 Shell 中作为变量注入
echo "Processing data for date: ${yyyyMMdd}"
hdfs dfs -ls /data/warehouse/dt=${yyyyMMdd-1d}/
场景 5:PySpark 中使用参数
# 调度系统会在运行前将参数替换为实际值
data_date = "${yyyyMMdd-1d}"
df = spark.sql(f"SELECT * FROM ods.events WHERE dt = '{data_date}'")
df.write.mode("overwrite").saveAsTable(f"dw.events_daily")

二、其他系统内置参数

2.1 非时间参数列表

参数
含义
示例值
${projectIdent}
项目标识
my_project
${workflowName}
工作流名称
daily_etl
${taskName}
任务名称
user_sync_task
${taskId}
任务 ID
task-abc123
${taskInCharge}
责任人
zhangsan
${taskType}
任务类型
SparkSQL

2.2 使用示例

场景 1:在 SQL 中获取任务上下文信息
SELECT
'${projectIdent}' AS project_ident,
'${workflowName}' AS workflow_name,
'${taskName}' AS task_name,
'${taskId}' AS task_id,
'${taskInCharge}' AS task_in_charge,
'${taskType}' AS task_type,
user_id
FROM wedata_demo_db.user_info
LIMIT 10;
场景 2:指定 Yarn 任务名称
在 SparkSQL、PySpark、Spark 任务中使用 --name + 变量来指定 Yarn 上的任务名称:
--name ${projectIdent}-${workflowName}-${taskInCharge}
在 SparkSQL 连接 Kyuubi 数据源时,使用 spark.app.name 参数指定:
spark.app.name=${projectIdent}-${workflowName}-${taskInCharge}




三、常见问题

补录时参数取的是哪天?

实例数据时间 ${}计划调度时间 $():取的是补录的业务日期(即你指定补录的那个日期),而不是实际执行补录操作的日期。
实例执行时间 $[]:取的是补录操作实际开始执行的时间。

${yyyyMMdd}$(yyyyMMdd) 对于天任务有区别吗?

有区别。以每天 02:00 执行的天任务为例:
${yyyyMMdd}20260322(数据时间,截断到天)
$(yyyyMMdd)20260322(调度时间,日期部分相同)
日期部分相同,但如果包含时分秒:
${yyyyMMddHHmmss}20260322000000(截断为 00:00:00
$(yyyyMMddHHmmss)20260322020000(保留调度时刻 02:00:00

为什么我的参数没有被替换?

常见原因:
1. 括号类型用错${} / $() / $[] 三种括号不可混用
2. 格式串拼写错误:如 ${YYYY} 应为 ${yyyy}(大小写敏感)
3. 多余空格${ yyyyMMdd } 内部不应有空格
4. 非调度环境:参数替换仅在调度系统执行时生效,IDE 中直接运行不会替换

不加 UTC+N_ 时区前缀默认是什么?

默认为 UTC+8(北京时间)。

特殊偏移 MEPME 的区别是什么?

+ME(MONTH END):当前月的月末日期。如数据时间为 2026-03-15,则 ${yyyyMMdd+ME}20260331
+PME(PRI MONTH END):上一个月的月末日期。如数据时间为 2026-03-15,则 ${yyyyMMdd+PME}20260228

偏移计算和时区前缀可以同时使用吗?

可以。语法为 ${UTC+N_<格式串><偏移>},如:
${UTC+0_yyyyMMdd-1d} :UTC+0 时区下前一天的日期
$(UTC+9_yyyyMMddHHmmss+6H) : UTC+9 时区下后 6 小时