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

TIMESTAMPADD

Описание​

Функциональность аналогична функции date_add. Функция TIMESTAMPADD прибавляет (или вычитает) указанный интервал времени в заданных единицах к заданному значению даты и времени и возвращает вычисленное значение даты и времени. Функция поддерживает различные единицы времени (секунды, минуты, часы, дни, недели, месяцы, годы и т. д.) и позволяет гибко вычислять смещения даты и времени. Отрицательные интервалы означают вычитание соответствующего времени.

Поведение этой функции соответствует поведению функции timestampadd в MySQL.

Синтаксис​

TIMESTAMPADD(<unit>, <interval>, <date_or_time_expr>)

Параметры​

ПараметрОписание
<unit>Единица времени, в которой задаётся добавляемый интервал. Распространённые значения: SECOND, MINUTE, HOUR, DAY, WEEK, MONTH, QUARTER, YEAR
<interval>Добавляемый интервал времени, обычно целое число. Может быть положительным или отрицательным, что означает прибавление или вычитание соответствующего промежутка времени
<date_or_time_expr>Допустимая исходная дата; поддерживаются входные значения типов date/datetime. Подробнее о форматах даты и времени см. в разделах преобразование datetime и преобразование date

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

Возвращаемое значение представляет собой результат прибавления указанного интервала к исходной дате и времени.

  • Если входное значение имеет тип date и единица времени равна YEAR/MONTH/WEEK/DAY, возвращается значение типа date; в остальных случаях возвращается значение типа datetime
  • Если входное значение имеет тип datetime, возвращаемое значение также имеет тип datetime
  • Если результат вычисления выходит за допустимый диапазон типа DATETIME (от 0000-01-01 00:00:00 до 9999-12-31 23:59:59.999999), возникает исключение
  • Если <datetime_expr> содержит недопустимую дату (например, 0000-00-00, 2023-13-01) или <unit> задаёт неподдерживаемую единицу времени, возникает исключение
  • Если любой из параметров равен NULL, возвращается NULL
  • При обработке месяцев/лет даты конца месяца корректируются автоматически (например, 2023-01-31 плюс 1 месяц даёт 2023-02-28 или 2023-02-29 в зависимости от того, является ли год високосным)

Примеры​

-- Add 1 minute
SELECT TIMESTAMPADD(MINUTE, 1, '2019-01-02') AS result;
+---------------------+
| result              |
+---------------------+
| 2019-01-02 00:01:00 |
+---------------------+

-- Add 1 week (7 days)
SELECT TIMESTAMPADD(WEEK, 1, '2019-01-02') AS result;
+------------+
| result     |
+------------+
| 2019-01-09 |
+------------+

-- Subtract 3 hours
SELECT TIMESTAMPADD(HOUR, -3, '2023-07-13 10:30:00') AS result;
+---------------------+
| result              |
+---------------------+
| 2023-07-13 07:30:00 |
+---------------------+

-- End of month plus 1 month (automatically adapts to February days)
SELECT TIMESTAMPADD(MONTH, 1, '2023-01-31') AS result;
+------------+
| result     |
+------------+
| 2023-02-28 |
+------------+

-- Cross-year add 1 year
SELECT TIMESTAMPADD(YEAR, 1, '2023-12-31 23:59:59') AS result;
+---------------------+
| result              |
+---------------------+
| 2024-12-31 23:59:59 |
+---------------------+

-- Invalid unit
SELECT TIMESTAMPADD(MIN, 5, '2023-01-01') AS result;
ERROR 1105 (HY000): errCode = 2, detailMessage = Unsupported time stamp diff time unit: MIN, supported time unit: YEAR/MONTH/WEEK/DAY/HOUR/MINUTE/SECOND

-- Any parameter is NULL
SELECT TIMESTAMPADD(YEAR,NULL, '2023-12-31 23:59:59') AS result;
+--------+
| result |
+--------+
| NULL   |
+--------+

-- Calculation result exceeds datetime range
SELECT TIMESTAMPADD(YEAR,10000, '2023-12-31 23:59:59') AS result;
ERROR 1105 (HY000): errCode = 2, detailMessage = (10.16.10.3)[E-218]Operation years_add of 2023-12-31 23:59:59, 10000 out of range
Report issue