DATE_CEIL

説明

date_ceil関数は、指定された日付または時刻値を、指定された時間間隔期間の最も近い開始点まで切り上げます。期間ルールは、固定開始点0001-01-01 00:00:00から計算されるperiod（単位数）とtype（単位）によって定義されます。

日付計算式: $$ \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$ はperiodの単位を表します

構文

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

パラメータ

パラメータ	説明
date_or_time_expr	有効な日付式で、datetimeまたはdate型の入力をサポートします。具体的なdatetimeとdateの形式については、datetime conversionとdate conversionを参照してください
period	各期間が構成される単位数を指定し、INT型です。開始時点は0001-01-01T00:00:00です
type	YEAR、QUARTER、MONTH、WEEK、DAY、HOUR、MINUTE、SECONDのいずれかを指定できます

戻り値

入力値を指定された単位まで切り上げた結果を表す日付または時刻値を返します。 切り上げられた結果はdatetimeと同じ型です:

• 入力がDATEの場合、DATE（日付部分のみ）を返します;
• 入力がDATETIMEの場合、DATETIME（日付と時刻を含む）を返します。
• scaleを持つdatetimeの場合、戻り値もscaleを持ち、小数部は0になります。

特殊ケース:

• いずれかのパラメータが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                                         |
+-------------------------------------------------------------+

-- 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