任务参数

特别注意：参数功能目前处于灰度阶段，完整的功能仅对部分客户开放使用。可使用文末的方式来验证是否支持。

什么是任务参数

为什么需要参数？

在日常数据开发中，我们经常遇到这样的场景：

每天处理前一天的数据：WHERE dt = '2023-09-21'
每月统计上月数据：WHERE month = '2023-08'
查询特定城市数据：WHERE city = 'Shanghai'

如果把日期、城市等信息写死在代码中，任务运行时就无法动态适应变化。任务参数就是为了解决这个问题而设计的。

参数的核心价值

动态替换：任务运行时自动替换参数值。
灵活配置：支持常量、时间表达式、系统参数。
复用性强：一次定义，多处使用。
易于维护：修改参数无需改动代码逻辑。

基本概念

分类	概念名称	含义	示意
参数定义	自定义参数	指用户在代码中，自定义输入，引用的参数。其格式固定为 ${自定义参数名}	${my_param}
参数赋值	常量	指固定不变的取值，比如字符串和数字，用于给自定义参数赋值	abcd 或 1234
参数赋值	系统内置参数	指由系统内置的一系列参数表达式，用来方便用户获取需要通过计算获取的动态的信息，比如任务实例的计划时间	sys_plan_datetime
参数赋值	系统内置时间函数	指由系统内置的一系列函数表达式，用于对时间做一些常用的转换计算	add_months(yyyy-MM-dd HH:mm:ss,N)

快速开始

三步快速上手

第1步：在代码中使用参数


SELECT * FROM sales_table WHERE city = '${city}' AND dt = '${yesterday}';

第2步：配置参数取值 点击"参数"按钮，系统会自动识别出 city 和 yesterday 两个参数，为它们赋值：

city = Shanghai
yesterday = $[yyyy-MM-dd, -1d]

第3步：运行验证 点击"运行"，系统会将参数替换后执行：


SELECT * FROM sales_table WHERE city = 'Shanghai' AND dt = '2023-09-21';  

-- 假设今天是2023-09-22

关键要点

参数格式固定为：${参数名}。
参数名只能包含字母、数字、下划线。
参数要在定义中使用内置参数或时间表达式等给赋值、然后在代码中引用。不能在代码中直接引用内置参数。
参数替换时，只替换 ${} 内的内容。
如需在SQL中加引号，需自行添加，比如：'${city}'。

参数类型与作用域

系统提供两种参数类型，支持不同的使用场景：

任务参数

特点：

作用范围：仅当前任务
使用场景：任务特定的配置

适用情况：

单个任务独有的参数
需要精细控制的场景
临时性的参数配置

创建方式：方式一：在脚本中输入${自定义参数}后，会将自定义参数自动添加至「参数」弹窗内。方式二：点击参数弹窗，在弹窗内输入信息。

配置项	说明	示例
参数名称	参数的唯一标识	city、yesterday
取值来源	选择"任务"或"任务组"	任务
参数取值	参数的实际值	Shanghai、$[yyyy-MM-dd, -1d]
加密取值	勾选后取值以密文显示	用于密码等敏感信息
是否忽略	勾选后不进行参数替换	将 ${var} 作为普通文本

示例：


-- 在某个具体任务中使用

SELECT * FROM table WHERE status = '${task_status}';

任务组参数

特点：

作用范围：任务组内所有任务
使用场景：多任务共享的配置

适用情况：

多个任务共用的参数（如项目代码、环境标识）
全局性的配置（如数据库名称）
需要统一管理的参数

创建方式：在任务组页面点击「参数」，在弹框中点击「新建」，填写参数名称、参数值。

如果要在具体任务中使用任务组参数，需要在任务参数定义的取值来源中做显式切换，指明该参数取值来源于任务组。

示例：


-- 任务组参数：db_name = warehouse_prod

-- 任务A
SELECT * FROM ${db_name}.table_a;

-- 任务B
SELECT * FROM ${db_name}.table_b;

-- 两个任务都使用同一个db_name参数

参数两种配置方法

方法一：基于代码自动识别

直接在脚本中输入 ${参数名}，系统会自动识别并添加到参数列表。

优点：快速、直观，参数名不会拼写错误。


-- 输入以下代码
SELECT * FROM table WHERE city = '${city}' AND dt = '${dt}';
-- 系统自动识别出 city 和 dt 两个参数

方法二：手动创建后再使用

点击"参数"按钮，在弹窗中点击"新建"，手动输入参数信息。

优点：可以提前定义参数，适合规划性强的场景。

不同运行方式下参数作用效果

临时运行（点击"运行"按钮）：

弹窗提示输入参数值
预览
本次运行生效，不影响已保存的参数配置
适合调试和验证

调度运行（自动定时调度）：

使用已保存的参数配置
根据调度时间动态计算参数值
适合生产环境

系统内置参数

系统预置了一系列常用参数，可直接用于参数赋值，无需手动计算。

请特别注意内置参数无法在代码中被直接引用。

日期时间类参数

