Skip to content

[fix](doc) Fix date function hour to millisecond functions #2810

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 8 commits into
base: master
Choose a base branch
from
Open

[fix](doc) Fix date function hour to millisecond functions #2810

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
48cb64c
fix_only_dev_hour_v2
dwdwqfwe Sep 9, 2025
f897cd9
fix_only_dev_hour_v3
dwdwqfwe Sep 9, 2025
365ee9d
fix_only_dev_hour_v4
dwdwqfwe Sep 11, 2025
c2de6e8
fix_only_dev_hour_v5
dwdwqfwe Sep 11, 2025
39c63ef
fix_only_dev_hour_v6
dwdwqfwe Sep 15, 2025
1d69d38
jh-v5
dwdwqfwe Sep 15, 2025
8bc8025
jh-v5
dwdwqfwe Sep 15, 2025
ca4e471
jh-v6
dwdwqfwe Sep 16, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
127 changes: 108 additions & 19 deletions docs/sql-manual/sql-functions/scalar-functions/date-time-functions/hour-ceil.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,45 +1,134 @@
---
{
"title": "HOUR_CEIL",
"language": "en"
"title": "HOUR_CEIL",
"language": "en"
}
---

## Description

Converts the date to the nearest rounded-up timestamp of the specified time interval period.
The HOUR_CEIL function rounds up the input datetime value to the nearest moment of the specified hour period. For example, if the period is specified as 5 hours, the function will adjust the input time to the next hour mark within that period (if the input time is already at the period origin, it remains unchanged).

Date calculation formula:
$$
\text{HOUR\_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{hour} \mid k \in \mathbb{Z} \land \langle\text{origin}\rangle + k \times \langle\text{period}\rangle \times \text{hour} \geq \langle\text{date\_or\_time\_expr}\rangle\}
$$
K represents the number of periods required from the baseline time to reach the target time.

## Syntax

```sql
HOUR_CEIL(<datetime>)
HOUR_CEIL(<datetime>, <origin>)
HOUR_CEIL(<datetime>, <period>)
HOUR_CEIL(<datetime>, <period>, <origin>)
HOUR_CEIL(`<date_or_time_expr>`)
HOUR_CEIL(`<date_or_time_expr>`, `<origin>`)
HOUR_CEIL(`<date_or_time_expr>`, `<period>`)
HOUR_CEIL(`<date_or_time_expr>`, `<period>`, `<origin>`)
```

## Parameters

| Parameter | Description |
| -- | -- |
| `<datetime>` | A valid date expression |
| `<period>`| Specifies how many hours make up each period|
| `<origin>` | The starting point of time. If not provided, the default is 0001-01-01T00:00:00 |
| `<date_or_time_expr>` | A valid date expression that supports datetime and date types. Date type will be converted to the start of the day at 00:00:00. For specific datetime/date formats, please refer to [datetime conversion](../../../../../docs/sql-manual/basic-element/sql-data-types/conversion/datetime-conversion) and [date conversion](../../../../../docs/sql-manual/basic-element/sql-data-types/conversion/date-conversion) |
| `<period>` | Optional parameter that specifies the period length (unit: hours), must be a positive integer (such as 1, 3, 5). Default value is 1, representing one period every 1 hour |
| `<origin>` | The starting time origin, supports datetime and date types. If not provided, the default is 0001-01-01T00:00:00 |

## Return Value

Returns the nearest rounded-up timestamp of the specified time interval period.
Returns a DATETIME type value representing the nearest period moment after rounding up.

- If the input period is a non-positive integer, returns an error.
- If any parameter is NULL, the result returns NULL.
- If origin or datetime has scale, the returned result has scale.
- If the calculation result exceeds the maximum datetime range 9999-12-31 23:59:59, returns an error.
- If the <origin> date and time is after the <period>, it will still be calculated according to the above formula, but the period k will be negative.


## Examples

```sql
select hour_ceil("2023-07-13 22:28:18", 5);
```

