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

HOURS_ADD

Описание​

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

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

Синтаксис​

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

Параметры​

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

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

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

  • Если первый параметр имеет тип DATE или DATETIME, возвращаемое значение имеет тип DATETIME; если он имеет тип TIMESTAMP_NS, возвращаемое значение имеет тип TIMESTAMP_NS.
  • Если первый параметр имеет тип 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