参数名	格式	说明	示例（基准时间2023-09-22 18:00:00）
bizdate	yyyyMMdd	业务日期（计划时间-1天）	20230921
sys_biz_day	yyyy-MM-dd	业务日期	2023/9/21
sys_biz_datetime	yyyy-MM-dd HH:mm:ss	业务时间	2023/9/21 18:00
sys_plan_day	yyyy-MM-dd	计划日期	2023/9/22
sys_plan_datetime	yyyy-MM-dd HH:mm:ss	计划时间	2023/9/22 18:00
sys_plan_timestamp	13位时间戳	计划时间戳（毫秒）	1695463200000

任务信息类参数

参数名	说明	示例	注意事项
sys_task_id	任务ID	1002	仅调度运行时支持
sys_task_name	任务名称	demo_task	仅调度运行时支持
sys_task_owner	任务负责人	UAT_TEST	仅调度运行时支持

使用示例


-- 示例1：使用业务日期
SELECT * FROM table WHERE dt = '${dt}';
-- 参数配置：dt = sys_biz_day
-- 调度时间2023-09-22，实际执行：WHERE dt = '2023-09-21'

-- 示例2：使用计划时间戳
SELECT * FROM table WHERE create_time >= ${start_ts};
-- 参数配置：start_ts = sys_plan_timestamp
-- 结果：WHERE create_time >= 1695463200000

-- 示例3：Python任务中使用
task_id = '${task_id}'
print(f"当前任务ID: {task_id}")
-- 参数配置：task_id = sys_task_id

使用建议

业务日期场景：优先使用 bizdate 或 sys_biz_day
需要时分秒：使用 sys_biz_datetime 或 sys_plan_datetime
时间戳计算：使用 sys_plan_timestamp
审计日志：使用 sys_task_* 系列参数记录任务信息

时间表达式详解

时间表达式是参数系统的核心功能，支持灵活的时间格式化和偏移计算。

基础语法


$[时间格式]                    # 基本格式化
$[时间格式, 偏移量]             # 带偏移量
$[时间格式, 偏移1, 偏移2, ...]  # 多个偏移量

时间格式元素

时间表达式遵循 ISO-8601 标准，严格区分大小写。

元素	含义	示例
yyyy	四位年份	2023
yy	两位年份	23
MM	两位月份（01-12）	9
dd	两位日期（01-31）	22
HH	24小时制小时（00-23）	18
mm	分钟（00-59）	59
ss	秒（00-59）	49
.SSS	毫秒	0.377
ZZ	时区	+08:00

常用格式组合


$[yyyy-MM-dd]                         → 2023-09-22
$[yyyyMMdd]                           → 20230922
$[yyyy/MM/dd]                         → 2023/09/22
$[yyyy-MM-dd HH:mm:ss]                → 2023-09-22 18:00:00
$[yyyyMMddHHmmss]                     → 20230922180000
$[HH:mm:ss]                           → 18:00:00
$[yyyy-MM-dd HH:mm:ss.SSSZZ]          → 2023-09-22 18:00:00.377+08:00

常见错误


❌ $[YYYY-MM-DD]           # 大写Y不支持
❌ $[yyyy-mm-dd]           # 小写m是分钟不是月份
❌ $[yyyy-MM-dd hh:mm:ss]  # 小写h是12小时制
✅ $[yyyy-MM-dd HH:mm:ss]  # 正确写法

时间偏移量

支持对时间进行增减操作，使用直观的单位缩写。

单位	缩写	全称	示例
毫秒	ms	milli/millisecond	400ms
秒	s	sec/second	400s
分钟	m	min/minute	3m
小时	h	hour	1h
天	d	day	2d
月	mon	month	1mon
年	y	year	-1y

偏移量示例


-- 单个偏移量
$[yyyy-MM-dd, -1d]                           → 昨天
$[yyyy-MM-dd, 1d]                            → 明天
$[yyyy-MM-dd, -1mon]                         → 上个月今天
$[yyyy-MM-dd, -1y]                           → 去年今天
$[HH:mm:ss, -1h]                             → 1小时前
$[HH:mm:ss, 30m]                             → 30分钟后

-- 多个偏移量（按顺序依次计算）
$[yyyy-MM-dd, -1y, -1mon, -1d]               → 去年上个月昨天
$[yyyy-MM-dd HH:mm:ss, -1d, -2h, -30m]       → 昨天减2小时再减30分钟
$[yyyyMMdd, 1mon, -7d]                       → 下月退7天

完整示例

假设当前计划时间为：2023-09-22 18:30:00


-- 基础格式
SELECT '${today}' as today;
-- 参数配置：today = $[yyyy-MM-dd]
-- 结果：2023-09-22

-- 昨天
SELECT '${yesterday}' as yesterday;
-- 参数配置：yesterday = $[yyyy-MM-dd, -1d]
-- 结果：2023-09-21

-- 上月同一天
SELECT '${last_month}' as last_month;
-- 参数配置：last_month = $[yyyy-MM-dd, -1mon]
-- 结果：2023-08-22

-- 去年昨天
SELECT '${last_year_yesterday}' as last_year_yesterday;
-- 参数配置：last_year_yesterday = $[yyyy-MM-dd, -1y, -1d]
-- 结果：2022-09-21

-- 时分秒
SELECT '${current_time}' as current_time;
-- 参数配置：current_time = $[HH:mm:ss]
-- 结果：18:30:00

