Azkaban UDF.md

Azkaban UDF是当前平台调度系统预知的udf，可用于SQL类代码中，入参需为固定内容，比如Azkaban时间参数、Java的Joda时间等，在SQL提交执行前，系统会进行udf识别和替换。

azkaban_date_modify

azkaban_date_modify(string date, < string calendarName, > bigint offset, string offset_position)

功能描述：

• 针对日期进行年月日的增减。

参数说明：

• date：表示日期，支持“yyyy-MM-dd”或“yyyyMMdd”格式的字符串
• calendarName：表示调度日历，非必填
• offset：仅支持正数和负数，不能输入0，最大会在调度日历中查找367天，未找到符合offset数的调度日期，会返回报错
• offset_position：偏移的位置，支持不输入、“dd”、“MM”、“yyyy”，不输入表示“dd”。对于输入calendarName后，此处仅支持不输入或“dd”，否则执行会报错

其具体用法如下表所示：

使用上述的Azkaban UDF的SQL示例如下：

azkaban_if

azkaban_if(< testCondition >, < valueTrue >, < valueFalseOrNull >)

功能描述：

• azkaban_if 函数用于根据提供的布尔条件 testCondition 返回两个字符串中的一个。如果条件为 true，则返回 trueValue；如果条件为 false，则返回 falseValue。

参数说明：

• testCondition：必填。要判断的表达式，Boolean类型，表达式中支持 =, >, <, ≥, ≤, &&, ||，支持Java的joda时间比较。

• valueTrue：必填。表达式testCondition为True时返回的值，可以为null值，valueTrue和valueFalseOrNull不能同时为null值。

• valueFalseOrNull：选填。表达式testCondition为False时返回的值，可以为null值，valueTrue和valueFalseOrNull不能同时为null值。

返回值说明：

• 返回值类型和参数valueTrue与valueFalseOrNull的数据类型一致，且支持字符串、数字、小数、布尔值

• 参数valueTrue和valueFalseOrNull若同时为null，返回报错

• 参数testCondition为null时，返回报错

使用示例：

select "$(azkaban_if(1 < 0, 'trueValue', 'falseValue'))"; --输出'falseValue'

select "$(azkaban_if(1 >= 0, 121))"; --输出121

azkaban_str_concat

azkaban_str_concat(, , ...)

功能描述：

• azkaban_str_concat 函数用于将两个或多个字符串参数拼接成一个字符串。如果有多个参数，它们将按照在函数中出现的顺序被拼接起来。

参数说明：

• str1：选填，第一个要拼接的字符串，仅支持String类型，不支持数字、小数、布尔值等类型，可为null。

• str2：选填，第二个要拼接的字符串，仅支持String类型，不支持数字、小数、布尔值等类型，可为null。

• ...：选填，其他要拼接的字符串，仅支持String类型，不支持数字、小数、布尔值等类型，可为null。

返回值说明：

• 返回所有输入字符串拼接后形成的字符串，String类型。

使用示例：

• select "$(azkaban_str_concat('Test ','Hello World!'))"; --输出'Test Hello World!'

azkaban_str_compare

azkaban_str_compare(, )

功能描述：

• azkaban_str_compare 函数用于比较两个字符串str1，str2的长度相差个多少字符，并且以int类型返回字符串比较结果。

参数说明：

• str1：必填，第一个要比较的字符串，String类型，不可为null值。

• str2：必填，第二个要比较的字符串，String类型，不可为null值。

返回值说明：

• 以int类型返回字符串比较结果：

• 若str1比str2长n个字符，则返回n；

• 若str1和str2相同，则返回0；

• 若str1比str2短n个字符，则返回-n。

使用示例：

select "$(azkaban_str_compare('123','1234'))"; --返回-1

select "$(azkaban_str_compare('1234','1234'))"; --返回0

select "$(azkaban_str_compare('1234444','1234'))"; --返回3

azkaban_day

azkaban_day()

功能描述：

• azkaban_day函数接收一个形如 yyyy-MM-dd 的字符串referenceDateStr作为输入参数，并返回该日期的天信息。

参数说明：

• referenceDateStr：必填。需要提取天信息的日期字符串。String类型，格式为 yyyy-MM-dd。

返回值说明：

• referenceDateStr值为null时，返回报错。

• 以int返回日期中的天数信息，取值范围[1,31]。

• 若提供的日期字符串不符合格式或天数与月份不匹配(如 '2024-04-31' )，返回报错。

使用示例：

select "$(azkaban_day('2023-04-01'))"; --输入2023-04-01，输出天为1

azkaban_day_of_week

azkaban_day_of_week()

功能描述：

