DATE_CEIL

Описание

Функция date_ceil округляет указанное значение даты или времени вверх до ближайшего начала заданного временного периода. Поддерживаются входные значения типов DATE, DATETIME, TIMESTAMP_NS и TIMESTAMPTZ. Правила округления задаются параметрами period (количество единиц) и type (единица измерения), а отсчёт ведётся от фиксированной начальной точки 0001-01-01 00:00:00.

Формула расчёта даты:

$$\begin{aligned} &\text{date\_ceil}(\langle\text{date\_or\_time\_expr}\rangle, \langle\text{period}\rangle, \langle\text{type}\rangle) = \\ &\min\{\langle\text{origin}\rangle + k \times \langle\text{period}\rangle \times \text{type} \mid \\ &k \in \mathbb{Z} \land \langle\text{origin}\rangle + k \times \langle\text{period}\rangle \times \text{type} \geq \langle\text{date\_or\_time\_expr}\rangle\} \end{aligned}$$

$k$ обозначает количество периодов, необходимое для достижения целевого времени от начальной точки отсчёта.

$type$ обозначает единицу измерения периода

Синтаксис

DATE_CEIL(<datetime>, INTERVAL <period> <type>)

Параметры

Параметр	Описание
date_or_time_expr	Корректное выражение даты. Поддерживаются типы DATE, DATETIME, TIMESTAMP_NS и TIMESTAMPTZ. Подробнее о форматах см. в разделах преобразование timestamptz, преобразование datetime и преобразование date.
period	Задаёт количество единиц в каждом периоде; имеет тип INT. Начальная точка отсчёта: 0001-01-01T00:00:00
type	Допустимые значения: YEAR, QUARTER, MONTH, WEEK, DAY, HOUR, MINUTE, SECOND

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

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

Если <origin> не указан для входного значения TIMESTAMP_NS, описанная в документации начальная точка по умолчанию используется только как внутренняя точка отсчёта для выравнивания; она не обязана находиться в диапазоне значений, которые может хранить TIMESTAMP_NS.

Возвращаемый тип: TIMESTAMPTZ, TIMESTAMP_NS, DATETIME или DATE. Возвращается значение даты или времени, полученное округлением входного значения вверх до указанной единицы измерения.

Тип округлённого результата соответствует типу <date_or_time_expr>:

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

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

• Если любой из параметров равен NULL, возвращается NULL;
• Если округлённый результат выходит за диапазон, поддерживаемый типом даты (например, за пределы '9999-12-31 23:59:59'), возвращается ошибка;
• Если параметр period является неположительным целым числом, возникает ошибка.

Примеры

-- Round up seconds to the nearest 5-second interval
mysql> select date_ceil(cast("2023-07-13 22:28:18" as datetime),interval 5 second);

+------------------------------------------------------------------------+
| date_ceil(cast("2023-07-13 22:28:18" as datetime),interval 5 second) |
+------------------------------------------------------------------------+
| 2023-07-13 22:28:20.000000                                             |
+------------------------------------------------------------------------+

-- Date time parameter with scale
mysql> select date_ceil(cast("2023-07-13 22:28:18.123" as datetime(3)),interval 5 second);
+-----------------------------------------------------------------------------+
| date_ceil(cast("2023-07-13 22:28:18.123" as datetime(3)),interval 5 second) |
+-----------------------------------------------------------------------------+
| 2023-07-13 22:28:20.000                                                     |
+-----------------------------------------------------------------------------+

-- Round up to the nearest 5-minute interval
select date_ceil("2023-07-13 22:28:18",interval 5 minute);
+--------------------------------------------------------------+
| minute_ceil('2023-07-13 22:28:18', 5, '0001-01-01 00:00:00') |
+--------------------------------------------------------------+
| 2023-07-13 22:30:00                                          |
+--------------------------------------------------------------+

-- Round up to the nearest 5-week interval
select date_ceil("2023-07-13 22:28:18",interval 5 WEEK);
+--------------------------------------------------+
| date_ceil("2023-07-13 22:28:18",interval 5 WEEK) |
+--------------------------------------------------+
| 2023-08-14 00:00:00                              |
+--------------------------------------------------+

-- Round up to the nearest 5-hour interval
select date_ceil("2023-07-13 22:28:18",interval 5 hour);

+--------------------------------------------------+
| date_ceil("2023-07-13 22:28:18",interval 5 hour) |
+--------------------------------------------------+
| 2023-07-13 23:00:00                   |
+--------------------------------------------------+

-- Round up to the nearest 5-day interval
select date_ceil("2023-07-13 22:28:18",interval 5 day);

+-----------------------------------------------------------+
| day_ceil('2023-07-13 22:28:18', 5, '0001-01-01 00:00:00') |
+-----------------------------------------------------------+
| 2023-07-15 00:00:00                                       |
+-----------------------------------------------------------+

-- Round up to the nearest 5-month interval
select date_ceil("2023-07-13 22:28:18",interval 5 month);

+-------------------------------------------------------------+
| month_ceil('2023-07-13 22:28:18', 5, '0001-01-01 00:00:00') |
+-------------------------------------------------------------+
| 2023-12-01 00:00:00                                         |
+-------------------------------------------------------------+


-- Round up to the nearest 5-year interval
select date_ceil("2023-07-13 22:28:18",interval 5 year);

+-------------------------------------------------------------+
| month_ceil('2023-07-13 22:28:18', 5, '0001-01-01 00:00:00') |
+-------------------------------------------------------------+
| 2023-12-01 00:00:00                                         |
+-------------------------------------------------------------+

-- TimeStampTz type example, SET time_zone = '+08:00'
-- Convert variable value to local_time(2026-01-01 02:59:59) then perform DATE_CEIL operation
SELECT DATE_CEIL('2025-12-31 23:59:59+05:00', INTERVAL 1 YEAR);
+---------------------------------------------------------+
| DATE_CEIL('2025-12-31 23:59:59+05:00', INTERVAL 1 YEAR) |
+---------------------------------------------------------+
| 2027-01-01 00:00:00+08:00                               |
+---------------------------------------------------------+

-- Exceeds the maximum year
mysql> select date_ceil("9999-07-13",interval 5 year);
ERROR 1105 (HY000): errCode = 2, detailMessage = (10.16.10.3)[E-218]Operation year_ceil of 9999-07-13 00:00:00, 5 out of range

-- Any parameter is NULL
mysql> select date_ceil("9900-07-13",interval NULL year);
+--------------------------------------------+
| date_ceil("9900-07-13",interval NULL year) |
+--------------------------------------------+
| NULL                                       |
+--------------------------------------------+

mysql> select date_ceil(NULL,interval 5 year);
+---------------------------------+
| date_ceil(NULL,interval 5 year) |
+---------------------------------+
| NULL                            |
+---------------------------------+

-- Invalid parameter, period is negative
mysql> select date_ceil("2023-01-13 22:28:18",interval -5 month);
ERROR 1105 (HY000): errCode = 2, detailMessage = (10.16.10.3)[INVALID_ARGUMENT]Operation month_ceil of 2023-01-13 22:28:18, -5, 0001-01-01 00:00:00 out of range