MONTH_CEIL

描述

MONTH_CEIL 函数用于将输入的日期时间值向上取整到最近的指定月份周期。若指定起始时间（origin），则以该时间为基准划分周期并取整；若未指定，默认以 0001-01-01 00:00:00 为基准。该函数支持处理 DATETIME、DATE 类型。

日期计算公式：

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

$k$ 代表基准时间到达目标时间所需的周期数

语法

MONTH_CEIL(`<date_or_time_expr>`)
MONTH_CEIL(`<date_or_time_expr>`, `<origin>`)
MONTH_CEIL(`<date_or_time_expr>`, `<period>`)
MONTH_CEIL(`<date_or_time_expr>`, `<period>`, `<origin>`)

参数

参数	说明
<date_or_time_expr>	需要向上取整的日期时间值，参数是合法的日期表达式，支持输入 date/datetime 类型,具体 datetime 和 date 格式请查看 datetime 的转换 和 date 的转换
<period>	月份周期值，类型为 INT，表示每个周期包含的月数
<origin>	周期的起始时间点，支持输入 date/datetime 类型，默认值为 0001-01-01 00:00:00

返回值

返回类型为 DATETIME，返回以输入日期时间为基准，向上取整到最近的指定月份周期后的时间值。结果的时间部分将被设置为 00:00:00,日部分会截断为 01。

• 若 <period> 为非正，返回错误。
• 若任一参数为 NULL，返回 NULL。
• 不指定 period 时，默认以 1 个月为周期。
• <origin> 未指定，默认以 0001-01-01 00:00:00 为基准。
• 输入为 DATE 类型（默认时间设置为 00:00:00）。
• 计算结果超过日期最大范围 9999-12-31 23:59:59，结果返回错误
• 若 <origin> 日期时间在 <period> 之后，也会按照上述公式计算，不过周期 k 为负数。
• 若 date_or_time_expr 带有 scale,则返回结果也带有 scale 且小数部分为零.

举例

--- 以默认周期1个月，默认起始时间 0001-01-01 00:00:00
SELECT MONTH_CEIL('2023-07-13 22:28:18') AS result;
+---------------------+
| result              |
+---------------------+
| 2023-08-01 00:00:00 |
+---------------------+

--- 以5个月为一周期，以默认起始点的向上取整结果
SELECT MONTH_CEIL('2023-07-13 22:28:18', 5) AS result;
+---------------------+
| result              |
+---------------------+
| 2023-12-01 00:00:00 |
+---------------------+

---输入日期时间恰好在周期起点，则返回输入日期时间
SELECT MONTH_CEIL('2023-12-01 00:00:00', 5) AS result;
+----------------------------+
| result                     |
+----------------------------+
| 2023-12-01 00:00:00        |
+----------------------------+

--- 指定起始时间（origin）
SELECT MONTH_CEIL('2023-07-13 22:28:18', 5, '2023-01-01 00:00:00') AS result;
+---------------------+
| result              |
+---------------------+
| 2023-11-01 00:00:00 |
+---------------------+

--- 带有 scale 的 datetime，时间部分及小数位均截断为 0
SELECT MONTH_CEIL('2023-07-13 22:28:18.456789', 5) AS result;
+----------------------------+
| result                     |
+----------------------------+
| 2023-12-01 00:00:00.000000 |
+----------------------------+

--- 若 <origin> 日期时间在 <period> 之后，也会按照上述公式计算，不过周期 k 为负数。
SELECT MONTH_CEIL('2022-09-13 22:28:18', 5, '2028-07-03 22:20:00') AS result;
+---------------------+
| result              |
+---------------------+
| 2023-02-03 22:20:00 |
+---------------------+

--- 输入为 DATE 类型（默认时间 00:00:00）
SELECT MONTH_CEIL('2023-07-13', 3) AS result;
+---------------------+
| result              |
+---------------------+
| 2023-10-01 00:00:00 |
+---------------------+

-- 计算结果超过日期最大范围 9999-12-31，结果返回错误
SELECT MONTH_CEIL('9999-12-13 22:28:18',5) AS result;
ERROR 1105 (HY000): errCode = 2, detailMessage = (10.16.10.3)[E-218]Operation month_ceil of 9999-12-13 22:28:18, 5 out of range

--- 周期为非正数，返回错误
SELECT MONTH_CEIL('2023-07-13 22:28:18', -5) AS result;
ERROR 1105 (HY000): errCode = 2, detailMessage = (10.16.10.3)[E-218]Operation month_ceil of 2023-07-13 22:28:18, -5 out of range

--- 任一参数为 NULL，返回 NULL
SELECT MONTH_CEIL(NULL, 5), MONTH_CEIL('2023-07-13 22:28:18', NULL) AS result;
+----------------------+--------+
| month_ceil(NULL, 5)  | result |
+----------------------+--------+
| NULL                 | NULL   |
+----------------------+--------+