• azkaban_day_of_week函数接收一个形如 yyyy-MM-dd 的字符串referenceDateStr作为输入参数，并返回日期的星期值。

参数说明：

• referenceDateStr：必填。需要提取星期信息的日期字符串。String类型，格式为 yyyy-MM-dd。

返回值说明：

• referenceDateStr值为null时，返回报错。

• 以int返回，取值范围为1~7，与星期的对应关系为1=Monday， 2=Tuesday，...，7=Sunday。

• 若提供的日期字符串不符合格式，返回报错。

使用示例：

select "$(azkaban_day_of_week('2024-08-28'))"; --输入2023-08-28，输出为3

azkaban_day_of_year

azkaban_day_of_year()

功能描述：

• azkaban_day_of_year函数接收一个形如 yyyy-MM-dd 的字符串referenceDateStr作为输入参数，并返回日期是该年中的第几天。

参数说明：

• referenceDateStr：必填。需要确定是该年中的第几天的日期。String类型，格式为 yyyy-MM-dd。

返回值说明：

• referenceDateStr值为null时，返回报错。

• 以int返回，取值范围为1~366。

• 若提供的日期字符串不符合格式，返回报错。

使用示例：

select "$(azkaban_day_of_year('2024-12-31'))"; --输入2024-12-31，输出为366

azkaban_hour

azkaban_hour()

功能描述：

• azkaban_hour函数接收一个形如 yyyy-MM-dd HH:mm:ss的字符串referenceDateStr作为输入参数，并返回该时间的小时信息。

参数说明：

• referenceDataStr：必填。需要提取小时的字符串。String类型，格式为 yyyy-MM-dd HH:mm:ss。

返回值说明：

• referenceDateStr值为null时，返回报错。

• 以int返回，取值范围[0, 23]。

• 若提供的日期字符串不符合格式，返回报错。

使用示例：

select "$(azkaban_hour('2023-07-09 05:00:00'))"; --输入2023-07-09 05:00:00，输出小时为5

azkaban_week

• azkaban_week()

功能描述：

• azkaban_week函数接收一个形如 yyyy-MM-dd 的字符串referenceDateStr作为输入参数，并返回日期位于该年的第几周。

参数说明：

• referenceDateStr：必填。需要确定是一年中第几周的日期。String类型，格式为 yyyy-MM-dd。

返回值说明：

• referenceDateStr值为null时，返回报错。

• 以int返回，若提供的日期字符串不符合格式，返回报错。

使用示例：

select "$(azkaban_week('2024-02-20'))"; --输入2024-02-20，输出为8

azkaban_month

azkaban_month()

功能描述：

• azkaban_month函数接收一个形如 yyyy-MM-dd 的字符串referenceDateStr作为输入参数，并返回该日期的月份信息。

参数说明：

• referenceDateStr：必填。需要提取月份的日期字符串。String类型，格式为 yyyy-MM-dd。

返回值说明：

• referenceDateStr值为null时，返回报错。

• 以int返回，取值范围[1,12]。

• 若提供的日期字符串不符合格式，返回报错。

使用示例：

• select "$(azkaban_month('2023-07-09'))"; --输入2023-07-09，输出月为7

azkaban_year

azkaban_year()

功能描述：

• azkaban_year函数接收一个形如 yyyy-MM-dd 的字符串referenceDateStr作为输入参数，并返回该日期的年份信息。

参数说明：

• referenceDataStr：必填。需要提取年份的日期字符串。String类型，格式为 yyyy-MM-dd。

返回值说明：

• referenceDateStr值为null时，返回报错。

• 以int返回，若提供的日期字符串不符合格式，返回报错。

使用示例：

select "$(azkaban_year('2023-07-09'))"; --输入2023-07-09，输出年份为2023

azkaban_date_compare

azkaban_date_compare(, , )

功能描述：

• azkaban_date_compare函数比较两个字符串d1，d2的日期，并以-1，0，1返回日期比较的结果。

参数说明：

• d1：必填。第一个要比较的日期字符串，String类型。

• d2：必填。第二个要比较的日期字符串，String类型。

• datePattern：选填。d1、d2参数的输入格式。默认格式为 yyyy-MM-dd。

返回值说明：

• 以int类型返回日期比较结果

• 若d1的日期晚于d2，则返回1；

• 若d1和d2相同，则返回0；

• 若d1的日期早于d2，则返回-1。

• 若d1、d2格式不一致，或与datePattern不符，返回报错。

使用示例：

select "$(azkaban_date_compare('2024-08-03','2024-08-13'))"; --返回-1

select "$(azkaban_date_compare('2024-08-13 12:23:23','2024-08-13 12:23:23','yyyy-MM-dd HH:mm:ss'))"; --返回0

