Функции для Работы с Датами и Временем
Большинство функций в этом разделе принимают необязательный аргумент часового пояса, например 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
Возвращает часовой пояс сервера, т.е. значение настройки timezone. Если функция выполняется в контексте распределенной таблицы, она генерирует нормальную колонку с значениями, соответствующими каждой шард. В противном случае она производит константное значение.
Синтаксис
Псевдоним: serverTimezone
.
Возвращаемое значение
- Часовой пояс. Строка.
Пример
Результат:
См. также
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
- Date, Date32, DateTime или DateTime64
Возвращаемое значение
- Год заданной даты/времени. UInt16.
Пример
Результат:
toQuarter
Возвращает квартал (1-4) даты или даты с временем.
Синтаксис
Псевдоним: QUARTER
Аргументы
value
- Date, Date32, DateTime или DateTime64
Возвращаемое значение
- Квартал года (1, 2, 3 или 4) заданной даты/времени. UInt8.
Пример
Результат:
toMonth
Возвращает компонент месяца (1-12) даты или даты с временем.
Синтаксис
Псевдоним: MONTH
Аргументы
value
- Date, Date32, DateTime или DateTime64
Возвращаемое значение
- Месяц года (1 - 12) заданной даты/времени. UInt8.
Пример
Результат:
toDayOfYear
Возвращает номер дня в году (1-366) даты или даты с временем.
Синтаксис
Псевдоним: DAYOFYEAR
Аргументы
value
- Date, Date32, DateTime или DateTime64
Возвращаемое значение
- День года (1 - 366) заданной даты/времени. UInt16.
Пример
Результат:
toDayOfMonth
Возвращает номер дня в месяце (1-31) даты или даты с временем.
Синтаксис
Псевдонимы: DAYOFMONTH
, DAY
Аргументы
value
- Date, Date32, DateTime или DateTime64
Возвращаемое значение
- День месяца (1 - 31) заданной даты/времени. UInt8.
Пример
Результат:
toDayOfWeek
Возвращает номер дня в неделе даты или даты с временем.
Двухаргументная форма toDayOfWeek()
позволяет указать, начинается ли неделя с понедельника или воскресенья, и нужно ли возвращаемое значение в диапазоне от 0 до 6 или от 1 до 7. Если аргумент mode опущен, то используется значение по умолчанию 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
- Date, Date32, DateTime или DateTime64mode
- определяет, какой день недели является первым. Возможные значения: 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 - 599) заданной даты/времени. 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
- Date, Date32, DateTime или DateTime64
Возвращаемое значение
- Первый день года входной даты/времени. Date.
Пример
Результат:
toStartOfISOYear
Округляет дату или дату с временем до первого дня ISO года, который может отличаться от "обычного" года. (См. https://en.wikipedia.org/wiki/ISO_week_date.)
Синтаксис
Аргументы
value
- Date, Date32, DateTime или DateTime64
Возвращаемое значение
- Первый день года входной даты/времени. Date.
Пример
Результат:
toStartOfQuarter
Округляет дату или дату с временем до первого дня квартала. Первый день квартала — это либо 1 января, 1 апреля, 1 июля, либо 1 октября. Возвращает дату.
Синтаксис
Аргументы
value
- Date, Date32, DateTime или DateTime64
Возвращаемое значение
- Первый день квартала заданной даты/времени. Date.
Пример
Результат:
toStartOfMonth
Округляет дату или дату с временем до первого дня месяца. Возвращает дату.
Синтаксис
Аргументы
value
- Date, Date32, DateTime или DateTime64
Возвращаемое значение
- Первый день месяца заданной даты/времени. Date.
Пример
Результат:
Поведение парсинга некорректных дат является специфичным для реализации. ClickHouse может вернуть нулевую дату, выбросить исключение или сделать "естественное" переполнение.
toLastDayOfMonth
Округляет дату или дату с временем до последнего дня месяца. Возвращает дату.
Синтаксис
Псевдоним: LAST_DAY
Аргументы
value
- Date, Date32, DateTime или DateTime64
Возвращаемое значение
- Последний день месяца заданной даты/времени. Date.
Пример
Результат:
toMonday
Округляет дату или дату с временем до ближайшего понедельника. Возвращает дату.
Синтаксис
Аргументы
value
- Date, Date32, DateTime или DateTime64
Возвращаемое значение
- Дата ближайшего понедельника на или до указанной даты. Date.
Пример
Результат:
toStartOfWeek
Округляет дату или дату с временем до ближайшего воскресенья или понедельника. Возвращает дату. Аргумент mode работает точно так же, как аргумент mode в функции toWeek()
. Если режим не указан, по умолчанию используется 0.
Синтаксис
Аргументы
t
- Дата, Date32, DateTime или DateTime64mode
- определяет первый день недели, как описано в функции toWeek()timezone
- необязательный параметр, ведет себя как любая другая функция преобразования
Возвращаемое значение
- Дата ближайшего воскресенья или понедельника до или на заданной дате, в зависимости от режима. Дата.
Пример
Результат:
toLastDayOfWeek
Округляет дату или дату с временем до ближайшей субботы или воскресенья. Возвращает дату. Аргумент mode работает точно так же, как аргумент mode в функции toWeek()
. Если режим не указан, режим считается равным 0.
Синтаксис
Аргументы
t
- Дата, Date32, DateTime или DateTime64mode
- определяет последний день недели, как описано в toWeek функцииtimezone
- необязательный параметр, ведет себя как любая другая функция преобразования
Возвращаемое значение
- Дата ближайшего воскресенья или понедельника на или после заданной даты, в зависимости от режима. Дата.
Пример
Результат:
toStartOfDay
Округляет дату с временем до начала дня.
Синтаксис
Аргументы
value
- Дата, Date32, DateTime или DateTime64
Возвращаемое значение
- Начало дня заданной даты/времени. DateTime.
Пример
Результат:
toStartOfHour
Округляет дату с временем до начала часа.
Синтаксис
Аргументы
value
- DateTime или DateTime64
Возвращаемое значение
- Начало часа заданной даты/времени. DateTime.
Пример
Результат:
toStartOfMinute
Округляет дату с временем до начала минуты.
Синтаксис
Аргументы
value
- DateTime или DateTime64
Возвращаемое значение
- Начало минуты заданной даты/времени. DateTime.
Пример
Результат:
toStartOfSecond
Убирает подсекунды.
Синтаксис
Аргументы
value
— Дата и время. DateTime64.timezone
— Часовой пояс для возвращаемого значения (необязательный). Если не указан, функция использует часовой пояс параметраvalue
. Строка.
Возвращаемое значение
- Входное значение без подсекунд. DateTime64.
Примеры
Запрос без часового пояса:
Результат:
Запрос с часовым поясом:
Результат:
См. также
- Часовой пояс параметр конфигурации сервера.
toStartOfMillisecond
Округляет дату с временем до начала миллисекунд.
Синтаксис
Аргументы
value
— Дата и время. DateTime64.timezone
— Часовой пояс для возвращаемого значения (необязательный). Если не указан, функция использует часовой пояс параметраvalue
. Строка.
Возвращаемое значение
- Входное значение с подмиллисекундами. DateTime64.
Примеры
Запрос без часового пояса:
Результат:
Запрос с часовым поясом:
Результат:
См. также
- Часовой пояс параметр конфигурации сервера.
toStartOfMicrosecond
Округляет дату с временем до начала микросекунд.
Синтаксис
Аргументы
value
— Дата и время. DateTime64.timezone
— Часовой пояс для возвращаемого значения (необязательный). Если не указан, функция использует часовой пояс параметраvalue
. Строка.
Возвращаемое значение
- Входное значение с подмикросекундами. DateTime64.
Примеры
Запрос без часового пояса:
Результат:
Запрос с часовым поясом:
Результат:
См. также
- Часовой пояс параметр конфигурации сервера.
toStartOfNanosecond
Округляет дату с временем до начала наносекунд.
Синтаксис
Аргументы
value
— Дата и время. DateTime64.timezone
— Часовой пояс для возвращаемого значения (необязательный). Если не указан, функция использует часовой пояс параметраvalue
. Строка.
Возвращаемое значение
- Входное значение с наносекундами. DateTime64.
Примеры
Запрос без часового пояса:
Результат:
Запрос с часовым поясом:
Результат:
См. также
- Часовой пояс параметр конфигурации сервера.
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
.
Вторая перегрузка эмулирует функцию TimescaleDB time_bucket()
, соответственно функцию PostgreSQL date_bin()
, например.
Результат:
См. также
toTimeWithFixedDate
Преобразует дату с временем в определенную фиксированную дату, сохраняя время.
Синтаксис
Псевдоним: toTime
- может использоваться только при включении настройки use_legacy_to_time
.
Аргументы
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
– Дата или DateTime.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
Возвращает для заданного числа дней, прошедших с 1 января 0000, соответствующую дату в пролептическом григорианском календаре, определенном ISO 8601. Расчет такой же, как в функции MySQL FROM_DAYS()
.
Результат не определен, если его нельзя представить в пределах границ типа Date.
Синтаксис
Псевдоним: FROM_DAYS
Аргументы
days
— число дней, прошедших с года ноль.
Возвращаемое значение
Дата, соответствующая числу дней, прошедших с года ноль. Date.
Пример
Результат:
Смотрите также
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
- Совместим только с DateTime64microsecond
- Совместим только с DateTime64millisecond
- Совместим только с DateTime64second
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).
Пример
Запрос без часового пояса:
Результат:
Запрос с указанным часовым поясом:
Результат:
Смотрите также
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.
Пример
Результат:
Результат:
Смотрите также
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.
Пример
Результат:
Результат:
Смотрите также
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 или Stringinterval
— интервал, который нужно добавить. Interval.
Возвращаемое значение
Дата или дата с временем, полученная путем добавления interval
к date
. Date, Date32, DateTime или DateTime64.
Пример
Результат:
Псевдоним: ADDDATE
Смотрите также
subDate
Вычитает временной интервал из заданной даты, даты с временем или строкового представления даты / даты с временем.
Если разность приводит к значению вне границ типа данных, результат не определен.
Синтаксис
Аргументы
date
— дата или дата с временем, из которой вычитаетсяinterval
. Date, Date32, DateTime, DateTime64 или Stringinterval
— интервал, который нужно вычесть. Interval.
Возвращаемое значение
Дата или дата с временем, полученная путем вычитания interval
из date
. Date, Date32, DateTime или DateTime64.
Пример
Результат:
Псевдоним: SUBDATE
Смотрите также
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.
Пример
Результат:
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 или DateTime64value
- новое значение года. Integer.
Возвращаемое значение
- Тот же тип, что и
date_or_datetime
.
Пример
Результат:
changeMonth
Изменяет компонент месяца даты или даты с временем.
Синтаксис
Аргументы
date_or_datetime
- Date, Date32, DateTime или DateTime64value
- новое значение месяца. Integer.
Возвращаемое значение
- Возвращает значение того же типа, что и
date_or_datetime
.
Пример
Результат:
changeDay
Изменяет компонент дня даты или даты с временем.
Синтаксис
Аргументы
date_or_datetime
- Date, Date32, DateTime или DateTime64value
- новое значение дня. Integer.
Возвращаемое значение
- Возвращает значение того же типа, что и
date_or_datetime
.
Пример
Результат:
changeHour
Изменяет компонент часа в дате или дате с временем.
Синтаксис
Аргументы
date_or_datetime
- Дата, Date32, DateTime или DateTime64value
- новое значение часа. Целое число.
Возвращаемое значение
- Возвращает значение того же типа, что и
date_or_datetime
. Если входные данные - Дата, возвращает DateTime. Если входные данные - Date32, возвращает DateTime64.
Пример
Результат:
changeMinute
Изменяет компонент минуты в дате или дате с временем.
Синтаксис
Аргументы
date_or_datetime
- Дата, Date32, DateTime или DateTime64value
- новое значение минуты. Целое число.
Возвращаемое значение
- Возвращает значение того же типа, что и
date_or_datetime
. Если входные данные - Дата, возвращает DateTime. Если входные данные - Date32, возвращает DateTime64.
Пример
Результат:
changeSecond
Изменяет компонент секунды в дате или дате с временем.
Синтаксис
Аргументы
date_or_datetime
- Дата, Date32, DateTime или DateTime64value
- новое значение секунды. Целое число.
Возвращаемое значение
- Возвращает значение того же типа, что и
date_or_datetime
. Если входные данные - Дата, возвращает DateTime. Если входные данные - Date32, возвращает DateTime64.
Пример
Результат:
addYears
Добавляет указанное количество лет к дате, дате с временем или строково-кодированной дате / дате с временем.
Синтаксис
Параметры
date
: Дата / дата с временем, к которой нужно добавить указанное количество лет. Дата/Date32/DateTime/DateTime64, Строка.num
: Количество лет для добавления. (U)Int*, Float*.
Возвращаемое значение
- Возвращает
date
плюсnum
лет. Дата/Date32/DateTime/DateTime64.
Пример
addQuarters
Добавляет указанное количество кварталов к дате, дате с временем или строково-кодированной дате / дате с временем.
Синтаксис
Параметры
date
: Дата / дата с временем, к которой нужно добавить указанное количество кварталов. Дата/Date32/DateTime/DateTime64, Строка.num
: Количество кварталов для добавления. (U)Int*, Float*.
Возвращаемое значение
- Возвращает
date
плюсnum
кварталов. Дата/Date32/DateTime/DateTime64.
Пример
addMonths
Добавляет указанное количество месяцев к дате, дате с временем или строково-кодированной дате / дате с временем.
Синтаксис
Параметры
date
: Дата / дата с временем, к которой нужно добавить указанное количество месяцев. Дата/Date32/DateTime/DateTime64, Строка.num
: Количество месяцев для добавления. (U)Int*, Float*.
Возвращаемое значение
- Возвращает
date
плюсnum
месяцев. Дата/Date32/DateTime/DateTime64.
Пример
addWeeks
Добавляет указанное количество недель к дате, дате с временем или строково-кодированной дате / дате с временем.
Синтаксис
Параметры
date
: Дата / дата с временем, к которой нужно добавить указанное количество недель. Дата/Date32/DateTime/DateTime64, Строка.num
: Количество недель для добавления. (U)Int*, Float*.
Возвращаемое значение
- Возвращает
date
плюсnum
недель. Дата/Date32/DateTime/DateTime64.
Пример
addDays
Добавляет указанное количество дней к дате, дате с временем или строково-кодированной дате / дате с временем.
Синтаксис
Параметры
date
: Дата / дата с временем, к которой нужно добавить указанное количество дней. Дата/Date32/DateTime/DateTime64, Строка.num
: Количество дней для добавления. (U)Int*, Float*.
Возвращаемое значение
- Возвращает
date
плюсnum
дней. Дата/Date32/DateTime/DateTime64.
Пример
addHours
Добавляет указанное количество часов к дате, дате с временем или строково-кодированной дате / дате с временем.
Синтаксис
Параметры
date
: Дата / дата с временем, к которой нужно добавить указанное количество часов. Дата/Date32/DateTime/DateTime64, Строка.num
: Количество часов для добавления. (U)Int*, Float*.
Возвращаемое значение
- Возвращает
date
плюсnum
часов. Дата/Date32/DateTime/DateTime64.
Пример
addMinutes
Добавляет указанное количество минут к дате, дате с временем или строково-кодированной дате / дате с временем.
Синтаксис
Параметры
date
: Дата / дата с временем, к которой нужно добавить указанное количество минут. Дата/Date32/DateTime/DateTime64, Строка.num
: Количество минут для добавления. (U)Int*, Float*.
Возвращаемое значение
- Возвращает
date
плюсnum
минут. Дата/Date32/DateTime/DateTime64.
Пример
addSeconds
Добавляет указанное количество секунд к дате, дате с временем или строково-кодированной дате / дате с временем.
Синтаксис
Параметры
date
: Дата / дата с временем, к которой нужно добавить указанное количество секунд. Дата/Date32/DateTime/DateTime64, Строка.num
: Количество секунд для добавления. (U)Int*, Float*.
Возвращаемое значение
- Возвращает
date
плюсnum
секунд. Дата/Date32/DateTime/DateTime64.
Пример
addMilliseconds
Добавляет указанное количество миллисекунд к дате с временем или строково-кодированной дате с временем.
Синтаксис
Параметры
date_time
: Дата с временем, к которой нужно добавить указанное количество миллисекунд. DateTime/DateTime64, Строка.num
: Количество миллисекунд для добавления. (U)Int*, Float*.
Возвращаемое значение
- Возвращает
date_time
плюсnum
миллисекунд. DateTime64.
Пример
addMicroseconds
Добавляет указанное количество микросекунд к дате с временем или строково-кодированной дате с временем.
Синтаксис
Параметры
date_time
: Дата с временем, к которой нужно добавить указанное количество микросекунд. DateTime/DateTime64, Строка.num
: Количество микросекунд для добавления. (U)Int*, Float*.
Возвращаемое значение
- Возвращает
date_time
плюсnum
микросекунд. DateTime64.
Пример
addNanoseconds
Добавляет указанное количество наносекунд к дате с временем или строково-кодированной дате с временем.
Синтаксис
Параметры
date_time
: Дата с временем, к которой нужно добавить указанное количество наносекунд. DateTime/DateTime64, Строка.num
: Количество наносекунд для добавления. (U)Int*, Float*.
Возвращаемое значение
- Возвращает
date_time
плюсnum
наносекунд. DateTime64.
Пример
addInterval
Добавляет интервал к другому интервалу или к кортежу интервалов.
Синтаксис
Параметры
interval_1
: Первый интервал или кортеж интервалов. интервал, кортеж(интервал).interval_2
: Второй интервал, который будет добавлен. интервал.
Возвращаемое значение
Интервалы одного типа будут объединены в единый интервал. Например, если переданы toIntervalDay(1)
и toIntervalDay(2)
, то результат будет (3)
, а не (1,1)
.
Пример
Запрос:
Результат:
addTupleOfIntervals
Последовательно добавляет кортеж интервалов к дате или дате с временем.
Синтаксис
Параметры
date
: Первый интервал или кортеж интервалов. дата/date32/datetime/datetime64.intervals
: Кортеж интервалов, который необходимо добавить кdate
. кортеж(интервал).
Возвращаемое значение
- Возвращает
date
с добавленнымиintervals
. дата/date32/datetime/datetime64.
Пример
Запрос:
Результат:
subtractYears
Вычитает указанное количество лет из даты, даты с временем или строково-кодированной даты / даты с временем.
Синтаксис
Параметры
date
: Дата / дата с временем, из которой нужно вычесть указанное количество лет. Дата/Date32/DateTime/DateTime64, Строка.num
: Количество лет, которые нужно вычесть. (U)Int*, Float*.
Возвращаемое значение
- Возвращает
date
минусnum
лет. Дата/Date32/DateTime/DateTime64.
Пример
subtractQuarters
Вычитает указанное количество кварталов из даты, даты с временем или строково-кодированной даты / даты с временем.
Синтаксис
Параметры
date
: Дата / дата с временем, из которой нужно вычесть указанное количество кварталов. Дата/Date32/DateTime/DateTime64, Строка.num
: Количество кварталов, которые нужно вычесть. (U)Int*, Float*.
Возвращаемое значение
- Возвращает
date
минусnum
кварталов. Дата/Date32/DateTime/DateTime64.
Пример
subtractMonths
Вычитает указанное количество месяцев из даты, даты с временем или строково-кодированной даты / даты с временем.
Синтаксис
Параметры
date
: Дата / дата с временем, из которой нужно вычесть указанное количество месяцев. Дата/Date32/DateTime/DateTime64, Строка.num
: Количество месяцев, которые нужно вычесть. (U)Int*, Float*.
Возвращаемое значение
- Возвращает
date
минусnum
месяцев. Дата/Date32/DateTime/DateTime64.
Пример
subtractWeeks
Вычитает указанное количество недель из даты, даты с временем или строково-кодированной даты / даты с временем.
Синтаксис
Параметры
date
: Дата / дата с временем, из которой нужно вычесть указанное количество недель. Дата/Date32/DateTime/DateTime64, Строка.num
: Количество недель, которые нужно вычесть. (U)Int*, Float*.
Возвращаемое значение
- Возвращает
date
минусnum
недель. Дата/Date32/DateTime/DateTime64.
Пример
subtractDays
Вычитает указанное количество дней из даты, даты с временем или строково-кодированной даты / даты с временем.
Синтаксис
Параметры
date
: Дата / дата с временем, из которой нужно вычесть указанное количество дней. Дата/Date32/DateTime/DateTime64, Строка.num
: Количество дней, которые нужно вычесть. (U)Int*, Float*.
Возвращаемое значение
- Возвращает
date
минусnum
дней. Дата/Date32/DateTime/DateTime64.
Пример
subtractHours
Вычитает указанное количество часов из даты, даты с временем или строково-кодированной даты / даты с временем.
Синтаксис
Параметры
date
: Дата / дата с временем, из которой нужно вычесть указанное количество часов. Дата/Date32/Datetime/Datetime64, Строка.num
: Количество часов, которые нужно вычесть. (U)Int*, Float*.
Возвращаемое значение
- Возвращает
date
минусnum
часов. Дата/Date32/Datetime/Datetime64.
Пример
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.
Возвращаемое значение
Интервалы одного и того же типа будут объединены в один интервал. Например, если передать toIntervalDay(2)
и toIntervalDay(1)
, то результатом будет (1)
, а не (2,1)
.
Пример
Запрос:
Результат:
subtractTupleOfIntervals
Последовательно вычитает кортеж интервалов из даты или DateTime.
Синтаксис
Параметры
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, смотрите 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), см. 'Примечание 5' ниже | 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 с точностью 0. Предыдущее поведение можно восстановить, используя настройку 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
.
Примечание 5: В версиях ClickHouse, ранее v25.5, функция parseDateTime
требовала для форматировщика %e
, чтобы дни с одной цифрой дополнялись пробелом, например, 3
. В более поздних версиях дополнение пробелом является необязательным, например, 3
и 3
работают. Чтобы сохранить предыдущее поведение, установите настройку parsedatetime_e_requires_space_padding = 1
. Аналогично, форматировщик %e
в функции formatDateTime
ранее дополнительно заполнял пробелом единично напечатанные числа безусловно, в то время как теперь он выводит их без ведущего пробела. Чтобы сохранить предыдущее поведение, установите настройку formatdatetime_e_with_space_padding = 1
.
Пример
Результат:
Результат:
Кроме того, функция formatDateTime
может принимать третий строковый аргумент, содержащий название часового пояса. Пример: Asia/Istanbul
. В этом случае время форматируется согласно указанному часовому поясу.
Пример
См. также
formatDateTimeInJodaSyntax
Похожие на formatDateTime, за исключением того, что форматирует дату и время в стиле Joda вместо стиля MySQL. Смотрите https://joda-time.sourceforge.net/apidocs/org/joda/time/format/DateTimeFormat.html.
Обратной операцией этой функции является parseDateTimeInJodaSyntax.
Замена полей
Используя поля замены, вы можете определить шаблон для результирующей строки.
Заполнитель | Описание | Презентация | Примеры |
---|---|---|---|
G | эра | текст | AD |
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
— Дата или дата с временем. Дата, ДатаВремя или ДатаВремя64.
Возвращаемое значение
- Название месяца. Строка
Пример
Результат:
fromUnixTimestamp
Эта функция преобразует метку времени Unix в календарную дату и время дня.
Она может быть вызвана двумя способами:
Когда передан единственный аргумент типа Целое число, она возвращает значение типа ДатаВремя, т.е. ведет себя как toDateTime.
Псевдоним: FROM_UNIXTIME
.
Пример:
Результат:
Когда передано два или три аргумента, где первый аргумент — это значение типа Целое число, Дата, Дата32, ДатаВремя или ДатаВремя64, второй аргумент — это строка формата константы, а третий аргумент — это необязательная строка константы временной зоны, функция возвращает значение типа Строка, т.е. ведет себя как formatDateTime. В этом случае используется стиль формата даты MySQL.
Пример:
Результат:
См. также
fromUnixTimestampInJodaSyntax
То же самое, что и fromUnixTimestamp, но при вызове во втором варианте (два или три аргумента) форматирование выполняется с использованием стиля Joda вместо стиля MySQL.
Пример:
Результат:
toModifiedJulianDay
Преобразует дату в текстовом формате Пролептического григориевского календаря YYYY-MM-DD
в число Модифицированного юлианского дня в Int32. Эта функция поддерживает даты с 0000-01-01
по 9999-12-31
. Она вызывает исключение, если аргумент не может быть разобран как дата, или дата неверна.
Синтаксис
Аргументы
date
— Дата в текстовом формате. Строка или Фиксированная строка.
Возвращаемое значение
- Номер модифицированного юлианского дня. Int32.
Пример
Результат:
toModifiedJulianDayOrNull
Похож на toModifiedJulianDay(), но вместо того, чтобы вызывать исключения, он возвращает NULL
.
Синтаксис
Аргументы
date
— Дата в текстовом формате. Строка или Фиксированная строка.
Возвращаемое значение
- Номер модифицированного юлианского дня. Nullable(Int32).
Пример
Результат:
fromModifiedJulianDay
Преобразует номер Модифицированного юлианского дня в дату в текстовом формате Пролептического григориевского календаря YYYY-MM-DD
. Эта функция поддерживает номер дня с -678941
по 2973483
(что представляет собой 0000-01-01
и 9999-12-31
соответственно). Она вызывает исключение, если номер дня находится за пределами поддерживаемого диапазона.
Синтаксис
Аргументы
day
— Номер модифицированного юлианского дня. Любые целые типы.
Возвращаемое значение
- Дата в текстовом формате. Строка
Пример
Результат:
fromModifiedJulianDayOrNull
Похож на fromModifiedJulianDayOrNull(), но вместо того, чтобы вызывать исключения, он возвращает NULL
.
Синтаксис
Аргументы
day
— Номер модифицированного юлианского дня. Любые целые типы.
Возвращаемое значение
- Дата в текстовом формате. Nullable(Строка)
Пример
Результат:
toUTCTimestamp
Преобразует значение типа ДатаВремя/ДатаВремя64 из другой временной зоны в метку времени в UTC. Эта функция в основном включена для совместимости с Apache Spark и подобными фреймворками.
Синтаксис
Аргументы
time_val
— Константное значение типа ДатаВремя/ДатаВремя64 или выражение. Типы ДатаВремя/ДатаВремя64time_zone
— Константное значение типа Строка или выражение, представляющее временную зону. Типы строк
Возвращаемое значение
- ДатаВремя/ДатаВремя64 в текстовом формате
Пример
Результат:
fromUTCTimestamp
Преобразует значение типа ДатаВремя/ДатаВремя64 из временной зоны UTC в метку времени другой временной зоны. Эта функция в основном включена для совместимости с Apache Spark и подобными фреймворками.
Синтаксис
Аргументы
time_val
— Константное значение типа ДатаВремя/ДатаВремя64 или выражение. Типы ДатаВремя/ДатаВремя64time_zone
— Константное значение типа Строка или выражение, представляющее временную зону. Типы строк
Возвращаемое значение
- ДатаВремя/ДатаВремя64 в текстовом формате
Пример
Результат:
UTCTimestamp
Возвращает текущую дату и время на момент анализа запроса. Функция является константным выражением.
Эта функция дает такой же результат, что и now('UTC')
. Она была добавлена только для поддержки MySQL, а now
является предпочтительным использованием.
Синтаксис
Псевдоним: UTC_timestamp
.
Возвращаемое значение
- Возвращает текущую дату и время на момент анализа запроса. ДатаВремя.
Пример
Запрос:
Результат:
timeDiff
Возвращает разницу между двумя датами или датами с временными значениями. Разница вычисляется в секундах. Это то же самое, что и dateDiff
, и эта функция добавлена только для поддержки MySQL. Предпочтительным является dateDiff
.
Синтаксис
Аргументы
first_datetime
— Константное значение типа ДатаВремя/ДатаВремя64 или выражение. Типы ДатаВремя/ДатаВремя64second_datetime
— Константное значение типа ДатаВремя/ДатаВремя64 или выражение. Типы ДатаВремя/ДатаВремя64
Возвращаемое значение
Разница между двумя датами или датами с временными значениями в секундах.
Пример
Запрос:
Результат: