GaussDB数据库MySQL兼容性B模式中日期时间函数的公共说明

以下为GaussDB数据库MySQL兼容性B模式中日期时间函数的公共说明，与MySQL行为一致。

• 函数入参为时间类型表达式的情况：

  时间类型表达式主要包括text、datetime、date或time，但所有可以隐式转换为时间表达式的类型都可以作为入参，比如数字类型可以通过先隐式转化为text，再作为时间类型表达式生效。

  但是，不同函数的具体生效情况会有所不同。例如：datediff函数仅计算日期之间的差值，因此时间表达式会被解析为日期；而timestampdiff函数在计算时间差值时，会根据unit参数来决定将时间表达式解析为date、time或 datetime。

• 函数入参为无效日期的情况：

  一般而言，日期时间函数支持date、datetime的范围和MySQL保持一致。date支持的范围为'0000-01-01'到'9999-12-31'，datetime支持的范围为'0000-01-01 00:00:00'到'9999-12-31 23:59:59'。虽然GaussDB支持的date、datetime范围大于MySQL，但是越界仍然算无效日期。

  大部分时间函数对于入参是无效日期时，会告警并返回NULL，只有能通过cast正常转换的日期，才是正常合理的日期。

• 函数入参的分隔符场景：

  对于时间函数，处理入参时会将所有非数字字符视作分隔符，然后根据数字所处的位置进行计算，推荐使用标准写法，年月日之间使用-分隔符，时分秒之间使用:分隔符，毫秒之前通过.来进行分隔。

  易错场景：在MySQL兼容性B模式数据库中执行“SELECT timestampdiff(hour, '2020-03-01 00:00:00', '2020-02-28 00:00:00+08');”时，时间函数不会自动计算时区，所以此处+08并未识别为时区，而是+作为分隔符当作秒来进行计算。

GaussDB的日期时间函数的大部分功能场景与MySQL一致，但仍有差异，部分差异如下：

• 函数入参为NULL时，函数返回NULL，无warning或error告警。这些函数包括：

  from_days、date_format、str_to_date、datediff、timestampdiff、date_add、subtime、month、time_to_sec、to_days、to_seconds、dayname、monthname、convert_tz、sec_to_time、addtime、adddate、date_sub、timediff、last_day、weekday、from_unixtime、unix_timestamp、subdate、day、year、weekofyear、dayofmonth、dayofyear、week、yearweek、dayofweek、time_format、hour、minute、second、microsecond、quarter、get_format、extract、makedate、period_add、timestampadd、period_diff、utc_time、utc_timestamp、maketime、curtime

  示例：

  gaussdb=# SELECT day(null);
   day 
  -----
  
  (1 row)

   

   
• 纯数字入参个别函数与MySQL有差异，不带引号的数字入参统一转成text入参来处理。

  示例：

  gaussdb=# SELECT day(19231221.123141);
  WARNING:  Incorrect datetime value: "19231221.123141"
  CONTEXT:  referenced column: day
   day
  -----
  
  (1 row)

   

   
• 时间日期运算函数：adddate、subdate、date_add、date_sub。当运算后的结果为日期时，支持的范围为[0000-01-01, 9999-12-31]，当运算后的结果为日期时间时，支持的范围为[0000-01-01 00:00:00.000000, 9999-12-31 23:59:59.999999]，当运算后的结果超过支持的范围时，在严格模式下报error，在宽松模式下报warning。另外，当运算后的日期结果在范围[0000-01-01, 0001-01-01]中时，GaussDB正常返回结果，MySQL返回'0000-00-00'。

  示例：

  gaussdb=# SELECT subdate('0000-01-01', interval 1 hour);
  ERROR:  Datetime function: datetime field overflow
  CONTEXT:  referenced column: subdate
  
  gaussdb=# SELECT subdate('0001-01-01', interval 1 day);
     subdate
  -------------
   0000-12-31
  
  (1 row)

   

   
• 对于日期和时间函数的date或datetime类型入参，含有0月或0日时为非法值，在严格模式下报error；在宽松模式，当输入为字符串或数字时，报warning，输入为date或datetime类型时视为上一年12月或上一月最后一日处理。

  对于cast函数，转换为date、datetime时，严格模式下会报error。宽松模式下不会报warning，而是视为上一年12月或上一月最后一日处理，需要注意此区别。MySQL对于包含0年、0月或0日的情况会原样输出。

  示例：

  gaussdb=# SELECT adddate('2023-01-00', 1);-- 严格模式
  ERROR:  Incorrect datetime value: "2023-01-00"
  CONTEXT:  referenced column: adddate
  
  gaussdb=# SELECT adddate('2023-01-00', 1);-- 宽松模式
  WARNING:  Incorrect datetime value: "2023-01-00"
  CONTEXT:  referenced column: adddate
   adddate 
  ---------
  
  (1 row)
  
  gaussdb=# SELECT adddate(date'2023-00-00', 1);-- 宽松模式
    adddate   
  ------------
   2022-12-01
  (1 row)
  
  gaussdb=# SELECT cast('2023/00/00' AS date);-- 宽松模式
      date    
  ------------
   2022-11-30
  (1 row)
  
  gaussdb=# SELECT cast('0000-00-00' AS datetime);-- 宽松模式
        timestamp      
  ---------------------
   0000-00-00 00:00:00
  (1 row)

   

   
• 若函数入参为numeric数据类型，在非法输入的情况下不会产生报错，会把入参当做0值处理。

  示例：

  gaussdb=# SELECT from_unixtime('aa');
      from_unixtime
  ---------------------
   1970-01-01 08:00:00
  (1 row)

   

   
• 最多保留6位小数，不保留后置都为0的小数。

  示例：

  gaussdb=# SELECT from_unixtime('1234567899.00000');
      from_unixtime
  ---------------------
   2009-02-14 07:31:39
  (1 row)

   

   

• 时间函数参数为字符串时，只保证年月日之间使用“-”分隔，时分秒之间使用“:”分隔时结果正确。

  示例：

  gaussdb=# SELECT adddate('20-12-12',interval 1 day);
    adddate   
  ------------
   2020-12-13
  (1 row)

   

   

• 在MySQL中，当函数的返回值为varchar时，在GaussDB中，函数对应的返回值为text。

  -- GaussDB中函数的返回值。
  gaussdb=# SELECT pg_typeof(adddate('2023-01-01', 1));
   pg_typeof 
  -----------
   text
  (1 row)
  
  -- MySQL中函数的返回值。
  mysql> CREATE VIEW v1 AS SELECT adddate('2023-01-01', 1);
  Query OK, 0 rows affected (0.00 sec)
  
  mysql> DESC v1;
  +--------------------------+-------------+------+-----+---------+-------+
  | Field                    | Type        | Null | Key | Default | Extra |
  +--------------------------+-------------+------+-----+---------+-------+
  | adddate('2023-01-01', 1) | varchar(29) | YES  |     | NULL    |       |
  +--------------------------+-------------+------+-----+---------+-------+
  1 row in set (0.00 sec)

更多详情请参考GaussDB 文档中心：https://doc.hcs.huawei.com/db/zh-cn/gaussdbqlh/24.1.30/productdesc/qlh_03_0001.html