-- 1小时前
SELECT '${one_hour_ago}' as one_hour_ago;
-- 参数配置：one_hour_ago = $[HH:mm:ss, -1h]
-- 结果：17:30:00

内置时间函数

除了时间表达式，系统还提供了丰富的时间函数，用于处理更复杂的时间计算场景。

月份相关函数

`first_day_of_month()` - 当月第一天

语法：


first_day_of_month()                        # 默认格式 yyyy-MM-dd
first_day_of_month(format)                  # 指定格式
first_day_of_month(format, duration)        # 带偏移量

示例：


-- 当月第一天
SELECT '${month_start}' as month_start;
-- 参数配置：month_start = first_day_of_month()
-- 假设当前2023-09-22，结果：2023-09-01

-- 上月第一天
SELECT '${last_month_start}' as last_month_start;
-- 参数配置：last_month_start = first_day_of_month('yyyy-MM-dd', '-1mon')
-- 结果：2023-08-01

-- 自定义格式
SELECT '${month_start_yyyymmdd}' as month_start_yyyymmdd;
-- 参数配置：month_start_yyyymmdd = first_day_of_month('yyyyMMdd')
-- 结果：20230901

`last_day_of_month()` - 当月最后一天

语法：


last_day_of_month()                         # 默认格式 yyyy-MM-dd
last_day_of_month(format)                   # 指定格式
last_day_of_month(format, duration)         # 带偏移量

示例：


-- 当月最后一天
SELECT '${month_end}' as month_end;
-- 参数配置：month_end = last_day_of_month()
-- 假设当前2023-09-22，结果：2023-09-30

-- 上月最后一天
SELECT '${last_month_end}' as last_month_end;
-- 参数配置：last_month_end = last_day_of_month('yyyy-MM-dd', '-1mon')
-- 结果：2023-08-31

-- 用于月报统计
SELECT * FROM table WHERE dt BETWEEN '${month_start}' AND '${month_end}';
-- month_start = first_day_of_month()
-- month_end = last_day_of_month()

周相关函数

系统中周一为每周第一天，周日为最后一天。

`first_day_of_week()` - 当周第一天（周一）

语法：


first_day_of_week()                         # 默认格式 yyyy-MM-dd
first_day_of_week(format)                   # 指定格式
first_day_of_week(format, duration)         # 带偏移量

示例：


-- 本周一
SELECT '${week_start}' as week_start;
-- 参数配置：week_start = first_day_of_week()
-- 假设当前2023-09-22(周五)，结果：2023-09-18

-- 上周一
SELECT '${last_week_start}' as last_week_start;
-- 参数配置：last_week_start = first_day_of_week('yyyy-MM-dd', '-1w')
-- 结果：2023-09-11

`last_day_of_week()` - 当周最后一天（周日）

语法：


last_day_of_week()                          # 默认格式 yyyy-MM-dd
last_day_of_week(format)                    # 指定格式
last_day_of_week(format, duration)          # 带偏移量

示例：


-- 本周日
SELECT '${week_end}' as week_end;
-- 参数配置：week_end = last_day_of_week()
-- 假设当前2023-09-22(周五)，结果：2023-09-24

-- 上周日
SELECT '${last_week_end}' as last_week_end;
-- 参数配置：last_week_end = last_day_of_week('yyyy-MM-dd', '-1w')
-- 结果：2023-09-17

-- 用于周报统计
SELECT * FROM table WHERE dt BETWEEN '${week_start}' AND '${week_end}';
-- week_start = first_day_of_week()
-- week_end = last_day_of_week()

`day_of_week()` - 返回是周几

语法：


day_of_week()                               # 今天是周几
day_of_week(duration)                       # 偏移后是周几

返回值：整数 1-7（1=周一，7=周日）

示例：


-- 判断今天是周几
SELECT ${weekday} as weekday;
-- 参数配置：weekday = day_of_week()
-- 假设今天是2023-09-25（周一），结果：1

-- 昨天是周几
SELECT ${yesterday_weekday} as yesterday_weekday;
-- 参数配置：yesterday_weekday = day_of_week('-1d')
-- 结果：7（周日）

-- Python中使用
weekday = ${weekday}
if weekday == 1:
    print("今天是周一")
-- 参数配置：weekday = day_of_week()

`get_day_of_week()` - 获取指定周几的日期

语法：


get_day_of_week(format, whichDay)                      # 本周的周几
get_day_of_week(format, whichDay, duration)            # 偏移后那周的周几

参数说明：

format：返回日期的格式
whichDay：1-7，表示周一到周日
duration：可选，时间偏移量

示例：


-- 本周二
SELECT '${this_tuesday}' as this_tuesday;
-- 参数配置：this_tuesday = get_day_of_week('yyyy-MM-dd', 2)
-- 假设当前2023-09-22（周五），结果：2023-09-19

-- 上周三
SELECT '${last_wednesday}' as last_wednesday;
-- 参数配置：last_wednesday = get_day_of_week('yyyy-MM-dd', 3, '-1w')
-- 结果：2023-09-13-- 下周五SELECT '${next_friday}' as next_friday;
-- 参数配置：next_friday = get_day_of_week('yyyy-MM-dd', 5, '1w')
-- 结果：2023-09-29

