Skip to content

parameter desc

Jump to bottom
qifeng dai edited this page Jul 28, 2017 · 18 revisions

在开发任务的过程中，我们需要有一些系统变量作为参数传给程序，比如，对于一个日常的 ETL 程序，需要每天进行调度，每天分析的数据是前一天的，而数据都是按照时间进行分区，类似的程序可能是这样的：

SELECT product_id, avg(price) FROM tb_order WHERE dt='20170307' GROUP BY product_id;

对于上面的 ETL，我在 20170308 号去运行它是没有问题的，但是，后面每天调度之前都需要修改时间，这显然是不可取的，合理的做法是改为这样：

SELECT product_id, avg(price) FROM tb_order WHERE dt='${date-variant}' GROUP BY product_id;

实际调度的时候，这个 date-variant 会根据调度的日期来进行替换，是一个动态的值。

下面我们会对相关的参数进行介绍。

1.系统参数

这里先定义几个变量：

  1. ${sf.system.bizdate}: 日常调度实例定时的时间日期的前一天，格式为 yyyyMMdd，这个变量的翻译分为三种：
  • 直接运行：直接运行的时候，这个变量指的是运行日期的前一天。
  • 定时调度：对于定时任务，比如每天 2:00 运行，或每小时运行一次等，那么如果是 2016.08.18 调度它的，该变量则会解释为 20160817。
  • 补数据：还有一种场景是补数据，我们可能补 2016.08.18 号的数据，那这个变量的值是 20160818，而非 20160817。

  1. ${sf.system.bizcurdate}: 日常调度实例定时的定时时间日期，格式为 yyyyMMdd，取值为 ${sf.system.bizdate} + 1。

  2. ${sf.system.execId}: 执行的 id，每个工作流执行的时候，有一个唯一的执行 id，大部分情况下，用户不需要关注该参数。

  3. ${sf.system.jobId}: 运行的 job id，每个结点执行的时候，有一个唯一的 job id，大部分情况下，用户不需要关注该参数，该参数仅用于获取结点的日志文件。

现在我们以一个实例来说明下如何对这两个变量进行翻译：

INSERT INTO TABLE stat FROM (SELECT appkey, count(0) FROM tb1 GROUP BY appkey WHERE ds ='${sf.system.bizdate}');
SELECT * FROM tb1 WHERE ds ='${sf.system.bizcurdate}';

上面 SQL 语句执行的时间是 2017-03-08 10:51:36。

  1. 如果我们直接运行上面的语句，那么 ${sf.system.bizdate} 替换为 20170307, ${sf.system.bizcurdate} 替换为 20170308。
  2. 如果是调度，比如我们工作流设置为小时调度，每天 00:00-23:59 时间段里每隔 1 小时执行一次，那么在 2017-03-08 当天，工作流调度生成 24 个实例：
  • 第一个实例定时时间为 2017-03-08 00:00:00，则：${sf.system.bizdate} 替换的结果为 20170307，${sf.system.bizcurdate} 替换的结果为 20170308。
  • 第二个实例定时时间为 2017-03-08 01:00:00，则：${sf.system.bizdate} 替换的结果为 20170307，${sf.system.bizcurdate} 替换的结果为 20170308。

依次类推，它们的时间都是一样的。

如果是补数据，我们实际上会设置补哪天的数据，比如我要补的是 2017-02-12 ~ 2017-02-20 的数据，然后补数据频率是每天 15:00 运行，那么我们解析如下：

  • 第一个实例定时时间为 2017-02-12 15:00:00，则：${sf.system.bizdate} 替换的结果为 20170212，${sf.system.bizcurdate} 替换的结果为 20170213。
  • 第二个实例定时时间为 2017-02-13 15:00:00，则：${sf.system.bizdate} 替换的结果为 20170213，${sf.system.bizcurdate} 替换的结果为 20170214。
  • 第三个实例补数据为 2017-02-14 15:00:00，则：${sf.system.bizdate} 替换的结果为 20170214，${sf.system.bizcurdate} 替换的结果为 20170215。

上面的时间也许能满足大部分需求了，但是相对比较粗，只能精确到日期，所以我们又定义了：${sf.system.cyctime}，格式 yyyyMMddHHmmss，表示的是日常调度实例定时时间（年月日时分秒）。

其中，yyyy 表示 4 位数年份，MM 表示 2 位数月份，dd 表示 2 位数天，HH 表示 24 小时制的时，mm 表示 2 位数分钟，ss 表示 2 位数秒。

我们还是以一个实例来说明如何对其进行解释。

SELECT * FROM tb1 WHERE ds ='${sf.system.cyctime}';

上面 SQL 语句执行的时间是 2017-03-08 10:51:36。

如果我们直接运行上面的语句，那么 ${sf.system.cyctime} 替换为 20170308105136。

如果是调度，比如我们工作流设置为小时调度，每天 00:00-23:59 时间段里每隔 1 小时执行一次，那么 2017-03-08 当天，工作流调度生成 24 个实例：

  • 第一个实例定时时间为 2017-03-08 00:00:00，则：${sf.system.cyctime} 替换的结果为 20170308000000。
  • 第二个实例定时时间为 2017-03-08 01:00:00，则：${sf.system.cyctime} 替换的结果为 20170308010000。

