流计算 Oceanus 时间相关函数

时间相关函数的函数名和功能描述如下：
函数名
功能描述
DATE string
将 "yyyy-MM-dd" 形式表示的字符串转为 SQL 日期（DATE）类型。
TIME string
将 "HH:mm:ss" 形式表示的字符串转为 SQL 时间（TIME）类型。
TIMESTAMP string
将 "yyyy-MM-dd HH:mm:ss[.SSS]" 形式的字符串转为 SQL 时间戳（TIMESTAMP）类型。
INTERVAL string range
接受 "dd hh:mm:ss.fff" 形式的字符串（毫秒），或者 "yyyy-MM" 形式的字符串（月）。
对于毫秒，可以接受 DAY、MINUTE、DAY TO HOUR、DAY TO SECOND 作为 range。
对于月，接受 YEAR 或 YEAR TO MONTH 作为 range。例如 INTERVAL '10 00:00:00.004' DAY TO SECOND、INTERVAL '10' DAY、INTERVAL '2-10' YEAR TO MONTH。
CURRENT_DATE
返回当前的 SQL DATE 格式表示的日期（UTC）。
CURRENT_TIME
返回当前的 SQL TIME 格式表示的时间（UTC）。
CURRENT_TIMESTAMP
返回当前 SQL TIMESTAMP 格式表示的时间戳（UTC）。
LOCALTIME
返回本地时区表示的 SQL 时间。
LOCALTIMESTAMP
返回本地时区表示的 SQL 时间戳。
EXTRACT(timeintervalunit FROM temporal)
获取时间点或时间段字符串中的某项。例如 EXTRACT(DAY FROM DATE '2006-06-05') 返回5，而 EXTRACT(YEAR FROM DATE '2018-06-12') 则返回2018。
YEAR(date)
返回指定日期中的年份，等价于 EXTRACT(YEAR FROM date)。例如 YEAR(DATE '2020-08-12') 返回2020。
QUARTER(date)
返回指定日期的季度，等价于 EXTRACT(QUARTER FROM date)。例如 QUARTER(DATE '2012-09-10')返回3。
MONTH(date)
返回指定日期的月份，等价于 EXTRACT(MONTH FROM date)。例如 MONTH(DATE '2012-09-10') 返回9。
WEEK(date)
返回指定日期的周数，即当年的第几周，等价于 EXTRACT(WEEK FROM date)。例如 WEEK(DATE '1994-09-27') 返回39。
DAYOFYEAR(date)
返回指定日期在当年的天数，即当年的第几天（范围是[1，366]），等价于 EXTRACT(DOY FROM date)。例如 DAYOFYEAR(DATE '1994-09-27') 返回270。
DAYOFMONTH(date)
返回指定日期在当月的天数，即当月的第几天（范围是[1，31]），等价于 EXTRACT(DAY FROM date)。例如 DAYOFMONTH(DATE '1994-09-27') 返回27。
DAYOFWEEK(date)
返回指定日期在本周的天数，即本周的第几天（范围是[1，7]），等价于 EXTRACT(DOW FROM date)。例如 DAYOFWEEK(DATE '1994-09-27') 返回3。
HOUR(timestamp)
返回指定时间戳的小时部分（范围是[0，23]）。等价于 EXTRACT(HOUR FROM timestamp)。例如 HOUR('2017-10-02 12:25:44') 返回12。
MINUTE(timestamp)
返回指定时间戳的分钟部分（范围是[0，59]）。等价于 EXTRACT(MINUTE FROM timestamp)。例如 MINUTE('2017-10-02 12:25:44') 返回25。
SECOND(timestamp)
返回指定时间戳的秒部分（范围是[0，59]）。等价于 EXTRACT(SECOND FROM timestamp)。例如 SECOND('2017-10-02 12:25:44') 返回44。
FLOOR(timepoint TO timeintervalunit)
将一个时间点向下取整，例如 FLOOR(TIME '12:44:31' TO MINUTE) 返回12:44:00。
CEIL(timepoint TO timeintervalunit)
将一个时间点向上取整，例如 CEIL(TIME '12:44:31' TO MINUTE) 返回12:45:00。
(timepoint, temporal) OVERLAPS (timepoint, temporal)
判断两个时间段是否重叠。例如 (TIME'2:55:00', INTERVAL '1' HOUR) OVERLAPS (TIME'3:30:00', INTERVAL '2' HOUR) 返回 TRUE；而 (TIME'9:00:00', TIME '10:00:00') OVERLAPS (TIME'10:15:00', INTERVAL '3' HOUR) 返回 FALSE。
TO_TIMESTAMP(string, simple_format)
将字符串格式的时间戳转为 Timestamp 类型。详见 类型转换函数。
DATE_FORMAT_SIMPLE (timestamp, simple_format)
将 BIGINT 类型以毫秒为单位的 Unix 时间戳格式化为字符串。详见 类型转换函数。
DATE_FORMAT(timestamp, format)
将 Timestamp 类型的时间戳格式化为字符串。详见 类型转换函数。
TIMESTAMP_TO_LONG(timestamp)
将 Timestamp 类型的时间戳转为 BIGINT 类型以毫秒或秒（可选）为单位的 Unix 时间戳。详见 类型转换函数。
TIMESTAMPADD(unit, interval, timestamp)
对指定 timestamp 增加一个时间段（允许为负数），单位区间必须为 SECOND、MINUTE、HOUR、DAY、WEEK、MONTH、QUARTER、YEAR 中的一种。例如 TIMESTAMPADD(WEEK, 1, '2013-01-02')返回'2013-01-09'。
TIMESTAMPDIFF(timepointunit, timepoint1, timepoint2)
计算指定单位区间下，timepoint1 和 timepoint2 之间的时间差（允许为负数）。timepointunit 区间必须为 SECOND、MINUTE、HOUR、DAY、WEEK、MONTH、QUARTER、YEAR 中的一种。例如 TIMESTAMPDIFF(DAY, TIMESTAMP '2003-01-02 10:00:00', TIMESTAMP '2003-01-03 10:00:00') 返回1，即相差正1天。
CONVERT_TZ(string1, string2, string3)
将 string1 表示的时间戳（必须是 'yyyy-MM-dd HH:mm:ss' 格式）从时区（允许缩写例如 "PST"，全称例如 "Asia/Shanghai"，或者任意时区例如 "GMT-8:00"）string2 转换到时区 string3。例如 CONVERT('1970-01-01 00:00:00', 'UTC', 'America/Los_Angeles') 返回 '1969-12-31 16:00:00'。
FROM_UNIXTIME(numeric[, string])
返回 numeric 代表的 Unix 时间戳（从 1970-01-01 00:00:00 UTC 到现今的秒数）转为 'YYYY-MM-DD hh:mm:ss' 格式的字符串。默认使用 UTC+8 时区，即北京时间（Asia/Shanghai）。
UNIX_TIMESTAMP()
返回以秒为单位的 Unix 时间戳（从 1970-01-01 00:00:00 UTC 到现今的秒数），类型为 BIGINT。默认使用 UTC+8 时区，即北京时间（Asia/Shanghai）。
UNIX_TIMESTAMP(string1[, string2])
将 string1 字符串以 string2 的格式（可选，默认是 'yyyy-MM-dd HH:mm:ss'）转为 Unix 时间戳，类型为 BIGINT。
TO_DATE(string1[, string2])
将 string1 字符串以 string2 的格式（可选，默认是 'yyyy-MM-dd HH:mm:ss'）转为 DATE 格式。
TO_TIMESTAMP(string1[, string2])
将 string1 字符串以 string2 的格式（可选，默认是 'yyyy-MM-dd HH:mm:ss'）转为 TIMESTAMP 格式。默认使用 UTC+8 时区，即北京时间（Asia/Shanghai）。
NOW()
返回当前的 SQL TIMESTAMP 时间戳，时区为 UTC。
DATEDIFF
DATEDIFF 用于计算两个日期/时间表达式之间相差的天数，返回 t1 - t2 的差值（以"日历日"为单位）。
DATE_ADD
DATE_ADD 用于在给定日期时间上增加指定的天数，返回新的日期字符串（yyyy-MM-dd 格式）。
DATE_SUB
DATE_SUB 用于在给定日期时间上减去指定的天数，返回新的日期字符串（yyyy-MM-dd 格式）。
DATE_FORMAT_TZ
DATE_FORMAT_TZ 用于将一个 TIMESTAMP 值转换到指定时区，并按给定格式输出为字符串。
TO_TIMESTAMP_TZ
TO_TIMESTAMP_TZ 用于将带有"原始时区"语义的日期时间字符串解析为 TIMESTAMP 值，得到的时间戳的本地表示对应当前 session 时区下的对应时刻。
DATEDIFF
支持版本：1.16及以上版本。
功能描述：DATEDIFF 用于计算两个日期/时间表达式之间相差的天数，返回 t1 - t2 的差值（以"日历日"为单位）。
语法：DATEDIFF(t1, t2)
示例测试语句：SELECT DATEDIFF(t1, t2) AS res;
测试数据和结果：
测试数据（VARCHAR/TIMESTAMP t1）
测试数据（VARCHAR/TIMESTAMP t2）
测试结果（INT res）
2017-12-14 01:00:34
2016-12-14 12:00:00
365
使用限制：
仅以"日历日"为粒度计算差值，时分秒部分会被忽略，因此同一天内不同时刻的差值为 0。
计算所用时区固定为 UTC，调用方需自行注意时区影响。
DATE_ADD
支持版本：1.16及以上版本。
功能描述：DATE_ADD 用于在给定日期时间上增加指定的天数，返回新的日期字符串（yyyy-MM-dd 格式）
语法：DATE_ADD(dateExpr, days)
示例测试语句：SELECT DATE_ADD(dateExpr, days) AS res;
测试数据和结果：
测试数据（VARCHAR/TIMESTAMP dateExpr）
测试数据（INT days）
测试结果（VARCHAR res）
2017-12-14
4
2017-12-18
DATE_SUB
支持版本：1.16及以上版本。
功能描述：DATE_SUB 用于在给定日期时间上减去指定的天数，返回新的日期字符串（yyyy-MM-dd 格式）
语法：DATE_SUB(dateExpr, days)
示例测试语句：SELECT DATE_SUB(dateExpr, days) AS res;
测试数据和结果：
测试数据（VARCHAR/TIMESTAMP dateExpr）
测试数据（INT days）
测试结果（VARCHAR res）
2017-12-14 09:00:23
3
2017-12-11
DATE_FORMAT_TZ
支持版本：1.16及以上版本。
功能描述：
DATE_FORMAT_TZ 用于将一个 TIMESTAMP 值转换到指定时区，并按给定格式输出为字符串。
函数会按照以下逻辑计算：
1. 如果 ts 为 NULL，则直接返回 NULL。
2. 将 ts 视为以毫秒为单位的时间戳值。
3. 根据 tzStr 解析得到目标时区，未传 format 时默认使用 yyyy-MM-dd HH:mm:ss。
 在该时区下使用 format 格式化时间戳并返回字符串。
