DATE_FORMAT

描述

DATE_FORMAT 函数用于将日期或时间值按照指定的格式字符串（format）转换为字符串。支持对 DATE（仅日期）和 DATETIME（日期和时间）类型进行格式化，输出结果为符合格式要求的字符串。

该函数与 mysql 中的 date_format 函数 行为一致

语法

DATE_FORMAT(<date_or_time_expr>, <format>)

参数

参数	说明
<date_or_time_expr>	合法的日期值，支持为 datetime 或者 date 类型，具体 datetime 和 date 格式请查看 datetime 的转换 和 date 的转换)
<format>	规定日期/时间的输出格式，为 varchar 类型

支持的 format 格式：

格式符	描述
%a	三字母缩写星期名
%b	三字母缩写月名
%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	月名
%m	月，数值 (00-12)
%p	AM 或 PM
%r	时间，12-小时（hh:mm:ss, 后跟 AM 或 PM）
%S	秒 (00-59)
%s	秒 (00-59)
%T	时间，24-小时 (hh:mm:ss)
%U	周 (00-53) 星期日是一周的第一天，week，模式 0
%u	周 (00-53) 星期一是一周的第一天，week，模式 1
%V	周 (01-53) 星期日是一周的第一天，week，模式 2，与 %X 使用
%v	周 (01-53) 星期一是一周的第一天，week，模式 3，与 %x 使用
%W	周中日的名称 (Sunday-Saturday)
%w	周的天（0=星期日，6=星期六）
%X	年，其中的星期日是周的第一天，4 位，与 %V 使用
%x	年，其中的星期一是周的第一天，4 位，与 %v 使用
%Y	年，4 位
%y	年，2 位
%%	用于表示 %
%x	对于任何未出现在上列的 x，表示 x 本身

还可以使用三种特殊格式：

yyyyMMdd --对应标准格式符：%Y%m%d
yyyy-MM-dd --对应标准格式符：%Y-%m-%d
yyyy-MM-dd HH:mm:ss --对应标准格式符：%Y-%m-%d %H:%i:%s

返回值

格式化后的日期字符串，类型为 Varchar。

特殊情况：

• format 为 NULL 返回 NULL。
• 任一参数为 NULL 返回 NULL。
• 如果输入字符超过 128 字符长度，返回错误
• 如果返回结果字符串长度超过 102 ,返回错误

举例

-- 输出星期名、月名、4位年份
select date_format(cast('2009-10-04 22:23:00' as datetime), '%W %M %Y');
+------------------------------------------------------------------+
| date_format(cast('2009-10-04 22:23:00' as datetime), '%W %M %Y') |
+------------------------------------------------------------------+
| Sunday October 2009                                              |
+------------------------------------------------------------------+

-- 输出24小时制时间（时:分:秒）
select date_format('2007-10-04 22:23:00', '%H:%i:%s');
+------------------------------------------------+
| date_format('2007-10-04 22:23:00', '%H:%i:%s') |
+------------------------------------------------+
| 22:23:00                                       |
+------------------------------------------------+

-- 组合多种格式符和普通字符
select date_format('1900-10-04 22:23:00', 'Day: %D, Year: %y, Month: %b, DayOfYear: %j');
+-----------------------------------------------------------------------------------+
| date_format('1900-10-04 22:23:00', 'Day: %D, Year: %y, Month: %b, DayOfYear: %j') |
+-----------------------------------------------------------------------------------+
| Day: 4th, Year: 00, Month: Oct, DayOfYear: 277                                    |
+-----------------------------------------------------------------------------------+

-- %X（年份）与 %V（周数）搭配（星期日为周首）
select date_format('1999-01-01 00:00:00', '%X-%V');
+---------------------------------------------+
| date_format('1999-01-01 00:00:00', '%X-%V') |
+---------------------------------------------+
| 1998-52                                     |
+---------------------------------------------+

-- 输出 % 字符（需用 %% 转义）
select date_format(cast('2006-06-01' as date), '%%%d/%m');
+----------------------------------------------------+
| date_format(cast('2006-06-01' as date), '%%%d/%m') |
+----------------------------------------------------+
| %01/06                                             |
+----------------------------------------------------+

---特殊的格式 yyyy-MM-dd HH:mm:ss
select date_format('2023-12-31 23:59:59', 'yyyy-MM-dd HH:mm:ss');
+-----------------------------------------------------------+
| date_format('2023-12-31 23:59:59', 'yyyy-MM-dd HH:mm:ss') |
+-----------------------------------------------------------+
| 2023-12-31 23:59:59                                       |
+-----------------------------------------------------------+

---匹配字符串未引用任何时间的结果
select date_format('2023-12-31 23:59:59', 'ghg');
+-------------------------------------------+
| date_format('2023-12-31 23:59:59', 'ghg') |
+-------------------------------------------+
| ghg                                       |
+-------------------------------------------+

---特殊格式 yyyyMMdd
select date_format('2023-12-31 23:59:59', 'yyyyMMdd');
+------------------------------------------------+
| date_format('2023-12-31 23:59:59', 'yyyyMMdd') |
+------------------------------------------------+
| 20231231                                       |
+------------------------------------------------+

---特殊格式 yyyy-MM-dd
select date_format('2023-12-31 23:59:59', 'yyyy-MM-dd');
+--------------------------------------------------+
| date_format('2023-12-31 23:59:59', 'yyyy-MM-dd') |
+--------------------------------------------------+
| 2023-12-31                                       |
+--------------------------------------------------+

---参数为 null
mysql> select date_format(NULL, '%Y-%m-%d');
+-------------------------------+
| date_format(NULL, '%Y-%m-%d') |
+-------------------------------+
| NULL                          |
+-------------------------------+

---超出函数输入字符串长度范围，返回错误
mysql> select date_format('2022-01-12',repeat('a',129));
ERROR 1105 (HY000): errCode = 2, detailMessage = (10.16.10.3)[INVALID_ARGUMENT]Operation date_format of invalid or oversized format is invalid

---输出结果超过 102 字符串长度，报错
mysql> select date_format('2022-11-13 10:12:12',repeat('%h',52));
ERROR 1105 (HY000): errCode = 2, detailMessage = (10.16.10.3)[INVALID_ARGUMENT]Operation date_format of 142335809712816128,%h%h%h%h%h%h%h%h%h%h%h%h%h%h%h%h%h%h%h%h%h%h%h%h%h%h%h%h%h%h%h%h%h%h%h%h%h%h%h%h%h%h%h%h%h%h%h%h%h%h%h%h is invalid