-- 昨天所在周的周二
SELECT '${tuesday_of_yesterday_week}' as tuesday_of_yesterday_week;
-- 参数配置：tuesday_of_yesterday_week = get_day_of_week('yyyy-MM-dd', 2, '-1d')
-- 假设今天2023-09-25（周一），昨天2023-09-24（周日），昨天所在周是上周
-- 结果：2023-09-19

`week_of_month()` - 本月第几周

语法：


week_of_month()                             # 今天在本月第几周
week_of_month(duration)                     # 偏移后在当月第几周

返回值：整数，表示在当月的第几周

示例：


-- 今天是本月第几周
SELECT ${week_num} as week_num;
-- 参数配置：week_num = week_of_month()
-- 假设今天2023-09-22，结果：4（第4周）

-- 上月今天是第几周
SELECT ${last_month_week} as last_month_week;
-- 参数配置：last_month_week = week_of_month('-1mon')

`week_of_year()` - 本年第几周

语法：


week_of_year()                              # 今天在本年第几周
week_of_year(duration)                      # 偏移后在当年第几周

返回值：整数，表示在当年的第几周

示例：


-- 今天是本年第几周
SELECT ${week_of_year} as week_of_year;
-- 参数配置：week_of_year = week_of_year()
-- 假设今天2023-09-22，结果：38（第38周）
-- 去年今天是第几周SELECT ${last_year_week} as last_year_week;
-- 参数配置：last_year_week = week_of_year('-1y')

时间戳函数

`timestamp()` - 毫秒时间戳

语法：


timestamp()                                 # 当前计划时间戳
timestamp(offset1, offset2, ...)            # 带偏移量的时间戳

返回值：13位毫秒时间戳

示例：


-- 当前时间戳
SELECT ${current_ts} as current_ts;
-- 参数配置：current_ts = timestamp()
-- 假设当前2023-09-22 18:00:00，结果：1695463200000

-- 昨天此刻时间戳
SELECT ${yesterday_ts} as yesterday_ts;
-- 参数配置：yesterday_ts = timestamp(-1d)
-- 结果：1695376800000

-- 一周前减2小时的时间戳
SELECT ${ts} as ts;
-- 参数配置：ts = timestamp(-1w, -2h)

`biz_timestamp()` - 业务时间戳（基于00:00:00）

语法：


biz_timestamp()                             # 今天00:00:00时间戳
biz_timestamp(offset1, offset2, ...)        # 带偏移量

返回值：13位毫秒时间戳，基于当天00:00:00计算

示例：


-- 今天00:00:00时间戳
SELECT ${today_start_ts} as today_start_ts;
-- 参数配置：today_start_ts = biz_timestamp()
-- 假设当前2023-09-22 18:00:00，结果：1695398400000（2023-09-22 00:00:00）

-- 昨天00:00:00时间戳
SELECT ${yesterday_start_ts} as yesterday_start_ts;
-- 参数配置：yesterday_start_ts = biz_timestamp(-1d)
-- 结果：1695312000000（2023-09-21 00:00:00）

-- 用于查询全天数据
SELECT * FROM tableWHERE create_time >= ${start_ts} AND create_time < ${end_ts};
-- start_ts = biz_timestamp()       # 今天00:00:00
-- end_ts = biz_timestamp(1d)       # 明天00:00:00

`unix_timestamp()` - 秒时间戳

语法：


unix_timestamp()                            # 当前计划时间秒时间戳
unix_timestamp(offset1, offset2, ...)       # 带偏移量

返回值：10位秒时间戳

示例：


-- 当前秒时间戳
SELECT ${current_unix_ts} as current_unix_ts;
-- 参数配置：current_unix_ts = unix_timestamp()
-- 假设当前2023-09-22 18:00:00，结果：1695463200

-- 昨天秒时间戳
SELECT ${yesterday_unix_ts} as yesterday_unix_ts;
-- 参数配置：yesterday_unix_ts = unix_timestamp(-1d)
-- 结果：1695376800

`biz_unix_timestamp()` - 业务秒时间戳

语法：


biz_unix_timestamp()                        # 今天00:00:00秒时间戳
biz_unix_timestamp(offset1, offset2, ...)   # 带偏移量

返回值：10位秒时间戳，基于当天00:00:00计算

示例：


-- 今天00:00:00秒时间戳
SELECT ${today_start_unix_ts} as today_start_unix_ts;
-- 参数配置：today_start_unix_ts = biz_unix_timestamp()
-- 假设当前2023-09-22 18:00:00，结果：1695398400

-- 昨天00:00:00秒时间戳
SELECT ${yesterday_start_unix_ts} as yesterday_start_unix_ts;
-- 参数配置：yesterday_start_unix_ts = biz_unix_timestamp(-1d)
-- 结果：1695312000

格式化函数

`$[format, offset...]` - 灵活的时间格式化

这是最基础也是最常用的函数，前面"时间表达式"章节已详细介绍。

语法：


$[format]                                   # 格式化当前时间
$[format, offset1, offset2, ...]            # 带偏移量格式化

`biz_format()` - 业务时间格式化

语法：


biz_format(format)                          # 格式化今天00:00:00
biz_format(format, offset1, offset2, ...)   # 带偏移量

