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

WEEK

Описание​

Функция WEEK возвращает номер недели для указанной даты. По умолчанию используется режим 0. Параметр mode позволяет настраивать правила расчёта недель: первый день недели (воскресенье или понедельник), диапазон номеров недель, критерии определения первой недели и т. д.

Влияние параметра mode показано в следующей таблице:

РежимПервый день неделиДиапазон номеров недельОпределение первой недели
0Воскресенье0-53Неделя, содержащая первое воскресенье года
1Понедельник0-53Первая неделя, в которой 4 или более дней относятся к текущему году
2Воскресенье1-53Неделя, содержащая первое воскресенье года
3Понедельник1-53Первая неделя, в которой 4 или более дней относятся к текущему году
4Воскресенье0-53Первая неделя, в которой 4 или более дней относятся к текущему году
5Понедельник0-53Неделя, содержащая первый понедельник года
6Воскресенье1-53Первая неделя, в которой 4 или более дней относятся к текущему году
7Понедельник1-53Неделя, содержащая первый понедельник года

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

Синтаксис​

WEEK(`<date_or_time_expr>`)
WEEK(`<date_or_time_expr>`, `<mode>`)

Параметры​

ПараметрОписание
<date_or_time_expr>Входное значение даты и времени; поддерживаются типы DATE/DATETIME/TIMESTAMP_NS. О форматах даты и времени см. разделы преобразование даты и времени и преобразование даты
<mode>Необязательное значение типа INT, по умолчанию 0. Правило расчёта определяется выражением mode & 7, которое выбирает режим 0-7 из таблицы выше.

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

Возвращает значение типа INT, представляющее номер недели для указанной даты. Конкретный диапазон определяется параметром <mode> (0-53 или 1-53).

  • Если <mode> — целое число вне диапазона 0-7, режим расчёта определяется его тремя младшими битами (mode & 7). Например, 8 выбирает режим 0, 9 выбирает режим 1, а -1 выбирает режим 7;
  • Если любой из параметров равен NULL, возвращается NULL;
  • Для дат на границе годов функция может возвращать номер последней недели предыдущего года (например, 1 января 2023 года в некоторых режимах относится к неделе 52 за 2022 год).

Примеры​

Для значений режима вне допустимого диапазона используются три младших бита. Например, 8 выбирает режим 0:

SELECT WEEK('2021-01-01', 8) AS mode_8,
       WEEK('2021-01-01', 0) AS mode_0,
       WEEK('2021-01-01', 7) AS mode_7;
+--------+--------+--------+
| mode_8 | mode_0 | mode_7 |
+--------+--------+--------+
|      0 |      0 |     52 |
+--------+--------+--------+
-- 2020-01-01 is Wednesday, the first Sunday of the year is 2020-01-05, so it belongs to week 0
SELECT WEEK('2020-01-01') AS week_result;
+-------------+
| week_result |
+-------------+
|           0 |
+-------------+

-- 2020-07-01 is Wednesday, its week contains ≥4 days belonging to 2020, so it's week 27
SELECT WEEK('2020-07-01', 1) AS week_result;
+-------------+
| week_result |
+-------------+
|          27 |
+-------------+

-- Compare mode=0 and mode=3 (differences between different rules)
SELECT 
  WEEK('2023-01-01', 0) AS mode_0, 
  WEEK('2023-01-01', 3) AS mode_3;  
+--------+--------+
| mode_0 | mode_3 |
+--------+--------+
|      1 |     52 |
+--------+--------+

-- -1 & 7 = 7, so mode 7 is used
SELECT WEEK('2023-01-01', -1) AS week_result;
+-------------+
| week_result |
+-------------+
|          52 |
+-------------+

-- Input is DATETIME type (ignores time portion)
SELECT WEEK('2023-12-31 23:59:59', 3) AS week_result;
+-------------+
| week_result |
+-------------+
|          52 |  
+-------------+

-- Any parameter is NULL, result returns NULL
SELECT WEEK('2023-12-31 23:59:59', NULL), WEEK(NULL, 3);
+-----------------------------------+--------------+
| WEEK('2023-12-31 23:59:59', NULL) | WEEK(NULL,3) |
+-----------------------------------+--------------+
|                              NULL |         NULL |
+-----------------------------------+--------------+
Report issue