文档首页/ 云数据库 GaussDB/ M-Compatibility开发指南（集中式）/ SQL参考/ 函数和操作符/ 日期时间函数
更新时间：2025-09-12 GMT+08:00
查看PDF
分享

日期时间函数

ADDDATE

  • ADDDATE(date, INTERVAL expr unit)

    描述：用于在指定的日期上添加一段时间间隔，并返回计算结果。该函数这种形式的功能用法与DATE_ADD函数相同。

    参数：参数具体说明见下表。

    参数

    类型

    描述

    取值范围

    date

    时间类型表达式、TEXT、DATETIME、DATE、TIME等类型。

    表示日期时间基准。

    和类型范围一致。

    expr

    整数、浮点数、字符串、表达式等。

    表示时间间隔，可以是负值。

    和类型范围一致。

    unit

    关键字。

    表示时间间隔的单位。

    YEAR、QUARTER、MONTH、WEEK、DAY、HOUR、MINUTE、SECOND、MICROSECOND等，详见时间间隔表达式。

    示例：

    m_db=# SELECT ADDDATE('2018-05-01', INTERVAL 1 DAY);
  adddate   
------------
 2018-05-02
(1 row)
  • ADDDATE(date, days)

    描述：用于将days指定的天数与date指定的日期相加，返回计算结果。

    参数：参数具体说明见下表。

    参数

    类型

    描述

    取值范围

    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类型支持范围，则不会发生转换。

参数：参数具体说明见下表。

参数

类型

描述

取值范围

dt

TEXT、DATETIME、DATE、TIME和其他可以隐式转换为DATETIME的类型。

表示日期时间值。

请参见表1。

from_tz/to_tz

±hh:mm格式的字符串。

表示相较于UTC时间的偏移，如'+08:00'。

[-12:59, +13:00]，正负号必须加。

命名时区。

如'MET'、'UTC'等。

具体请参考PG_TIMEZONE_NAMES系统视图。

返回值类型：DATETIME

示例：

1
2
3
4
5
 
m_db=# SELECT CONVERT_TZ('2023-01-01 10:10:10', '+00:00', '+08:00');
     convert_tz      
---------------------
 2023-01-01 18:10:10
(1 row)

CURDATE

CURDATE()

描述：返回本地函数调用开始时刻的系统日期。支持在同一连接内修改时区，返回的日期受时区的影响。

返回值类型：DATE

示例：

1
2
3
4
5
 
m_db=# SELECT CURDATE();
  curdate   
------------
 2023-12-09
(1 row)

CURRENT_DATE

CURRENT_DATE/CURRENT_DATE()

描述：返回本地函数调用开始时刻的系统日期。支持在同一连接内修改时区，返回的日期受时区的影响。该函数是CURDATE的别名。

返回值类型：DATE

示例：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
 
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

示例：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
 
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

示例：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
 
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

示例：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
 
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

示例：

1
2
3
4
5
 
m_db=# SELECT DATE('2023-01-01 10:11:12');
    date    
------------
 2023-01-01
(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)

DATE_ADD

DATE_ADD(date, INTERVAL expr unit)

描述：用于在指定的日期上添加一段时间间隔，并返回计算结果。

参数：参数具体说明见下表。

参数

类型

描述

取值范围

date

时间类型表达式、TEXT、DATETIME、DATE、TIME等类型。

表示日期时间基准。

和类型范围一致。

expr

整数、浮点数、字符串、表达式等。

表示时间间隔，可以是负值。

和类型范围一致。

unit

关键字。

表示时间间隔的单位。

YEAR、QUARTER、MONTH、WEEK、DAY、HOUR、MINUTE、SECOND、MICROSECOND等，详见时间间隔表达式。

返回值类型：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)

描述：将日期时间以指定格式输出。

参数：参数具体说明见下表。

参数

类型

描述

取值范围

date

时间类型表达式、TEXT、DATETIME、DATE、TIME等类型。

需要格式化的日期。

和类型范围一致。

format

TEXT。

格式化字符串。

详见表1
表1 格式化字符串的具体取值和含义

格式符

含义

%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)

描述：用于在指定的日期上减去一段时间间隔，并返回计算结果。

参数：参数具体说明见下表。

参数

类型

描述

取值范围

date

时间类型表达式、TEXT、DATETIME、DATE、TIME等类型。

表示日期时间基准。

和类型范围一致。

expr

整数、浮点数、字符串、表达式等。

表示时间间隔，可以是负值。

和类型范围一致。

unit

关键字。

表示时间间隔的单位。

YEAR、QUARTER、MONTH、WEEK、DAY、HOUR、MINUTE、SECOND、MICROSECOND等，详见时间间隔表达式。

返回值类型：TEXT、DATE、DATETIME或TIME。

示例：

m_db=# SELECT DATE_SUB('2018-05-01', INTERVAL 1 DAY);
  date_sub  
------------
 2018-04-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：表示时间间隔单位，详见时间间隔表达式。
  • 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：返回指定格式的日期时间字符串。

返回值类型：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

示例：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
 
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)

SECOND

SECOND(expr)

描述：返回时间或日期时间表达式expr中的秒数。

参数：expr，表示时间，可以是时间类型表达式、TEXT、DATETIME、DATE、TIME等类型。

返回值类型：INT

示例：

m_db=# SELECT SECOND('10:11:12');
 second 
--------
     12
(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.000000
(1 row)

STR_TO_DATE

STR_TO_DATE(str, format)

描述：将指定的字符串根据指定日期格式转为日期或时间。

参数：

  • str：需要格式化成日期的字符串。
  • format：格式化字符串，详见表1。

返回值类型：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函数相同。

    参数：参数具体说明见下表。

    参数

    类型

    描述

    取值范围

    date

    时间类型表达式、TEXT、DATETIME、DATE、TIME等类型。

    表示日期时间基准。

    和类型范围一致。

    expr

    整数、浮点数、字符串、表达式等。

    表示时间间隔，可以是负值。

    和类型范围一致。

    unit

    关键字。

    表示时间间隔的单位。

    YEAR、QUARTER、MONTH、WEEK、DAY、HOUR、MINUTE、SECOND、MICROSECOND等，详见时间间隔表达式。

    返回值类型：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指定的日期相减，返回计算结果。

    参数：参数具体说明见下表。

    参数

    类型

    描述

    取值范围

    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

示例：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
 
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

示例：

1
2
3
4
5
 
m_db=# SELECT TIME('2023-01-01 10:11:12');
   time   
----------
 10:11:12
(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相加后的日期时间值。如果expr2中包含日期，返回NULL空值。

    参数：时间类型表达式、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计算得到的。

参数：参数的具体说明如下表。

参数

类型

描述

取值范围

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为单位返回两个日期时间的间隔。

参数：参数的具体说明如下表。

参数

类型

描述

取值范围

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)

TIME_FORMAT

TIME_FORMAT(time, format)

描述：根据格式说明符format格式化time入参。

参数：

  • time：时间类型表达式、TEXT、DATETIME、DATE、TIME等类型。
  • format：格式化字符串，具体取值和含义如下表所示。

    格式符

    含义

    %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)

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的含义如下表所示，默认值为0。
    表2 mode参数的取值及含义说明

    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详见表2。

返回值类型：BIGINT

示例：

m_db=#  SELECT YEARWEEK('2000-01-01', 3);
 yearweek 
----------
   199952
(1 row)
父主题： 函数和操作符

相关文档