时间函数
概述
时间函数用于对DATE、TIME、TIMESTAMP类型数据进行操作,包括类型转换、获取当前时间、提取时间分量、格式化、时间取整、时间偏移计算等。
更多内容请参考Temporal Functions。
适用场景
- Watermark定义:通过CURRENT_TIMESTAMP和INTERVAL定义Watermark策略。
- 窗口分组:通过DATE_FORMAT将时间格式化为小时/天级别用于窗口分组。
- 时间计算:通过TIMESTAMPADD/TIMESTAMPDIFF计算时间偏移和差值。
- ETL时间字段处理:提取年月日等分量用于数据分区和聚合。
约束与限制
- CURRENT_TIMESTAMP返回的是UTC时区的时间戳,LOCALTIMESTAMP返回的是本地时区的时间戳。
- DATE_FORMAT使用Java DateTimeFormatter格式模式(如yyyy-MM-dd、HH:mm:ss),与SimpleDateFormat模式有部分差异。
- INTERVAL支持年月间隔(YEAR、MONTH)和日时间隔(DAY、HOUR、MINUTE、SECOND)两种类型,不能混用。
- PROCTIME()只能用于DDL中声明处理时间属性,不能用于查询中直接调用。
类型转换类语法结构
| 语法 | 返回类型 | 说明 | 示例 |
|---|---|---|---|
| DATE string | DATE | 将字符串转换为DATE类型。参数string必须为DATE或STRING类型,格式须为yyyy-MM-dd,否则返回NULL。返回值为DATE类型。 | SELECT DATE '2024-01-15'; -- 2024-01-15 |
| TIME string | TIME | 将字符串转换为TIME类型。参数string必须为TIME或STRING类型,格式须为HH:mm:ss,否则返回NULL。返回值为TIME类型。 | SELECT TIME '10:30:00'; -- 10:30:00 |
| TIMESTAMP string | TIMESTAMP | 将字符串转换为TIMESTAMP类型。参数string必须为TIMESTAMP或STRING类型,格式须为yyyy-MM-dd HH:mm:ss[.SSSSSS],否则返回NULL。返回值为TIMESTAMP类型。 | SELECT TIMESTAMP '2024-01-15 10:30:00'; -- 2024-01-15 10:30:00 |
| INTERVAL string range | INTERVAL | 将字符串转换为时间间隔。参数string为表示间隔的STRING类型,range为单位限定符,可选YEAR、MONTH、DAY、HOUR、MINUTE、SECOND、YEAR TO MONTH、DAY TO SECOND等。返回值为INTERVAL类型。 | SELECT INTERVAL '1' DAY; -- +1 00:00:00.000 |
| TO_DATE(string[, format]) | DATE | 将字符串按指定格式转换为DATE类型。参数string为STRING类型,format为可选的Java DateTimeFormatter格式字符串,默认yyyy-MM-dd。格式不匹配时返回NULL。返回值为DATE类型。 | SELECT TO_DATE('2024-01-15', 'yyyy-MM-dd'); -- 2024-01-15 |
| TO_TIMESTAMP(string[, format]) | TIMESTAMP | 将字符串按指定格式转换为TIMESTAMP类型。参数string为STRING类型,format为可选的Java DateTimeFormatter格式字符串,默认yyyy-MM-dd HH:mm:ss。格式不匹配时返回NULL。返回值为TIMESTAMP类型。 | SELECT TO_TIMESTAMP('2024-01-15 10:30:00', 'yyyy-MM-dd HH:mm:ss'); -- 2024-01-15 10:30:00 |
获取当前时间类语法结构
| 语法 | 返回类型 | 说明 | 示例 |
|---|---|---|---|
| CURRENT_DATE | DATE | 返回当前SQL会话的日期(UTC时区)。无参数。返回值为DATE类型。 | SELECT CURRENT_DATE; -- 2024-01-15 |
| CURRENT_TIME | TIME WITH TIME ZONE | 返回当前SQL会话的时间(带时区)。无参数。返回值为TIME WITH TIME ZONE类型。 | SELECT CURRENT_TIME; -- 10:30:00+08:00 |
| CURRENT_TIMESTAMP | TIMESTAMP_LTZ(3) | 返回当前SQL会话的时间戳(带本地时区,精度为3位毫秒)。无参数。返回值为TIMESTAMP_LTZ(3)类型。 | SELECT CURRENT_TIMESTAMP; -- 2024-01-15T10:30:00.000+08:00 |
| LOCALTIME | TIME | 返回当前SQL会话的本地时间(不带时区)。无参数。返回值为TIME类型。 | SELECT LOCALTIME; -- 10:30:00 |
| LOCALTIMESTAMP | TIMESTAMP(3) | 返回当前SQL会话的本地时间戳(不带时区,精度为3位毫秒)。无参数。返回值为TIMESTAMP(3)类型。 | SELECT LOCALTIMESTAMP; -- 2024-01-15 10:30:00.000 |
| NOW() | TIMESTAMP_LTZ(3) | 返回当前时间戳,与CURRENT_TIMESTAMP等价。无参数。返回值为TIMESTAMP_LTZ(3)类型。 | SELECT NOW(); -- 2024-01-15T10:30:00.000+08:00 |
时间分量提取类语法结构
| 语法 | 返回类型 | 说明 | 示例 |
|---|---|---|---|
| EXTRACT(timeintervalunit FROM temporal) | INT | 从时间值中提取指定时间部分的值。参数timeintervalunit为时间单位枚举,可选YEAR、MONTH、DAY、HOUR、MINUTE、SECOND、QUARTER、WEEK、DOW、DOY等;参数temporal必须为DATE、TIME、TIMESTAMP或INTERVAL类型。返回值为INT类型。 | SELECT EXTRACT(YEAR FROM TIMESTAMP '2024-01-15 10:30:00'); -- 2024 |
| YEAR(date) | INT | 提取日期中的年份。参数date必须为DATE或TIMESTAMP类型。返回值为INT类型,范围1~9999。 | SELECT YEAR(DATE '2024-01-15'); -- 2024 |
| QUARTER(date) | INT | 提取日期中的季度。参数date必须为DATE或TIMESTAMP类型。返回值为INT类型,范围1~4。 | SELECT QUARTER(DATE '2024-04-15'); -- 2 |
| MONTH(date) | INT | 提取日期中的月份。参数date必须为DATE或TIMESTAMP类型。返回值为INT类型,范围1~12。 | SELECT MONTH(DATE '2024-01-15'); -- 1 |
| WEEK(date) | INT | 提取日期在年中的周数。参数date必须为DATE或TIMESTAMP类型。返回值为INT类型,范围1~53。 | SELECT WEEK(DATE '2024-01-15'); -- 3 |
| DAYOFYEAR(date) | INT | 提取日期在年中的天数。参数date必须为DATE或TIMESTAMP类型。返回值为INT类型,范围1~366。 | SELECT DAYOFYEAR(DATE '2024-02-01'); -- 32 |
| DAYOFMONTH(date) | INT | 提取日期在月中的天数。参数date必须为DATE或TIMESTAMP类型。返回值为INT类型,范围1~31。 | SELECT DAYOFMONTH(DATE '2024-01-15'); -- 15 |
| DAYOFWEEK(date) | INT | 提取日期在周中的天数。参数date必须为DATE或TIMESTAMP类型。返回值为INT类型,范围1(周日)~7(周六)。 | SELECT DAYOFWEEK(DATE '2024-01-15'); -- 2 |
| HOUR(timestamp) | INT | 提取时间戳中的小时部分。参数timestamp必须为TIME或TIMESTAMP类型。返回值为INT类型,范围0~23。 | SELECT HOUR(TIMESTAMP '2024-01-15 10:30:00'); -- 10 |
| MINUTE(timestamp) | INT | 提取时间戳中的分钟部分。参数timestamp必须为TIME或TIMESTAMP类型。返回值为INT类型,范围0~59。 | SELECT MINUTE(TIMESTAMP '2024-01-15 10:30:00'); -- 30 |
| SECOND(timestamp) | INT | 提取时间戳中的秒部分。参数timestamp必须为TIME或TIMESTAMP类型。返回值为INT类型,范围0~59。 | SELECT SECOND(TIMESTAMP '2024-01-15 10:30:45'); -- 45 |
时间取整类语法结构
| 语法 | 返回类型 | 说明 | 示例 |
|---|---|---|---|
| FLOOR(temporal TO timeintervalunit) | 与输入类型一致 | 将时间值向下取整到指定时间单位。参数temporal必须为DATE、TIME或TIMESTAMP类型;参数timeintervalunit为取整单位,可选YEAR、MONTH、DAY、HOUR、MINUTE、SECOND等。返回值类型与输入一致。 | SELECT FLOOR(TIMESTAMP '2024-01-15 10:30:45' TO HOUR); -- 2024-01-15 10:00:00 |
| CEIL(temporal TO timeintervalunit) | 与输入类型一致 | 将时间值向上取整到指定时间单位。参数temporal必须为DATE、TIME或TIMESTAMP类型;参数timeintervalunit为取整单位,可选YEAR、MONTH、DAY、HOUR、MINUTE、SECOND等。返回值类型与输入一致。 | SELECT CEIL(TIMESTAMP '2024-01-15 10:30:45' TO HOUR); -- 2024-01-15 11:00:00 |
时间格式化类
| 语法 | 返回类型 | 说明 | 示例 |
|---|---|---|---|
| DATE_FORMAT(timestamp, format) | STRING | 将时间戳按指定格式转为字符串。参数timestamp必须为TIMESTAMP或TIMESTAMP_LTZ类型;参数format为STRING类型,使用Java DateTimeFormatter格式模式(如yyyy-MM-dd、HH:mm:ss、yyyyMMdd等)。返回值为STRING类型。 | SELECT DATE_FORMAT(TIMESTAMP '2024-01-15 10:30:00', 'yyyy-MM-dd'); -- '2024-01-15' |
时间运算类
| 语法 | 返回类型 | 说明 | 示例 |
|---|---|---|---|
| TIMESTAMPADD(unit, interval, timestamp) | TIMESTAMP | 对时间戳增加指定间隔。参数unit为时间单位,可选YEAR、MONTH、QUARTER、WEEK、DAY、HOUR、MINUTE、SECOND等;参数interval必须为INT类型,表示要增加的数量(可为负数实现减法);参数timestamp必须为TIMESTAMP类型。返回值为TIMESTAMP类型。 | SELECT TIMESTAMPADD(DAY, 7, TIMESTAMP '2024-01-15 10:30:00'); -- 2024-01-22 10:30:00 |
| TIMESTAMPDIFF(unit, timestamp1, timestamp2) | INT | 计算两个时间戳之间的差值。参数unit为时间单位,可选YEAR、MONTH、QUARTER、WEEK、DAY、HOUR、MINUTE、SECOND等;参数timestamp1和timestamp2必须为TIMESTAMP类型。返回值为INT类型,表示timestamp2 - timestamp1在指定单位下的差值。 | SELECT TIMESTAMPDIFF(DAY, TIMESTAMP '2024-01-01 00:00:00', TIMESTAMP '2024-01-15 00:00:00'); -- 14 |
| DATE_ADD | STRING | DATE_ADD函数用于返回指定日期增加目标天数后的日期。当目标天数为负数时,相当于减去对应天数。 | 详情请参见DATE_ADD。 |
| DATE_SUB | STRING | DATE_SUB函数用于返回指定日期减去目标天数后的日期。当目标天数为负数时,相当于增加对应天数。 | 详情请参见DATE_SUB。 |
| DATEDIFF | INT | DATEDIFF函数用于计算两个日期之间的天数差值。计算方式为enddate减去startdate,即返回值 = enddate - startdate。当enddate晚于startdate时返回正数,当enddate早于startdate时返回负数。 | 详情请参见DATEDIFF。 |
时间属性处理类
| 语法 | 返回类型 | 说明 | 示例 |
|---|---|---|---|
| PROCTIME() | TIMESTAMP_LTZ(3) | 声明处理时间属性,返回当前处理时间戳。无参数。仅可在DDL的表定义中作为列的类型声明使用,不能在查询中直接调用。返回值为TIMESTAMP_LTZ(3)类型,表示数据被处理时的机器时间。 | -- 在DDL中使用: proctime AS PROCTIME() |