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

HOURS_SUB

Описание​

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

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

Синтаксис​

HOURS_SUB(`<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:00 до 9999-12-31 23:59:59), возвращается ошибка.
  • Если любой из входных параметров равен NULL, возвращается NULL.
  • Если входное количество часов отрицательное, возвращается значение даты и времени с прибавленным соответствующим количеством часов.

Примеры​


-- Subtract positive hours
SELECT HOURS_SUB('2020-02-02 02:02:02', 1);
+------------------------------------------------------------+
| hours_sub(cast('2020-02-02 02:02:02' as DATETIMEV2(0)), 1) |
+------------------------------------------------------------+
| 2020-02-02 01:02:02                                        |
+------------------------------------------------------------+

-- Subtract hours from date type
select hours_sub('2023-10-01', 12);
+-----------------------------+
| hours_sub('2023-10-01', 12) |
+-----------------------------+
| 2023-09-30 12:00:00         |
+-----------------------------+

-- Input hours is negative, returns datetime plus hours
select hours_sub('2023-10-01 10:00:00', -3);
+--------------------------------------+
| hours_sub('2023-10-01 10:00:00', -3) |
+--------------------------------------+
| 2023-10-01 13:00:00                  |
+--------------------------------------+

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

-- Any parameter is NULL, return NULL
select hours_sub('2023-10-01 10:00:00', NULL);
+----------------------------------------+
| hours_sub('2023-10-01 10:00:00', NULL) |
+----------------------------------------+
| NULL                                   |
+----------------------------------------+

-- Exceeds datetime range, return NULL
mysql> select hours_sub('9999-12-31 12:00:00', -20);
ERROR 1105 (HY000): errCode = 2, detailMessage = (10.16.10.2)[E-218]Operation hours_add of 9999-12-31 12:00:00, 20 out of range

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