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

QUARTERS_ADD

Описание​

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

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

Синтаксис​

QUARTERS_ADD(`<date_or_time_expr>`, `<quarters>`)

Параметры​

ПараметрОписание
<date_or_time_expr>Входное значение даты или даты и времени. Поддерживаются типы DATE/DATETIME/TIMESTAMP_NS/TIMESTAMPTZ. Подробные сведения о форматах см. в разделах Преобразование timestamptz, Преобразование datetime и Преобразование date.
<quarters>Количество кварталов для прибавления или вычитания. Положительные целые числа означают прибавление, отрицательные целые числа означают вычитание.

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

Для входного значения TIMESTAMP_NS возвращается TIMESTAMP_NS с фиксированной точностью дробной части секунды до девяти знаков. Результаты проверяются на соответствие диапазону возвращаемого типа; для TIMESTAMP_NS используется диапазон [1677-09-21 00:12:43.145224192, 2262-04-11 23:47:16.854775807].

Возвращает значение даты, соответствующее типу входной даты. Тип возвращаемого значения определяется типом первого параметра:

  • Если значение <quarters> отрицательное, функция действует так же, как вычитание соответствующего количества кварталов из исходного значения времени (то есть QUARTERS_ADD(date, -n) эквивалентно QUARTERS_SUB(date, n)).
  • Если входное значение имеет тип DATE (содержит только год, месяц и день), результат имеет тип DATE; если входное значение имеет тип DATETIME, результат имеет тип DATETIME и сохраняет исходную составляющую времени (например, '2023-01-01 12:34:56' превращается в '2023-04-01 12:34:56' после прибавления 1 квартала).
  • Если входное значение имеет тип TIMESTAMPTZ, возвращаемое значение имеет тип TIMESTAMPTZ (включает дату, время и смещение часового пояса).
  • Если входная дата приходится на последний день месяца и в целевом месяце меньше дней, чем номер дня во входной дате, дата автоматически корректируется до последнего дня целевого месяца (например, 31 января плюс 1 квартал (3 месяца) даёт 30 апреля).
  • Если результат вычисления выходит за допустимый диапазон типа даты (тип DATE: от 0000-01-01 до 9999-12-31; тип DATETIME: от 0000-01-01 00:00:00 до 9999-12-31 23:59:59), возникает исключение.
  • Если хотя бы один параметр равен NULL, возвращается NULL.

Примеры​

--- Add quarters to DATE type
SELECT QUARTERS_ADD('2020-01-31', 1) AS result;
+------------+
| result     |
+------------+
| 2020-04-30 |
+------------+

--- Add quarters to DATETIME type (preserves time component)
SELECT QUARTERS_ADD('2020-01-31 02:02:02', 1) AS result;
+---------------------+
| result              |
+---------------------+
| 2020-04-30 02:02:02 |
+---------------------+

--- Negative quarters (equivalent to subtraction)
SELECT QUARTERS_ADD('2020-04-30', -1) AS result;
+------------+
| result     |
+------------+
| 2020-01-30 |
+------------+

--- Non-end-of-month date adding quarters (direct accumulation)
SELECT QUARTERS_ADD('2023-07-13 22:28:18', 2) AS result;
+---------------------+
| result              |
+---------------------+
| 2024-01-13 22:28:18 |
+---------------------+

--- DATETIME with microseconds (preserves precision)
SELECT QUARTERS_ADD('2023-07-13 22:28:18.456789', 1) AS result;
+----------------------------+
| result                     |
+----------------------------+
| 2023-10-13 22:28:18.456789 |
+----------------------------+

--- Adding quarters across years
SELECT QUARTERS_ADD('2023-10-01', 2) AS result;
+------------+
| result     |
+------------+
| 2024-04-01 |
+------------+

--- Returns NULL when input is NULL
SELECT QUARTERS_ADD(NULL, 1), QUARTERS_ADD('2023-07-13', NULL) AS result;
+-------------------------+--------+
| quarters_add(NULL, 1)   | result |
+-------------------------+--------+
| NULL                    | NULL   |
+-------------------------+--------+

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

--- Calculation result exceeds date range
SELECT QUARTERS_ADD('9999-10-31', 2) AS result;
ERROR 1105 (HY000): errCode = 2, detailMessage = (10.16.10.3)[E-218]Operation quarters_add of 9999-10-31, 6 out of range

SELECT QUARTERS_ADD('0000-01-01',-2) AS result;
ERROR 1105 (HY000): errCode = 2, detailMessage = (10.16.10.3)[E-218]Operation quarters_add of 0000-01-01, -6 out of range
Report issue