Функции для работы с датами и временем

Большинство функций в этом разделе принимают необязательный аргумент часового пояса, например Europe/Amsterdam. В этом случае используется указанный часовой пояс вместо локального (по умолчанию).

Пример

makeDate

Создает Date

из аргументов год, месяц и день, или
из аргументов год и номер дня в году.

Синтаксис

Псевдонимы:

MAKEDATE(year, month, day);
MAKEDATE(year, day_of_year);

Аргументы

year — Год. Целое число, С плавающей запятой или Десятичное.
month — Месяц. Целое число, С плавающей запятой или Десятичное.
day — День. Целое число, С плавающей запятой или Десятичное.
day_of_year — Номер дня в году. Целое число, С плавающей запятой или Десятичное.

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

Дата, созданная из аргументов. Date.

Пример

Создать дату из года, месяца и дня:

Результат:

Создать дату из года и номера дня в году:

Результат:

makeDate32

Создает дату типа Date32 из года, месяца, дня (или опционально года и дня).

Синтаксис

Аргументы

year — Год. Целое число, С плавающей запятой или Десятичное.
month — Месяц (необязательный). Целое число, С плавающей запятой или Десятичное.
day — День. Целое число, С плавающей запятой или Десятичное.

примечание

Если month опущен, то day должен принимать значение от 1 до 365, в противном случае оно должно принимать значение от 1 до 31.

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

Дата, созданная из аргументов. Date32.

Примеры

Создать дату из года, месяца и дня:

Запрос:

Результат:

Создать дату из года и номера дня в году:

Запрос:

Результат:

makeDateTime

Создает DateTime из аргументов года, месяца, дня, часа, минуты и секунды.

Синтаксис

Аргументы

year — Год. Целое число, С плавающей запятой или Десятичное.
month — Месяц. Целое число, С плавающей запятой или Десятичное.
day — День. Целое число, С плавающей запятой или Десятичное.
hour — Час. Целое число, С плавающей запятой или Десятичное.
minute — Минута. Целое число, С плавающей запятой или Десятичное.
second — Секунда. Целое число, С плавающей запятой или Десятичное.
timezone — Часовой пояс для возвращаемого значения (необязательный).

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

Дата и время, созданные из аргументов. DateTime.

Пример

Результат:

makeDateTime64

Создает значение типа DateTime64 из его компонентов: год, месяц, день, час, минута, секунда. С опциональной точностью до субсекунд.

Синтаксис

Аргументы

year — Год (0-9999). Целое число, С плавающей запятой или Десятичное.
month — Месяц (1-12). Целое число, С плавающей запятой или Десятичное.
day — День (1-31). Целое число, С плавающей запятой или Десятичное.
hour — Час (0-23). Целое число, С плавающей запятой или Десятичное.
minute — Минута (0-59). Целое число, С плавающей запятой или Десятичное.
second — Секунда (0-59). Целое число, С плавающей запятой или Десятичное.
precision — Опциональная точность компонента субсекунд (0-9). Целое число.

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

Дата и время, созданные из предоставленных аргументов. DateTime64.

Пример

timestamp

Преобразует первый аргумент 'expr' в тип DateTime64(6). Если предоставлен второй аргумент 'expr_time', он добавляет указанное время к преобразованному значению.

Синтаксис

Псевдоним: TIMESTAMP

Аргументы

expr - Дата или дата с временем. Строка.
expr_time - Необязательный параметр. Время для добавления. Строка.

Примеры

Результат:

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

DateTime64(6)

timeZone

Возвращает часовой пояс текущей сессии, т.е. значение настройки session_timezone. Если функция выполняется в контексте распределенной таблицы, то она создает нормальный столбец со значениями, относящимися к каждому шард, в противном случае возвращает постоянное значение.

Синтаксис

Псевдоним: timezone.

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

Часовой пояс. Строка.

Пример

Результат:

Смотрите также

serverTimeZone

serverTimeZone

Возвращает часовой пояс сервера, т.е. значение настройки timezone. Если функция выполняется в контексте распределенной таблицы, то она создает нормальный столбец со значениями, относящимися к каждому шард. В противном случае возвращает постоянное значение.

Синтаксис

Псевдоним: serverTimezone.

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

Часовой пояс. Строка.

Пример

Результат:

Смотрите также

timeZone

toTimeZone

Преобразует дату или дату с временем в указанный часовой пояс. Не изменяет внутреннее значение (количество unix-секунд) данных, только атрибут часового пояса значения и строковое представление значения изменяются.

Синтаксис

Псевдоним: toTimezone.

Аргументы

value — Время или дата и время. DateTime64.
timezone — Часовой пояс для возвращаемого значения. Строка. Этот аргумент является постоянным, потому что toTimezone изменяет часовой пояс столбца (часовой пояс является атрибутом типов DateTime*).

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

Дата и время. DateTime.

Пример

Результат:

Смотрите также

formatDateTime - поддерживает неконстантный часовой пояс.
toString - поддерживает неконстантный часовой пояс.

timeZoneOf

Возвращает название часового пояса типов DateTime или DateTime64.

Синтаксис

Псевдоним: timezoneOf.

Аргументы

value — Дата и время. DateTime или DateTime64.

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

Название часового пояса. Строка.

Пример

Результат:

timeZoneOffset

Возвращает смещение часового пояса в секундах от UTC. Функция учитывает летнее время и исторические изменения часового пояса на указанную дату и время. Для вычисления смещения используется база данных часовых поясов IANA.

Синтаксис

Псевдоним: timezoneOffset.

Аргументы

value — Дата и время. DateTime или DateTime64.

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

Смещение от UTC в секундах. Int32.

Пример

Результат:

toYear

Возвращает компонент года (н.э.) из даты или даты с временем.

Синтаксис

Псевдоним: YEAR

Аргументы

value - Дата, Date32, DateTime или DateTime64

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

Год указанной даты/времени. UInt16.

Пример

Результат:

toQuarter

Возвращает квартал (1-4) даты или даты с временем.

Синтаксис

Псевдоним: QUARTER

Аргументы

value - Дата, Date32, DateTime или DateTime64

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

Квартал года (1, 2, 3 или 4) указанной даты/времени. UInt8.

Пример

Результат:

toMonth

Возвращает компонент месяца (1-12) даты или даты с временем.

Синтаксис

Псевдоним: MONTH

Аргументы

value - Дата, Date32, DateTime или DateTime64

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

Месяц года (1 - 12) указанной даты/времени. UInt8.

Пример

Результат:

toDayOfYear

Возвращает номер дня в году (1-366) даты или даты с временем.

Синтаксис

Псевдоним: DAYOFYEAR

Аргументы

value - Дата, Date32, DateTime или DateTime64

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

Номер дня в году (1 - 366) указанной даты/времени. UInt16.

Пример

Результат:

toDayOfMonth

Возвращает номер дня в месяце (1-31) даты или даты с временем.

Синтаксис

Псевдонимы: DAYOFMONTH, DAY

Аргументы

value - Дата, Date32, DateTime или DateTime64

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

Номер дня в месяце (1 - 31) указанной даты/времени. UInt8.

Пример

Результат:

toDayOfWeek

Возвращает номер дня в неделе даты или даты с временем.

Двухаргументная форма toDayOfWeek() позволяет вам указать, начинается ли неделя с понедельника или воскресенья, и должен ли возвращаемый результат находиться в диапазоне от 0 до 6 или от 1 до 7. Если аргумент режима опущен, по умолчанию используется режим 0. Часовой пояс даты можно указать в качестве третьего аргумента.

Режим	Первый день недели	Диапазон
0	Понедельник	1-7: Понедельник = 1, Вторник = 2, ..., Воскресенье = 7
1	Понедельник	0-6: Понедельник = 0, Вторник = 1, ..., Воскресенье = 6
2	Воскресенье	0-6: Воскресенье = 0, Понедельник = 1, ..., Суббота = 6
3	Воскресенье	1-7: Воскресенье = 1, Понедельник = 2, ..., Суббота = 7

Синтаксис

Псевдоним: DAYOFWEEK.

Аргументы

t - Дата, Date32, DateTime или DateTime64
mode - определяет, какой первый день недели. Возможные значения: 0, 1, 2 или 3. См. таблицу выше для различий.
timezone - необязательный параметр, он ведет себя как любая другая функция преобразования

Первый аргумент также может быть указан как Строка в формате, поддерживаемом parseDateTime64BestEffort(). Поддержка строковых аргументов существует только по причинам совместимости с MySQL, на которые рассчитывают определенные сторонние инструменты. Поскольку поддержка строковых аргументов в будущем может быть сделана зависимой от новых настроек совместимости с MySQL и потому, что парсинг строк обычно медленный, рекомендуется не использовать его.

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

День недели (1-7), в зависимости от выбранного режима, указанной даты/времени

Пример

Следующая дата - 21 апреля 2023 года, который был пятницей:

Результат:

toHour

Возвращает часовую компоненту (0-24) даты с временем.