返回值：格式化后的时间字符串，基于当天00:00:00计算

示例：


-- 今天00:00:00
SELECT '${today_start}' as today_start;
-- 参数配置：today_start = biz_format('yyyy-MM-dd HH:mm:ss')
-- 假设当前2023-09-22 18:00:00，结果：2023-09-22 00:00:00

-- 昨天00:00:00
SELECT '${yesterday_start}' as yesterday_start;
-- 参数配置：yesterday_start = biz_format('yyyy-MM-dd HH:mm:ss', -1d)
-- 结果：2023-09-21 00:00:00

-- 去年今天00:00:00
SELECT '${last_year_today_start}' as last_year_today_start;
-- 参数配置：last_year_today_start = biz_format('yyyy-MM-dd HH:mm:ss', -1y)
-- 结果：2022-09-22 00:00:00

函数选择建议

场景	推荐函数	示例
查询昨天数据	$[yyyy-MM-dd, -1d]	WHERE dt = '${yesterday}'
本月统计	first_day_of_month() + last_day_of_month()	WHERE dt BETWEEN ... AND ...
本周统计	first_day_of_week() + last_day_of_week()	WHERE dt BETWEEN ... AND ...
按周几统计	get_day_of_week()	获取每周二的数据
时间戳范围查询	biz_timestamp()	WHERE ts >= ${start} AND ts < ${end}
审计日志	sys_plan_datetime	记录任务执行时间

快速参考表

常用时间参数速查

需求	参数配置	示例结果（基准2023-09-22）
今天	$[yyyy-MM-dd] 或 sys_plan_day	2023/9/22
昨天	$[yyyy-MM-dd, -1d] 或 sys_biz_day	2023/9/21
明天	$[yyyy-MM-dd, 1d]	2023/9/23
上周同一天	$[yyyy-MM-dd, -7d]	2023/9/15
上月同一天	$[yyyy-MM-dd, -1mon]	2023/8/22
去年同一天	$[yyyy-MM-dd, -1y]	2022/9/22
本月第一天	first_day_of_month()	2023/9/1
本月最后一天	last_day_of_month()	2023/9/30
上月第一天	first_day_of_month('yyyy-MM-dd', '-1mon')	2023/8/1
上月最后一天	last_day_of_month('yyyy-MM-dd', '-1mon')	2023/8/31
本周一	first_day_of_week()	2023/9/18
本周日	last_day_of_week()	2023/9/24
上周一	first_day_of_week('yyyy-MM-dd', '-1w')	2023/9/11
上周日	last_day_of_week('yyyy-MM-dd', '-1w')	2023/9/17
本周二	get_day_of_week('yyyy-MM-dd', 2)	2023/9/19
上周三	get_day_of_week('yyyy-MM-dd', 3, '-1w')	2023/9/13
去年昨天	$[yyyy-MM-dd, -1y, -1d]	2022/9/21

常用格式速查

格式需求	参数配置	示例结果
yyyyMMdd	$[yyyyMMdd]	20230922
yyyy-MM-dd	$[yyyy-MM-dd]	2023/9/22
yyyy/MM/dd	$[yyyy/MM/dd]	2023/9/22
yyyyMMddHHmmss	$[yyyyMMddHHmmss]	20230922180000
yyyy-MM-dd HH:mm:ss	$[yyyy-MM-dd HH:mm:ss]	2023/9/22 18:00
HH:mm:ss	$[HH:mm:ss]	18:00:00
毫秒时间戳	timestamp()	1695463200000
秒时间戳	unix_timestamp()	1695463200

系统参数速查

参数名	说明	格式	调度运行	临时运行
bizdate	业务日期（计划时间-1天）	yyyyMMdd	✓	✓
sys_biz_day	业务日期	yyyy-MM-dd	✓	✓
sys_biz_datetime	业务时间	yyyy-MM-dd HH:mm:ss	✓	✓
sys_plan_day	计划日期	yyyy-MM-dd	✓	✓
sys_plan_datetime	计划时间	yyyy-MM-dd HH:mm:ss	✓	✓
sys_plan_timestamp	计划时间戳	13位毫秒	✓	✓
sys_task_id	任务ID	整数	✓	✗
sys_task_name	任务名称	字符串	✓	✗
sys_task_owner	任务负责人	字符串	✓	✗

偏移量单位速查

单位	缩写	全称	示例
毫秒	ms	milli/millisecond	400ms
秒	s	sec/second	30s
分钟	m	min/minute	15m
小时	h	hour	2h
天	d	day	-1d
周	w	week	-1w
月	mon	month	-1mon
年	y	year	-1y

时间函数速查

函数	功能	示例
first_day_of_month()	当月第一天	first_day_of_month('yyyy-MM-dd', '-1mon')
last_day_of_month()	当月最后一天	last_day_of_month()
first_day_of_week()	当周第一天（周一）	first_day_of_week('yyyy-MM-dd')
last_day_of_week()	当周最后一天（周日）	last_day_of_week()
day_of_week()	返回周几（1-7）	day_of_week('-1d')
week_of_month()	本月第几周	week_of_month()
week_of_year()	本年第几周	week_of_year()
get_day_of_week()	获取指定周几的日期	get_day_of_week('yyyy-MM-dd', 2, '-1w')
timestamp()	毫秒时间戳	timestamp(-1d)
biz_timestamp()	业务时间戳（00:00:00）	biz_timestamp(-1d)
unix_timestamp()	秒时间戳	unix_timestamp()
biz_unix_timestamp()	业务秒时间戳	biz_unix_timestamp()
biz_format()	业务时间格式化	biz_format('yyyy-MM-dd', -1d)

