DATE_TRUNC

Описание

Функция DATE_TRUNC усекает значение типа DATE, DATETIME, TIMESTAMP_NS или TIMESTAMPTZ (datetime) до указанной единицы времени (time_unit). При этом сохраняются компоненты даты и времени, соответствующие указанной единице и более крупным единицам, а компоненты более мелких единиц сбрасываются до минимальных значений. Например, при усечении до единицы "hour" сохраняются год, месяц, день и час, а минуты, секунды и т. д. обнуляются. При усечении до года день и месяц сбрасываются до xxxx-01-01.

Синтаксис

DATE_TRUNC(<datetime>, <time_unit>)
DATE_TRUNC(<time_unit>, <datetime>)

Параметры

Параметр	Описание
<datetime>	Допустимое выражение даты. Поддерживаются DATE, DATETIME, TIMESTAMP_NS и TIMESTAMPTZ. Подробнее о форматах см. в разделах преобразование timestamptz, преобразование datetime и преобразование date.
<time_unit>	Единица времени, до которой выполняется усечение. Доступные значения: [second,minute,hour,day,week,month,quarter,year] Единица времени должна быть строковой константой; столбец или неконстантное выражение использовать нельзя.

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

Если входное значение имеет тип TIMESTAMP_NS, возвращается значение типа TIMESTAMP_NS с фиксированной точностью дробной части секунды до девяти знаков. Результаты проверяются на соответствие диапазону возвращаемого типа; для TIMESTAMP_NS используется диапазон [1677-09-21 00:12:43.145224192, 2262-04-11 23:47:16.854775807].

Возвращает усечённый результат того же типа, что и datetime:

• Если входное значение имеет тип DATE, возвращается DATE;
• Если входное значение имеет тип DATETIME или представляет собой строку, содержащую время, возвращается DATETIME (включая дату и усечённое время).
• Если входное значение имеет тип TIMESTAMP_NS, возвращается TIMESTAMP_NS с девятью знаками в дробной части секунды.
• Если входное значение имеет тип TIMESTAMPTZ, оно сначала преобразуется в local_time (например, если значение переменной сеанса равно +08:00, то local_time для 2025-12-31 23:59:59+05:00 равно 2026-01-01 02:59:59), после чего выполняется усечение.
• Для типов datetime с заданным масштабом дробная часть обнуляется, но масштаб сохраняется в возвращаемом значении.

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

• Если любой из параметров равен NULL, возвращается NULL;
• Если time_unit не поддерживается, возвращается ошибка.

Примеры

-- Truncate by second, minute, hour, day, week, month, quarter, year
mysql> select date_trunc(cast('2010-12-02 19:28:30' as datetime), 'second');

+---------------------------------------------------------------+
| date_trunc(cast('2010-12-02 19:28:30' as datetime), 'second') |
+---------------------------------------------------------------+
| 2010-12-02 19:28:30                                           |
+---------------------------------------------------------------+

select date_trunc('2010-12-02 19:28:30', 'minute');

+-------------------------------------------------+
| date_trunc('2010-12-02 19:28:30', 'minute')     |
+-------------------------------------------------+
| 2010-12-02 19:28:00                             |
+-------------------------------------------------+

select date_trunc('2010-12-02 19:28:30', 'hour');

+-------------------------------------------------+
| date_trunc('2010-12-02 19:28:30', 'hour')       |
+-------------------------------------------------+
| 2010-12-02 19:00:00                             |
+-------------------------------------------------+

select date_trunc('2010-12-02 19:28:30', 'day');

+-------------------------------------------------+
| date_trunc('2010-12-02 19:28:30', 'day')        |
+-------------------------------------------------+
| 2010-12-02 00:00:00                             |
+-------------------------------------------------+

select date_trunc('2023-4-05 19:28:30', 'week');

+-------------------------------------------+
| date_trunc('2023-04-05 19:28:30', 'week') |
+-------------------------------------------+
| 2023-04-03 00:00:00                       |
+-------------------------------------------+

select date_trunc(cast('2010-12-02' as date), 'month');
+-------------------------------------------------+
| date_trunc(cast('2010-12-02' as date), 'month') |
+-------------------------------------------------+
| 2010-12-01                                      |
+-------------------------------------------------+

select date_trunc('2010-12-02 19:28:30', 'quarter');

+-------------------------------------------------+
| date_trunc('2010-12-02 19:28:30', 'quarter')    |
+-------------------------------------------------+
| 2010-10-01 00:00:00                             |
+-------------------------------------------------+

select date_trunc('2010-12-02 19:28:30', 'year');

+-------------------------------------------------+
| date_trunc('2010-12-02 19:28:30', 'year')       |
+-------------------------------------------------+
| 2010-01-01 00:00:00                             |
+-------------------------------------------------+

-- For datetime with scale, fractional digits will be truncated to zero without rounding, but return value retains scale
mysql> select date_trunc('2010-12-02 19:28:30.523', 'second');
+-------------------------------------------------+
| date_trunc('2010-12-02 19:28:30.523', 'second') |
+-------------------------------------------------+
| 2010-12-02 19:28:30.000                         |
+-------------------------------------------------+

-- Example of TimeStampTz type, SET time_zone = '+08:00'
-- Convert the variable value to local_time(2026-01-01 02:59:59) before truncation
SELECT DATE_TRUNC('2025-12-31 23:59:59+05:00', 'year');
+-------------------------------------------------+
| DATE_TRUNC('2025-12-31 23:59:59+05:00', 'year') |
+-------------------------------------------------+
| 2026-01-01 00:00:00+08:00                       |
+-------------------------------------------------+

-- Unsupported unit, returns error
select date_trunc('2010-12-02 19:28:30', 'quar');
ERROR 1105 (HY000): errCode = 2, detailMessage = date_trunc function time unit param only support argument is year|quarter|month|week|day|hour|minute|second