select "$(azkaban_date_compare('20240823','20240813','yyyyMMdd'))"; --返回1

azkaban_date_format

azkaban_date_format(, , )

功能描述：

• azkaban_date_format函数将 referenceDateStr 的日期数据，转换为dateFormat指定格式的字符串。

参数说明：

• referenceDateStr：必填。待转换的日期值。String类型，若未指定datePattern，则只支持以下三种格式：

• "yyyy-MM-dd"，例如"2024-08-28"

• "yyyy-MM-dd HH:mm:ss"，例如"2024-08-28 12:14:13"

• "yyyyMMdd"，例如"20240828"

• dateFormat：必填。转换后日期值的返回格式。String类型。

• datePattern：选填。referenceDateStr参数的输入格式。

返回值说明：

• referenceDateStr格式错误或与datePattern不符，返回报错。

• referenceDateStr为null，返回报错。

• dateFormat为null，返回报错。

使用示例：

select "$(azkaban_date_format('20240803 12:13:14', 'yyyy-MM','yyyyMMdd 12:13:14'))"; --输入20240803 12:13:14，输出2024-08

azkaban_date_minus_months

azkaban_date_minus_months(, , )

功能描述：

• azkaban_date_minus_months函数将months指定的月数，从给定的日期referenceDateStr上减去，并返回日期字符串结果。

参数说明：

• referenceDateStr：必填。需要被执行月数减法的日期字符串，String类型。

• months：必填。需要从referenceDateStr减去的月数，i nt类型。

• datePattern：选填。referenceDateStr参数的输入格式。默认格式为 yyyy-MM-dd。

返回值说明：

• referenceDateStr值为null时，返回报错。

• months值为null时，返回报错。

• referenceDateStr格式错误或与datePattern不符，返回报错。

• 以String形式返回月数减法结果。

使用示例：

select "$(azkaban_date_minus_months('2024-01-13',1,'yyyy-MM-dd'))"; --输入2024-01-13，输出2023-12-13

azkaban_date_plus_months

azkaban_date_plus_months(, , )

功能描述：

• azkaban_date_plus_months函数将months指定的月数，加到给定的日期referenceDateStr上，并返回日期字符串结果。

参数说明：

• referenceDateStr：必填。需要执行月数加法的日期字符串，String类型。

• months：必填。需要加到referenceDateStr的月数，int型数值。

• datePattern：选填。referenceDateStr参数的输入格式。默认格式为 yyyy-MM-dd。

返回值说明：

• referenceDateStr值为null时，返回报错。

• months值为null时，返回报错。

• referenceDateStr格式错误或与datePattern不符，返回报错。

• 以String形式返回月数加法结果。

使用示例：

select "$(azkaban_date_plus_months('2024-08-13',1,'yyyy-MM-dd'))"; --输入2023-08-13，输出2024-09-13

azkaban_date_minus_days

azkaban_date_minus_days(, , )

功能描述：

• azkaban_date_minus_days函数将days指定的天数，从给定的日期referenceDateStr上减去，并返回日期字符串结果。

参数说明：

• referenceDateStr：必填。需要被执行日期减法的日期字符串，String类型。

• days：必填。需要从referenceDateStr减去的日期数量，int类型。

• datePattern：选填。referenceDateStr参数的输入格式。默认格式为 yyyy-MM-dd。

返回值说明：

• referenceDateStr值为null时，返回报错。

• days值为null时，返回报错。

• referenceDateStr格式错误或与datePattern不符，返回报错。

• 以String形式返回日期减法结果。

使用示例：

select "$(azkaban_date_minus_days('2024-08-13',1,'yyyy-MM-dd'))"; --输入2024-08-13，输出2024-08-12

azkaban_date_plus_days

azkaban_date_plus_days(, , )

功能描述：

• azkaban_date_plus_days函数将days指定的天数，加到给定的日期referenceDateStr上，并返回日期字符串结果。

参数说明：

• referenceDateStr：必填。需要被执行日期加法的日期字符串，String类型。

• days：必填。需要加到referenceDateStr的日期数量，int类型。

• datePattern：选填。referenceDateStr参数的输入格式。默认格式为 yyyy-MM-dd。

返回值说明：

• referenceDateStr值为null时，返回报错。

• days值为null时，返回报错。

• referenceDateStr格式错误或与datePattern不符，返回报错。

• 以String形式返回日期加法结果。

使用示例：

select "$(azkaban_date_plus_days('2024-01-13 13:00:00',1,'yyyy-MM-dd HH:mm:ss'))"; --输入2024-01-13 13:00:00，输出2024-01-14 12:00:00