实际场景示例

场景1：处理昨天的分区数据

需求：每天凌晨处理前一天的订单数据


-- SQL任务
INSERT OVERWRITE TABLE order_summary PARTITION(dt='${yesterday}')
SELECT 
    order_id,
    SUM(amount) as total_amount,
    COUNT(*) as order_count
FROM order_detail
WHERE dt = '${yesterday}'
GROUP BY order_id;

参数配置：

yesterday = $[yyyy-MM-dd, -1d]

说明：假设任务在2023-09-22执行，参数替换为 2023-09-21

场景2：生成月报（上月数据统计）

需求：每月1号生成上月的销售报表


-- SQL任务
SELECT 
    product_id,
    SUM(sales_amount) as total_sales,
    COUNT(DISTINCT user_id) as unique_users
FROM sales_table
WHERE dt BETWEEN '${last_month_start}' AND '${last_month_end}'
GROUP BY product_id;

参数配置：

last_month_start = first_day_of_month('yyyy-MM-dd', '-1mon')
last_month_end = last_day_of_month('yyyy-MM-dd', '-1mon')

说明：假设在2023-09-01执行

last_month_start → 2023-08-01
last_month_end → 2023-08-31

场景3：周报统计（上周一到周日）

需求：每周一生成上周的用户活跃报告


-- SQL任务
SELECT 
    DATE(login_time) as login_date,
    COUNT(DISTINCT user_id) as active_users
FROM user_login_log
WHERE dt BETWEEN '${last_week_monday}' AND '${last_week_sunday}'
GROUP BY DATE(login_time)
ORDER BY login_date;

参数配置：

last_week_monday = first_day_of_week('yyyy-MM-dd', '-1w')
last_week_sunday = last_day_of_week('yyyy-MM-dd', '-1w')

说明：假设在2023-09-25（周一）执行

last_week_monday → 2023-09-18（上周一）
last_week_sunday → 2023-09-24（上周日）

场景4：获取每周二的数据

需求：定期分析每周二的促销活动效果


-- SQL任务
SELECT 
    promotion_id,
    SUM(sales_amount) as tuesday_sales
FROM sales_table
WHERE dt = '${this_tuesday}'
GROUP BY promotion_id;

参数配置：

this_tuesday = get_day_of_week('yyyy-MM-dd', 2)

说明：

假设任务在2023-09-22（周五）执行 → 2023-09-19（本周二）
假设任务在2023-09-25（周一）执行 → 2023-09-26（本周二）

场景5：时间戳范围查询（查询今天全天数据）

需求：实时查询今天00:00:00到当前时间的订单数据


-- SQL任务
SELECT 
    order_id,
    order_time,
    amount
FROM orders
WHERE order_timestamp >= ${today_start_ts} 
  AND order_timestamp < ${current_ts};

参数配置：

today_start_ts = biz_timestamp()
current_ts = timestamp()

说明：假设当前2023-09-22 18:30:00

today_start_ts → 1695398400000（2023-09-22 00:00:00）
current_ts → 1695465000000（2023-09-22 18:30:00）

场景6：同比数据对比（去年同期）

需求：对比今年与去年同期的销售数据


-- SQL任务
SELECT 
    '本年' as year_type,
    SUM(sales_amount) as total_sales
FROM sales_table
WHERE dt BETWEEN '${this_year_start}' AND '${this_year_end}'

UNION ALL

SELECT 
    '去年同期' as year_type,
    SUM(sales_amount) as total_sales
FROM sales_table
WHERE dt BETWEEN '${last_year_start}' AND '${last_year_end}';

参数配置：

this_year_start = first_day_of_month('yyyy-MM-dd')
this_year_end = $[yyyy-MM-dd]
last_year_start = first_day_of_month('yyyy-MM-dd', '-1y')
last_year_end = $[yyyy-MM-dd, -1y]

说明：假设在2023-09-22执行

本年：2023-09-01 到 2023-09-22
去年同期：2022-09-01 到 2022-09-22

场景7：多时区数据处理

需求：处理包含时区信息的国际业务数据


-- SQL任务
SELECT 
    order_id,
    '${order_time_with_tz}' as order_time
FROM orders
WHERE created_date = '${yesterday}';

参数配置：

yesterday = $[yyyy-MM-dd, -1d]
order_time_with_tz = $[yyyy-MM-dd HH:mm:ss.SSSZZ]

说明：假设在2023-09-22 18:30:00.500执行（东八区）

order_time_with_tz → 2023-09-22 18:30:00.500+08:00

场景8：动态分区和文件路径

需求：将处理结果按日期分区存储，并生成带日期的文件


-- Python任务
import pandas as pd

# 获取参数
partition_date = '${partition_date}'
file_name = f'report_{partition_date.replace("-", "")}.csv'

