DATE_FORMAT

Описание

Функция DATE_FORMAT преобразует значение даты или времени в строку в соответствии с заданной строкой формата (format). Она поддерживает значения типов DATE, DATETIME, TIMESTAMP_NS и TIMESTAMPTZ и возвращает строку, соответствующую указанному формату.

Поведение этой функции соответствует функции date_format в MySQL.

Синтаксис

DATE_FORMAT(<date_or_time_expr>, <format>)

Параметры

Параметр	Описание
<date_or_time_expr>	Допустимое значение типа DATE, DATETIME, TIMESTAMP_NS или TIMESTAMPTZ. Подробные сведения о форматах даты и времени см. в разделах Преобразование даты, Преобразование даты и времени, Преобразование timestamp_ns и Преобразование timestamptz.
<format>	Задаёт формат вывода даты и времени; имеет тип varchar

Поддерживаемые спецификаторы формата:

Спецификатор формата	Описание
%a	Сокращённое название дня недели (3 буквы)
%b	Сокращённое название месяца (3 буквы)
%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), где первый день недели приходится на воскресенье; режим 0 функции week
%u	Неделя (00-53), где первый день недели приходится на понедельник; режим 1 функции week
%V	Неделя (01-53), где первый день недели приходится на воскресенье; режим 2 функции week, используется с %X
%v	Неделя (01-53), где первый день недели приходится на понедельник; режим 3 функции week, используется с %x
%W	Полное название дня недели (воскресенье-суббота)
%w	День недели (0 = воскресенье, 6 = суббота)
%X	Год при отсчёте недель с воскресенья (4 цифры), используется с %V
%x	Год при отсчёте недель с понедельника (4 цифры), используется с %v
%Y	Год (4 цифры)
%y	Год (2 цифры)
%%	Обозначает символ %
%x	Для любого x, не указанного выше, обозначает сам символ x

Также доступны три специальных формата:

yyyyMMdd --corresponds to standard format specifier：%Y%m%d
yyyy-MM-dd --corresponds to standard format specifier：%Y-%m-%d
yyyy-MM-dd HH:mm:ss --corresponds to standard format specifier：%Y-%m-%d %H:%i:%s

Возвращаемое значение

Отформатированная строка даты типа Varchar.

Особые случаи:

• Возвращает NULL, если format равен 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 |
+-------------------------------+

-- Output weekday name, month name, and 4-digit year
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                                              |
+------------------------------------------------------------------+

-- Output time in 24-hour format (hour:minute:second)
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                                       |
+------------------------------------------------+

-- Combine multiple format specifiers and plain characters
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 (year) used with %V (week number), where Sunday is the first day of the week
select date_format('1999-01-01 00:00:00', '%X-%V');

+---------------------------------------------+
| date_format('1999-01-01 00:00:00', '%X-%V') |
+---------------------------------------------+
| 1998-52                                     |
+---------------------------------------------+

-- Output the % character (escaped with %%)
select date_format(cast('2006-06-01' as date), '%%%d/%m');

+----------------------------------------------------+
| date_format(cast('2006-06-01' as date), '%%%d/%m') |
+----------------------------------------------------+
| %01/06                                             |
+----------------------------------------------------+

-- Special format 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                                       |
+-----------------------------------------------------------+

-- String that does not reference any time information
select date_format('2023-12-31 23:59:59', 'ghg');
+-------------------------------------------+
| date_format('2023-12-31 23:59:59', 'ghg') |
+-------------------------------------------+
| ghg                                       |
+-------------------------------------------+

-- Special format yyyyMMdd
select date_format('2023-12-31 23:59:59', 'yyyyMMdd');
+------------------------------------------------+
| date_format('2023-12-31 23:59:59', 'yyyyMMdd') |
+------------------------------------------------+
| 20231231                                       |
+------------------------------------------------+

-- Special format 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                                       |
+--------------------------------------------------+

-- Parameter is null
mysql> select date_format(NULL, '%Y-%m-%d');
+-------------------------------+
| date_format(NULL, '%Y-%m-%d') |
+-------------------------------+
| NULL                          |
+-------------------------------+

---Returns error if the result string exceeds the function's maximum length limit.
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

---output length over 102 size,throw error
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