语法：
DATE_FORMAT_TZ(ts, tzStr)
DATE_FORMAT_TZ(ts, format, tzStr)
示例测试语句：SELECT DATE_FORMAT_TZ(ts, format, tzStr) AS res;
测试数据和结果：
测试数据（TIMESTAMP dateStr）
测试数据（VARCHAR format）
测试数据（VARCHAR tzStr）
测试结果（VARCHAR res）
TIMESTAMP '2018-03-14 03:00:00'
yyyy/MM/dd HH:mm:ss
Asia/Shanghai
2018/03/14 11:00:00
使用限制：
tzStr 须为 JDK 可识别的时区 ID；不可识别的时区会被回退为 GMT，可能导致结果与预期不符。
TO_TIMESTAMP_TZ
支持版本：1.16及以上版本。
功能描述：TO_TIMESTAMP_TZ 用于将带有"原始时区"语义的日期时间字符串解析为 TIMESTAMP 值，得到的时间戳的本地表示对应当前 session 时区下的对应时刻。
函数会按照以下逻辑计算：
1. 如果 dateStr 为 NULL，则返回 NULL。
2. 根据 tzStr 解析得到原始时区，未传 format 时默认使用 yyyy-MM-dd HH:mm:ss。
3. 在原始时区下按 format 解析 dateStr 得到 UTC 毫秒数，解析失败返回 NULL。
4. 加上 session 时区相对 UTC 的偏移量，得到 TIMESTAMP 值，使其在 session 时区下展示为对应"原始时区时刻"映射后的本地时间。
语法：
TO_TIMESTAMP_TZ(dateStr, tzStr)
TO_TIMESTAMP_TZ(dateStr, format, tzStr)
示例测试语句：SELECT TO_TIMESTAMP_TZ(dateStr, tzStr) AS res;
测试数据和结果：
测试数据（VARCHAR dateStr）
测试数据（VARCHAR tzStr）
测试结果（VARCHAR res）
2018-03-14 11:00:00
Asia/Shanghai
2018-03-14 11:00:00.000000
使用限制：
tzStr 须为 JDK 可识别的时区 ID；不可识别的时区会被回退为 GMT。
结果取决于 session 本地时区配置，跨时区任务需显式设置以避免歧义。

