更新时间:2026-11-06 GMT+08:00
分享

时间函数

概述

时间函数用于对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()

相关文档