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

QUARTERS_SUB

Описание​

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

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

Синтаксис​

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

Примеры​

--- Subtract quarters from DATE type
SELECT QUARTERS_SUB('2020-01-31', 1) AS result;
+------------+
| result     |
+------------+
| 2019-10-31 |
+------------+

--- Subtract quarters from DATETIME type (preserves time component)
SELECT QUARTERS_SUB('2020-01-31 02:02:02', 1) AS result;
+---------------------+
| result              |
+---------------------+
| 2019-10-31 02:02:02 |
+---------------------+

--- Negative quarters (equivalent to addition)
SELECT QUARTERS_SUB('2019-10-31', -1) AS result;
+------------+
| result     |
+------------+
| 2020-01-31 |
+------------+

--- Non-end-of-month date subtracting quarters (direct decrement)
SELECT QUARTERS_SUB('2023-07-13 22:28:18', 2) AS result;
+---------------------+
| result              |
+---------------------+
| 2023-01-13 22:28:18 |
+---------------------+

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

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

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

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

--- Calculation result exceeds date range
SELECT QUARTERS_SUB('0000-04-30', 1) AS result;
ERROR 1105 (HY000): errCode = 2, detailMessage = (10.16.10.3)[E-218]Operation quarters_sub of 0000-04-30, 1 out of range

SELECT QUARTERS_SUB('9999-12-31', -1) AS result;
ERROR 1105 (HY000): errCode = 2, detailMessage = (10.16.10.3)[E-218]Operation quarters_sub of 9999-12-31, -1 out of range
Report issue