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

WEEKS_SUB

Описание​

Функция WEEKS_SUB вычитает заданное количество недель из указанного значения даты или времени (или прибавляет их) и возвращает изменённое значение даты или времени (по сути, вычитает weeks_value × 7 дней). Она поддерживает обработку типов DATE, DATETIME, TIMESTAMP_NS и TIMESTAMPTZ.

Поведение этой функции соответствует функции weeks_sub с единицей измерения WEEK в MySQL.

Синтаксис​

WEEKS_SUB(`<date_or_time_expr>`, `<week_period>`)

Параметры​

ПараметрОписание
<date_or_time_expr>Входное значение даты и времени; поддерживаются типы DATE/DATETIME/TIMESTAMP_NS/TIMESTAMPTZ. Сведения о конкретных форматах см. в разделах преобразование timestamptz, преобразование datetime и преобразование date
week_periodЦелое число типа INT, задающее количество вычитаемых недель (положительное значение означает вычитание, отрицательное — прибавление).

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

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

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

Особые случаи:

  • Отрицательное значение <weeks_value> означает прибавление недель (эквивалентно вызову WEEKS_ADD(<datetime_or_date_value>, <weeks_value>)).
  • Если любой из входных параметров равен NULL, возвращается NULL.
  • Если результат вычисления выходит за допустимый диапазон типа даты (от 0000-01-01 00:00:00 до 9999-12-31 23:59:59), возвращается ошибка.

Примеры​

-- DATETIME type subtract 1 week (basic functionality, hours, minutes, seconds remain unchanged)
SELECT WEEKS_SUB('2023-10-01 08:30:45', 1) AS sub_1_week_datetime;
+---------------------+
| sub_1_week_datetime |
+---------------------+
| 2023-09-24 08:30:45 |
+---------------------+

-- DATETIME type add 1 week (negative weeks_value, cross-month)
SELECT WEEKS_SUB('2023-09-24 14:20:10', -1) AS add_1_week_datetime;
+---------------------+
| add_1_week_datetime |
+---------------------+
| 2023-10-01 14:20:10 |
+---------------------+

-- DATE type subtract 2 weeks (only adjust date, no time portion)
SELECT WEEKS_SUB('2023-06-03', 2) AS sub_2_week_date;
+-----------------+
| sub_2_week_date |
+-----------------+
| 2023-05-20      |
+-----------------+

-- Cross-year subtraction (early January minus 1 week, to late December of previous year)
SELECT WEEKS_SUB('2024-01-01', 1) AS cross_year_sub;
+----------------+
| cross_year_sub |
+----------------+
| 2023-12-25     |
+----------------+

-- Input is NULL (returns NULL)
SELECT WEEKS_SUB(NULL, 5) AS null_input;
+------------+
| null_input |
+------------+
| NULL       |
+------------+

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

-- The calculation result exceeds the lower bound of the datetime range.
SELECT WEEKS_SUB('0000-01-01', 1);
ERROR 1105 (HY000): errCode = 2, detailMessage = (10.16.10.3)[E-218]Operation weeks_sub of 0000-01-01, -1 out of range

-- The calculation result exceeds the upper bound of the datetime range.
SELECT WEEKS_SUB('9999-12-31', -1);
ERROR 1105 (HY000): errCode = 2, detailMessage = (10.16.10.3)[E-218]Operation weeks_sub of 9999-12-31, 1 out of range
Report issue