Предполагает, что если часы переводятся вперед, то на один час и происходит это в 2 часа, а если часы переводятся назад, то на один час и происходит это в 3 часа. (что не всегда именно так происходит - это зависит от часового пояса).

Синтаксис

Псевдоним: HOUR

Аргументы

value - DateTime или DateTime64

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

Час дня (0 - 23) указанной даты/времени. UInt8.

Пример

Результат:

toMinute

Возвращает минутную компоненту (0-59) даты с временем.

Синтаксис

Псевдоним: MINUTE

Аргументы

value - DateTime или DateTime64

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

Минута часа (0 - 59) указанной даты/времени. UInt8.

Пример

Результат:

toSecond

Возвращает секунду (0-59) даты с временем. Високосные секунды не учитываются.

Синтаксис

Псевдоним: SECOND

Аргументы

value - DateTime или DateTime64

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

Секунда в минуте (0 - 59) указанной даты/времени. UInt8.

Пример

Результат:

toMillisecond

Возвращает миллисекундную компоненту (0-999) даты с временем.

Синтаксис

Аргументы*

value - DateTime или DateTime64

Псевдоним: MILLISECOND

Результат:

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

Миллисекунда в минуте (0 - 59) указанной даты/времени. UInt16.

toUnixTimestamp

Преобразует строку, дату или дату с временем в Unix Timestamp в представлении UInt32.

Если функция вызывается со строкой, она принимает необязательный аргумент часового пояса.

Синтаксис

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

Возвращает Unix timestamp. UInt32.

Пример

Результат:

примечание

Тип возвращаемого значения toStartOf*, toLastDayOf*, toMonday, timeSlot функций, описанных ниже, определяется параметром конфигурации enable_extended_results_for_datetime_functions, который по умолчанию равен 0.

Поведение для

enable_extended_results_for_datetime_functions = 0:
- Функции toStartOfYear, toStartOfISOYear, toStartOfQuarter, toStartOfMonth, toStartOfWeek, toLastDayOfWeek, toLastDayOfMonth, toMonday возвращают Date или DateTime.
- Функции toStartOfDay, toStartOfHour, toStartOfFifteenMinutes, toStartOfTenMinutes, toStartOfFiveMinutes, toStartOfMinute, timeSlot возвращают DateTime. Хотя эти функции могут принимать значения расширенных типов Date32 и DateTime64 в качестве аргумента, передача им времени за пределами нормального диапазона (год 1970 до 2149 для Date / 2106 для DateTime) приведет к неправильным результатам.
enable_extended_results_for_datetime_functions = 1:
- Функции toStartOfYear, toStartOfISOYear, toStartOfQuarter, toStartOfMonth, toStartOfWeek, toLastDayOfWeek, toLastDayOfMonth, toMonday возвращают Date или DateTime, если их аргументом является Date или DateTime, и возвращают Date32 или DateTime64, если их аргументом является Date32 или DateTime64.
- Функции toStartOfDay, toStartOfHour, toStartOfFifteenMinutes, toStartOfTenMinutes, toStartOfFiveMinutes, toStartOfMinute, timeSlot возвращают DateTime, если их аргументом является Date или DateTime, и возвращают DateTime64, если их аргументом является Date32 или DateTime64.

toStartOfYear

Округляет дату или дату с временем до первого дня года. Возвращает дату в виде объекта Date.

Синтаксис

Аргументы

value - Дата, Date32, DateTime или DateTime64

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

Первый день года указанной даты/времени. Date.

Пример

Результат:

toStartOfISOYear

