본문으로 건너뛰기
최종 수정: 에

QUARTERS_ADD

설명​

QUARTERS_ADD 함수는 지정된 날짜/시간 값에 지정된 분기 수(1분기 = 3개월)를 더하거나 빼고 계산된 날짜/시간 값을 반환합니다. 이 함수는 DATE, DATETIME, TIMESTAMP_NS 타입을 처리할 수 있습니다. 음수를 입력하면 해당 분기 수만큼 빼는 것과 같습니다. 이 함수는 DATE, DATETIME, TIMESTAMP_NS, TIMESTAMPTZ 입력 타입을 지원합니다.

이 함수는 QUARTER를 단위로 사용하는 date_add 함수와 동일하게 동작합니다.

구문​

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'에 1분기를 더하면 '2023-04-01 12:34:56'이 됩니다).
  • 입력이 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