# 数据处理
df = pd.read_sql(f"""
    SELECT * FROM table 
    WHERE dt = '{partition_date}'
""", conn)

# 保存文件
df.to_csv(f'/output/{file_name}', index=False)
print(f'文件已保存：{file_name}')

参数配置：

partition_date = $[yyyy-MM-dd, -1d]

说明：假设在2023-09-22执行

partition_date → 2023-09-21
file_name → report_20230921.csv

场景9：任务审计日志

需求：记录任务执行信息用于审计和监控


-- SQL任务
INSERT INTO task_audit_log (
    task_id,
    task_name,
    task_owner,
    execute_time,
    biz_date,
    status
) VALUES (
    ${task_id},
    '${task_name}',
    '${task_owner}',
    '${execute_time}',
    '${biz_date}',
    'SUCCESS'
);

参数配置：

task_id = sys_task_id
task_name = sys_task_name
task_owner = sys_task_owner
execute_time = sys_plan_datetime
biz_date = sys_biz_day

说明：仅在调度运行时生效，临时运行时任务信息参数不可用

场景10：环境配置管理（任务组参数）

需求：多个任务共享数据库配置，便于切换环境


-- 任务组参数配置（在任务组级别设置）
-- db_name = warehouse_prod
-- table_prefix = prod_

-- 任务A
SELECT * FROM ${db_name}.${table_prefix}orders 
WHERE dt = '${yesterday}';

-- 任务B  
SELECT * FROM ${db_name}.${table_prefix}users
WHERE register_date = '${yesterday}';

-- 任务C
INSERT INTO ${db_name}.${table_prefix}summary
SELECT * FROM temp_table;

参数配置：

任务组参数：
- db_name = warehouse_prod
- table_prefix = prod_
任务参数（在任务中单独设定）：
- yesterday = $[yyyy-MM-dd, -1d]

优势：

切换环境时只需修改任务组参数
测试环境：db_name = warehouse_test, table_prefix = test_
生产环境：db_name = warehouse_prod, table_prefix = prod_

常见问题FAQ

Q1：参数没有被替换，仍然显示 `${param}` 怎么办？

可能原因：

参数被设置为"忽略"状态
参数名拼写错误（代码中与配置中不一致）
参数值未配置

解决方法：

检查参数配置中是否勾选了"是否忽略"
确认代码中的 ${param} 与参数配置中的名称完全一致
确保参数取值已填写

Q2：时间参数计算结果不对？

检查清单：

格式大小写：确认使用 yyyy-MM-dd 而不是 YYYY-MM-DD 或 yyyy-mm-dd
偏移单位：确认使用正确的单位（d=天，mon=月，y=年）
多偏移量顺序：多个偏移量按顺序依次计算
基准时间：确认是基于计划时间还是业务时间（00:00:00）

示例：


-- ❌ 错误写法
$[YYYY-MM-DD]           # 大写Y不支持
$[yyyy-mm-dd, -1m]      # m是分钟不是月份
$[yyyy-MM-dd, -1M]      # 月份应该用mon-- 

✅ 正确写法
$[yyyy-MM-dd]
$[yyyy-MM-dd, -1d]
$[yyyy-MM-dd, -1mon]

Q3：如何在引号中正确使用参数？

重要提示：参数替换只替换 ${} 内的内容，不会自动添加引号。

正确用法：


-- ✅ 字符串类型需要加引号
WHERE city = '${city}'
WHERE dt = '${yesterday}'

-- ✅ 数值类型不需要引号
WHERE id = ${user_id}
WHERE amount > ${threshold}

-- ✅ 时间戳不需要引号
WHERE create_time >= ${start_ts}

错误用法：


-- ❌ 缺少引号导致SQL语法错误
WHERE city = ${city}        # 替换后：WHERE city = Shanghai（语法错误）

-- ❌ 多余的引号
WHERE id = '${user_id}'     # 替换后：WHERE id = '12345'（类型错误）

Q4：临时运行和调度运行的参数有什么区别？

维度	临时运行	调度运行
参数来源	弹窗手动输入	参数配置中的取值
生效范围	仅本次运行	每次调度都生效
时间基准	点击运行的时刻	调度计划时间
任务信息参数	不支持（无实际任务实例）	支持 sys_task_* 系列参数
适用场景	调试、验证	生产环境自动运行

注意：临时运行时输入的参数值不会保存到参数配置中，参数配置中只保存给参数赋值的逻辑。

Q5：如何验证参数配置是否正确？

使用简单查询验证


SELECT '${lastDay}' as lastDay;

参数配置：lastDay = add_days('yyyy-MM-dd', -1)

查看执行日志 执行后查看日志中的实际执行SQL，确认参数是否正确替换。

如果返回昨天的日期（如 2023-09-21），说明参数功能正常。

Q6：Python任务中如何使用参数？

示例：


# 定义参数（使用字符串变量）
yesterday = '${yesterday}'
start_ts = ${start_ts}
task_name = '${task_name}'

# 使用参数
print(f"处理日期：{yesterday}")
print(f"开始时间戳：{start_ts}")

# 在SQL中使用
sql = f"""
    SELECT * FROM table 
    WHERE dt = '{yesterday}'
      AND create_time >= {start_ts}
"""