```text
+------------------------------------------------------------+
| hour_ceil(cast('2023-07-13 22:28:18' as DATETIMEV2(0)), 5) |
+------------------------------------------------------------+
| 2023-07-14 02:00:00 |
+------------------------------------------------------------+
-- Round up with a 5-hour period
mysql> select hour_ceil("2023-07-13 22:28:18", 5);
+-------------------------------------+
| hour_ceil("2023-07-13 22:28:18", 5) |
+-------------------------------------+
| 2023-07-13 23:00:00 |
+-------------------------------------+

-- Using 2023-07-13 08:00 as the origin, divide by 4-hour periods
mysql> select hour_ceil('2023-07-13 19:30:00', 4, '2023-07-13 08:00:00') as custom_origin;
+----------------------------+
| custom_origin |
+----------------------------+
| 2023-07-13 20:00:00 |
+----------------------------+

-- Input date type will be converted to the start time 00:00:00 of the corresponding date
mysql> select hour_ceil('2023-07-13 00:30:00', 6, '2023-07-13');
+---------------------------------------------------+
| hour_ceil('2023-07-13 00:30:00', 6, '2023-07-13') |
+---------------------------------------------------+
| 2023-07-13 06:00:00 |
+---------------------------------------------------+

-- If exactly at the edge of a period, return the input datetime
select hour_ceil('2023-07-13 01:00:00');
+----------------------------------+
| hour_ceil('2023-07-13 01:00:00') |
+----------------------------------+
| 2023-07-13 01:00:00 |
+----------------------------------+

-- If origin or datetime has scale, the returned result has scale
mysql> select hour_ceil('2023-07-13 19:30:00', 4, '2023-07-13 08:00:00.123') ;
+----------------------------------------------------------------+
| hour_ceil('2023-07-13 19:30:00', 4, '2023-07-13 08:00:00.123') |
+----------------------------------------------------------------+
| 2023-07-13 20:00:00.123 |
+----------------------------------------------------------------+

mysql> select hour_ceil('2023-07-13 19:30:00.123', 4, '2023-07-13 08:00:00') ;
+----------------------------------------------------------------+
| hour_ceil('2023-07-13 19:30:00.123', 4, '2023-07-13 08:00:00') |
+----------------------------------------------------------------+
| 2023-07-13 20:00:00.000 |
+----------------------------------------------------------------+

--- If the <origin> date and time is after the <period>, it will still be calculated according to the above formula, but the period k will be negative.
select hour_ceil('2023-07-13 19:30:00.123', 4, '2028-07-14 08:00:00') ;
+----------------------------------------------------------------+
| hour_ceil('2023-07-13 19:30:00.123', 4, '2028-07-14 08:00:00') |
+----------------------------------------------------------------+
| 2023-07-13 20:00:00.000 |
+----------------------------------------------------------------+

-- If calculation result exceeds maximum datetime range 9999-12-31 23:59:59, return NULL
select hour_ceil("9999-12-31 22:28:18", 6);
ERROR 1105 (HY000): errCode = 2, detailMessage = (10.16.10.3)[E-218]Operation hour_ceil of 9999-12-31 22:28:18, 6 out of range

-- If period is less than or equal to 0, return error
mysql> select hour_ceil("2023-07-13 22:28:18", 0);
ERROR 1105 (HY000): errCode = 2, detailMessage = (10.16.10.3)[INVALID_ARGUMENT]Operation hour_ceil of 2023-07-13 22:28:18, 0 input wrong parameters, period can not be negative or zero

-- If any input parameter is NULL, return NULL
mysql> select hour_ceil(null, 3) as null_input;
+------------+
| null_input |
+------------+
| NULL |
+------------+

mysql> select hour_ceil("2023-07-13 22:28:18", NULL);
+----------------------------------------+
| hour_ceil("2023-07-13 22:28:18", NULL) |
+----------------------------------------+
| NULL |
+----------------------------------------+

mysql> select hour_ceil("2023-07-13 22:28:18", 5,NULL);
+------------------------------------------+
| hour_ceil("2023-07-13 22:28:18", 5,NULL) |
+------------------------------------------+
| NULL |
+------------------------------------------+
```
111 changes: 93 additions & 18 deletions docs/sql-manual/sql-functions/scalar-functions/date-time-functions/hour-floor.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,40 +7,115 @@

