Перейти к содержимому
Последнее обновление

HOURS_ADD

Описание​

Функция HOURS_ADD прибавляет указанное количество часов к входному значению даты или даты и времени либо вычитает их из него и возвращает полученное значение даты и времени. Функция поддерживает входные значения типов DATE, DATETIME и TIMESTAMPTZ. Если входное значение имеет тип DATE (содержит только год, месяц и день), перед добавлением часов временная часть по умолчанию устанавливается в 00:00:00.

Поведение этой функции соответствует поведению функции date_add и функции date_add в MySQL при использовании единицы измерения HOUR.

Синтаксис​

HOURS_ADD(`<date_or_time_expr>`, `<hours>`)

Параметры​

ПараметрОписание
<date_or_time_expr>Допустимое выражение даты, поддерживающее типы date/datetime/timestamptz. Сведения о форматах см. в разделах преобразование timestamptz, преобразование datetime и преобразование date
<hours>Количество добавляемых часов, целое число типа INT. Может быть положительным или отрицательным: положительное число добавляет указанное количество часов, отрицательное — вычитает указанное количество часов (что эквивалентно вычитанию часов)

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

Возвращает исходное время <date_or_time_expr> с добавлением указанного количества часов <hours>. Тип возвращаемого значения определяется типом первого параметра:

  • Если первый параметр имеет тип DATE/DATETIME, возвращаемое значение имеет тип DATETIME.
  • Если первый параметр имеет тип TIMESTAMPTZ, возвращаемое значение имеет тип TIMESTAMPTZ.

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

  • Если результат вычисления выходит за допустимый диапазон типа DATETIME [0000-01-01 00:00:01, 9999-12-31 23:59:59], возвращается ошибка.
  • Если хотя бы один из параметров равен NULL, возвращается NULL.

Примеры​


-- Add hours to datetime type
SELECT HOURS_ADD('2020-02-02 02:02:02', 1);
+------------------------------------------------------------+
| hours_add(cast('2020-02-02 02:02:02' as DATETIMEV2(0)), 1) |
+------------------------------------------------------------+
| 2020-02-02 03:02:02                                        |
+------------------------------------------------------------+

-- Add hours to date type (default time is 00:00:00)
SELECT HOURS_ADD('2020-02-02', 51);
+-----------------------------+
| HOURS_ADD('2020-02-02', 51) |
+-----------------------------+
| 2020-02-04 03:00:00         |
+-----------------------------+

-- Add negative hours (i.e., subtract hours)
select hours_add('2023-10-01 10:00:00', -3) ;
+--------------------------------------+
| hours_add('2023-10-01 10:00:00', -3) |
+--------------------------------------+
| 2023-10-01 07:00:00                  |
+--------------------------------------+

-- Example of TimeStampTz type, SET time_zone = '+08:00'
SELECT HOURS_ADD('2025-10-10 11:22:33.123+07:00', 1);
+-----------------------------------------------+
| HOURS_ADD('2025-10-10 11:22:33.123+07:00', 1) |
+-----------------------------------------------+
| 2025-10-10 13:22:33.123+08:00                 |
+-----------------------------------------------+

-- Input parameter is NULL, return NULL
select hours_add(null, 5) ;
+--------------------+
| hours_add(null, 5) |
+--------------------+
| NULL               |
+--------------------+

select hours_add('2023-10-01 10:00:00',NULL) ;
+---------------------------------------+
| hours_add('2023-10-01 10:00:00',NULL) |
+---------------------------------------+
| NULL                                  |
+---------------------------------------+

-- Exceeds datetime range
select hours_add('9999-12-31 23:59:59', 2);
ERROR 1105 (HY000): errCode = 2, detailMessage = (10.16.10.2)[E-218]Operation hours_add of 9999-12-31 23:59:59, 2 out of range

mysql> select hours_add('0000-01-01',-2);
ERROR 1105 (HY000): errCode = 2, detailMessage = (10.16.10.2)[E-218]Operation hours_add of 0000-01-01 00:00:00, -2 out of range
Report issue