Округляет дату или дату с временем до первого дня ISO года, который может отличаться от "обычного" года. (См. https://en.wikipedia.org/wiki/ISO_week_date.)

Синтаксис

Аргументы

value - Дата, Date32, DateTime или DateTime64

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

Первый день года указанной даты/времени. Date.

Пример

Результат:

toStartOfQuarter

Округляет дату или дату с временем до первого дня квартала. Первым днем квартала является либо 1 января, 1 апреля, 1 июля или 1 октября. Возвращает дату.

Синтаксис

Аргументы

value - Дата, Date32, DateTime или DateTime64

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

Первый день квартала указанной даты/времени. Date.

Пример

Результат:

toStartOfMonth

Округляет дату или дату с временем до первого дня месяца. Возвращает дату.

Синтаксис

Аргументы

value - Дата, Date32, DateTime или DateTime64

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

Первый день месяца указанной даты/времени. Date.

Пример

Результат:

примечание

Поведение разбора неправильных дат зависит от реализации. ClickHouse может вернуть нулевую дату, выбросить исключение или выполнить "естественное" переполнение.

toLastDayOfMonth

Округляет дату или дату с временем до последнего дня месяца. Возвращает дату.

Синтаксис

Псевдоним: LAST_DAY

Аргументы

value - Дата, Date32, DateTime или DateTime64

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

Последний день месяца указанной даты/времени. Date.

Пример

Результат:

toMonday

Округляет дату или дату с временем до ближайшего понедельника. Возвращает дату.

Синтаксис

Аргументы

value - Дата, Date32, DateTime или DateTime64

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

Дата ближайшего понедельника на или до указанной даты. Дата.

Пример

Результат:

toStartOfWeek

Округляет дату или дату с временем вниз до ближайшего воскресенья или понедельника. Возвращает дату. Аргумент mode работает точно так же, как аргумент mode в функции toWeek(). Если режим не указан, по умолчанию используется 0.

Синтаксис

Аргументы

t - Дата, Date32, DateTime или DateTime64
mode - определяет первый день недели, как описано в функции toWeek()
timezone - необязательный параметр, ведет себя как любая другая функция преобразования

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

Дата ближайшего воскресенья или понедельника до или на указанной дате, в зависимости от режима. Дата.

Пример

Результат:

toLastDayOfWeek

Округляет дату или дату с временем вверх до ближайшей субботы или воскресенья. Возвращает дату. Аргумент mode работает точно так же, как аргумент mode в функции toWeek(). Если режим не указан, предполагается, что mode равен 0.

Синтаксис

Аргументы

t - Дата, Date32, DateTime или DateTime64
mode - определяет последний день недели, как описано в функции toWeek
timezone - необязательный параметр, ведет себя как любая другая функция преобразования

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

Дата ближайшего воскресенья или понедельника на или после указанной даты, в зависимости от режима. Дата.

Пример

Результат:

toStartOfDay

Округляет дату с временем вниз до начала дня.

Синтаксис

Аргументы

value - Дата, Date32, DateTime или DateTime64

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

Начало дня указанной даты/времени. DateTime.

Пример

Результат:

toStartOfHour

Округляет дату с временем вниз до начала часа.

Синтаксис

Аргументы

value - DateTime или DateTime64

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

Начало часа указанной даты/времени. DateTime.

Пример

Результат:

toStartOfMinute

Округляет дату с временем вниз до начала минуты.

Синтаксис

Аргументы

value - DateTime или DateTime64

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

Начало минуты указанной даты/времени. DateTime.

Пример

Результат:

toStartOfSecond

Отсекает субсекунды.

Синтаксис

Аргументы

value — Дата и время. DateTime64.
timezone — Часовой пояс для возвращаемого значения (необязательный). Если не указан, функция использует часовой пояс параметра value. Строка.

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

Входное значение без субсекунд. DateTime64.

Примеры

Запрос без часового пояса:

Результат:

Запрос с часовым поясом:

Результат:

Смотрите также

Параметр конфигурации сервера Timezone

toStartOfMillisecond

Округляет дату с временем вниз до начала миллисекунд.

Синтаксис

Аргументы

value — Дата и время. DateTime64.
timezone — Часовой пояс для возвращаемого значения (необязательный). Если не указан, функция использует часовой пояс параметра value. Строка.

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

Входное значение с субмиллисекундами. DateTime64.

Примеры

Запрос без часового пояса:

Результат:

Запрос с часовым поясом:

Результат:

toStartOfMicrosecond

Округляет дату с временем вниз до начала микросекунд.

Синтаксис

Аргументы

value — Дата и время. DateTime64.
timezone — Часовой пояс для возвращаемого значения (необязательный). Если не указан, функция использует часовой пояс параметра value. Строка.

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

Входное значение с субмикросекундами. DateTime64.

Примеры

Запрос без часового пояса:

Результат:

Запрос с часовым поясом:

Результат:

Смотрите также

Параметр конфигурации сервера Timezone

toStartOfNanosecond

Округляет дату с временем вниз до начала наносекунд.

Синтаксис

Аргументы

value — Дата и время. DateTime64.
timezone — Часовой пояс для возвращаемого значения (необязательный). Если не указан, функция использует часовой пояс параметра value. Строка.

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

Входное значение с наносекундами. DateTime64.

Примеры

Запрос без часового пояса:

Результат:

Запрос с часовым поясом:

Результат:

Смотрите также

Параметр конфигурации сервера Timezone

toStartOfFiveMinutes

Округляет дату с временем вниз до начала пятиминутного интервала.

Синтаксис

Аргументы

value - DateTime или DateTime64

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

Начало пятиминутного интервала указанной даты/времени. DateTime.

Пример

Результат:

toStartOfTenMinutes

Округляет дату с временем вниз до начала десятиминутного интервала.

Синтаксис

Аргументы

value - DateTime или DateTime64

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

Начало десятиминутного интервала указанной даты/времени. DateTime.

Пример

Результат:

toStartOfFifteenMinutes

Округляет дату с временем вниз до начала пятнадцатиминутного интервала.

Синтаксис

Аргументы

value - DateTime или DateTime64

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

Начало пятнадцатиминутного интервала указанной даты/времени. DateTime.

Пример

Результат:

toStartOfInterval

Эта функция обобщает другие функции toStartOf*() с синтаксисом toStartOfInterval(date_or_date_with_time, INTERVAL x unit [, time_zone]). Например,

toStartOfInterval(t, INTERVAL 1 YEAR) возвращает то же самое, что и toStartOfYear(t),
toStartOfInterval(t, INTERVAL 1 MONTH) возвращает то же самое, что и toStartOfMonth(t),
toStartOfInterval(t, INTERVAL 1 DAY) возвращает то же самое, что и toStartOfDay(t),
toStartOfInterval(t, INTERVAL 15 MINUTE) возвращает то же самое, что и toStartOfFifteenMinutes(t).

Расчет выполняется относительно конкретных моментов времени:

Интервал	Начало
ГОД	год 0
КВАРТАЛ	1900 Q1
МЕСЯЦ	Январь 1900
НЕДЕЛЯ	1970, 1-я неделя (01-05)
ДЕНЬ	1970-01-01
ЧАС	(*)
МИНУТА	1970-01-01 00:00:00
СЕКУНДА	1970-01-01 00:00:00
МИЛЛИСЕКУНДА	1970-01-01 00:00:00
МИКРОСЕКУНДА	1970-01-01 00:00:00
НАНОСЕКУНДА	1970-01-01 00:00:00

(*) интервалы часов являются специальными: расчет всегда выполняется относительно 00:00:00 (полночь) текущего дня. В результате только значения часов от 1 до 23 полезны.

Если был указан параметр WEEK, toStartOfInterval предполагает, что недели начинаются с понедельника. Обратите внимание, что это поведение отличается от функции toStartOfWeek, в которой недели по умолчанию начинаются с воскресенья.

Синтаксис

Псевдонимы: time_bucket, date_bin.

Вторая перегрузка эмулирует функцию time_bucket() TimescaleDB, соответственно функцию date_bin() PostgreSQL, например.

Результат:

Смотрите также

date_trunc

toTime

Преобразует дату с временем в определенную фиксированную дату, сохраняя время.

Синтаксис

Аргументы

date — Дата для преобразования во время. Дата/DateTime/DateTime64.
timezone (необязательный) — Часовой пояс для возвращаемого значения. Строка.

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

DateTime с установленной датой в 1970-01-02, сохраняя время. DateTime.

примечание

Если входной аргумент date содержал компоненты субсекунд, они будут отброшены в возвращаемом значении DateTime с точностью до секунды.

Пример

Запрос:

Результат:

toRelativeYearNum

Преобразует дату или дату с временем в количество лет, прошедших с определенной фиксированной точки в прошлом.

Синтаксис

Аргументы

date — Дата или дата с временем. Дата/DateTime/DateTime64.

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

Количество лет от фиксированной отправной точки в прошлом. UInt16.

Пример

Запрос:

Результат:

toRelativeQuarterNum

Преобразует дату или дату с временем в количество кварталов, прошедших с определенной фиксированной точки в прошлом.

Синтаксис

Аргументы

date — Дата или дата с временем. Дата/DateTime/DateTime64.

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

Количество кварталов от фиксированной отправной точки в прошлом. UInt32.

Пример

Запрос:

Результат:

toRelativeMonthNum

Преобразует дату или дату с временем в количество месяцев, прошедших с определенной фиксированной точки в прошлом.

Синтаксис

Аргументы

date — Дата или дата с временем. Дата/DateTime/DateTime64.

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

Количество месяцев от фиксированной отправной точки в прошлом. UInt32.

Пример

Запрос:

Результат:

toRelativeWeekNum

Преобразует дату или дату с временем в количество недель, прошедших с определенной фиксированной точки в прошлом.

Синтаксис

Аргументы

date — Дата или дата с временем. Дата/DateTime/DateTime64.

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

Количество недель от фиксированной отправной точки в прошлом. UInt32.

Пример

Запрос:

Результат:

toRelativeDayNum

Преобразует дату или дату с временем в количество дней, прошедших с определенной фиксированной точки в прошлом.

Синтаксис

Аргументы

date — Дата или дата с временем. Дата/DateTime/DateTime64.

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

Количество дней от фиксированной отправной точки в прошлом. UInt32.

Пример

Запрос:

Результат:

toRelativeHourNum

Преобразует дату или дату с временем в количество часов, прошедших с определенной фиксированной точки в прошлом.

Синтаксис

Аргументы

date — Дата или дата с временем. Дата/DateTime/DateTime64.

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

Количество часов от фиксированной отправной точки в прошлом. UInt32.

Пример

Запрос:

Результат:

toRelativeMinuteNum

Преобразует дату или дату с временем в количество минут, прошедших с определенной фиксированной точки в прошлом.

Синтаксис

Аргументы

date — Дата или дата с временем. Дата/DateTime/DateTime64.

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

Количество минут от фиксированной отправной точки в прошлом. UInt32.

Пример

Запрос:

Результат:

toRelativeSecondNum

Преобразует дату или дату с временем в количество секунд, прошедших с определенной фиксированной точки в прошлом.

Синтаксис

Аргументы

date — Дата или дата с временем. Дата/DateTime/DateTime64.

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

Количество секунд от фиксированной отправной точки в прошлом. UInt32.

Пример

Запрос:

Результат:

toISOYear

Преобразует дату или дату с временем в ISO-год как число UInt16.

Синтаксис

Аргументы

value — Значение с датой или датой с временем. Дата, Date32, DateTime или DateTime64

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

Входное значение, преобразованное в номер ISO-года. UInt16.

Пример

Запрос:

Результат:

toISOWeek

Преобразует дату или дату с временем в число UInt8, содержащее номер ISO-недели.

Синтаксис

Аргументы

value — Значение с датой или датой с временем.

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

value, преобразованное в номер текущей ISO-недели. UInt8.

Пример

Запрос:

Ответ:

toWeek

Эта функция возвращает номер недели для даты или даты с временем. Двухаргументная форма toWeek() позволяет указать, начинается ли неделя с воскресенья или понедельника и должен ли возвращаемый результат быть в диапазоне от 0 до 53 или от 1 до 53. Если аргумент mode опущен, используется режим по умолчанию 0.

toISOWeek() - это функция совместимости, которая эквивалентна toWeek(date,3).

В следующей таблице описывается, как работает аргумент mode.

Режим	Первый день недели	Диапазон	Недея 1 это первая неделя ...
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	с понедельником в этом году
8	Воскресенье	1-53	содержит 1 января
9	Понедельник	1-53	содержит 1 января

Для значений режима с смыслом "с 4 или более днями в этом году" недели нумеруются в соответствии с ISO 8601:1988:

Если неделя, содержащая 1 января, имеет 4 или более дней в новом году, она будет неделей 1.
В противном случае это последняя неделя предыдущего года, а следующая неделя - неделя 1.

Для значений режима с смыслом "содержит 1 января" неделя, содержащая 1 января, считается неделей 1. Не имеет значения, сколько дней в новом году неделя содержала, даже если это всего лишь один день. То есть, если последняя неделя декабря содержит 1 января следующего года, это будет неделя 1 следующего года.

Синтаксис

Псевдоним: WEEK

Аргументы

t – Дата или ДатаВремя.
mode – Необязательный параметр, диапазон значений [0,9], по умолчанию 0.
timezone – Необязательный параметр, ведет себя как любая другая функция преобразования.

Первый аргумент также может быть указан как Строка в формате, поддерживаемом parseDateTime64BestEffort(). Поддержка строковых аргументов существует только по причинам совместимости с MySQL, что ожидается определенными сторонними инструментами. Поскольку поддержка строковых аргументов может в будущем зависеть от новых настроек совместимости с MySQL и потому что парсинг строк обычно медленный, рекомендуется не использовать это.

Пример

toYearWeek

Возвращает год и неделю для даты. Год в результате может отличаться от года в аргументе даты для первой и последней недели года.

Аргумент mode работает так же, как аргумент mode для toWeek(). Для синтаксиса с одним аргументом используется значение режима 0.

toISOYear() - это функция совместимости, которая эквивалентна intDiv(toYearWeek(date,3),100).

осторожно

Номер недели, возвращаемый toYearWeek(), может отличаться от того, что возвращает toWeek(). toWeek() всегда возвращает номер недели в контексте данного года, и если toWeek() возвращает 0, toYearWeek() возвращает значение, соответствующее последней неделе предыдущего года. См. prev_yearWeek в примере ниже.

Синтаксис

Псевдоним: YEARWEEK

Первый аргумент также может быть указан как Строка в формате, поддерживаемом parseDateTime64BestEffort(). Поддержка строковых аргументов существует только по причинам совместимости с MySQL, что ожидается определенными сторонними инструментами. Поскольку поддержка строковых аргументов может в будущем зависеть от новых настроек совместимости с MySQL и потому что парсинг строк обычно медленный, рекомендуется не использовать это.

Пример

toDaysSinceYearZero

Возвращает для данной даты количество дней, прошедших с 1 января 0000 по пролептическому григорианскому календарю, определенному ISO 8601. Расчет такой же, как в функции MySQL TO_DAYS().

Синтаксис

Псевдоним: TO_DAYS

Аргументы

date — Дата, от которой рассчитывается количество дней, прошедших с года ноль. Дата, Date32, DateTime или DateTime64.
time_zone — Константное значение типа строки или выражение, представляющее часовой пояс. Строковые типы

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

Количество дней, прошедших с даты 0000-01-01. UInt32.

Пример

Результат:

Смотрите также

fromDaysSinceYearZero

fromDaysSinceYearZero

Возвращает для данного числа дней, прошедших с 1 января 0000, соответствующую дату в пролептическом григорианском календаре, определенном ISO 8601. Вычисление такое же, как в функции MySQL FROM_DAYS().

Результат непредсказуем, если он не может быть представлен в пределах типа Date.

Синтаксис

Псевдоним: FROM_DAYS

Аргументы

days — Число дней, прошедших с года ноль.

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

Дата, соответствующая числу дней, прошедших с года ноль. Date.

Пример

Результат:

См. также

toDaysSinceYearZero

fromDaysSinceYearZero32

Как fromDaysSinceYearZero, но возвращает Date32.

age

Возвращает компонент unit разности между startdate и enddate. Разность вычисляется с точностью 1 наносекунда. Например, разность между 2021-12-29 и 2022-01-01 составляет 3 дня для единицы day, 0 месяцев для единицы month, 0 лет для единицы year.

Для альтернативы функции age см. функцию date_diff.

Синтаксис

Аргументы

unit — Тип интервала для результата. String. Возможные значения:
- nanosecond, nanoseconds, ns
- microsecond, microseconds, us, u
- millisecond, milliseconds, ms
- second, seconds, ss, s
- minute, minutes, mi, n
- hour, hours, hh, h
- day, days, dd, d
- week, weeks, wk, ww
- month, months, mm, m
- quarter, quarters, qq, q
- year, years, yyyy, yy
startdate — Первое значение времени для вычитания (уменьшаемое). Date, Date32, DateTime или DateTime64.
enddate — Второе значение времени, из которого вычитается (уменьшаемое). Date, Date32, DateTime или DateTime64.
timezone — Имя часового пояса (опционально). Если указано, он применяется как к startdate, так и к enddate. Если не указано, используются часовые пояса startdate и enddate. Если они не совпадают, результат непредсказуем. String.

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

Разность между enddate и startdate, выраженная в unit. Int.

Пример

Результат:

date_diff

Возвращает количество пересеченных границ указанного unit между startdate и enddate. Разность вычисляется с использованием относительных единиц, например разность между 2021-12-29 и 2022-01-01 составляет 3 дня для единицы day (см. toRelativeDayNum), 1 месяц для единицы month (см. toRelativeMonthNum) и 1 год для единицы year (см. toRelativeYearNum).

Если была указана единица week, date_diff предполагает, что недели начинаются с понедельника. Обратите внимание, что это поведение отличается от функции toWeek(), в которой недели по умолчанию начинаются с воскресенья.

Для альтернативы функции date_diff см. функцию age.

Синтаксис

Псевдонимы: dateDiff, DATE_DIFF, timestampDiff, timestamp_diff, TIMESTAMP_DIFF.

Аргументы

unit — Тип интервала для результата. String. Возможные значения:
- nanosecond, nanoseconds, ns
- microsecond, microseconds, us, u
- millisecond, milliseconds, ms
- second, seconds, ss, s
- minute, minutes, mi, n
- hour, hours, hh, h
- day, days, dd, d
- week, weeks, wk, ww
- month, months, mm, m
- quarter, quarters, qq, q
- year, years, yyyy, yy
startdate — Первое значение времени для вычитания (уменьшаемое). Date, Date32, DateTime или DateTime64.
enddate — Второе значение времени, из которого вычитается (уменьшаемое). Date, Date32, DateTime или DateTime64.
timezone — Имя часового пояса (опционально). Если указано, он применяется как к startdate, так и к enddate. Если не указано, используются часовые пояса startdate и enddate. Если они не совпадают, результат непредсказуем. String.

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

Разность между enddate и startdate, выраженная в unit. Int.

Пример

Результат:

date_trunc

Обрезает данные даты и времени до указанной части даты.

Синтаксис

Псевдоним: dateTrunc.

Аргументы

unit — Тип интервала, к которому нужно обрезать результат. String Literal. Возможные значения:
- nanosecond - Совместим только с DateTime64
- microsecond - Совместим только с DateTime64
- milisecond - Совместим только с DateTime64
- second
- minute
- hour
- day
- week
- month
- quarter
- year
Аргумент unit нечувствителен к регистру.
value — Дата и время. Date, Date32, DateTime или DateTime64.
timezone — Имя часового пояса для возвращаемого значения (опционально). Если не указано, функция использует часовой пояс параметра value. String.

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

Если аргумент unit равен Год, Квартал, Месяц или Неделя,

и аргумент value является Date32 или DateTime64, то возвращается Date32,
в противном случае возвращается Date.

Если аргумент unit равен День, Час, Минута или Секунда,

и аргумент value является Date32 или DateTime64, то возвращается DateTime64,
в противном случае возвращается DateTime.

Если аргумент unit равен Миллисекунда, Микросекунда или Наносекунда, то возвращается DateTime64 с масштабом 3 или 6 или 9 (в зависимости от аргумента unit).

Пример

Запрос без часового пояса:

Результат:

Запрос с указанным часовым поясом:

Результат:

См. также

toStartOfInterval

date_add

Добавляет временной интервал или интервал даты к предоставленной дате или дате с временем.

Если сложение приводит к значению вне пределов типа данных, результат непредсказуем.

Синтаксис

Альтернативный синтаксис:

Псевдонимы: dateAdd, DATE_ADD.

Аргументы

unit — Тип интервала для добавления. Обратите внимание: это не String и не должно быть заключено в кавычки. Возможные значения:
- second
- minute
- hour
- day
- week
- month
- quarter
- year
value — Значение интервала для добавления. Int.
date — Дата или дата с временем, к которой добавляется value. Date, Date32, DateTime или DateTime64.

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

Дата или дата с временем, полученная путем добавления value, выраженного в unit, к date. Date, Date32, DateTime или DateTime64.

Пример

Результат:

См. также

addDate

date_sub

Вычитает временной интервал или интервал даты из предоставленной даты или даты с временем.

Если вычитание приводит к значению вне пределов типа данных, результат непредсказуем.

Синтаксис

Альтернативный синтаксис:

Псевдонимы: dateSub, DATE_SUB.

Аргументы

unit — Тип интервала для вычитания. Обратите внимание: это не String и не должно быть заключено в кавычки.

Возможные значения:
- second
- minute
- hour
- day
- week
- month
- quarter
- year
value — Значение интервала для вычитания. Int.
date — Дата или дата с временем, из которой вычитается value. Date, Date32, DateTime или DateTime64.

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

Дата или дата с временем, полученная путем вычитания value, выраженного в unit, из date. Date, Date32, DateTime или DateTime64.

Пример

Результат:

См. также

subDate

timestamp_add

Добавляет указанное значение времени к предоставленной дате или значению даты и времени.

Если сложение приводит к значению вне пределов типа данных, результат непредсказуем.

Синтаксис

Псевдонимы: timeStampAdd, TIMESTAMP_ADD.

Аргументы

date — Дата или дата с временем. Date, Date32, DateTime или DateTime64.
value — Значение интервала для добавления. Int.
unit — Тип интервала для добавления. String. Возможные значения:
- second
- minute
- hour
- day
- week
- month
- quarter
- year

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

Дата или дата с временем, к которому добавлено указанное value, выраженное в unit. Date, Date32, DateTime или DateTime64.

Пример

Результат:

timestamp_sub

Вычитает временной интервал из предоставленной даты или даты с временем.

Если вычитание приводит к значению вне пределов типа данных, результат непредсказуем.

Синтаксис

Псевдонимы: timeStampSub, TIMESTAMP_SUB.

Аргументы

unit — Тип интервала для вычитания. String. Возможные значения:
- second
- minute
- hour
- day
- week
- month
- quarter
- year
value — Значение интервала для вычитания. Int.
date — Дата или дата с временем. Date, Date32, DateTime или DateTime64.

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

Дата или дата с временем, полученная путем вычитания value, выраженного в unit, из date. Date, Date32, DateTime или DateTime64.

Пример

Результат:

addDate

Добавляет временной интервал к предоставленной дате, дате с временем или строковому представлению даты / даты с временем.

Если сложение приводит к значению вне пределов типа данных, результат непредсказуем.

Синтаксис

Аргументы

date — Дата или дата с временем, к которой добавляется interval. Date, Date32, DateTime, DateTime64 или String
interval — Интервал для добавления. Interval.

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

Дата или дата с временем, полученная путем добавления interval к date. Date, Date32, DateTime или DateTime64.

Пример

Результат:

Псевдоним: ADDDATE

См. также

date_add

subDate

Вычитает временной интервал из предоставленной даты, даты с временем или строкового представления даты / даты с временем.

Если вычитание приводит к значению вне пределов типа данных, результат непредсказуем.

Синтаксис

Аргументы

date — Дата или дата с временем, из которой вычитается interval. Date, Date32, DateTime, DateTime64 или String
interval — Интервал для вычитания. Interval.

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

Дата или дата с временем, полученная путем вычитания interval из date. Date, Date32, DateTime или DateTime64.

Пример

Результат:

Псевдоним: SUBDATE

См. также

date_sub

now

Возвращает текущую дату и время в момент анализа запроса. Функция является константным выражением.

Псевдоним: current_timestamp.

Синтаксис

Аргументы

timezone — Имя часового пояса для возвращаемого значения (опционально). String.

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

Текущая дата и время. DateTime.

Пример

Запрос без часового пояса:

Результат:

Запрос с указанным часовым поясом:

Результат:

now64

Возвращает текущее время с долями секунды в момент анализа запроса. Функция является константным выражением.

Синтаксис

Аргументы

scale - Размер тика (точность): 10^-precision секунд. Допустимый диапазон: [ 0 : 9 ]. Обычно используются - 3 (по умолчанию) (миллисекунды), 6 (микросекунды), 9 (наносекунды).
timezone — Имя часового пояса для возвращаемого значения (опционально). String.

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

Текущая дата и время с долями секунды. DateTime64.

Пример

Результат:

nowInBlock

Возвращает текущую дату и время в момент обработки каждого блока данных. В отличие от функции now, это не константное выражение, и возвращаемое значение будет различаться в разных блоках для долгих запросов.

Имеет смысл использовать эту функцию для генерации текущего времени в длительных запросах INSERT SELECT.

Синтаксис

Аргументы

timezone — Имя часового пояса для возвращаемого значения (опционально). String.

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

Текущая дата и время в момент обработки каждого блока данных. DateTime.

Пример

Результат:

today

Возвращает текущую дату в момент анализа запроса. Это то же самое, что 'toDate(now())' и имеет псевдонимы: curdate, current_date.

Синтаксис

Аргументы

Нет

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

Текущая дата. DateTime.

Пример

Запрос:

Результат:

Выполнение приведенного выше запроса 3 марта 2024 года вернет следующий ответ:

yesterday

Принимает ноль аргументов и возвращает дату вчера в один из моментов анализа запроса. То же самое, что и 'today() - 1'.

timeSlot

Округляет время до начала полудо-часового интервала.

Синтаксис

Аргументы

time — Время, которое нужно округлить до начала полудо-часового интервала. DateTime/Date32/DateTime64.
time_zone — Константное значение типа String или выражение, представляющее часовой пояс. String.

примечание

Хотя эта функция может принимать значения расширенных типов Date32 и DateTime64 в качестве аргумента, передача ей времени за пределами обычного диапазона (год 1970 до 2149 для Date / 2106 для DateTime) даст некорректные результаты.

Тип возвращаемого значения

Возвращает время, округленное до начала полудо-часового интервала. DateTime.

Пример

Запрос:

Результат:

toYYYYMM

Преобразует дату или дату с временем в число UInt32, содержащее номер года и месяца (YYYY * 100 + MM). Принимает второй необязательный аргумент часового пояса. Если предоставлен, часовой пояс должен быть строковым константным значением.

Эта функция является противоположной функции YYYYMMDDToDate().

Пример

Результат:

toYYYYMMDD

Преобразует дату или дату с временем в число UInt32, содержащее номер года, месяца и дня (YYYY * 10000 + MM * 100 + DD). Принимает второй необязательный аргумент часового пояса. Если предоставлен, часовой пояс должен быть строковым константным значением.

Пример

Результат:

toYYYYMMDDhhmmss

Преобразует дату или дату с временем в число UInt64, содержащее номер года, месяца, дня, часов, минут и секунд (YYYY * 10000000000 + MM * 100000000 + DD * 1000000 + hh * 10000 + mm * 100 + ss). Принимает второй необязательный аргумент часового пояса. Если предоставлен, часовой пояс должен быть строковым константным значением.

Пример

Результат:

YYYYMMDDToDate

Преобразует число, содержащее номер года, месяца и дня, в Date.

Эта функция является противоположной функции toYYYYMMDD().

Вывод непредсказуем, если входные данные не кодируют допустимое значение Date.

Синтаксис

Аргументы

yyyymmdd - Число, представляющее год, месяц и день. Integer, Float или Decimal.

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

дата, созданная из аргументов. Date.

Пример

Результат:

YYYYMMDDToDate32

Как функция YYYYMMDDToDate(), но производит Date32.

YYYYMMDDhhmmssToDateTime

Преобразует число, содержащее год, месяц, день, часы, минуты и секунды, в DateTime.

Вывод непредсказуем, если входные данные не кодируют допустимое значение DateTime.

Эта функция является противоположной функции toYYYYMMDDhhmmss().

Синтаксис

Аргументы

yyyymmddhhmmss - Число, представляющее год, месяц и день. Integer, Float или Decimal.
timezone - Часовой пояс для возвращаемого значения (опционально).

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

дата и время, созданные из аргументов. DateTime.

Пример

Результат:

YYYYMMDDhhmmssToDateTime64

Как функция YYYYMMDDhhmmssToDate(), но производит DateTime64.

Принимает дополнительный необязательный параметр precision после параметра timezone.

changeYear

Изменяет компонент года даты или даты времени.

Синтаксис

Аргументы

date_or_datetime - Date, Date32, DateTime или DateTime64
value - новое значение года. Integer.

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

Тот же тип, что и date_or_datetime.

Пример

Результат:

changeMonth

Изменяет компонент месяца даты или даты времени.

Синтаксис

Аргументы

date_or_datetime - Date, Date32, DateTime или DateTime64
value - новое значение месяца. Integer.

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

Возвращает значение того же типа, что и date_or_datetime.

Пример

Результат:

changeDay

Изменяет компонент дня даты или даты времени.

Синтаксис

Аргументы

date_or_datetime - Date, Date32, DateTime или DateTime64
value - новое значение дня. Integer.

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

Возвращает значение того же типа, что и date_or_datetime.

Пример

Результат:

changeHour

Изменяет компонент часа даты или даты с временем.

Синтаксис

Аргументы

date_or_datetime - Дата, Date32, ДатаВремя или ДатаВремя64
value - новое значение часа. Целое число.

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

Возвращает значение того же типа, что и date_or_datetime. Если входное значение - это Дата, возвращает ДатаВремя. Если входное значение - это Date32, возвращает ДатаВремя64.

Пример

Результат:

changeMinute

Изменяет компонент минуты даты или даты с временем.

Синтаксис

Аргументы

date_or_datetime - Дата, Date32, ДатаВремя или ДатаВремя64
value - новое значение минуты. Целое число.

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

Возвращает значение того же типа, что и date_or_datetime. Если входное значение - это Дата, возвращает ДатаВремя. Если входное значение - это Date32, возвращает ДатаВремя64.

Пример

Результат:

changeSecond

Изменяет компонент секунды даты или даты с временем.

Синтаксис

Аргументы

date_or_datetime - Дата, Date32, ДатаВремя или ДатаВремя64
value - новое значение секунды. Целое число.

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

Возвращает значение того же типа, что и date_or_datetime. Если входное значение - это Дата, возвращает ДатаВремя. Если входное значение - это Date32, возвращает ДатаВремя64.

Пример

Результат:

addYears

Добавляет указанное количество лет к дате, дате с временем или дате/дате с временем в виде строки.

Синтаксис

Параметры

date: Дата / дата с временем, к которой нужно добавить указанное количество лет. Дата/Date32/ДатаВремя/ДатаВремя64, Строка.
num: Количество лет для добавления. (U)Int*, Float*.

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

Возвращает date плюс num лет. Дата/Date32/ДатаВремя/ДатаВремя64.

Пример

addQuarters

Добавляет указанное количество кварталов к дате, дате с временем или дате/дате с временем в виде строки.

Синтаксис

Параметры

date: Дата / дата с временем, к которой нужно добавить указанное количество кварталов. Дата/Date32/ДатаВремя/ДатаВремя64, Строка.
num: Количество кварталов для добавления. (U)Int*, Float*.

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

Возвращает date плюс num кварталов. Дата/Date32/ДатаВремя/ДатаВремя64.

Пример

addMonths

Добавляет указанное количество месяцев к дате, дате с временем или дате/дате с временем в виде строки.

Синтаксис

Параметры

date: Дата / дата с временем, к которой нужно добавить указанное количество месяцев. Дата/Date32/ДатаВремя/ДатаВремя64, Строка.
num: Количество месяцев для добавления. (U)Int*, Float*.

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

Возвращает date плюс num месяцев. Дата/Date32/ДатаВремя/ДатаВремя64.

Пример

addWeeks

Добавляет указанное количество недель к дате, дате с временем или дате/дате с временем в виде строки.

Синтаксис

Параметры

date: Дата / дата с временем, к которой нужно добавить указанное количество недель. Дата/Date32/ДатаВремя/ДатаВремя64, Строка.
num: Количество недель для добавления. (U)Int*, Float*.

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

Возвращает date плюс num недель. Дата/Date32/ДатаВремя/ДатаВремя64.

Пример

addDays

Добавляет указанное количество дней к дате, дате с временем или дате/дате с временем в виде строки.

Синтаксис

Параметры

date: Дата / дата с временем, к которой нужно добавить указанное количество дней. Дата/Date32/ДатаВремя/ДатаВремя64, Строка.
num: Количество дней для добавления. (U)Int*, Float*.

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

Возвращает date плюс num дней. Дата/Date32/ДатаВремя/ДатаВремя64.

Пример

addHours

Добавляет указанное количество часов к дате, дате с временем или дате/дате с временем в виде строки.

Синтаксис

Параметры

date: Дата / дата с временем, к которой нужно добавить указанное количество часов. Дата/Date32/ДатаВремя/ДатаВремя64, Строка.
num: Количество часов для добавления. (U)Int*, Float*.

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

Возвращает date плюс num часов. Дата/Date32/ДатаВремя/ДатаВремя64.

Пример

addMinutes

Добавляет указанное количество минут к дате, дате с временем или дате/дате с временем в виде строки.

Синтаксис

Параметры

date: Дата / дата с временем, к которой нужно добавить указанное количество минут. Дата/Date32/ДатаВремя/ДатаВремя64, Строка.
num: Количество минут для добавления. (U)Int*, Float*.

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

Возвращает date плюс num минут. Дата/Date32/ДатаВремя/ДатаВремя64.

Пример

addSeconds

Добавляет указанное количество секунд к дате, дате с временем или дате/дате с временем в виде строки.

Синтаксис

Параметры

date: Дата / дата с временем, к которой нужно добавить указанное количество секунд. Дата/Date32/ДатаВремя/ДатаВремя64, Строка.
num: Количество секунд для добавления. (U)Int*, Float*.

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

Возвращает date плюс num секунд. Дата/Date32/ДатаВремя/ДатаВремя64.

Пример

addMilliseconds

Добавляет указанное количество миллисекунд к дате с временем или дате с временем в виде строки.

Синтаксис

Параметры

date_time: Дата с временем, к которой нужно добавить указанное количество миллисекунд. ДатаВремя/ДатаВремя64, Строка.
num: Количество миллисекунд для добавления. (U)Int*, Float*.

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

Возвращает date_time плюс num миллисекунд. ДатаВремя64.

Пример

addMicroseconds

Добавляет указанное количество микросекунд к дате с временем или дате с временем в виде строки.

Синтаксис

Параметры

date_time: Дата с временем, к которой нужно добавить указанное количество микросекунд. ДатаВремя/ДатаВремя64, Строка.
num: Количество микросекунд для добавления. (U)Int*, Float*.

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

Возвращает date_time плюс num микросекунд. ДатаВремя64.

Пример

addNanoseconds

Добавляет указанное количество наносекунд к дате с временем или дате с временем в виде строки.

Синтаксис

Параметры

date_time: Дата с временем, к которой нужно добавить указанное количество наносекунд. ДатаВремя/ДатаВремя64, Строка.
num: Количество наносекунд для добавления. (U)Int*, Float*.

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

Возвращает date_time плюс num наносекунд. ДатаВремя64.

Пример

addInterval

Добавляет интервал к другому интервалу или к кортежу интервалов.

Синтаксис

Параметры

interval_1: Первый интервал или кортеж интервалов. интервал, кортеж(интервал).
interval_2: Второй интервал для добавления. интервал.

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

Возвращает кортеж интервалов. кортеж(интервал).

примечание

Интервалы одного типа будут объединены в один интервал. Например, если передать toIntervalDay(1) и toIntervalDay(2), то результат будет (3), а не (1,1).

Пример

Запрос:

Результат:

addTupleOfIntervals

Последовательно добавляет кортеж интервалов к дате или к дате с временем.

Синтаксис

Параметры

date: Первый интервал или кортеж интервалов. дата/date32/датаВремя/датаВремя64.
intervals: Кортеж интервалов, который нужно добавить к date. кортеж(интервал).

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

Возвращает date с добавленными intervals. дата/date32/датаВремя/датаВремя64.

Пример

Запрос:

Результат:

subtractYears

Вычитает указанное количество лет из даты, даты с временем или даты/даты с временем в виде строки.

Синтаксис

Параметры

date: Дата / дата с временем, из которой нужно вычесть указанное количество лет. Дата/Date32/ДатаВремя/ДатаВремя64, Строка.
num: Количество лет для вычитания. (U)Int*, Float*.

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

Возвращает date минус num лет. Дата/Date32/ДатаВремя/ДатаВремя64.

Пример

subtractQuarters

Вычитает указанное количество кварталов из даты, даты с временем или даты/даты с временем в виде строки.

Синтаксис

Параметры

date: Дата / дата с временем, из которой нужно вычесть указанное количество кварталов. Дата/Date32/ДатаВремя/ДатаВремя64, Строка.
num: Количество кварталов для вычитания. (U)Int*, Float*.

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

Возвращает date минус num кварталов. Дата/Date32/ДатаВремя/ДатаВремя64.

Пример

subtractMonths

Вычитает указанное количество месяцев из даты, даты с временем или даты/даты с временем в виде строки.

Синтаксис

Параметры

date: Дата / дата с временем, из которой нужно вычесть указанное количество месяцев. Дата/Date32/ДатаВремя/ДатаВремя64, Строка.
num: Количество месяцев для вычитания. (U)Int*, Float*.

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

Возвращает date минус num месяцев. Дата/Date32/ДатаВремя/ДатаВремя64.

Пример

subtractWeeks

Вычитает указанное количество недель из даты, даты с временем или даты/даты с временем в виде строки.

Синтаксис

Параметры

date: Дата / дата с временем, из которой нужно вычесть указанное количество недель. Дата/Date32/ДатаВремя/ДатаВремя64, Строка.
num: Количество недель для вычитания. (U)Int*, Float*.

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

Возвращает date минус num недель. Дата/Date32/ДатаВремя/ДатаВремя64.

Пример

subtractDays

Вычитает указанное количество дней из даты, даты с временем или даты/даты с временем в виде строки.

Синтаксис

Параметры

date: Дата / дата с временем, из которой нужно вычесть указанное количество дней. Дата/Date32/ДатаВремя/ДатаВремя64, Строка.
num: Количество дней для вычитания. (U)Int*, Float*.

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

Возвращает date минус num дней. Дата/Date32/ДатаВремя/ДатаВремя64.

Пример

subtractHours

Вычитает указанное количество часов из даты, даты с временем или даты/даты с временем в виде строки.

Синтаксис

Параметры

date: Дата / дата с временем, из которой нужно вычесть указанное количество часов. Дата/Date32/Datetime/Datetime64, Строка.
num: Количество часов для вычитания. (U)Int*, Float*.

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

Возвращает date минус num часов. Дата/Date32/Datetime/ДатаВремя64.

Пример

subtractMinutes

Вычитает указанное количество минут из даты, даты с временем или даты/даты с временем в виде строки.

Синтаксис

Параметры

date: Дата / дата с временем, от которой нужно вычесть указанное количество минут. Date/Date32/DateTime/DateTime64, String.
num: Количество минут, которые нужно вычесть. (U)Int*, Float*.

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

Возвращает date минус num минут. Date/Date32/DateTime/DateTime64.

Пример

subtractSeconds

Вычитает указанное количество секунд из даты, даты с временем или даты/даты с временем в виде строки.

Синтаксис

Параметры

date: Дата / дата с временем, из которой нужно вычесть указанное количество секунд. Date/Date32/DateTime/DateTime64, String.
num: Количество секунд, которые нужно вычесть. (U)Int*, Float*.

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

Возвращает date минус num секунд. Date/Date32/DateTime/DateTime64.

Пример

subtractMilliseconds

Вычитает указанное количество миллисекунд из даты с временем или даты с временем в виде строки.

Синтаксис

Параметры

date_time: Дата с временем, из которой нужно вычесть указанное количество миллисекунд. DateTime/DateTime64, String.
num: Количество миллисекунд, которые нужно вычесть. (U)Int*, Float*.

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

Возвращает date_time минус num миллисекунд. DateTime64.

Пример

subtractMicroseconds

Вычитает указанное количество микросекунд из даты с временем или даты с временем в виде строки.

Синтаксис

Параметры

date_time: Дата с временем, из которой нужно вычесть указанное количество микросекунд. DateTime/DateTime64, String.
num: Количество микросекунд, которые нужно вычесть. (U)Int*, Float*.

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

Возвращает date_time минус num микросекунд. DateTime64.

Пример

subtractNanoseconds

Вычитает указанное количество наносекунд из даты с временем или даты с временем в виде строки.

Синтаксис

Параметры

date_time: Дата с временем, из которой нужно вычесть указанное количество наносекунд. DateTime/DateTime64, String.
num: Количество наносекунд, которые нужно вычесть. (U)Int*, Float*.

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

Возвращает date_time минус num наносекунд. DateTime64.

Пример

subtractInterval

Прибавляет отрицательный интервал к другому интервалу или кортежу интервалов.

Синтаксис

Параметры

interval_1: Первый интервал или интервал кортежей. interval, tuple(interval).
interval_2: Второй интервал, который будет отрицаться. interval.

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

Возвращает кортеж интервалов. tuple(interval).

примечание

Интервалы одного типа будут объединены в один интервал. Например, если передать toIntervalDay(2) и toIntervalDay(1), то результат будет (1), а не (2,1).

Пример

Запрос:

Результат:

subtractTupleOfIntervals

Последовательно вычитает кортеж интервалов из даты или даты с временем.

Синтаксис

Параметры

date: Первая дата или интервал кортежей. Date/Date32/DateTime/DateTime64.
intervals: Кортеж интервалов, которые нужно вычесть из date. tuple(interval).

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

Возвращает date с вычтенными intervals. Date/Date32/DateTime/DateTime64.

Пример

Запрос:

Результат:

timeSlots

Для временного интервала, начинающегося с 'StartTime' и продолжающегося в течение 'Duration' секунд, возвращает массив моментов времени, состоящий из точек этого интервала, округленных вниз до 'Size' в секундах. 'Size' — это необязательный параметр, установленный по умолчанию на 1800 (30 минут). Это необходимо, например, при поиске просмотров страниц в соответствующей сессии. Принимает DateTime и DateTime64 в качестве аргумента 'StartTime'. Для DateTime аргументы 'Duration' и 'Size' должны быть UInt32. Для 'DateTime64' они должны быть Decimal64. Возвращает массив DateTime/DateTime64 (тип возвращаемого значения совпадает с типом 'StartTime'). Для DateTime64 масштаб возвращаемого значения может отличаться от масштаба 'StartTime' — принимается самый высокий масштаб среди всех переданных аргументов.

Синтаксис

Пример

Результат:

formatDateTime

Форматирует время согласно заданной строке формата. Формат является константным выражением, поэтому вы не можете иметь несколько форматов для одного столбца результата.

formatDateTime использует стиль формата MySQL datetime, см. https://dev.mysql.com/doc/refman/8.0/en/date-and-time-functions.html#function_date-format.

Обратная операция этой функции — parseDateTime.

Псевдоним: DATE_FORMAT.

Синтаксис

Возвращаемое значение(я)

Возвращает значения времени и даты в соответствии с определенным форматом.

Поля замены

Используя поля замены, вы можете определить шаблон для результирующей строки. В колонке «Пример» показан результат форматирования для 2018-01-02 22:33:44.

Заполнитель	Описание	Пример
%a	сокращенное название дня недели (Пн-Вс)	Пн
%b	сокращенное название месяца (Янв-Дек)	Янв
%c	месяц как целое число (01-12), см. 'Примечание 4' ниже	01
%C	год, деленный на 100 и округленный до целого (00-99)	20
%d	день месяца, с нулевым заполнением (01-31)	02
%D	Короткая дата в формате MM/DD/YY, эквивалентная %m/%d/%y	01/02/18
%e	день месяца, с пробеловым заполнением ( 1-31)	2
%f	дробная секунда, см. 'Примечание 1' и 'Примечание 2' ниже	123456
%F	короткая дата в формате YYYY-MM-DD, эквивалентная %Y-%m-%d	2018-01-02
%g	двухзначный год, выровненный по стандарту ISO 8601, сокращенный от четырехзначной записи	18
%G	год в четырехзначном формате для номера недели ISO, рассчитанный на основе года численности недель определяемого стандартом ISO 8601, обычно полезен только с %V	2018
%h	час в 12-часовом формате (01-12)	09
%H	час в 24-часовом формате (00-23)	22
%i	минуты (00-59)	33
%I	час в 12-часовом формате (01-12)	10
%j	день в году (001-366)	002
%k	час в 24-часовом формате (00-23), см. 'Примечание 4' ниже	14
%l	час в 12-часовом формате (01-12), см. 'Примечание 4' ниже	09
%m	месяц как целое число (01-12)	01
%M	полное название месяца (Январь-Декабрь), см. 'Примечание 3' ниже	Январь
%n	символ новой строки ('')
%p	обозначение AM или PM	PM
%Q	Квартал (1-4)	1
%r	время в формате 12-часового формата HH:MM AM/PM, эквивалентное %h:%i %p	10:30 PM
%R	время в 24-часовом формате HH:MM, эквивалентное %H:%i	22:33
%s	секунды (00-59)	44
%S	секунды (00-59)	44
%t	символ горизонтальной табуляции (')
%T	ISO 8601 формат времени (HH:MM:SS), эквивалентный %H:%i:%S	22:33:44
%u	ISO 8601 день недели как число с понедельником как 1 (1-7)	2
%V	номер недели ISO 8601 (01-53)	01
%w	день недели как целое число с воскресеньем как 0 (0-6)	2
%W	полное название дня недели (Понедельник-Воскресенье)	Понедельник
%y	Год, последние две цифры (00-99)	18
%Y	Год	2018
%z	Смещение времени от UTC, записанное в формате +HHMM или -HHMM	-0500
%%	символ %	%

Примечание 1: В версиях ClickHouse, предшествующих v23.4, %f выводит один ноль (0), если форматированное значение является датой, Date32 или DateTime (которые не имеют дробных секунд) или DateTime64 с нулевой точностью. Предыдущее поведение можно восстановить, установив параметр formatdatetime_f_prints_single_zero = 1.

Примечание 2: В версиях ClickHouse, предшествующих v25.1, %f выводит столько же знаков, сколько указано в масштабе DateTime64, вместо фиксированных 6 знаков. Предыдущее поведение можно восстановить, установив параметр formatdatetime_f_prints_scale_number_of_digits= 1.

Примечание 3: В версиях ClickHouse, предшествующих v23.4, %M выводит минуты (00-59), а не полное название месяца (Январь-Декабрь). Предыдущее поведение можно восстановить, установив параметр formatdatetime_parsedatetime_m_is_month_name = 0.

Примечание 4: В версиях ClickHouse, предшествующих v23.11, функция parseDateTime() требовала начальных нулей для форматтеров %c (месяц) и %l/%k (час), например, 07. В более поздних версиях начальный ноль можно опустить, например, 7. Предыдущее поведение можно восстановить, установив параметр parsedatetime_parse_without_leading_zeros = 0. Обратите внимание, что функция formatDateTime() по умолчанию все еще выводит начальные нули для %c и %l/%k, чтобы не нарушать существующие случаи использования. Это поведение можно изменить, установив параметр formatdatetime_format_without_leading_zeros = 1.

Пример

Результат:

Дополнительно, функция formatDateTime может принимать третий строковый аргумент, содержащий название часового пояса. Пример: Asia/Istanbul. В этом случае время форматируется в соответствии с указанным часовым поясом.

Пример

См. также

formatDateTimeInJodaSyntax

formatDateTimeInJodaSyntax

Похож на formatDateTime, за исключением того, что форматирует datetime в стиле Joda, а не в стиле MySQL. Смотрите https://joda-time.sourceforge.net/apidocs/org/joda/time/format/DateTimeFormat.html.

Обратная операция этой функции — parseDateTimeInJodaSyntax.

Поля замены

Используя поля замены, вы можете определить шаблон для результирующей строки.

Заполнитель	Описание	Презентация	Примеры
G	эра	текст	Н.Э.
C	век эры (>=0)	число	20
Y	год эры (>=0)	год	1996
x	недельный год (пока не поддерживается)	год	1996
w	неделя недельного года (пока не поддерживается)	число	27
e	день недели	число	2
E	день недели	текст	Вторник; Вт
y	год	год	1996
D	день в году	число	189
M	месяц года	месяц	Июль; Июл; 07
d	день месяца	число	10
a	половина дня	текст	PM
K	час половины дня (0~11)	число	0
h	час секунды (1~12)	число	12
H	час дня (0~23)	число	0
k	час дня (1~24)	число	24
m	минуты часа	число	30
s	секунды минуты	число	55
S	дробная секунда	число	978
z	часовой пояс	текст	Восточное стандартное время; EST
Z	смещение часового пояса	зона	-0800; -0812
'	экранирование для текста	разделитель
''	одиночная кавычка	литерал	'

Пример

Результат:

dateName

Возвращает указанную часть даты.

Синтаксис

Аргументы

date_part — Часть даты. Возможные значения: 'year', 'quarter', 'month', 'week', 'dayofyear', 'day', 'weekday', 'hour', 'minute', 'second'. String.
date — Дата. Date, Date32, DateTime или DateTime64.
timezone — Часовой пояс. Необязательный. String.

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

Указанная часть даты. String

Пример

Результат:

monthName

Возвращает название месяца.

Синтаксис

Аргументы

date — Дата или дата с временем. Date, DateTime или DateTime64.

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

Название месяца. String

Пример

Результат:

fromUnixTimestamp

Эта функция конвертирует метку времени Unix в календарную дату и время суток.

Её можно вызвать двумя способами:

Когда указан единственный аргумент типа Integer, она возвращает значение типа DateTime, то есть ведёт себя как toDateTime.

Псевдоним: FROM_UNIXTIME.

Пример:

Результат:

Когда переданы два или три аргумента, где первый аргумент имеет тип Integer, Date, Date32, DateTime или DateTime64, второй аргумент — это строка формата константы, а третий аргумент — необязательная строка временной зоны, то функция возвращает значение типа String, то есть ведёт себя как formatDateTime. В этом случае используется формат стиля даты MySQL.

Пример:

Результат:

См. Также

fromUnixTimestampInJodaSyntax

fromUnixTimestampInJodaSyntax

То же самое, что и fromUnixTimestamp, но при вызове вторым способом (два или три аргумента) форматирование выполняется с использованием стиля Joda, а не стиля MySQL.

Пример:

Результат:

toModifiedJulianDay

Конвертирует дату в текстовом формате Proleptic Gregorian calendar YYYY-MM-DD в число Modified Julian Day в Int32. Эта функция поддерживает даты с 0000-01-01 по 9999-12-31. Она вызывает исключение, если аргумент не может быть разобран как дата или дата недействительна.

Синтаксис

Аргументы

date — Дата в текстовом формате. String или FixedString.

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

Число Modified Julian Day. Int32.

Пример

Результат:

toModifiedJulianDayOrNull

Похоже на toModifiedJulianDay(), но вместо вызова исключений возвращает NULL.

Синтаксис

Аргументы

date — Дата в текстовом формате. String или FixedString.

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

Число Modified Julian Day. Nullable(Int32).

Пример

Результат:

fromModifiedJulianDay

Конвертирует число Modified Julian Day в дату в текстовом формате Proleptic Gregorian calendar YYYY-MM-DD. Эта функция поддерживает номера дней с -678941 по 2973483 (что соответствует 0000-01-01 и 9999-12-31 соответственно). Она вызывает исключение, если номер дня выходит за пределы поддерживаемого диапазона.

Синтаксис

Аргументы

day — Число Modified Julian Day. Любые целые типы.

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

Дата в текстовом формате. String

Пример

Результат:

fromModifiedJulianDayOrNull

Похоже на fromModifiedJulianDayOrNull(), но вместо вызова исключений возвращает NULL.

Синтаксис

Аргументы

day — Число Modified Julian Day. Любые целые типы.

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

Дата в текстовом формате. Nullable(String)

Пример

Результат:

toUTCTimestamp

Конвертирует значение типа DateTime/DateTime64 из другой временной зоны в метку времени в UTC. Эта функция в основном включена для совместимости с Apache Spark и подобными фреймворками.

Синтаксис

Аргументы

time_val — Константное значение типа DateTime/DateTime64 или выражение. Типы DateTime/DateTime64
time_zone — Константное строковое значение или выражение, представляющее временную зону. Строковые типы

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

DateTime/DateTime64 в текстовом формате

Пример

Результат:

fromUTCTimestamp

Конвертирует значение типа DateTime/DateTime64 из временной зоны UTC в метку времени в другой временной зоне. Эта функция в основном включена для совместимости с Apache Spark и подобными фреймворками.

Синтаксис

Аргументы

time_val — Константное значение типа DateTime/DateTime64 или выражение. Типы DateTime/DateTime64
time_zone — Константное строковое значение или выражение, представляющее временную зону. Строковые типы

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

DateTime/DateTime64 в текстовом формате

Пример

Результат:

UTCTimestamp

Возвращает текущую дату и время на момент анализа запроса. Функция является константным выражением.

примечание

Эта функция выдаёт тот же результат, что и now('UTC'). Она была добавлена только для поддержки MySQL, и now является предпочтительным вариантом использования.

Синтаксис

Псевдоним: UTC_timestamp.

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

Возвращает текущую дату и время на момент анализа запроса. DateTime.

Пример

Запрос:

Результат:

timeDiff

Возвращает разницу между двумя датами или датами с часовыми значениями. Разница рассчитывается в единицах секунд. Это то же самое, что и dateDiff, и было добавлено только для поддержки MySQL. dateDiff рекомендуется использовать.

Синтаксис

Аргументы

first_datetime — Константное значение типа DateTime/DateTime64 или выражение. Типы DateTime/DateTime64
second_datetime — Константное значение типа DateTime/DateTime64 или выражение. Типы DateTime/DateTime64

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

Разница между двумя датами или датами с часовыми значениями в секундах.

Пример

Запрос:

Результат:

Блог: Работа с данными временных рядов в ClickHouse

makeDate​

makeDate32​

makeDateTime​

makeDateTime64​

timestamp​

timeZone​

serverTimeZone​

toTimeZone​

timeZoneOf​

timeZoneOffset​

toYear​

toQuarter​

toMonth​

toDayOfYear​

toDayOfMonth​

toDayOfWeek​

toHour​

toMinute​

toSecond​

toMillisecond​

toUnixTimestamp​

toStartOfYear​

toStartOfISOYear​

toStartOfQuarter​

toStartOfMonth​

toLastDayOfMonth​

toMonday​

toStartOfWeek​

toLastDayOfWeek​

toStartOfDay​

toStartOfHour​

toStartOfMinute​

toStartOfSecond​

toStartOfMillisecond​

toStartOfMicrosecond​

toStartOfNanosecond​

toStartOfFiveMinutes​

toStartOfTenMinutes​

toStartOfFifteenMinutes​

toStartOfInterval​

toTime​

toRelativeYearNum​

toRelativeQuarterNum​

toRelativeMonthNum​

toRelativeWeekNum​

toRelativeDayNum​

toRelativeHourNum​

toRelativeMinuteNum​

toRelativeSecondNum​

toISOYear​

toISOWeek​

toWeek​

toYearWeek​

toDaysSinceYearZero​

fromDaysSinceYearZero​

fromDaysSinceYearZero32​

age​

date_diff​

date_trunc​

date_add​

date_sub​

timestamp_add​

timestamp_sub​

addDate​

subDate​

now​

now64​

nowInBlock​

today​

yesterday​

timeSlot​

toYYYYMM​

toYYYYMMDD​

toYYYYMMDDhhmmss​

YYYYMMDDToDate​

YYYYMMDDToDate32​

YYYYMMDDhhmmssToDateTime​

YYYYMMDDhhmmssToDateTime64​

changeYear​

changeMonth​

makeDate

makeDate32

makeDateTime

makeDateTime64

timestamp

timeZone

serverTimeZone

toTimeZone

timeZoneOf

timeZoneOffset

toYear

toQuarter

toMonth

toDayOfYear

toDayOfMonth

toDayOfWeek

toHour

toMinute

toSecond

toMillisecond

toUnixTimestamp

toStartOfYear

toStartOfISOYear

toStartOfQuarter

toStartOfMonth

toLastDayOfMonth

toMonday

toStartOfWeek

toLastDayOfWeek

toStartOfDay

toStartOfHour

toStartOfMinute

toStartOfSecond

toStartOfMillisecond

toStartOfMicrosecond

toStartOfNanosecond

toStartOfFiveMinutes

toStartOfTenMinutes

toStartOfFifteenMinutes

toStartOfInterval

toTime

toRelativeYearNum

toRelativeQuarterNum

toRelativeMonthNum

toRelativeWeekNum

toRelativeDayNum

toRelativeHourNum

toRelativeMinuteNum

toRelativeSecondNum

toISOYear

toISOWeek

toWeek

toYearWeek

toDaysSinceYearZero

fromDaysSinceYearZero

fromDaysSinceYearZero32

age

date_diff

date_trunc

date_add

date_sub

timestamp_add

timestamp_sub

addDate

subDate

now

now64

nowInBlock

today

yesterday

timeSlot

toYYYYMM

toYYYYMMDD

toYYYYMMDDhhmmss

YYYYMMDDToDate

YYYYMMDDToDate32

YYYYMMDDhhmmssToDateTime

YYYYMMDDhhmmssToDateTime64

changeYear

changeMonth