## Description

Converts the date to the nearest rounded-down timestamp of the specified time interval period.
The HOUR_FLOOR function rounds down the input datetime value to the nearest moment of the specified hour period. For example, if the period is specified as 5 hours, the function will adjust the input time to the starting hour mark within that period.

Datetime calculation formula:

$$
\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\}
$$

K represents the number of periods from the baseline time to the target time.

## Syntax

```sql
HOUR_FLOOR(<datetime>)
HOUR_FLOOR(<datetime>, <origin>)
HOUR_FLOOR(<datetime>, <period>)
HOUR_FLOOR(<datetime>, <period>, <origin>)
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>`)
```

## Parameters

| Parameter | Description |
| -- | -- |
| `<datetime>` | A valid date expression |
| `<period>` | Specifies how many hours make up each period|
| `<origin>` | The starting point of time. If not provided, the default is 0001-01-01T00:00:00 |
| `<date_or_time_expr>` | A valid date expression that supports datetime/date types. Date type will be converted to the start time 00:00:00 of the corresponding date. For specific datetime/date formats, please refer to [datetime conversion](../../../../../docs/sql-manual/basic-element/sql-data-types/conversion/datetime-conversion) and [date conversion](../../../../../docs/sql-manual/basic-element/sql-data-types/conversion/date-conversion) |
| `<period>` | Optional parameter that specifies the period length (unit: hours), must be a positive integer (such as 2, 6, 12). Default value is 1, representing one period every 1 hour |
| `<origin>` | The starting time origin, supports datetime/date types. If not provided, the default is 0001-01-01T00:00:00 |

## Return Value

Returns the nearest rounded-down timestamp of the specified time interval period.
Returns a DATETIME type value representing the nearest period moment after rounding down.

- If the input period is a non-positive integer, returns NULL.
- If any parameter is NULL, the result returns NULL.
- If origin or datetime has scale, the returned result has scale.
- If the `<origin>` date and time is after the `<period>`, it will still be calculated according to the above formula, but the period k will be negative.

## Examples

```sql
select hour_floor("2023-07-13 22:28:18", 5);
```

```text
+-------------------------------------------------------------+
| hour_floor(cast('2023-07-13 22:28:18' as DATETIMEV2(0)), 5) |
+-------------------------------------------------------------+
| 2023-07-13 21:00:00 |
+-------------------------------------------------------------+
```
-- Round down by 5-hour period, default origin is 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 |
+--------------------------------------+

-- Using 2023-07-13 08:00 as origin, divide by 4-hour periods
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 |
+---------------------+

-- Input datetime exactly at period edge, return input datetime value
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 |
+--------------------------------------+

-- Input date type will be converted to start time 2023-07-13 00:00:00 of the day
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 |
+----------------------------------------------------+

-- If origin or datetime has scale, the returned result has 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 |
+-------------------------+

--- If the <origin> date and time is after the <period>, it will still be calculated according to the above formula, but the period k will be negative.
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 |
+-----------------------------------------------------------------+

-- Input any parameter as NULL (returns NULL)
mysql> select hour_floor(null, 6) as null_input;
+------------+
| null_input |
+------------+
| NULL |
+------------+

-- Period is negative, returns NULL
mysql> select hour_floor('2023-12-31 23:59:59', -3);
+---------------------------------------+
| hour_floor('2023-12-31 23:59:59', -3) |
+---------------------------------------+
| NULL |
+---------------------------------------+

```
83 changes: 61 additions & 22 deletions docs/sql-manual/sql-functions/scalar-functions/date-time-functions/hour.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,46 +7,85 @@

## Description

Obtains the hour information from the given datetime.
The HOUR function extracts the hour part from a datetime or time expression. This function supports multiple time type inputs, including DATE/DATETIME and TIME, and returns the corresponding hour value.