参数配置：

yesterday = $[yyyy-MM-dd, -1d]
start_ts = biz_timestamp()
task_name = sys_task_name

注意：

字符串类型参数需要加引号：'${yesterday}'
数值类型参数不加引号：${start_ts}

Q7：如何处理月末日期偏移问题？

问题：1月31日减1个月应该是12月31日，但有些月份没有31日

解决方案：使用 last_day_of_month() 函数


-- 推荐写法（明确要上月最后一天）
SELECT '${last_month_end}' as last_month_end;
-- 参数配置：last_month_end = last_day_of_month('yyyy-MM-dd', '-1mon')
-- 始终返回上月最后一天

Q8：如何调试复杂的参数表达式？

技巧1：逐步验证


-- 先验证基础表达式
SELECT '${base_date}' as base_date;
-- base_date = $[yyyy-MM-dd]

-- 再添加偏移量
SELECT '${offset_date}' as offset_date;
-- offset_date = $[yyyy-MM-dd, -1mon]

-- 最后添加多个偏移量
SELECT '${final_date}' as final_date;
-- final_date = $[yyyy-MM-dd, -1mon, -7d]

技巧2：使用注释说明


SELECT 
    '${report_start}' as report_start,  -- 上月第一天
    '${report_end}' as report_end,      -- 上月最后一天
    '${last_year_date}' as last_year_date  -- 去年同期
FROM table;

在参数配置中也添加说明，方便后续维护。

Q9：参数加密后如何修改？

步骤：

点击参数配置，找到加密的参数
取消勾选"加密取值"
参数值会明文显示，可以修改
修改完成后重新勾选"加密取值"

注意：加密仅用于显示，不影响参数实际使用。

附录：如何确认是否支持完整参数功能？

使用以下验证SQL：


SELECT '${lastDay}' as lastDay;

参数配置：

lastDay 赋值填写 add_days('yyyy-MM-dd', -1)

校验逻辑：


检查参数替换、任务执行返回结果是否正常。
如果返回正常，则说明在灰度范围内、支持完整的参数功能，否则说明不支持。
假定当前日期是2023-11-12，正常的返回值会是2023-11-11。

联系我们

任务参数

什么是任务参数

为什么需要参数？

参数的核心价值

基本概念

快速开始

三步快速上手

关键要点

参数类型与作用域

任务参数

任务组参数

参数两种配置方法

方法一：基于代码自动识别

方法二：手动创建后再使用

不同运行方式下参数作用效果

系统内置参数

日期时间类参数

任务信息类参数

使用示例

使用建议

时间表达式详解

基础语法

时间格式元素

常用格式组合

常见错误

时间偏移量

偏移量示例

完整示例

内置时间函数

月份相关函数

first_day_of_month() - 当月第一天

last_day_of_month() - 当月最后一天

周相关函数

first_day_of_week() - 当周第一天（周一）

last_day_of_week() - 当周最后一天（周日）

day_of_week() - 返回是周几

get_day_of_week() - 获取指定周几的日期

week_of_month() - 本月第几周

week_of_year() - 本年第几周

时间戳函数

timestamp() - 毫秒时间戳

biz_timestamp() - 业务时间戳（基于00:00:00）

unix_timestamp() - 秒时间戳

biz_unix_timestamp() - 业务秒时间戳

格式化函数

$[format, offset...] - 灵活的时间格式化

biz_format() - 业务时间格式化

函数选择建议

快速参考表

常用时间参数速查

常用格式速查

系统参数速查

偏移量单位速查

时间函数速查

实际场景示例

场景1：处理昨天的分区数据

场景2：生成月报（上月数据统计）

场景3：周报统计（上周一到周日）

场景4：获取每周二的数据

场景5：时间戳范围查询（查询今天全天数据）

场景6：同比数据对比（去年同期）

场景7：多时区数据处理

场景8：动态分区和文件路径

场景9：任务审计日志

场景10：环境配置管理（任务组参数）

常见问题FAQ

Q1：参数没有被替换，仍然显示 ${param} 怎么办？

Q2：时间参数计算结果不对？

Q3：如何在引号中正确使用参数？

Q4：临时运行和调度运行的参数有什么区别？

Q5：如何验证参数配置是否正确？

Q6：Python任务中如何使用参数？

Q7：如何处理月末日期偏移问题？

Q8：如何调试复杂的参数表达式？

Q9：参数加密后如何修改？

附录：如何确认是否支持完整参数功能？

`first_day_of_month()` - 当月第一天

`last_day_of_month()` - 当月最后一天

`first_day_of_week()` - 当周第一天（周一）

`last_day_of_week()` - 当周最后一天（周日）

`day_of_week()` - 返回是周几

`get_day_of_week()` - 获取指定周几的日期

`week_of_month()` - 本月第几周

`week_of_year()` - 本年第几周

`timestamp()` - 毫秒时间戳

`biz_timestamp()` - 业务时间戳（基于00:00:00）

`unix_timestamp()` - 秒时间戳

`biz_unix_timestamp()` - 业务秒时间戳

`$[format, offset...]` - 灵活的时间格式化

`biz_format()` - 业务时间格式化

Q1：参数没有被替换，仍然显示 `${param}` 怎么办？