HOUR_FLOOR

描述

HOUR_FLOOR 函数用于将输入的日期时间值向下取整到指定小时周期的最近时刻。例如，若指定周期为 5 小时，函数会将输入时间调整为该周期内的起始整点时刻.

日期时间的计算公式：

$$\begin{aligned} &\text{hour\_floor}(\langle\text{date\_or\_time\_expr}\rangle, \langle\text{period}\rangle, \langle\text{origin}\rangle) = \\ &\max\{\langle\text{origin}\rangle + k \times \langle\text{period}\rangle \times \text{hour} \mid \\ &k \in \mathbb{Z} \land \langle\text{origin}\rangle + k \times \langle\text{period}\rangle \times \text{hour} \leq \langle\text{date\_or\_time\_expr}\rangle\} \end{aligned}$$

$k$ 代表的是基准时间到目标时间的周期数

语法

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

参数

参数	说明
<date_or_time_expr>	参数是合法的日期表达式，支持输入 datetime/date 类型,date 类型会转换为对应日期的一天起始时间 00:00:00 ,具体 datetime/date 格式请查看 datetime 的转换 和 date 的转换
<period>	可选参数，指定周期长度（单位：小时），为正整数（如 2、6、12）。默认值为 1，表示每 1 小时一个周期。
<origin>	开始的时间起点，支持输入 datetime/date 类型，如果不填，默认是 0001-01-01T00:00:00

返回值

返回 DATETIME 类型的值，表示向下取整后的最近周期时刻。

• 若输入的 period 为非正数，返回错误。
• 若是任意参数为 NULL ,结果返回 NULL.
• origin 或 datetime 带有 scale,返回结果带有 scale，小数部分变为零
• 若 <origin> 日期时间在 <period> 之后，也会按照上述公式计算，不过周期 k 为负数。

举例

-- 按5小时周期向下取整，默认起点为0001-01-01 00:00:00

mysql> select hour_floor("2023-07-13 22:28:18", 5);
+--------------------------------------+
| hour_floor("2023-07-13 22:28:18", 5) |
+--------------------------------------+
| 2023-07-13 18:00:00                  |
+--------------------------------------+

-- 以2023-07-13 08:00为起点，按4小时周期划分

mysql> select hour_floor('2023-07-13 19:30:00', 4, '2023-07-13 08:00:00') as custom_origin;
+---------------------+
| custom_origin       |
+---------------------+
| 2023-07-13 16:00:00 |
+---------------------+

---输入日期时间恰好为周期边缘，返回输入日期时间值
 select hour_floor("2023-07-13 18:00:00", 5);
+--------------------------------------+
| hour_floor("2023-07-13 18:00:00", 5) |
+--------------------------------------+
| 2023-07-13 18:00:00                  |
+--------------------------------------+

---输入 date 类型，会转换为一天 起始时间 2023-07-13 00:00:00
mysql>  select hour_floor('2023-07-13 20:30:00', 4, '2023-07-13');
+----------------------------------------------------+
| hour_floor('2023-07-13 20:30:00', 4, '2023-07-13') |
+----------------------------------------------------+
| 2023-07-13 20:00:00                                |
+----------------------------------------------------+

---origin 或 datetime 带有 scale,返回结果带有 scale
mysql> select hour_floor('2023-07-13 19:30:00.123', 4, '2023-07-03 08:00:00') as custom_origin;
+-------------------------+
| custom_origin           |
+-------------------------+
| 2023-07-13 16:00:00.000 |
+-------------------------+

mysql> select hour_floor('2023-07-13 19:30:00', 4, '2023-07-03 08:00:00.123') as custom_origin;
+-------------------------+
| custom_origin           |
+-------------------------+
| 2023-07-13 16:00:00.123 |
+-------------------------+

--- 若 <origin> 日期时间在 <period> 之后，也会按照上述公式计算，不过周期 k 为负数。
select hour_floor('2023-07-13 19:30:00.123', 4, '2028-07-14 08:00:00');
+-----------------------------------------------------------------+
| hour_floor('2023-07-13 19:30:00.123', 4, '2028-07-14 08:00:00') |
+-----------------------------------------------------------------+
| 2023-07-13 16:00:00.000                                         |
+-----------------------------------------------------------------+

-- 输入任一参数为 NULL（返回NULL）
mysql> select hour_floor(null, 6) as null_input;
+------------+
| null_input |
+------------+
| NULL       |
+------------+

---period 为负数，返回 错误
mysql> select hour_floor('2023-12-31 23:59:59', -3);
ERROR 1105 (HY000): errCode = 2, detailMessage = (10.16.10.3)[E-218]Operation hour_floor of 2023-12-31 23:59:59, -3 out of range