For DATETIME (such as '2023-10-01 14:30:00'), the return value ranges from 0-23 (24-hour format).
For TIME type (such as '456:26:32'), the return value can exceed 24, ranging from [0,838].

This function behaves consistently with the [hour function](https://dev.mysql.com/doc/refman/8.4/en/date-and-time-functions.html#function_hour) in MySQL.

## Syntax

```sql
HOUR(<dt>)
HOUR(`<date_or_time_expr>`)
```

## Parameters

| Parameter | Description |
| -- | -- |
| `<dt>` | The date to be calculated. |
| `<date_or_time_expr>` | A valid date expression that supports datetime/date/time types. Date type will be converted to the start time 00:00:00 of the corresponding date. For specific datetime/date/time formats, please refer to [datetime conversion](../../../../../docs/sql-manual/basic-element/sql-data-types/conversion/datetime-conversion) and [date conversion](../../../../../docs/sql-manual/basic-element/sql-data-types/conversion/date-conversion), and [time conversion](../../../../../docs/sql-manual/basic-element/sql-data-types/conversion//time-conversion) |

## Return Value

Returns the hour information from the given date. The return value ranges from 0 to 23. When the parameter is of type TIME, the return value can be greater than 24.
Returns an integer type (INT) representing the hour part of the input expression.
- For DATETIME, returns an integer from 0-23.
- For DATE type, returns 0.
- For TIME type, returns an integer from 0 to 838 (consistent with the TIME type range), it return tht absolute value.
- If the input parameter is NULL, returns NULL.

## Examples

```sql
select hour('2018-12-31 23:59:59');
```
-- Extract hour from datetime (24-hour format)
select
hour('2018-12-31 23:59:59') as last_hour,
hour('2023-01-01 00:00:00') as midnight,
hour('2023-10-01 12:30:45') as noon;

```text
+-----------------------------+
| hour('2018-12-31 23:59:59') |
+-----------------------------+
| 23 |
+-----------------------------+
```
+-----------+----------+------+
| last_hour | midnight | noon |
+-----------+----------+------+
| 23 | 0 | 12 |
+-----------+----------+------+

```sql
select cast(4562632 as time),hour(cast(4562632 as time)), minute(cast(4562632 as time)),second(cast(4562632 as time));
```
-- Extract hour from TIME type (supports over 24 or negative values)
select
hour(cast('14:30:00' as time)) as normal_hour,
hour(cast('25:00:00' as time)) as over_24,
hour(cast('456:26:32' as time)) as large_hour,
hour(cast('-12:30:00' as time)) as negative_hour,
hour(cast('838:59:59' as time)) as max_hour,
hour(cast('-838:59:59' as time)) as min_hour;

+-------------+---------+------------+---------------+----------+----------+
| normal_hour | over_24 | large_hour | negative_hour | max_hour | min_hour |
+-------------+---------+------------+---------------+----------+----------+
| 14 | 25 | 456 | 12 | 838 | 838 |
+-------------+---------+------------+---------------+----------+----------+

-- Extract hour from date type, returns 0
select hour("2022-12-12");
+--------------------+
| hour("2022-12-12") |
+--------------------+
| 0 |
+--------------------+

```text
+-----------------------+-----------------------------+-------------------------------+-------------------------------+
| cast(4562632 as TIME) | hour(cast(4562632 as TIME)) | minute(cast(4562632 as TIME)) | second(cast(4562632 as TIME)) |
+-----------------------+-----------------------------+-------------------------------+-------------------------------+
| 456:26:32 | 456 | 26 | 32 |
+-----------------------+-----------------------------+-------------------------------+-------------------------------+
-- Will not automatically convert input time string to time, returns NULL
select hour('14:30:00') as normal_hour;
+-------------+
| normal_hour |
+-------------+
| NULL |
+-------------+

-- Input parameter is NULL, returns NULL
mysql> select hour(NULL);
+------------+
| hour(NULL) |
+------------+
| NULL |
+------------+
```

Loading