大网数据广告活动
数据库部署与 SQL 参考

Apache Doris 中文参考:DATE_FORMAT

· 52CE 我爱测

特殊情况: - format 为 NULL 返回 NULL。 - 任一参数为 NULL 返回 NULL。 - 如果输入字符超过 128 字符长度,返回错误 - 如果返回结果字符串长度超过 102 ,返回错误

描述

DATE_FORMAT 函数按照指定格式字符串(format)将 DATE、DATETIME、TIMESTAMP_NS 或 TIMESTAMPTZ 值转换为字符串。

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

语法

DATE_FORMAT(<date_or_time_expr>, <format>)

参数

参数 说明
<date_or_time_expr> 合法的 DATE、DATETIME、TIMESTAMP_NS 或 TIMESTAMPTZ 值。格式请参见 date 转换、datetime 转换、TIMESTAMP_NS 转换和 timestamptz 转换。
<format> 规定日期/时间的输出格式,为 varchar 类型

支持的 format 格式:

格式符 描述
%a 三字母缩写星期名
%b 三字母缩写月名
%c 月,数值 (0-12)
%D 带有英文后缀的月中的天 (0th, 1st, 2nd, 3rd, …)
%d 月的天,数值 (00-31)
%e 月的天,数值 (0-31)
%f 微秒 (000000-999999)
%n 纳秒 (000000000-999999999)。低精度类型缺少的位数在末尾补零。
%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 ,返回错误

举例

SELECT DATE_FORMAT(
    CAST('2024-02-29 12:34:56.123456789' AS TIMESTAMP_NS),
    '%Y-%m-%d %H:%i:%s.%n'
) AS result;
+-------------------------------+
| result                        |
+-------------------------------+
| 2024-02-29 12:34:56.123456789 |
+-------------------------------+
-- 输出星期名、月名、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

本文来自 Apache Doris 文档贡献者,按 Apache 2.0 整理版式与相对链接,保留正文与代码。图示请参阅原文。作者与贡献记录。

资料来源与适用范围

资料来源
Apache Doris 文档贡献者
适用范围
master 文档快照(2026-11-16)
内容语言
中文;命令、路径和错误标识保留技术原文
本地收录日期
2026-11-16
授权说明
Apache 2.0

正文与所需资源由本站本地存储。查看来源及更新记录 ↗

请按适用版本和实际日志确认原因;本站没有对每一种系统或设备逐项执行文中的操作。