如果是补数据，我们实际上会设置补数据的时间，比如我要补的是 2017-02-12 ~ 2017-02-20 数据，是每天 15:00 运行，那么我们解析如下：

  1. 第一个实例定时时间为 2017-02-12 15:00:00，则：${sf.system.cyctime} 替换的结果为 20170213150000。
  2. 第二个实例定时时间为 2017-02-13 15:00:00，则：${sf.system.cyctime} 替换的结果为 20170214150000。
  3. 第三个实例定时时间为 2017-02-14 15:00:00，则：${sf.system.cyctime} 替换的结果为 20170215150000。

依次类推。

  • 系统参数总结
变量名称 含义 示例
${sf.system.bizdate} 日常调度实例定时的定时时间前一天，格式为 yyyyMMdd，补数据时，该日期 +1
${sf.system.bizcurdate} 日常调度实例定时的定时时间，格式为 yyyyMMdd，补数据时，该日期 +1
${sf.system.cyctime} 日常调度实例定时的定时时间，格式为 yyyyMMddHHmmss，补数据时，该日期 +1

2.自定义参数

支持代码中自定义变量名，声明方式：${变量名}。那么变量的值怎么设置呢？可以是引用 "系统参数" 或指定 "常量", 当然也可以混合使用。

如，我们可以配置: ${tableName} 为 table1。

自定义参数的一个强大之处还在于，可以基于系统参数 ${dw.system.cyctime} 来定义，这里实际上定义了一个基准参数。

其实基准参数:

${dw.system.cyctime}=$[yyyyMMddHHmmss]

注意，我们定义这种基准变量为 $[...] 格式的，$[yyyyMMddHHmmss] 是可以任意分解组合的，比如：$[yyyyMMdd], $[HHmmss], $[yyyy-MM-dd], $[HH:mm:ss] 等。

注意 $[...] 中的 ... 不允许出现空格。

另外，我们定义获取 "+/-周期" 的方法：

注意：下面的 yyyyMMdd, HHmmss 都可以随意扩展，比如可以替换为 yyyyMMddHHmmss, yyyy-MM-dd/HHmmss 等等。

  • 后 N 年：$[add_months(yyyyMMdd,12*N)]
  • 前 N 年：$[add_months(yyyyMMdd,-12*N)]
  • 后 N 月：$[add_months(yyyyMMdd,N)]
  • 前 N 月：$[add_months(yyyyMMdd,-N)]
  • 后 N 周：$[yyyyMMdd+7*N]
  • 前 N 周：$[yyyyMMdd-7*N]
  • 后 N 天：$[yyyyMMdd+N]
  • 前 N 天：$[yyyyMMdd-N]
  • 后 N 小时：$[HHmmss+N/24]
  • 前 N 小时：$[HHmmss-N/24]
  • 后 N 分钟：$[HHmmss+N/24/60]
  • 前 N 分钟：$[HHmmss-N/24/60]

另外，我们定义了如下的一些规则：

  • $[month_begin(yyyyMMdd,N)]：月初，N 为 0 表示月初，为其它正数，表示相对于月初的偏移，比如 $[month_begin(yyyyMMdd,1)] 表示当月 2 号。
  • $[month_end(yyyyMMdd,-N)]：月末，N 为 0 表示月末，为其它正数，表示相对于月末的偏移，比如 $[month_begin(yyyyMMdd, -1)] 表示当月最后一天往前推一天。
  • $[week_begin(yyyyMMdd,N)]：表示的是周的逻辑，推理逻辑同上。
  • $[week_end(yyyyMMdd,-N)]：表示的是周的逻辑，推理逻辑同上。
  • $[timestamp(...)]：其中 ... 表示的是格式 yyyyMMddHHmmss，比如 $[timestamp(yyyyMMddHHmmss-N/24/60)]、$[timestamp(week_begin(yyyyMMddHHmmss,N))] 等，注意参数如 yyyyMMddHHmmss-N/24/60 不能写成 $[yyyyMMddHHmmss-N/24/60]，这里会自动的解析，也就是说，不支持 $[...] 里面嵌套 $[] 的形式。

例如，自定义参数配置如下：

thishour=$[yyyy-MM-dd/HH:mm:ss]
lasthour=$[yyyy-MM-dd/HH:mm:ss-1/24]

2017.03.08 当天，工作流生成 24 个实例：

  1. 第一个实例定时时间为 2017-03-08 00:00:00，那么 thishour 替换的结果为 2017-03-08/00:00:00，lasthour 替换的结果为 2017-03-07/23:00:00。
  2. 第二个实例定时时间为 2017-03-08 01:00:00，那么 thishour 替换的结果为 2017-03-08/01:00:00，lasthour 替换的结果为 2017-03-08/00:00:00。
  3. 以此类推第 24 个实例定时时间为 2017-03-08 23:00:00，那么 thishour 替换的结果为 2017-03-08/23:00:00，lasthour 替换的结果为 2017-03-08/22:00:00。

2.1自定义参数描述

参数 类型 是否必选 描述 说明
prop string 是 参数 key
value string 是 参数 value

示例：

{
  "prop": "year",
  "value": "$[yyyy]"
}
Clone this wiki locally