# 日期时间函数
#### ADDDATE
- ADDDATE(date, INTERVAL expr unit) 描述：用于在指定的日期上添加一段时间间隔，并返回计算结果。该函数这种形式的功能用法与[DATE_ADD]函数相同。
  参数：具体说明如[表1]所示。
   表1ADDDATE参数说明 
  | 参数   | 类型                                  | 描述            | 取值范围                                                                                                                                                                                              |
  |:---|:---|:---|:---|
  | date | 时间类型表达式、TEXT、DATETIME、DATE、TIME等类型。 | 表示日期时间基准。     | 和类型范围一致。                                                                                                                                                                                          |
  | expr | 整数、浮点数、字符串、表达式等。                    | 表示时间间隔，可以是负值。 | 和类型范围一致。                                                                                                                                                                                          |
  | unit | 关键字。                                | 表示时间间隔的单位。    | YEAR、QUARTER、MONTH、WEEK、DAY、HOUR、MINUTE、SECOND或MICROSECOND等，具体请参见[时间间隔表达式](https://support.huaweicloud.com/distributed-m-comp-devg-v8-gaussdb/gaussdb-81-0179.html#ZH-CN_TOPIC_0000002527965476)。 |
     
  示例：
  ```
  m_db=# SELECT ADDDATE('2018-05-01', INTERVAL 1 DAY);
    adddate   
  ------------
   2018-05-02
  (1 row)
  ```
  

- ADDDATE(date, days) 描述：用于将days指定的天数与date指定的日期相加，返回计算结果。
  参数：具体说明如[表2]所示。
   表2ADDDATE参数说明 
  | 参数   | 类型                                  | 描述            | 取值范围    |
  |:---|:---|:---|:---|
  | date | 时间类型表达式、TEXT、DATETIME、DATE、TIME等类型。 | 表示日期时间基准。     | 和类型范围一致 |
  | days | 整数、浮点数、字符串等。                        | 表示时间间隔，可以是负值。 | 和类型范围一致 |
     
  返回值类型：TEXT、DATE、DATETIME或TIME。
  示例：
  ```
  m_db=# SELECT ADDDATE('2018-05-01', 1);
    adddate   
  ------------
   2018-05-02
  (1 row)
  ```
  
 
#### ADDTIME
ADDTIME(expr1, expr2)
描述：返回时间或时间日期表达式expr1与时间表达式expr2相加后的值，返回值的格式与expr1保持一致。
参数：
- expr1：时间或时间日期表达式。
- expr2：时间表达式。
 
返回值类型：TEXT、DATETIME或TIME。返回值类型与expr1类型有关，expr1解析为DATETIME，则返回DATETIME，expr1解析为TIME，则返回TIME。
示例：
```
m_db=# SELECT ADDTIME('2000-03-01 20:59:59', '00:00:01');
       addtime       
---------------------
 2000-03-01 21:00:00
(1 row)
m_db=# SELECT ADDTIME('20:59:59', '00:00:01');
 addtime  
----------
 21:00:00
(1 row)
```
#### CONVERT_TZ
CONVERT_TZ(dt, from_tz, to_tz)
描述：CONVERT_TZ函数用于将日期时间值dt从from_tz时区转换到to_tz时区。如果参数dt无效，则返回空。如果dt超出TIMESTAMP类型支持范围，则不会发生转换。
参数：具体说明如[表3]所示。
 表3CONVERT_TZ参数说明 
| 参数            | 类型                                            | 描述                       | 取值范围                                                                                                                                                                                                           |
|:---|:---|:---|:---|
| dt            | TEXT、DATETIME、DATE、TIME和其他可以隐式转换为DATETIME的类型。 | 表示日期时间值。                 | 请参见[表1](https://support.huaweicloud.com/distributed-m-comp-devg-v8-gaussdb/gaussdb-81-0163.html#ZH-CN_TOPIC_0000002527965468__zh-cn_topic_0000002527053524_zh-cn_topic_0000001736245148_table181541055181410)。 |
| from_tz/to_tz | ±hh:mm格式的字符串。                                 | 表示相较于UTC时间的偏移，如'+08:00'。 | \[-12:59, +13:00\]，正负号必须加。                                                                                                                                                                                     |
| from_tz/to_tz | 命名时区。                                         | 如'MET'、'UTC'等。           | 具体请参见PG_TIMEZONE_NAMES系统视图。                                                                                                                                                                                    |
   
返回值类型：DATETIME
示例：
```
m_db=# SELECT CONVERT_TZ('2023-01-01 10:10:10', '+00:00', '+08:00');
     convert_tz      
---------------------
 2023-01-01 11:10:10
(1 row)
```
 #### CURDATE
CURDATE()
描述：返回本地函数调用开始时刻的系统日期。支持在同一连接内修改时区，返回的日期受时区的影响。
返回值类型：DATE
示例：
```
m_db=# SELECT CURDATE();
  curdate   
------------
 2023-12-09
(1 row)
```
#### CURRENT_DATE
CURRENT_DATE/CURRENT_DATE()
描述：返回本地函数调用开始时刻的系统日期。支持在同一连接内修改时区，返回的日期受时区的影响。该函数是[CURDATE]的别名。
返回值类型：DATE
示例：
```
m_db=# SELECT CURRENT_DATE;
 current_date 
--------------
 2023-12-09
(1 row)
m_db=# SELECT CURRENT_DATE();
 current_date 
--------------
 2023-12-09
(1 row)
```
 #### CURRENT_TIME
CURRENT_TIME/CURRENT_TIME(\[scale\])
描述：返回本地函数调用开始时刻的时间，不含日期的部分。
参数：scale，表示微秒部分的精度，有效值为0到6的整数，默认值为0。
返回值类型：TIME
示例：
```
m_db=# SELECT CURRENT_TIME;
 current_time 
--------------
 10:14:12
(1 row)
m_db=# SELECT CURRENT_TIME(6);
  current_time   
-----------------
 10:14:15.512064
(1 row)
```
#### CURRENT_TIMESTAMP
CURRENT_TIMESTAMP/CURRENT_TIMESTAMP(\[scale\])
描述：返回本地函数调用开始时刻的日期时间。该函数是[NOW]的别名。
参数：scale，表示微秒部分的精度，有效值为0到6的整数，默认值为0。
返回值类型：DATETIME
示例：
```
m_db=# SELECT CURRENT_TIMESTAMP;
  current_timestamp  
---------------------
 2023-12-09 11:20:04
(1 row)
m_db=# SELECT CURRENT_TIMESTAMP(6);
     current_timestamp      
----------------------------
 2023-12-09 11:20:07.059582
(1 row)
```
#### CURTIME
CURTIME(\[scale\])
描述：返回本地函数调用开始时刻的时间，不含日期的部分。该函数是[CURRENT_TIME]的别名。
参数：scale，表示微秒部分的精度，有效值为0到6的整数，默认值为0。
返回值类型：TIME
示例：
```
m_db=# SELECT CURTIME();
 curtime  
----------
 11:24:03
(1 row)
m_db=# SELECT CURTIME(6);
     curtime     
-----------------
 11:24:05.590022
(1 row)
```
#### DATE()
DATE(expr)
描述：返回时间或日期表达式expr的日期部分。
参数：expr，可取的类型有TEXT、DATETIME、DATE、TIME、时间或日期表达式等。
返回值类型：DATE
示例：
```
m_db=# SELECT DATE('2023-01-01 10:11:12');
    date    
------------
 2023-01-01
(1 row)
```
 #### DATE_ADD
DATE_ADD(date, INTERVAL expr unit)
描述：用于在指定的日期上添加一段时间间隔，并返回计算结果。
参数：具体说明如[表4]所示。
 表4DATE_ADD参数说明 
| 参数   | 类型                                  | 描述            | 取值范围                                                                                                                                                                                              |
|:---|:---|:---|:---|
| date | 时间类型表达式、TEXT、DATETIME、DATE、TIME等类型。 | 表示日期时间基准。     | 和类型范围一致。                                                                                                                                                                                          |
| expr | 整数、浮点数、字符串、表达式等。                    | 表示时间间隔，可以是负值。 | 和类型范围一致。                                                                                                                                                                                          |
| unit | 关键字。                                | 表示时间间隔的单位。    | YEAR、QUARTER、MONTH、WEEK、DAY、HOUR、MINUTE、SECOND或MICROSECOND等，具体请参见[时间间隔表达式](https://support.huaweicloud.com/distributed-m-comp-devg-v8-gaussdb/gaussdb-81-0179.html#ZH-CN_TOPIC_0000002527965476)。 |
   
返回值类型：TEXT、DATE、DATETIME或TIME。
示例：
```
m_db=# SELECT DATE_ADD('2018-05-01', INTERVAL 1 DAY);
  adddate   
------------
 2018-05-02
(1 row)
```
 #### DATE_FORMAT
DATE_FORMAT(date, format)
描述：将日期时间以指定格式输出。
参数：具体说明如[表5]所示。
 表5DATE_FORMAT参数说明 
| 参数     | 类型                                  | 描述       | 取值范围                                                                                         |
|:---|:---|:---|:---|
| date   | 时间类型表达式、TEXT、DATETIME、DATE、TIME等类型。 | 需要格式化的日期 | 和类型范围一致。                                                                                     |
| format | TEXT。                               | 格式化字符串   | 具体信息如[表6]所示。 |
   
 表6格式化字符串的具体取值和含义 
| 格式符  | 含义                                      |
|:---|:---|
| %a   | 星期的缩写（Sun..Sat）。                        |
| %b   | 月份的缩写（Jan..Dec）。                        |
| %c   | 月份数字（0..12）。                            |
| %D   | 带有英语前缀的月份中的每天（0th, 1st, 2nd, 3rd, ...）。 |
| %d   | 月份中的每天的两位数字表示（00..31）。                  |
| %e   | 月份中的每天的数字表示（0..31）。                     |
| %f   | 微秒（000000..999999）。                     |
| %H   | 小时（00..23）。                             |
| %h   | 小时（01..12）。                             |
| %I   | 小时（01..12）。                             |
| %i   | 分钟（00..59）。                             |
| %j   | 一年中的每天（001..366）。                       |
| %k   | 小时（0..23）。                              |
| %l   | 小时（1..12）。                              |
| %M   | 月份名称（January..December）。                |
| %m   | 两位数字月份（00..12）。                         |
| %p   | AM或者PM。                                 |
| %r   | 十二小时制时间（hh:mm:ss后跟AM或PM）。               |
| %S   | 秒（00..59）。                              |
| %s   | 秒（00..59）。                              |
| %T   | 二十四小时制时间（hh:mm:ss）。                     |
| %U   | 一年中的星期（00..53），每周的开始是星期天。               |
| %u   | 一年中的星期（00..53），每周的开始是星期一。               |
| %V   | 一年中的星期（01..53），每周的开始是星期天。               |
| %v   | 一年中的星期（01..53），每周的开始是星期一。               |
| %W   | 星期的名称（Sunday..Saturday）。                |
| %w   | 星期中的每天（0=星期天..6=星期六）。                   |
| %X   | 一年中的星期，每周的开始是星期天，四位数字，用于%V。             |
| %x   | 一年中的星期，每周的开始是星期一，四位数字，用于%v。             |
| %Y   | 四位数字年份。                                 |
| %y   | 两位数字年份。                                 |
| %%   | 文字字符%。                                  |
| %*x* | *x* ，对于以上未列出的任何"*x*"。                   |
   
返回值类型：TEXT
示例：
```
m_db=# SELECT DATE_FORMAT('2023-10-11 12:13:14.151617','%b %c %M %m');    
     date_format    
-------------------
 Oct 10 October 10
(1 row)
```
 #### DATE_SUB
DATE_SUB(date, INTERVAL expr unit)
描述：用于在指定的日期上减去一段时间间隔，并返回计算结果。
参数：具体说明如[表7]所示。
 表7DATE_SUB参数说明 
| 参数   | 类型                                  | 描述            | 取值范围                                                                                                                                                                                              |
|:---|:---|:---|:---|
| date | 时间类型表达式、TEXT、DATETIME、DATE、TIME等类型。 | 表示日期时间基准。     | 和类型范围一致。                                                                                                                                                                                          |
| expr | 整数、浮点数、字符串、表达式等。                    | 表示时间间隔，可以是负值。 | 和类型范围一致。                                                                                                                                                                                          |
| unit | 关键字。                                | 表示时间间隔的单位。    | YEAR、QUARTER、MONTH、WEEK、DAY、HOUR、MINUTE、SECOND或MICROSECOND等，具体请参见[时间间隔表达式](https://support.huaweicloud.com/distributed-m-comp-devg-v8-gaussdb/gaussdb-81-0179.html#ZH-CN_TOPIC_0000002527965476)。 |
   
返回值类型：TEXT、DATE、DATETIME或TIME。
示例：
```
m_db=# SELECT DATE_SUB('2018-05-01', INTERVAL 1 DAY);
  date_sub  
------------
 2018-04-30
(1 row)
```
#### DATEDIFF
DATEDIFF(date1, date2)
描述：返回date1和date2之间的天数。计算中只用到参数的日期部分，忽略时间部分。
参数：
- date1：时间类型表达式、TEXT、DATETIME、DATE、TIME等类型。
- date2：时间类型表达式、TEXT、DATETIME、DATE、TIME等类型。
返回值类型：INT
示例：
```
m_db=# SELECT DATEDIFF('2018-05-01', '2018-04-01');
 datediff 
----------
       30
(1 row)
```
 #### DAY
DAY(date)
描述：提取日期时间的天数部分，将结果返回。该函数是[DAYOFMONTH]的别名。
参数：date，表示指定提取的日期时间，可以是时间类型表达式、TEXT、DATETIME、DATE、TIME等类型。
返回值类型：INT
示例：
```
m_db=# SELECT DAY('2018-05-12');
 day 
-----
  12
(1 row)
```
#### DAYNAME
DAYNAME(date)
描述：返回日期的星期几名称。返回值使用的语言由GUC参数lc_time_names控制。
参数：date，表示日期时间，可以是时间类型表达式、TEXT、DATETIME、DATE、TIME等类型。
返回值类型：TEXT
示例：
```
m_db=# SELECT DAYNAME('2018-05-12');
 dayname  
----------
 Saturday
(1 row)
```
 #### DAYOFMONTH
DAYOFMONTH(date)
描述：提取日期时间的天数部分，将结果返回。该函数是[DAY]的别名。
参数：date，表示指定提取的日期时间，可以是时间类型表达式、TEXT、DATETIME、DATE、TIME等类型。
返回值类型：INT
示例：
```
m_db=# SELECT DAYOFMONTH('2018-05-12');
 dayofmonth 
------------
         12
(1 row)
```
#### DAYOFWEEK
DAYOFWEEK(date)
描述：返回日期的工作日索引（1=周日，2=周一，...，7=周六）。
参数：date，表示日期时间，可以是时间类型表达式、TEXT、DATETIME、DATE、TIME等类型。
返回值类型：BIGINT
示例：
```
m_db=# SELECT DAYOFWEEK('2023-04-16');
 dayofweek 
-----------
         1
(1 row)
```
#### DAYOFYEAR
DAYOFYEAR(date)
描述：返回一年中的第几天。
参数：date，表示日期时间，可以是时间类型表达式、TEXT、DATETIME、DATE、TIME等类型。
返回值类型：INT，范围\[1, 366\]。
示例：
```
m_db=# SELECT DAYOFYEAR('2000-12-31');
 dayofyear 
-----------
       366
(1 row)
```
#### EXTRACT
EXTRACT(unit FROM date)
描述：以整数类型返回date的unit指定部分值。如果unit指定多个部分，则将所有的值按顺序拼接。
参数：
- unit：表示时间间隔单位，具体请参见[时间间隔表达式](https://support.huaweicloud.com/distributed-m-comp-devg-v8-gaussdb/gaussdb-81-0179.html#ZH-CN_TOPIC_0000002527965476)。
- date：表示日期时间，可以是时间类型表达式、TEXT、DATETIME、DATE、TIME等类型。
返回值类型：BIGINT
示例：
```
m_db=# SELECT EXTRACT(DAY FROM '2000-12-31');
 extract 
---------
      31
(1 row)
m_db=# SELECT EXTRACT(WEEK FROM '2000-12-31');
 extract 
---------
      53
(1 row)
m_db=# SELECT EXTRACT(YEAR_MONTH FROM '2000-12-31');
 extract 
---------
  200012
(1 row)
```
#### FROM_DAYS
FROM_DAYS(days)
描述：返回指定天数days对应的日期值。天数指距离"0000-01-01"的天数。
参数：days，指定的天数。
返回值类型：DATE
示例：
```
m_db=# SELECT FROM_DAYS(50000);
 from_days  
------------
 0136-11-23
(1 row)
```
#### FROM_UNIXTIME
FROM_UNIXTIME(unix_timestamp\[, format\])
描述：将Unix时间戳转换为日期时间格式的函数。Unix时间戳是指从1970年1月1日08:00:00 UTC到指定时间的秒数。
参数：
- unix_timestamp：表示UNIX时间戳。
- format：返回指定格式的日期时间字符串。 具体返回指定格式请参见[DATE_FORMAT]函数。
  
返回值类型：TEXT/DATETIME
示例：
```
m_db=# SELECT FROM_UNIXTIME(1111885200);
    from_unixtime    
---------------------
 2005-03-27 09:00:00
(1 row)
m_db=# SELECT FROM_UNIXTIME(1447430881, '%Y %D %M %h:%i:%s %x');
          from_unixtime           
----------------------------------
 2015 14th November 12:08:01 2015
(1 row)
```
#### GET_FORMAT
GET_FORMAT({DATE \| TIME \| DATETIME \| TIMESTAMP}, {'EUR' \| 'USA' \| 'JIS' \| 'ISO' \| 'INTERNAL'})
描述：返回指定格式的字符串，即不同地区的"年月日 时分秒"格式和排序标准。
参数：
- DATE \| TIME \| DATETIME \| TIMESTAMP：表示时间类型，为关键字。
- 'EUR' \| 'USA' \| 'JIS' \| 'ISO' \| 'INTERNAL'：五种时间格式，TEXT类型。
返回值类型：TEXT
示例：
```
m_db=# SELECT GET_FORMAT(DATE, 'EUR');
 get_format 
------------
 %d.%m.%Y
(1 row)
m_db=# SELECT GET_FORMAT(DATE, 'USA');
 get_format 
------------
 %m.%d.%Y
(1 row)
```
#### HOUR
HOUR(expr)
描述：返回时间或日期时间表达式expr中的的小时部分的数值。
参数：time，表示时间，可以是时间类型表达式、TEXT、DATETIME、DATE、TIME等类型。
返回值类型：INT
示例：
```
m_db=# SELECT HOUR('10:11:12');
 hour 
------
   10
(1 row)
```
#### LAST_DAY
LAST_DAY(date)
描述：返回日期时间date当月最后一天的日期值。
参数：date，表示日期时间，可以是时间类型表达式、TEXT、DATETIME、DATE、TIME等类型。
返回值类型：DATE
示例：
```
m_db=# SELECT LAST_DAY('2023-01-01');
  last_day  
------------
 2023-01-31
(1 row)
m_db=# SELECT LAST_DAY('2023-01-01 10:11:12');
  last_day  
------------
 2023-01-31
(1 row)
```
#### LOCALTIME
LOCALTIME/LOCALTIME(\[scale\])
描述：返回本地函数调用开始时刻的日期时间。LOCALTIME和LOCALTIME()是[NOW]的同义词。
参数：scale，表示微秒部分的精度，有效值为0到6的整数，默认值为0。
返回值类型：DATETIME
示例：
```
m_db=# SELECT LOCALTIME;
      localtime      
---------------------
 2023-12-09 17:58:18
(1 row)
m_db=# SELECT LOCALTIME(6);
         localtime          
----------------------------
 2023-12-09 17:58:21.283227
(1 row)
```
#### LOCALTIMESTAMP
LOCALTIMESTAMP/LOCALTIMESTAMP(\[scale\])
描述：返回当前的日期时间。LOCALTIMESTAMP和LOCALTIMESTAMP()是[NOW]的同义词。
参数：scale，表示微秒部分的精度，有效值为0到6的整数，默认值为0。
返回值类型：DATETIME
示例：
```
m_db=# SELECT LOCALTIMESTAMP;
   localtimestamp    
---------------------
 2023-12-09 18:00:34
(1 row)
m_db=# SELECT LOCALTIMESTAMP(6);
       localtimestamp       
----------------------------
 2023-12-09 18:01:03.053427
(1 row)
```
#### MAKEDATE
MAKEDATE(year, dayofyear)
描述：根据年份和天数值返回日期。
参数：
- year：BIGINT，指定的年份。
- dayofyear：BIGINT，该年的第若干天，允许跨年，小于等于0时返回NULL。
返回值类型：DATE
示例：
```
m_db=# SELECT MAKEDATE(2000, 60);
  makedate  
------------
 2000-02-29
(1 row)
```
#### MAKETIME
MAKETIME(hour, minute, second)
描述：通过入参hour、minute、second生成指定的时间值。
参数：
- hour：小时部分对应的数值。
- minute：分钟部分对应的数值。
- second：秒数部分对应的数值，可以有小数部分。
返回值类型：TIME
示例：
```
m_db=# SELECT MAKETIME(8, 15, 26.53);
  maketime   
-------------
 08:15:26.53
(1 row)
m_db=# SELECT MAKETIME(-838, 15, 26.53);
   maketime    
---------------
 -838:15:26.53
(1 row)
```
#### MICROSECOND
MICROSECOND(expr)
描述：返回时间或日期时间表达式expr的微秒数。
参数：expr，可取的类型有TEXT、DATETIME、DATE、TIME、时间或日期表达式等。
返回值类型：BIGINT
示例：
```
m_db=# SELECT MICROSECOND('2023-5-5 10:10:10.24485');
 microsecond 
-------------
      244850
(1 row)
```
#### MINUTE
MINUTE(expr)
描述：返回时间或日期时间表达式expr中的分钟数。
参数：expr，可取的类型有TEXT、DATETIME、DATE、TIME、时间或日期表达式等。
返回值类型：INT
示例：
```
m_db=# SELECT MINUTE('10:11:12');
 minute 
--------
     11
(1 row)
```
#### MONTH
MONTH(date)
描述：提取日期时间的月份部分，将结果返回。
参数：date，表示指定提取的日期时间，可以是时间类型表达式、TEXT、DATETIME、DATE、TIME等类型。
返回值类型：INT
示例：
```
m_db=# SELECT MONTH('2018-05-12');
 month 
-------
     5
(1 row)
```
#### MONTHNAME
MONTHNAME(date)
描述：返回日期的月份全名称。
参数：date，表示日期时间，可以是时间类型表达式、TEXT、DATETIME、DATE、TIME等类型。
返回值类型：TEXT
示例：
```
m_db=# SELECT MONTHNAME('2018-05-12');
 monthname 
-----------
 May
(1 row)
```
 #### NOW
NOW(\[scale\])
描述：返回本地函数调用开始时刻的日期时间，受时区设置的影响。
参数：scale，表示微秒部分的精度，有效值为0到6的整数，默认值为0。
返回值类型：DATETIME
示例：
```
m_db=# SELECT NOW();
         now         
---------------------
 2023-12-11 09:46:56
(1 row)
m_db=# SELECT NOW(6);
            now            
---------------------------
 2023-12-11 09:46:58.404811
(1 row)
```
#### PERIOD_ADD
PERIOD_ADD(period, month_number)
描述：在指定格式的日期上添加指定的月数，并按照YYYYMM格式进行返回。
参数：
- period：使用YYYYMM或YYMM格式表示的日期。
- month_number：需要添加的月数，允许为负数。
返回值类型：BIGINT。
示例：
```
m_db=# SELECT PERIOD_ADD(202205, -12);
 period_add 
------------
     202105
(1 row)
```
#### PERIOD_DIFF
PERIOD_DIFF(P1, P2)
描述：计算两个日期的月份差。
参数：P1和P2均为YYMM或YYYYMM格式的日期。
返回值类型：BIGINT，月份差。
示例：
```
m_db=# SELECT PERIOD_DIFF('202101', '202102'); 
 period_diff 
-------------
          -1
(1 row)
```
#### QUARTER
QUARTER(date)
描述：返回指定日期的季度值，取值范围为\[1, 4\]。
参数：date，表示指定的日期时间，可以是时间类型表达式、TEXT、DATETIME、DATE、TIME等类型。
返回值类型：INT
示例：
```
m_db=# SELECT QUARTER('2018-05-12');
 quarter 
---------
       2
(1 row)
```
#### SEC_TO_TIME
SEC_TO_TIME(seconds)
描述：将seconds表示的秒数转换为TIME类型的时间。
参数：seconds，指定的秒数，取值范围\[-3020399, +3020399\]。
返回值类型：TIME
示例：
```
m_db=# SELECT SEC_TO_TIME(3020399);
 sec_to_time
-------------
 838:59:59
(1 row)
```
#### SECOND
SECOND(expr)
描述：返回时间或日期时间表达式expr中的秒数。
参数：expr，表示时间，可以是时间类型表达式、TEXT、DATETIME、DATE、TIME等类型。
返回值类型：INT
示例：
```
m_db=# SELECT SECOND('10:11:12');
 second 
--------
     12
(1 row)
```
#### STR_TO_DATE
STR_TO_DATE(str, format)
描述：将指定的字符串根据指定日期格式转为日期或时间。
参数：
- str：需要格式化成日期的字符串。
- format：格式化字符串，详见[表6]。
返回值类型：DATETIME、DATE、TIME。
示例：
```
m_db=# SELECT STR_TO_DATE('May 1, 2013','%M %d,%Y');
 str_to_date 
-------------
 2013-05-01
(1 row)
```
#### SUBDATE
- SUBDATE(date, INTERVAL expr unit) 描述：用于在指定的日期上减去一段时间间隔，并返回计算结果。该函数这种形式的功能用法与[DATE_SUB]函数相同。
  参数：具体说明如[表8]所示。
   表8SUBDATE参数说明 
  | 参数   | 类型                                  | 描述            | 取值范围                                                                                                                                                                                              |
  |:---|:---|:---|:---|
  | date | 时间类型表达式、TEXT、DATETIME、DATE、TIME等类型。 | 表示日期时间基准。     | 和类型范围一致。                                                                                                                                                                                          |
  | expr | 整数、浮点数、字符串、表达式等。                    | 表示时间间隔，可以是负值。 | 和类型范围一致。                                                                                                                                                                                          |
  | unit | 关键字。                                | 表示时间间隔的单位。    | YEAR、QUARTER、MONTH、WEEK、DAY、HOUR、MINUTE、SECOND或MICROSECOND等，具体请参见[时间间隔表达式](https://support.huaweicloud.com/distributed-m-comp-devg-v8-gaussdb/gaussdb-81-0179.html#ZH-CN_TOPIC_0000002527965476)。 |
     
  返回值类型：TEXT、DATE、DATETIME或TIME。
  示例：
  ```
  m_db=# SELECT SUBDATE('2018-05-01', INTERVAL 1 DAY);
    subdate   
  ------------
   2018-04-30
  (1 row)
  ```
  

- SUBDATE(date, days) 描述：用于将days指定的天数与date指定的日期相减，返回计算结果。
  参数：具体说明如[表9]所示。
   表9SUBDATE参数说明 
  | 参数   | 类型                                  | 描述            | 取值范围    |
  |:---|:---|:---|:---|
  | date | 时间类型表达式、TEXT、DATETIME、DATE、TIME等类型。 | 表示日期时间基准。     | 和类型范围一致 |
  | days | 整数、浮点数、字符串等。                        | 表示时间间隔，可以是负值。 | 和类型范围一致 |
     
  返回值类型：TEXT、DATE、DATETIME或TIME。
  示例：
  ```
  m_db=# SELECT SUBDATE('2018-05-01', 1);
    subdate   
  ------------
   2018-04-30
  (1 row)
  ```
  
 
#### SUBTIME
SUBTIME(expr1, expr2)
描述：返回时间或时间日期表达式expr1与时间表达式expr2相减后的值，返回值的格式与expr1保持一致。
参数：
- expr1：时间或时间日期表达式。
- expr2：时间表达式。
 
返回值类型：TEXT、DATETIME或TIME。返回值类型与expr1类型有关，expr1解析为DATETIME，则返回DATETIME，expr1解析为TIME，则返回TIME。
示例：
```
m_db=# SELECT SUBTIME('2000-03-01 20:59:59', '00:00:01');
       subtime       
---------------------
 2000-03-01 20:59:58
(1 row)
m_db=# SELECT SUBTIME('20:59:59', '00:00:01');
 subtime  
----------
 20:59:58
(1 row)
```
#### SYSDATE
SYSDATE(\[precision\])
描述：返回函数执行时刻的系统日期和时间。
参数：precision，表示微秒部分的精度，有效值为0到6的整数，默认值为0。
返回值类型：DATETIME
示例：
```
m_db=# SELECT SYSDATE();
       sysdate       
---------------------
 2023-12-11 11:28:29
(1 row)
m_db=# SELECT SYSDATE(6);
          sysdate           
----------------------------
 2023-12-11 11:28:31.535374
(1 row)
```
#### TIME
TIME(expr)
描述：返回时间或日期表达式expr的时间部分。
参数：expr，可取的类型有TEXT、DATETIME、DATE、TIME、时间或日期表达式等。
返回值类型：TIME
示例：
```
m_db=# SELECT TIME('2023-01-01 10:11:12');
   time   
----------
 10:11:12
(1 row)
```
#### TIME_FORMAT
TIME_FORMAT(time, format)
描述：根据格式说明符format格式化time入参。
参数：
- time：时间类型表达式、TEXT、DATETIME、DATE、TIME等类型。
- format：格式化字符串，具体取值和含义如[表10]所示。
   表10格式化字符串 
  | 格式符                                    | 含义                                |
  |:---|:---|
  | %f                                     | 微秒（000000至999999）。                |
  | %H                                     | 小时（00到23）。                        |
  | %h、%I                                  | 小时（00到12）。                        |
  | %l                                     | 小时（0到12）。                         |
  | %k                                     | 小时（0到838）。                        |
  | %i                                     | 分钟（00至59）。                        |
  | %p                                     | AM or PM。                         |
  | %r                                     | 时间为12小时AM或PM格式（hh：mm：ss AM / PM）。 |
  | %S、%s                                  | 秒（00到59）。                         |
  | %T                                     | 24小时格式的时间（hh：mm：ss）。              |
  | %a、%b、%D、%j、%M、%U、%u、%V、%v、%W、%w、%X、%x | NULL。                             |
  | %c、%e                                  | 0。                                |
  | %d、%m、%y                               | 00。                               |
  | %Y                                     | 0000。                             |
  | %其他字符/其他字符，如%A/A                       | 返回字符本身，如A。                        |
  | %单个字符+字符串s                             | 解析（%单个字符），拼接s。                    |
     
  
返回值类型：TEXT
示例：
```
m_db=# SELECT TIME_FORMAT('25:30:30', '%T|%r|%H|%h|%I|%i|%S|%f|%p|%k');
                   time_format                    
--------------------------------------------------
 25:30:30|01:30:30 AM|25|01|01|30|30|000000|AM|25
(1 row)
```
#### TIME_TO_SEC
TIME_TO_SEC(time)
描述：将TIME类型入参转化为秒数。
参数：time，时间类型表达式、TEXT、DATETIME、DATE或TIME等类型。时间表达式按照TIME来解析。
返回值类型：INT
示例：
```
m_db=# SELECT TIME_TO_SEC('10:11:12');
 time_to_sec 
-------------
       36672
(1 row)
```
#### TIMEDIFF
TIMEDIFF(date1, date2)
描述：以TIME类型返回两个日期的时间间隔。
参数：date1或date2，时间类型表达式、TEXT、DATETIME、DATE或TIME等类型。
返回值类型：TIME
示例：
```
m_db=# SELECT TIMEDIFF(date'2022-12-30',20221229);
 timediff 
----------
 24:00:00
(1 row)
```
#### TIMESTAMP
- TIMESTAMP(expr) 描述：返回日期时间表达式expr的日期时间值。
  参数：时间类型表达式、TEXT、DATETIME、DATE或TIME等类型。
  返回值类型：DATETIME
  示例：
  ```
  m_db=# SELECT TIMESTAMP('2022-12-30');
        timestamp      
  ---------------------
   2022-12-30 00:00:00
  (1 row)
  ```
  

- TIMESTAMP(expr1, expr2) 描述：返回日期时间表达式expr1与时间表达式expr2相加后的日期时间值。
  参数：时间类型表达式、TEXT、DATETIME、DATE或TIME等类型。
  返回值类型：DATETIME
  示例：
  ```
  m_db=# SELECT TIMESTAMP('2022-12-30', '12:00:00');
        timestamp      
  ---------------------
   2022-12-30 12:00:00
  (1 row)
  ```
  
 
#### TIMESTAMPADD
TIMESTAMPADD(unit, interval, datetime_expr)
描述：返回一个新的日期时间，该日期时间是通过将unit的多个interval添加到datetime_expr计算得到的。
参数：具体说明如[表11]所示。
 表11TIMESTAMPADD参数说明 
| 参数            | 类型                                  | 描述      | 取值范围                                                        |
|:---|:---|:---|:---|
| unit          | 关键字。                                | 时间间隔单位  | YEAR、QUARTER、MONTH、WEEK、DAY、HOUR、MINUTE、SECOND、MICROSECOND。 |
| interval      | 数值表达式。                              | 时间间隔数值  | 和类型范围一致。                                                    |
| datetime_expr | 时间类型表达式、TEXT、DATETIME、DATE或TIME等类型。 | 时间日期基准值 | 和类型范围一致。                                                    |
   
返回值类型：TEXT、DATE、DATETIME或TIME。
示例：
```
m_db=#  SELECT TIMESTAMPADD(DAY,-2,'2022-07-27');
 timestampadd 
--------------
 2022-07-25
(1 row)
```
#### TIMESTAMPDIFF
TIMESTAMPDIFF(unit, date1, date2)
描述：以unit为单位返回两个日期时间的间隔。
参数：具体说明如[表12]所示。
 表12TIMESTAMPDIFF参数说明 
| 参数    | 类型                                  | 描述     | 取值范围                                                        |
|:---|:---|:---|:---|
| unit  | 关键字。                                | 时间间隔单位 | YEAR、QUARTER、MONTH、WEEK、DAY、HOUR、MINUTE、SECOND、MICROSECOND。 |
| date1 | 时间类型表达式、TEXT、DATETIME、DATE或TIME等类型。 | 表示日期时间 | 和类型范围一致。                                                    |
| date2 | 时间类型表达式、TEXT、DATETIME、DATE或TIME等类型。 | 表示日期时间 | 和类型范围一致。                                                    |
   
返回值类型：BIGINT
示例：
```
m_db=# SELECT TIMESTAMPDIFF(SECOND, '2023-01-01 10:11:12', '2023-01-01 05:00:00');
 timestampdiff 
---------------
        -18672
(1 row)
```
#### TO_DAYS
TO_DAYS(date)
描述：返回指定日期距离"0000-01-01"的天数。
参数：入参为时间类型表达式、TEXT、DATETIME、DATE或TIME等类型。时间表达式按照DATE来解析。
返回值类型：INT
示例：
```
m_db=# SELECT TO_DAYS('2000-1-1');
 to_days 
---------
  730485
(1 row)
```
#### TO_SECONDS
TO_SECONDS(expr)
描述：返回时间或日期时间表达式expr自公元零年以来的秒数。
参数：入参为时间或日期时间表达式、TEXT、DATETIME、DATE或TIME等类型。时间表达式按照DATETIME来解析。
返回值类型：BIGINT
示例：
```
m_db=# SELECT TO_SECONDS('2009-11-29 13:43:32');
 to_seconds  
-------------
 63426721412
(1 row)
```
#### UNIX_TIMESTAMP
UNIX_TIMESTAMP(\[date\])
描述：
- 不指定date参数时，返回当前时间距离"1970-01-01 00:00:00"的秒数，受时区参数设置的影响。
- 指定参数date参数时，返回指定时间距离"1970-01-01 00:00:00"的秒数，受时区参数设置的影响。
参数：时间类型表达式、TEXT、DATETIME、DATE或TIME等类型。
返回值类型：DECIMAL/BIGINT。当入参存在小数部分或者入参为非法的时间类型字符串时，返回DECIMAL，否则返回BIGINT。
示例：
```
m_db=# SELECT UNIX_TIMESTAMP('2022-12-22');
 unix_timestamp 
----------------
     1671638400
(1 row)
```
#### UTC_DATE
UTC_DATE/UTC_DATE()
描述：将函数执行时的当前UTC日期作为"YYYY-MM-DD"格式的值返回。
返回值类型：DATE
示例：
```
m_db=# SELECT UTC_DATE;
  utc_date  
------------
 2023-12-11
(1 row)
m_db=# SELECT UTC_DATE();
  utc_date  
------------
 2023-12-11
(1 row)
```
#### UTC_TIME
UTC_TIME/UTC_TIME(\[scale\])
描述：将函数执行时的当前UTC时间作为"HH:MM:SS"格式的值返回。
参数：scale，表示微秒部分的精度，有效值为0到6的整数，默认值为0。
返回值类型：TIME
示例：
```
m_db=# SELECT UTC_TIME;
 utc_time 
----------
 07:10:49
(1 row)
m_db=# SELECT UTC_TIME();
 utc_time 
----------
 07:10:49
(1 row)
m_db=# SELECT UTC_TIME(6);
    utc_time     
-----------------
 07:10:51.445213
(1 row)
```
#### UTC_TIMESTAMP
UTC_TIMESTAMP/UTC_TIMESTAMP(\[scale\])
描述：将函数执行时的当前UTC时间戳作为"YYYY-MM-DD HH:MM:SS"格式的值返回。
参数：scale，表示微秒部分的精度，有效值为0到6的整数，默认值为0。
返回值类型：DATETIME
示例：
```
m_db=# SELECT UTC_TIMESTAMP;
    utc_timestamp    
---------------------
 2023-12-11 07:12:02
(1 row)
m_db=# SELECT UTC_TIMESTAMP();
    utc_timestamp    
---------------------
 2023-12-11 07:12:04
(1 row)
m_db=# SELECT UTC_TIMESTAMP(3);
      utc_timestamp      
-------------------------
 2023-12-11 07:12:06.413
(1 row)
```
 #### WEEK
WEEK(date\[, mode\])
描述：返回日期的周数。周数根据ISO 8601:1988计算，在ISO定义里，一月份的前几天可能是前一年的第52或者第53周，十二月份的后几天可能是下一年的第1周。
参数：
- date：指定日期时间，时间类型表达式、TEXT、DATETIME、DATE、TIME等类型。
- 当省略mode参数时，使用系统变量default_week_format的值，默认值为0。当指定mode参数时，可以指定一周的开始，以及返回值的范围。可选参数mode的含义如[表13]所示，默认值为0。
   表13mode参数的取值及含义说明 
  | mode | 一周的第一天 | 返回值范围 | 一月份的哪一个周是第一周 |
  |:---|:---|:---|:---|
  | 0    | 周日     | 0\~53 | 第一个有周日的周。    |
  | 1    | 周一     | 0\~53 | 第一个有4天及以上的周。 |
  | 2    | 周日     | 1\~53 | 第一个有周日的周。    |
  | 3    | 周一     | 1\~53 | 第一个有4天及以上的周。 |
  | 4    | 周日     | 0\~53 | 第一个有4天及以上的周。 |
  | 5    | 周一     | 0\~53 | 第一个有周一的周。    |
  | 6    | 周日     | 1\~53 | 第一个有4天及以上的周。 |
  | 7    | 周一     | 1\~53 | 第一个有周一的周。    |
     
  
返回值类型：BIGINT
示例：
```
m_db=# SELECT WEEK('2000-01-01');
 week 
------
    0
(1 row)
m_db=# SELECT WEEK('2000-01-01', 2);
 week 
------
   52
(1 row)
```
#### WEEKDAY
WEEKDAY(date)
描述：返回一个日期的工作日索引值，即星期一为0，星期二为1，星期三为2，星期四为3，星期五为4，星期六为5，星期日为6。
参数：时间类型表达式、TEXT、DATETIME、DATE或TIME等类型。
返回值类型：INT
示例：
```
m_db=# SELECT WEEKDAY('1970-01-01 12:00:00');
 weekday 
---------
 3
(1 row)
```
#### WEEKOFYEAR
WEEKOFYEAR(date)
描述：返回日期时间的日历周，范围\[1, 53\]。与[WEEK(date, 3)]功能相同。
参数：时间类型表达式、TEXT、DATETIME、DATE或TIME等类型。
返回值类型：INT
示例：
```
m_db=# SELECT WEEKOFYEAR('1970-05-22');
 weekofyear 
------------
         21
(1 row)
```
#### YEAR
YEAR(date)
描述：提取日期时间的年份部分，将结果返回。
参数：date，表示指定提取的日期时间，可以是时间类型表达式、TEXT、DATETIME、DATE、TIME等类型。
返回值类型：INT。
示例：
```
m_db=# SELECT YEAR('2018-05-12');
 year 
------
 2018
(1 row)
```
#### YEARWEEK
YEARWEEK(date\[, mode\])
描述：返回日期的年份和周数。
参数：
- date：指定日期时间，时间类型表达式、TEXT、DATETIME、DATE、TIME等类型。
- 可选参数mode，具体请参见[表13]。
返回值类型：BIGINT
示例：
```
m_db=#  SELECT YEARWEEK('2000-01-01', 3);
 yearweek 
----------
   199952
(1 row)
```