函数名	功能描述
DATE string	将 "yyyy-MM-dd" 形式表示的字符串转为 SQL 日期（DATE）类型。
TIME string	将 "HH:mm:ss" 形式表示的字符串转为 SQL 时间（TIME）类型。
TIMESTAMP string	将 "yyyy-MM-dd HH:mm:ss[.SSS]" 形式的字符串转为 SQL 时间戳（TIMESTAMP）类型。
INTERVAL string range	接受 "dd hh:mm:ss.fff" 形式的字符串（毫秒），或者 "yyyy-MM" 形式的字符串（月）。对于毫秒，可以接受 DAY、MINUTE、DAY TO HOUR、DAY TO SECOND 作为 range。对于月，接受 YEAR 或 YEAR TO MONTH 作为 range。例如 INTERVAL '10 00:00:00.004' DAY TO SECOND、INTERVAL '10' DAY、INTERVAL '2-10' YEAR TO MONTH。
CURRENT_DATE	返回当前的 SQL DATE 格式表示的日期（UTC）。
CURRENT_TIME	返回当前的 SQL TIME 格式表示的时间（UTC）。
CURRENT_TIMESTAMP	返回当前 SQL TIMESTAMP 格式表示的时间戳（UTC）。
LOCALTIME	返回本地时区表示的 SQL 时间。
LOCALTIMESTAMP	返回本地时区表示的 SQL 时间戳。
EXTRACT(timeintervalunit FROM temporal)	获取时间点或时间段字符串中的某项。例如 EXTRACT(DAY FROM DATE '2006-06-05') 返回5，而 EXTRACT(YEAR FROM DATE '2018-06-12') 则返回2018。
YEAR(date)	返回指定日期中的年份，等价于 EXTRACT(YEAR FROM date)。例如 YEAR(DATE '2020-08-12') 返回2020。
QUARTER(date)	返回指定日期的季度，等价于 EXTRACT(QUARTER FROM date)。例如 QUARTER(DATE '2012-09-10')返回3。
MONTH(date)	返回指定日期的月份，等价于 EXTRACT(MONTH FROM date)。例如 MONTH(DATE '2012-09-10') 返回9。
WEEK(date)	返回指定日期的周数，即当年的第几周，等价于 EXTRACT(WEEK FROM date)。例如 WEEK(DATE '1994-09-27') 返回39。
DAYOFYEAR(date)	返回指定日期在当年的天数，即当年的第几天（范围是[1，366]），等价于 EXTRACT(DOY FROM date)。例如 DAYOFYEAR(DATE '1994-09-27') 返回270。
DAYOFMONTH(date)	返回指定日期在当月的天数，即当月的第几天（范围是[1，31]），等价于 EXTRACT(DAY FROM date)。例如 DAYOFMONTH(DATE '1994-09-27') 返回27。
DAYOFWEEK(date)	返回指定日期在本周的天数，即本周的第几天（范围是[1，7]），等价于 EXTRACT(DOW FROM date)。例如 DAYOFWEEK(DATE '1994-09-27') 返回3。
HOUR(timestamp)	返回指定时间戳的小时部分（范围是[0，23]）。等价于 EXTRACT(HOUR FROM timestamp)。例如 HOUR('2017-10-02 12:25:44') 返回12。
MINUTE(timestamp)	返回指定时间戳的分钟部分（范围是[0，59]）。等价于 EXTRACT(MINUTE FROM timestamp)。例如 MINUTE('2017-10-02 12:25:44') 返回25。
SECOND(timestamp)	返回指定时间戳的秒部分（范围是[0，59]）。等价于 EXTRACT(SECOND FROM timestamp)。例如 SECOND('2017-10-02 12:25:44') 返回44。
FLOOR(timepoint TO timeintervalunit)	将一个时间点向下取整，例如 FLOOR(TIME '12:44:31' TO MINUTE) 返回12:44:00。
CEIL(timepoint TO timeintervalunit)	将一个时间点向上取整，例如 CEIL(TIME '12:44:31' TO MINUTE) 返回12:45:00。
(timepoint, temporal) OVERLAPS (timepoint, temporal)	判断两个时间段是否重叠。例如 (TIME'2:55:00', INTERVAL '1' HOUR) OVERLAPS (TIME'3:30:00', INTERVAL '2' HOUR) 返回 TRUE；而 (TIME'9:00:00', TIME '10:00:00') OVERLAPS (TIME'10:15:00', INTERVAL '3' HOUR) 返回 FALSE。
TO_TIMESTAMP(string, simple_format)	将字符串格式的时间戳转为 Timestamp 类型。详见类型转换函数。
DATE_FORMAT_SIMPLE (timestamp, simple_format)	将 BIGINT 类型以毫秒为单位的 Unix 时间戳格式化为字符串。详见类型转换函数。
DATE_FORMAT(timestamp, format)	将 Timestamp 类型的时间戳格式化为字符串。详见类型转换函数。
TIMESTAMP_TO_LONG(timestamp)	将 Timestamp 类型的时间戳转为 BIGINT 类型以毫秒或秒（可选）为单位的 Unix 时间戳。详见类型转换函数。
TIMESTAMPADD(unit, interval, timestamp)	对指定 timestamp 增加一个时间段（允许为负数），单位区间必须为 SECOND、MINUTE、HOUR、DAY、WEEK、MONTH、QUARTER、YEAR 中的一种。例如 TIMESTAMPADD(WEEK, 1, '2013-01-02')返回'2013-01-09'。
TIMESTAMPDIFF(timepointunit, timepoint1, timepoint2)	计算指定单位区间下，timepoint1 和 timepoint2 之间的时间差（允许为负数）。timepointunit 区间必须为 SECOND、MINUTE、HOUR、DAY、WEEK、MONTH、QUARTER、YEAR 中的一种。例如 TIMESTAMPDIFF(DAY, TIMESTAMP '2003-01-02 10:00:00', TIMESTAMP '2003-01-03 10:00:00') 返回1，即相差正1天。
CONVERT_TZ(string1, string2, string3)	将 string1 表示的时间戳（必须是 'yyyy-MM-dd HH:mm:ss' 格式）从时区（允许缩写例如 "PST"，全称例如 "Asia/Shanghai"，或者任意时区例如 "GMT-8:00"）string2 转换到时区 string3。例如 CONVERT('1970-01-01 00:00:00', 'UTC', 'America/Los_Angeles') 返回 '1969-12-31 16:00:00'。
FROM_UNIXTIME(numeric[, string])	返回 numeric 代表的 Unix 时间戳（从 1970-01-01 00:00:00 UTC 到现今的秒数）转为 'YYYY-MM-DD hh:mm:ss' 格式的字符串。默认使用 UTC+8 时区，即北京时间（Asia/Shanghai）。
UNIX_TIMESTAMP()	返回以秒为单位的 Unix 时间戳（从 1970-01-01 00:00:00 UTC 到现今的秒数），类型为 BIGINT。默认使用 UTC+8 时区，即北京时间（Asia/Shanghai）。
UNIX_TIMESTAMP(string1[, string2])	将 string1 字符串以 string2 的格式（可选，默认是 'yyyy-MM-dd HH:mm:ss'）转为 Unix 时间戳，类型为 BIGINT。
TO_DATE(string1[, string2])	将 string1 字符串以 string2 的格式（可选，默认是 'yyyy-MM-dd HH:mm:ss'）转为 DATE 格式。
TO_TIMESTAMP(string1[, string2])	将 string1 字符串以 string2 的格式（可选，默认是 'yyyy-MM-dd HH:mm:ss'）转为 TIMESTAMP 格式。默认使用 UTC+8 时区，即北京时间（Asia/Shanghai）。
NOW()	返回当前的 SQL TIMESTAMP 时间戳，时区为 UTC。
DATEDIFF	DATEDIFF 用于计算两个日期/时间表达式之间相差的天数，返回 t1 - t2 的差值（以"日历日"为单位）。
DATE_ADD	DATE_ADD 用于在给定日期时间上增加指定的天数，返回新的日期字符串（yyyy-MM-dd 格式）。
DATE_SUB	DATE_SUB 用于在给定日期时间上减去指定的天数，返回新的日期字符串（yyyy-MM-dd 格式）。
DATE_FORMAT_TZ	DATE_FORMAT_TZ 用于将一个 TIMESTAMP 值转换到指定时区，并按给定格式输出为字符串。
TO_TIMESTAMP_TZ	TO_TIMESTAMP_TZ 用于将带有"原始时区"语义的日期时间字符串解析为 TIMESTAMP 值，得到的时间戳的本地表示对应当前 session 时区下的对应时刻。

测试数据（VARCHAR/TIMESTAMP t1）	测试数据（VARCHAR/TIMESTAMP t2）	测试结果（INT res）
2017-12-14 01:00:34	2016-12-14 12:00:00	365

测试数据（VARCHAR/TIMESTAMP dateExpr）	测试数据（INT days）	测试结果（VARCHAR res）
2017-12-14	4	2017-12-18

测试数据（TIMESTAMP dateStr）	测试数据（VARCHAR format）	测试数据（VARCHAR tzStr）	测试结果（VARCHAR res）
TIMESTAMP '2018-03-14 03:00:00'	yyyy/MM/dd HH:mm:ss	Asia/Shanghai	2018/03/14 11:00:00

测试数据（VARCHAR dateStr）	测试数据（VARCHAR tzStr）	测试结果（VARCHAR res）
2018-03-14 11:00:00	Asia/Shanghai	2018-03-14 11:00:00.000000

时间相关函数

本页目录：

DATEDIFF

DATE_ADD

DATE_SUB

DATE_FORMAT_TZ

TO_TIMESTAMP_TZ