# 时间函数
#### 概述
时间函数用于对DATE、TIME、TIMESTAMP类型数据进行操作，包括类型转换、获取当前时间、提取时间分量、格式化、时间取整、时间偏移计算等。
更多内容请参考[Temporal Functions](https://nightlies.apache.org/flink/flink-docs-release-1.20/docs/dev/table/functions/systemfunctions/#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](https://support.huaweicloud.com/sqlref-flink-aidatalake/aidatalake_11_0045.html)。 |
| DATE_SUB                                    | STRING     | DATE_SUB函数用于返回指定日期减去目标天数后的日期。当目标天数为负数时，相当于增加对应天数。                                                                                                              | 详情请参见[DATE_SUB](https://support.huaweicloud.com/sqlref-flink-aidatalake/aidatalake_11_0046.html)。   |
| DATEDIFF                                    | INT       | DATEDIFF函数用于计算两个日期之间的天数差值。计算方式为enddate减去startdate，即返回值 = enddate - startdate。当enddate晚于startdate时返回正数，当enddate早于startdate时返回负数。    | 详情请参见[DATEDIFF](https://support.huaweicloud.com/sqlref-flink-aidatalake/aidatalake_11_0047.html)。   |
   
#### 时间属性处理类
| 语法       | 返回类型               | 说明                                                                                             | 示例   |
|:---|:---|:---|:---|
| PROCTIME() | TIMESTAMP_LTZ(3) | 声明处理时间属性，返回当前处理时间戳。无参数。仅可在DDL的表定义中作为列的类型声明使用，不能在查询中直接调用。返回值为TIMESTAMP_LTZ(3)类型，表示数据被处理时的机器时间。 | ``` -- 在DDL中使用： proctime AS PROCTIME() ``` |
   
