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

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

Пример

SELECT
    toDateTime('2016-06-15 23:00:00') AS time,
    toDate(time) AS date_local,
    toDate(time, 'Asia/Yekaterinburg') AS date_yekat,
    toString(time, 'US/Samoa') AS time_samoa

┌────────────────time─┬─date_local─┬─date_yekat─┬─time_samoa──────────┐
│ 2016-06-15 23:00:00 │ 2016-06-15 │ 2016-06-16 │ 2016-06-15 09:00:00 │
└─────────────────────┴────────────┴────────────┴─────────────────────┘

UTCTimestamp

Введена в: v22.11

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

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

Синтаксис

UTCTimestamp()

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

Аргументы

Отсутствуют.

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

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

Примеры

Получение текущей временной метки в UTC

SELECT UTCTimestamp()

┌──────UTCTimestamp()─┐
│ 2024-05-28 08:32:09 │
└─────────────────────┘

YYYYMMDDToDate

Добавлена в: v23.9

Преобразует число, содержащее год, месяц и день, в тип Date. Эта функция является противоположностью функции toYYYYMMDD(). Результат не определён, если на вход подано значение, не кодирующее корректную дату.

Синтаксис

YYYYMMDDToDate(YYYYMMDD)

Аргументы

YYYYMMDD — Числовое значение, содержащее год, месяц и день. (U)Int* или Float* или Decimal

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

Возвращает значение типа Date из переданного аргумента Date

Примеры

Пример

SELECT YYYYMMDDToDate(20230911);

┌─toYYYYMMDD(20230911)─┐
│           2023-09-11 │
└──────────────────────┘

YYYYMMDDToDate32

Появилась в версии v23.9

Преобразует число, содержащее год, месяц и день, в Date32. Эта функция является противоположностью функции toYYYYMMDD(). Результат не определён, если входное значение не кодирует допустимое значение Date32.

Синтаксис

YYYYMMDDToDate32(YYYYMMDD)

Аргументы

YYYYMMDD — число, задающее год, месяц и день. (U)Int* или Float* или Decimal

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

Возвращает значение типа Date32 на основе переданного аргумента Date32

Примеры

Пример

SELECT YYYYMMDDToDate32(20000507);

┌─YYYYMMDDToDate32(20000507)─┐
│                 2000-05-07 │
└────────────────────────────┘

YYYYMMDDhhmmssToDateTime

Введена в версии: v23.9

Преобразует число, содержащее год, месяц, день, час, минуту и секунду, в DateTime. Эта функция является противоположностью функции toYYYYMMDDhhmmss(). Результат не определён, если входное значение не представляет допустимое значение DateTime.

Синтаксис

YYYYMMDDhhmmssToDateTime(YYYYMMDDhhmmss[, timezone])

Аргументы

YYYYMMDDhhmmss — число, содержащее год, месяц, день, час, минуту и секунду. (U)Int* или Float* или Decimal
timezone — название часового пояса. String

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

Возвращает значение типа DateTime на основе переданных аргументов. DateTime

Примеры

Пример

SELECT YYYYMMDDToDateTime(20230911131415);

┌──────YYYYMMDDhhmmssToDateTime(20230911131415)─┐
│                           2023-09-11 13:14:15 │
└───────────────────────────────────────────────┘

YYYYMMDDhhmmssToDateTime64

Появилась в: v23.9

Преобразует число, содержащее год, месяц, день, час, минуту и секунду, в DateTime64. Эта функция является противоположностью функции toYYYYMMDDhhmmss(). Результат не определён, если входное значение не представляет корректное значение DateTime64.

Синтаксис

YYYYMMDDhhmmssToDateTime64(YYYYMMDDhhmmss[, precision[, timezone]])

Аргументы

YYYYMMDDhhmmss — число, содержащее год, месяц, день, час, минуту и секунду. (U)Int* или Float* или Decimal
precision — точность дробной части (0–9). UInt8
timezone — название часового пояса. String

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

Возвращает значение типа DateTime64 на основе указанных аргументов.

Примеры

Пример

SELECT YYYYMMDDhhmmssToDateTime64(20230911131415, 3, 'Asia/Istanbul');

┌─YYYYMMDDhhmm⋯/Istanbul')─┐
│  2023-09-11 13:14:15.000 │
└──────────────────────────┘

addDate

Добавлено в версии: v23.9

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

Синтаксис

addDate(datetime, interval)

Аргументы

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

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

Возвращает дату или дату со временем, полученную при добавлении interval к datetime. Date или Date32 или DateTime или DateTime64

Примеры

Добавление интервала к дате

SELECT addDate(toDate('2018-01-01'), INTERVAL 3 YEAR)

┌─addDate(toDa⋯valYear(3))─┐
│               2021-01-01 │
└──────────────────────────┘

addDays

Появилась в версии: v1.1

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

Синтаксис

addDays(datetime, num)

Аргументы

datetime — дата или дата и время, к которой нужно добавить указанное количество дней. Date или Date32 или DateTime или DateTime64 или String
num — количество добавляемых дней. (U)Int* или Float*

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

Возвращает значение datetime, увеличенное на num дней. Date или Date32 или DateTime или DateTime64

Примеры

Добавление дней к различным типам дат

WITH
    toDate('2024-01-01') AS date,
    toDateTime('2024-01-01 00:00:00') AS date_time,
    '2024-01-01 00:00:00' AS date_time_string
SELECT
    addDays(date, 5) AS add_days_with_date,
    addDays(date_time, 5) AS add_days_with_date_time,
    addDays(date_time_string, 5) AS add_days_with_date_time_string

┌─add_days_with_date─┬─add_days_with_date_time─┬─add_days_with_date_time_string─┐
│         2024-01-06 │     2024-01-06 00:00:00 │        2024-01-06 00:00:00.000 │
└────────────────────┴─────────────────────────┴────────────────────────────────┘

Использование альтернативного синтаксиса INTERVAL

SELECT dateAdd('1998-06-16'::Date, INTERVAL 10 day)

┌─plus(CAST('1⋯valDay(10))─┐
│               1998-06-26 │
└──────────────────────────┘

addHours

Введена в версии: v1.1

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

Синтаксис

addHours(datetime, num)

Аргументы

datetime — дата или дата со временем, к которой нужно прибавить указанное количество часов. Date или Date32 или DateTime или DateTime64 или String
num — количество часов, которое нужно прибавить. (U)Int* или Float*

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

Возвращает datetime плюс num часов, результат имеет тип DateTime или DateTime64(3)

Примеры

Добавление часов к разным типам дат

WITH
    toDate('2024-01-01') AS date,
    toDateTime('2024-01-01 00:00:00') AS date_time,
    '2024-01-01 00:00:00' AS date_time_string
SELECT
    addHours(date, 12) AS add_hours_with_date,
    addHours(date_time, 12) AS add_hours_with_date_time,
    addHours(date_time_string, 12) AS add_hours_with_date_time_string

┌─add_hours_with_date─┬─add_hours_with_date_time─┬─add_hours_with_date_time_string─┐
│ 2024-01-01 12:00:00 │      2024-01-01 12:00:00 │         2024-01-01 12:00:00.000 │
└─────────────────────┴──────────────────────────┴─────────────────────────────────┘

Использование альтернативного синтаксиса INTERVAL

SELECT dateAdd('1998-06-16'::Date, INTERVAL 10 hour)

┌─plus(CAST('1⋯alHour(10))─┐
│      1998-06-16 10:00:00 │
└──────────────────────────┘

addInterval

Добавлена в версии: v22.11

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

Примечание

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

Синтаксис

addInterval(interval_1, interval_2)

Аргументы

interval_1 — первый интервал или кортеж интервалов. Interval или Tuple(Interval)
interval_2 — второй интервал, который добавляется. Interval

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

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

Примеры

Сложение интервалов

SELECT addInterval(INTERVAL 1 DAY, INTERVAL 1 MONTH);
SELECT addInterval((INTERVAL 1 DAY, INTERVAL 1 YEAR), INTERVAL 1 MONTH);
SELECT addInterval(INTERVAL 2 DAY, INTERVAL 1 DAY)

┌─addInterval(toIntervalDay(1), toIntervalMonth(1))─┐
│ (1,1)                                             │
└───────────────────────────────────────────────────┘
┌─addInterval((toIntervalDay(1), toIntervalYear(1)), toIntervalMonth(1))─┐
│ (1,1,1)                                                                │
└────────────────────────────────────────────────────────────────────────┘
┌─addInterval(toIntervalDay(2), toIntervalDay(1))─┐
│ (3)                                             │
└─────────────────────────────────────────────────┘

addMicroseconds

Добавлена в версии: v22.6

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

Синтаксис

addMicroseconds(datetime, num)

Аргументы

datetime — Дата и время, к которым нужно прибавить заданное количество микросекунд. DateTime или DateTime64 или String
num — Количество микросекунд, которое нужно добавить. (U)Int* или Float*

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

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

Примеры

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

WITH
    toDateTime('2024-01-01 00:00:00') AS date_time,
    '2024-01-01 00:00:00' AS date_time_string
SELECT
    addMicroseconds(date_time, 1000000) AS add_microseconds_with_date_time,
    addMicroseconds(date_time_string, 1000000) AS add_microseconds_with_date_time_string

┌─add_microseconds_with_date_time─┬─add_microseconds_with_date_time_string─┐
│      2024-01-01 00:00:01.000000 │             2024-01-01 00:00:01.000000 │
└─────────────────────────────────┴────────────────────────────────────────┘

Использование альтернативного синтаксиса INTERVAL

SELECT dateAdd('1998-06-16'::DateTime, INTERVAL 10 microsecond)

┌─plus(CAST('19⋯osecond(10))─┐
│ 1998-06-16 00:00:00.000010 │
└────────────────────────────┘

addMilliseconds

Добавлена в версии: v22.6

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

Синтаксис

addMilliseconds(datetime, num)

Аргументы

datetime — дата и время, к которым нужно добавить указанное количество миллисекунд. DateTime или DateTime64 или String
num — количество миллисекунд, которое нужно добавить. (U)Int* или Float*

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

Возвращает datetime, увеличенное на num миллисекунд. Тип результата — DateTime64

Примеры

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

WITH
    toDateTime('2024-01-01 00:00:00') AS date_time,
    '2024-01-01 00:00:00' AS date_time_string
SELECT
    addMilliseconds(date_time, 1000) AS add_milliseconds_with_date_time,
    addMilliseconds(date_time_string, 1000) AS add_milliseconds_with_date_time_string

┌─add_milliseconds_with_date_time─┬─add_milliseconds_with_date_time_string─┐
│         2024-01-01 00:00:01.000 │                2024-01-01 00:00:01.000 │
└─────────────────────────────────┴────────────────────────────────────────┘

Использование альтернативного синтаксиса для INTERVAL

SELECT dateAdd('1998-06-16'::DateTime, INTERVAL 10 millisecond)

┌─plus(CAST('1⋯second(10))─┐
│  1998-06-16 00:00:00.010 │
└──────────────────────────┘

addMinutes

Добавлена в версии: v1.1

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

Синтаксис

addMinutes(datetime, num)

Аргументы

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

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

Возвращает datetime, увеличенное на num минут, типа DateTime или DateTime64(3)

Примеры

Добавление минут к различным типам дат

WITH
    toDate('2024-01-01') AS date,
    toDateTime('2024-01-01 00:00:00') AS date_time,
    '2024-01-01 00:00:00' AS date_time_string
SELECT
    addMinutes(date, 20) AS add_minutes_with_date,
    addMinutes(date_time, 20) AS add_minutes_with_date_time,
    addMinutes(date_time_string, 20) AS add_minutes_with_date_time_string

┌─add_minutes_with_date─┬─add_minutes_with_date_time─┬─add_minutes_with_date_time_string─┐
│   2024-01-01 00:20:00 │        2024-01-01 00:20:00 │           2024-01-01 00:20:00.000 │
└───────────────────────┴────────────────────────────┴───────────────────────────────────┘

Использование альтернативного синтаксиса для INTERVAL

SELECT dateAdd('1998-06-16'::Date, INTERVAL 10 minute)

┌─plus(CAST('1⋯Minute(10))─┐
│      1998-06-16 00:10:00 │
└──────────────────────────┘

addMonths

Добавлена в версии: v1.1

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

Синтаксис

addMonths(datetime, num)

Аргументы

datetime — дата или дата со временем, к которой нужно прибавить указанное число месяцев. Date или Date32 или DateTime или DateTime64 или String
num — число месяцев, которое нужно прибавить. (U)Int* или Float*

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

Возвращает значение datetime, увеличенное на num месяцев, типа Date или Date32 или DateTime или DateTime64

Примеры

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

WITH
    toDate('2024-01-01') AS date,
    toDateTime('2024-01-01 00:00:00') AS date_time,
    '2024-01-01 00:00:00' AS date_time_string
SELECT
    addMonths(date, 6) AS add_months_with_date,
    addMonths(date_time, 6) AS add_months_with_date_time,
    addMonths(date_time_string, 6) AS add_months_with_date_time_string

┌─add_months_with_date─┬─add_months_with_date_time─┬─add_months_with_date_time_string─┐
│           2024-07-01 │       2024-07-01 00:00:00 │          2024-07-01 00:00:00.000 │
└──────────────────────┴───────────────────────────┴──────────────────────────────────┘

Использование альтернативного синтаксиса INTERVAL

SELECT dateAdd('1998-06-16'::Date, INTERVAL 10 month)

┌─plus(CAST('1⋯lMonth(10))─┐
│               1999-04-16 │
└──────────────────────────┘

addNanoseconds

Добавлена в: v22.6

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

Синтаксис

addNanoseconds(datetime, num)

Аргументы

datetime — дата и время, к которым нужно добавить указанное количество наносекунд. DateTime или DateTime64 или String
num — количество наносекунд, которое нужно добавить. (U)Int* или Float*

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

Возвращает datetime, увеличенное на num наносекунд. Тип результата — DateTime64

Примеры

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

WITH
    toDateTime('2024-01-01 00:00:00') AS date_time,
    '2024-01-01 00:00:00' AS date_time_string
SELECT
    addNanoseconds(date_time, 1000) AS add_nanoseconds_with_date_time,
    addNanoseconds(date_time_string, 1000) AS add_nanoseconds_with_date_time_string

┌─add_nanoseconds_with_date_time─┬─add_nanoseconds_with_date_time_string─┐
│  2024-01-01 00:00:00.000001000 │         2024-01-01 00:00:00.000001000 │
└────────────────────────────────┴───────────────────────────────────────┘

Использование альтернативного синтаксиса INTERVAL

SELECT dateAdd('1998-06-16'::DateTime, INTERVAL 1000 nanosecond)

┌─plus(CAST('199⋯osecond(1000))─┐
│ 1998-06-16 00:00:00.000001000 │
└───────────────────────────────┘

addQuarters

Была добавлена в версии: v20.1

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

Синтаксис

addQuarters(datetime, num)

Аргументы

datetime — дата или дата со временем, к которой нужно прибавить заданное количество кварталов. Date или Date32 или DateTime или DateTime64 или String
num — количество кварталов, которое нужно прибавить. (U)Int* или Float*

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

Возвращает значение datetime, увеличенное на num кварталов, типа Date или Date32 или DateTime или DateTime64.

Примеры

Добавление кварталов к различным типам дат

WITH
    toDate('2024-01-01') AS date,
    toDateTime('2024-01-01 00:00:00') AS date_time,
    '2024-01-01 00:00:00' AS date_time_string
SELECT
    addQuarters(date, 1) AS add_quarters_with_date,
    addQuarters(date_time, 1) AS add_quarters_with_date_time,
    addQuarters(date_time_string, 1) AS add_quarters_with_date_time_string

┌─add_quarters_with_date─┬─add_quarters_with_date_time─┬─add_quarters_with_date_time_string─┐
│             2024-04-01 │         2024-04-01 00:00:00 │            2024-04-01 00:00:00.000 │
└────────────────────────┴─────────────────────────────┴────────────────────────────────────┘

Использование альтернативного синтаксиса INTERVAL

SELECT dateAdd('1998-06-16'::Date, INTERVAL 10 quarter)

┌─plus(CAST('1⋯uarter(10))─┐
│               2000-12-16 │
└──────────────────────────┘

addSeconds

Добавлена в: v1.1

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

Синтаксис

addSeconds(datetime, num)

Аргументы

datetime — дата или дата со временем, к которой нужно добавить указанное количество секунд. Date, Date32, DateTime, DateTime64 или String
num — количество секунд, которое нужно добавить. (U)Int* или Float*

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

Возвращает значение datetime, увеличенное на num секунд, типа DateTime или DateTime64(3)

Примеры

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

WITH
    toDate('2024-01-01') AS date,
    toDateTime('2024-01-01 00:00:00') AS date_time,
    '2024-01-01 00:00:00' AS date_time_string
SELECT
    addSeconds(date, 30) AS add_seconds_with_date,
    addSeconds(date_time, 30) AS add_seconds_with_date_time,
    addSeconds(date_time_string, 30) AS add_seconds_with_date_time_string

┌─add_seconds_with_date─┬─add_seconds_with_date_time─┬─add_seconds_with_date_time_string─┐
│   2024-01-01 00:00:30 │        2024-01-01 00:00:30 │           2024-01-01 00:00:30.000 │
└───────────────────────┴────────────────────────────┴───────────────────────────────────┘

Использование альтернативного синтаксиса INTERVAL

SELECT dateAdd('1998-06-16'::Date, INTERVAL 10 second)

┌─dateAdd('1998-06-16'::Date, INTERVAL 10 second)─┐
│                             1998-06-16 00:00:10 │
└─────────────────────────────────────────────────┘

addTupleOfIntervals

Введена в версии: v22.11

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

Синтаксис

addTupleOfIntervals(datetime, intervals)

Аргументы

datetime — дата или дата со временем, к которой добавляются интервалы. Date или Date32 или DateTime или DateTime64
intervals — кортеж интервалов, которые добавляются к datetime. Tuple(Interval)

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

Возвращает date с добавленными intervals — Date или Date32 или DateTime или DateTime64

Примеры

Добавление кортежа интервалов к дате

WITH toDate('2018-01-01') AS date
SELECT addTupleOfIntervals(date, (INTERVAL 1 DAY, INTERVAL 1 MONTH, INTERVAL 1 YEAR))

┌─addTupleOfIntervals(date, (toIntervalDay(1), toIntervalMonth(1), toIntervalYear(1)))─┐
│                                                                           2019-02-02 │
└──────────────────────────────────────────────────────────────────────────────────────┘

addWeeks

Добавлена в версии v1.1

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

Синтаксис

addWeeks(datetime, num)

Аргументы

datetime — дата или дата со временем, к которой нужно добавить указанное количество недель. Date или Date32 или DateTime или DateTime64 или String
num — количество недель для добавления. (U)Int* или Float*

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

Возвращает значение datetime, увеличенное на num недель. Date или Date32 или DateTime или DateTime64

Примеры

Добавление недель к различным типам дат

WITH
    toDate('2024-01-01') AS date,
    toDateTime('2024-01-01 00:00:00') AS date_time,
    '2024-01-01 00:00:00' AS date_time_string
SELECT
    addWeeks(date, 5) AS add_weeks_with_date,
    addWeeks(date_time, 5) AS add_weeks_with_date_time,
    addWeeks(date_time_string, 5) AS add_weeks_with_date_time_string

┌─add_weeks_with_date─┬─add_weeks_with_date_time─┬─add_weeks_with_date_time_string─┐
│          2024-02-05 │      2024-02-05 00:00:00 │         2024-02-05 00:00:00.000 │
└─────────────────────┴──────────────────────────┴─────────────────────────────────┘

Использование альтернативного синтаксиса INTERVAL

SELECT dateAdd('1998-06-16'::Date, INTERVAL 10 week)

┌─plus(CAST('1⋯alWeek(10))─┐
│               1998-08-25 │
└──────────────────────────┘

addYears

Добавлена в версии v1.1

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

Синтаксис

addYears(datetime, num)

Аргументы

datetime — дата или дата со временем, к которой нужно прибавить указанное количество лет. Date или Date32 или DateTime или DateTime64 или String
num — количество лет, которое нужно добавить. (U)Int* или Float*

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

Возвращает значение datetime, увеличенное на num лет, типа Date или Date32 или DateTime или DateTime64

Примеры

Добавление лет к различным типам дат

WITH
    toDate('2024-01-01') AS date,
    toDateTime('2024-01-01 00:00:00') AS date_time,
    '2024-01-01 00:00:00' AS date_time_string
SELECT
    addYears(date, 1) AS add_years_with_date,
    addYears(date_time, 1) AS add_years_with_date_time,
    addYears(date_time_string, 1) AS add_years_with_date_time_string

┌─add_years_with_date─┬─add_years_with_date_time─┬─add_years_with_date_time_string─┐
│          2025-01-01 │      2025-01-01 00:00:00 │         2025-01-01 00:00:00.000 │
└─────────────────────┴──────────────────────────┴─────────────────────────────────┘

Использование альтернативного синтаксиса INTERVAL

SELECT dateAdd('1998-06-16'::Date, INTERVAL 10 year)

┌─plus(CAST('1⋯alYear(10))─┐
│               2008-06-16 │
└──────────────────────────┘

age

Введена в версии v23.1

Возвращает компонент разности между startdate и enddate в соответствующей единице измерения. Разность вычисляется с точностью до 1 наносекунды.

Например, разность между 2021-12-29 и 2022-01-01 составляет 3 дня для единицы «день», 0 месяцев для единицы «месяц» и 0 лет для единицы «год».

В качестве альтернативы age смотрите функцию dateDiff.

Синтаксис

age('unit', startdate, enddate[, timezone])

Аргументы

unit — Тип единицы измерения результата.

Unit	Possible values
nanosecond	`nanosecond`, `nanoseconds`, `ns`
microsecond	`microsecond`, `microseconds`, `us`, `u`
millisecond	`millisecond`, `milliseconds`, `ms`
second	`second`, `seconds`, `ss`, `s`
minute	`minute`, `minutes`, `mi`, `n`
hour	`hour`, `hours`, `hh`, `h`
day	`day`, `days`, `dd`, `d`
week	`week`, `weeks`, `wk`, `ww`
month	`month`, `months`, `mm`, `m`
quarter	`quarter`, `quarters`, `qq`, `q`
year	`year`, `years`, `yyyy`, `yy`

startdate — Первое значение времени, которое вычитается (вычитаемое). Date или Date32 или DateTime или DateTime64
enddate — Второе значение времени, из которого производится вычитание (уменьшаемое). Date или Date32 или DateTime или DateTime64
timezone — Необязательный параметр. Название часового пояса. Если задан, он применяется как к startdate, так и к enddate. Если не задан, используются часовые пояса startdate и enddate. Если они различаются, результат не определён. String

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

Возвращает разницу между enddate и startdate, выраженную в unit. Int32

Примеры

Вычисление возраста в часах

SELECT age('hour', toDateTime('2018-01-01 22:30:00'), toDateTime('2018-01-02 23:00:00'))

┌─age('hour', toDateTime('2018-01-01 22:30:00'), toDateTime('2018-01-02 23:00:00'))─┐
│                                                                                24 │
└───────────────────────────────────────────────────────────────────────────────────┘

Рассчитать возраст в разных единицах

SELECT
    toDate('2022-01-01') AS e,
    toDate('2021-12-29') AS s,
    age('day', s, e) AS day_age,
    age('month', s, e) AS month_age,
    age('year', s, e) AS year_age

┌──────────e─┬──────────s─┬─day_age─┬─month_age─┬─year_age─┐
│ 2022-01-01 │ 2021-12-29 │       3 │         0 │        0 │
└────────────┴────────────┴─────────┴───────────┴──────────┘

changeDay

Введена в версии v24.7

Изменяет компонент дня в значении типа Date или DateTime.

Синтаксис

changeDay(date_or_datetime, value)

Аргументы

date_or_datetime — значение, которое нужно изменить. Date или Date32 или DateTime или DateTime64
value — новое значение. (U)Int*

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

Возвращает значение того же типа, что и date_or_datetime, с изменённым компонентом дня. Date или Date32 или DateTime или DateTime64

Примеры

Пример использования

SELECT changeDay('2024-01-31'::DateTime, 15)

2024-01-15 00:00:00

changeHour

Впервые появилась в версии v24.7

Изменяет часовую часть значения типа Date или DateTime.

Синтаксис

changeHour(date_or_datetime, value)

Аргументы

date_or_datetime — Значение для изменения. Date или Date32 или DateTime или DateTime64
value — Новое значение. (U)Int*

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

Возвращает значение того же типа, что и date_or_datetime, но с изменённым значением часа. DateTime или DateTime64

Примеры

Пример использования

SELECT changeHour('2024-01-01 12:00:00'::DateTime, 5)

2024-01-01 05:00:00

changeMinute

Добавлена в версии: v24.7

Изменяет компонент минуты у значения типа date или date time.

Синтаксис

changeMinute(date_or_datetime, value)

Аргументы

date_or_datetime — значение, которое нужно изменить. Date или Date32 или DateTime или DateTime64
value — новое значение. (U)Int*

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

Возвращает значение того же типа, что и date_or_datetime, с изменённой минутной компонентой. DateTime или DateTime64

Примеры

Пример использования

SELECT changeMinute('2024-01-01 12:30:00'::DateTime, 45)

2024-01-01 12:45:00

changeMonth

Добавлена в версии v24.7

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

Синтаксис

changeMonth(date_or_datetime, value)

Аргументы

date_or_datetime — значение, которое нужно изменить. Date или Date32 или DateTime или DateTime64
value — новое значение. (U)Int*

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

Возвращает значение того же типа, что и date_or_datetime, с изменённым компонентом месяца. Date или Date32 или DateTime или DateTime64

Примеры

Пример использования

SELECT changeMonth('2024-01-01'::DateTime, 12)

2024-12-01 00:00:00

changeSecond

Добавлена в: v24.7

Изменяет секундную часть даты или даты-времени.

Синтаксис

changeSecond(date_or_datetime, value)

Аргументы

date_or_datetime — значение, которое нужно изменить. Date или Date32 или DateTime или DateTime64
value — новое значение. (U)Int*

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

Возвращает значение того же типа, что и date_or_datetime, с изменённой компонентой секунд. DateTime или DateTime64

Примеры

Пример использования

SELECT changeSecond('2024-01-01 12:30:45'::DateTime, 15)

2024-01-01 12:30:15

changeYear

Добавлена в версии: v24.7

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

Синтаксис

changeYear(date_or_datetime, value)

Аргументы

date_or_datetime — значение для изменения. Date или Date32 или DateTime или DateTime64
value — новое значение. (U)Int*

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

Возвращает значение того же типа, что и date_or_datetime, с изменённым компонентом года. Date или Date32 или DateTime или DateTime64

Примеры

Пример использования

SELECT changeYear('2024-01-01'::DateTime, 2023)

2023-01-01 00:00:00

dateDiff

Введена в: v23.4

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

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

В качестве альтернативы dateDiff см. функцию age.

Синтаксис

dateDiff(unit, startdate, enddate[, timezone])

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

Аргументы

unit — Тип интервала для результата.

Единица	Допустимые значения
nanosecond	`nanosecond`, `nanoseconds`, `ns`
microsecond	`microsecond`, `microseconds`, `us`, `u`
millisecond	`millisecond`, `milliseconds`, `ms`
second	`second`, `seconds`, `ss`, `s`
minute	`minute`, `minutes`, `mi`, `n`
hour	`hour`, `hours`, `hh`, `h`
day	`day`, `days`, `dd`, `d`
week	`week`, `weeks`, `wk`, `ww`
month	`month`, `months`, `mm`, `m`
quarter	`quarter`, `quarters`, `qq`, `q`
year	`year`, `years`, `yyyy`, `yy`

startdate — Первое значение времени (вычитаемое). Date или Date32 или DateTime или DateTime64
enddate — Второе значение времени, из которого выполняется вычитание (уменьшаемое). Date или Date32 или DateTime или DateTime64
timezone — Необязательный параметр. Название часового пояса. Если указано, применяется к startdate и enddate. Если не указано, используются часовые пояса startdate и enddate. Если они не совпадают, результат не определён. String

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

Возвращает разницу между enddate и startdate, выраженную в unit. Int64

Примеры

Вычисление разницы между датами в часах

SELECT dateDiff('hour', toDateTime('2018-01-01 22:00:00'), toDateTime('2018-01-02 23:00:00')) AS res

┌─res─┐
│  25 │
└─────┘

Вычисление разницы между датами в разных единицах измерения

SELECT
    toDate('2022-01-01') AS e,
    toDate('2021-12-29') AS s,
    dateDiff('day', s, e) AS day_diff,
    dateDiff('month', s, e) AS month_diff,
    dateDiff('year', s, e) AS year_diff

┌──────────e─┬──────────s─┬─day_diff─┬─month_diff─┬─year_diff─┐
│ 2022-01-01 │ 2021-12-29 │        3 │          1 │         1 │
└────────────┴────────────┴──────────┴────────────┴───────────┘

dateName

Появилась в версии: v21.7

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

Возможные значения:

'year'
'quarter'
'month'
'week'
'dayofyear'
'day'
'weekday'
'hour'
'minute'
'second'

Синтаксис

dateName(date_part, date[, timezone])

Аргументы

date_part — часть даты, которую нужно извлечь. String
datetime — значение даты или даты со временем. Date или Date32 или DateTime или DateTime64
timezone — необязательный. Часовой пояс. String

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

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

Примеры

Извлечение различных частей даты

WITH toDateTime('2021-04-14 11:22:33') AS date_value
SELECT
    dateName('year', date_value),
    dateName('month', date_value),
    dateName('day', date_value)

┌─dateName('year', date_value)─┬─dateName('month', date_value)─┬─dateName('day', date_value)─┐
│ 2021                         │ April                         │ 14                          │
└──────────────────────────────┴───────────────────────────────┴─────────────────────────────┘

dateTrunc

Добавлена в версии: v20.8

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

Синтаксис

dateTrunc(unit, datetime[, timezone])

Псевдонимы: DATE_TRUNC

Аргументы

unit — Тип интервала, до которого будет усечён результат. Аргумент unit нечувствителен к регистру.

Unit	Совместимость
`nanosecond`	Совместим только с DateTime64
`microsecond`	Совместим только с DateTime64
`millisecond`	Совместим только с DateTime64
`second`
`minute`
`hour`
`day`
`week`
`month`
`quarter`
`year`
`String`

datetime — Дата и время. Date или Date32 или DateTime или DateTime64
timezone — Необязательный параметр. Имя часового пояса для возвращаемого значения datetime. Если не указано, функция использует часовой пояс параметра datetime. String

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

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

Аргумент Unit	Аргумент `datetime`	Возвращаемый тип
Year, Quarter, Month, Week	`Date32` или `DateTime64` или `Date` или `DateTime`	`Date32` или `Date`
Day, Hour, Minute, Second	`Date32`, `DateTime64`, `Date` или `DateTime`	`DateTime64` или `DateTime`
Millisecond, Microsecond,	Любой	`DateTime64`
Nanosecond		с масштабом 3, 6 или 9

Примеры

Усечение без указания часового пояса

SELECT now(), dateTrunc('hour', now());

┌───────────────now()─┬─dateTrunc('hour', now())──┐
│ 2020-09-28 10:40:45 │       2020-09-28 10:00:00 │
└─────────────────────┴───────────────────────────┘

Усечение с указанным часовым поясом

SELECT now(), dateTrunc('hour', now(), 'Asia/Istanbul');

┌───────────────now()─┬─dateTrunc('hour', now(), 'Asia/Istanbul')──┐
│ 2020-09-28 10:46:26 │                        2020-09-28 13:00:00 │
└─────────────────────┴────────────────────────────────────────────┘

formatDateTime

Введена в версии v1.1

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

formatDateTime использует стиль формата datetime MySQL, см. документацию MySQL.

Обратной операцией для этой функции является parseDateTime.

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

Подстановочные поля:

Placeholder	Описание	Пример
%a	сокращённое название дня недели (Mon-Sun)	Mon
%b	сокращённое название месяца (Jan-Dec)	Jan
%c	месяц в виде целого числа (01-12)	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	дробная часть секунды	123456
%F	короткий формат даты YYYY-MM-DD, эквивалентен %Y-%m-%d	2018-01-02
%g	двухзначный формат года, выровненный по ISO 8601	18
%G	четырёхзначный формат года для номера недели ISO	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)	14
%l	час в 12-часовом формате (01-12)	09
%m	месяц в виде целого числа (01-12)	01
%M	полное название месяца (January-December)	January
%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	полное название дня недели (Monday-Sunday)	Monday
%y	год, две последние цифры (00-99)	18
%Y	год	2018
%z	смещение времени от UTC в формате +HHMM или -HHMM	-0500
%%	знак %	%

В версиях ClickHouse ранее v23.4 %f выводит один ноль (0), если форматируемое значение имеет тип Date, Date32 или DateTime (у которых нет дробных секунд), или DateTime64 с точностью 0.
В версиях ClickHouse ранее v25.1 %f выводит столько цифр, сколько задано масштабом DateTime64, вместо фиксированных 6 цифр.
В версиях ClickHouse ранее v23.4 %M выводит минуту (00-59) вместо полного названия месяца (January-December).

Синтаксис

formatDateTime(datetime, format[, timezone])

Синонимы: DATE_FORMAT

Аргументы

datetime — Дата или дата и время для форматирования. Date или Date32 или DateTime или DateTime64
format — Строка формата со строками подстановки. String
timezone — Необязательный параметр. Название часового пояса для форматируемого времени. String

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

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

Примеры

Форматирование даты со спецификатором года

SELECT formatDateTime(toDate('2010-01-04'), '%g')

┌─formatDateTime(toDate('2010-01-04'), '%g')─┐
│ 10                                         │
└────────────────────────────────────────────┘

Форматирование DateTime64 с дробной частью секунды

SELECT formatDateTime(toDateTime64('2010-01-04 12:34:56.123456', 7), '%f')

┌─formatDateTime(toDateTime64('2010-01-04 12:34:56.123456', 7), '%f')─┐
│ 1234560                                                             │
└─────────────────────────────────────────────────────────────────────┘

Формат с часовым поясом

SELECT
    now() AS ts,
    time_zone,
    formatDateTime(ts, '%T', time_zone) AS str_tz_time
FROM system.time_zones
WHERE time_zone LIKE 'Europe%'
LIMIT 10

┌──────────────────ts─┬─time_zone─────────┬─str_tz_time─┐
│ 2023-09-08 19:13:40 │ Europe/Amsterdam  │ 21:13:40    │
│ 2023-09-08 19:13:40 │ Europe/Andorra    │ 21:13:40    │
│ 2023-09-08 19:13:40 │ Europe/Astrakhan  │ 23:13:40    │
│ 2023-09-08 19:13:40 │ Europe/Athens     │ 22:13:40    │
│ 2023-09-08 19:13:40 │ Europe/Belfast    │ 20:13:40    │
│ 2023-09-08 19:13:40 │ Europe/Belgrade   │ 21:13:40    │
│ 2023-09-08 19:13:40 │ Europe/Berlin     │ 21:13:40    │
│ 2023-09-08 19:13:40 │ Europe/Bratislava │ 21:13:40    │
│ 2023-09-08 19:13:40 │ Europe/Brussels   │ 21:13:40    │
│ 2023-09-08 19:13:40 │ Europe/Bucharest  │ 22:13:40    │
└─────────────────────┴───────────────────┴─────────────┘

formatDateTimeInJodaSyntax

Введена в версии v20.1

Аналогична formatDateTime, за исключением того, что форматирует дату и время в стиле Joda вместо стиля MySQL. См. документацию Joda Time.

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

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

Поля подстановки:

Placeholder	Описание	Представление	Примеры
G	эра	текст	AD
C	столетие эпохи (>=0)	число	20
Y	год эпохи (>=0)	год	1996
x	год для недельного счёта (пока не поддерживается)	год	1996
w	неделя в году по недельному счёту (пока не поддерживается)	число	27
e	день недели	число	2
E	день недели	текст	Tuesday; Tue
y	год	год	1996
D	день года	число	189
M	месяц года	месяц	July; Jul; 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	часовой пояс	текст	Eastern Standard Time; EST
Z	смещение часового пояса	зона	-0800; -0812
'	экранирование текста	разделитель
''	одинарная кавычка	литерал	'

Синтаксис

formatDateTimeInJodaSyntax(datetime, format[, timezone])

Аргументы

datetime — дата или дата-время для форматирования. DateTime или Date или Date32 или DateTime64
format — строка формата с полями подстановки в стиле Joda. String
timezone — необязательный параметр. Название часового пояса, используемого при форматировании времени. String

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

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

Примеры

Форматирование datetime с использованием синтаксиса Joda

SELECT formatDateTimeInJodaSyntax(toDateTime('2010-01-04 12:34:56'), 'yyyy-MM-dd HH:mm:ss')

┌─formatDateTimeInJodaSyntax(toDateTime('2010-01-04 12:34:56'), 'yyyy-MM-dd HH:mm:ss')─┐
│ 2010-01-04 12:34:56                                                                     │
└─────────────────────────────────────────────────────────────────────────────────────────┘

fromDaysSinceYearZero

Добавлена в: v23.11

Вычисление выполняется так же, как в функции MySQL FROM_DAYS(). Результат не определён, если его невозможно представить в пределах типа Date.

Синтаксис

fromDaysSinceYearZero(days)

Псевдонимы: FROM_DAYS

Аргументы

days — количество дней, прошедших с нулевого года. UInt32

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

Возвращает дату, соответствующую количеству дней, прошедших с нулевого года. Date

Примеры

Преобразование количества дней с нулевого года в даты

SELECT
fromDaysSinceYearZero(739136) AS date1,
fromDaysSinceYearZero(toDaysSinceYearZero(toDate('2023-09-08'))) AS date2

┌──────date1─┬──────date2─┐
│ 2023-09-08 │ 2023-09-08 │
└────────────┴────────────┘

fromDaysSinceYearZero32

Появилась в версии: v23.11

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

Синтаксис

fromDaysSinceYearZero32(days)

Аргументы

days — количество дней, прошедших с нулевого года. UInt32

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

Возвращает дату, соответствующую количеству дней, прошедших с нулевого года. Date32

Примеры

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

SELECT
fromDaysSinceYearZero32(739136) AS date1,
fromDaysSinceYearZero32(toDaysSinceYearZero(toDate('2023-09-08'))) AS date2

┌──────date1─┬──────date2─┐
│ 2023-09-08 │ 2023-09-08 │
└────────────┴────────────┘

fromModifiedJulianDay

Впервые представлена в: v21.1

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

Синтаксис

fromModifiedJulianDay(day)

Аргументы

day — номер модифицированного юлианского дня. (U)Int*

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

Возвращает дату в текстовом формате. String

Примеры

Преобразование модифицированного юлианского дня в дату

SELECT fromModifiedJulianDay(58849)

┌─fromModifiedJulianDay(58849)─┐
│ 2020-01-01                   │
└──────────────────────────────┘

fromModifiedJulianDayOrNull

Добавлена в: v21.1

Аналогична fromModifiedJulianDay(), но вместо выброса исключений возвращает NULL.

Синтаксис

fromModifiedJulianDayOrNull(day)

Аргументы

day — номер модифицированного юлианского дня (Modified Julian Day). (U)Int*

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

Возвращает дату в текстовом формате для допустимого аргумента day, в противном случае — null. Nullable(String)

Примеры

Преобразование Modified Julian Day в дату с обработкой null

SELECT fromModifiedJulianDayOrNull(58849);
SELECT fromModifiedJulianDayOrNull(60000000); -- некорректный аргумент, возвращает NULL

┌─fromModified⋯Null(58849)─┐
│ 2020-01-01               │
└──────────────────────────┘
┌─fromModified⋯l(60000000)─┐
│ ᴺᵁᴸᴸ                     │
└──────────────────────────┘

fromUTCTimestamp

Добавлена в версии: v22.1

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

Синтаксис

fromUTCTimestamp(datetime, time_zone)

Псевдонимы: from_utc_timestamp

Аргументы

datetime — константное значение даты или даты и времени либо выражение. DateTime или DateTime64
time_zone — константное строковое значение или выражение, задающее часовой пояс. String

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

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

Примеры

Преобразование часового пояса UTC в указанный часовой пояс

SELECT fromUTCTimestamp(toDateTime64('2023-03-16 10:00:00', 3), 'Asia/Shanghai')

┌─fromUTCTimestamp(toDateTime64('2023-03-16 10:00:00',3), 'Asia/Shanghai')─┐
│                                                 2023-03-16 18:00:00.000 │
└─────────────────────────────────────────────────────────────────────────┘

fromUnixTimestamp

Введена в версии: v20.8

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

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

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

Синтаксис

fromUnixTimestamp(timestamp)
fromUnixTimestamp(timestamp[, format[, timezone]])

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

Аргументы

timestamp — Unix-метка времени или значение типа дата/дата и время. (U)Int* или Date или Date32 или DateTime или DateTime64
format — Необязательный параметр. Константная строка формата вывода. String
timezone — Необязательный параметр. Константная строка часового пояса. String

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

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

Примеры

Преобразование Unix-метки времени в DateTime

SELECT fromUnixTimestamp(423543535)

┌─fromUnixTimestamp(423543535)─┐
│          1983-06-04 10:58:55 │
└──────────────────────────────┘

Преобразование Unix‑метки времени с форматированием

SELECT fromUnixTimestamp(1234334543, '%Y-%m-%d %R:%S') AS DateTime

┌─DateTime────────────┐
│ 2009-02-11 14:42:23 │
└─────────────────────┘

fromUnixTimestampInJodaSyntax

Введена в версии v23.1

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

Функцию можно вызывать двумя способами:

Если передан один аргумент типа Integer, возвращается значение типа DateTime, т.е. функция ведёт себя как toDateTime.

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

Синтаксис

fromUnixTimestampInJodaSyntax(timestamp)
fromUnixTimestampInJodaSyntax(timestamp, format[, timezone])

Аргументы

timestamp — Unix-метка времени или значение даты/времени. (U)Int* или Date или Date32 или DateTime или DateTime64
format — Необязательный параметр. Константная строка формата, использующая синтаксис Joda для форматирования вывода. String
timezone — Необязательный параметр. Константная строка часового пояса. String

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

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

Примеры

Преобразование Unix-метки времени с использованием формата Joda

SELECT fromUnixTimestampInJodaSyntax(1234334543, 'yyyy-MM-dd HH:mm:ss', 'UTC') AS DateTime

┌─DateTime────────────┐
│ 2009-02-11 06:42:23 │
└─────────────────────┘

makeDate

Впервые представлена в версии v22.6

Создаёт значение типа Date из одного из следующих наборов аргументов:

год, месяц и день
год и порядковый номер дня в году

Синтаксис

makeDate(year, month, day)
makeDate(year, day_of_year)

Аргументы

year — Год. (U)Int* или Float* или Decimal
month — Месяц (1–12). (U)Int* или Float* или Decimal
day — День месяца (1–31). (U)Int* или Float* или Decimal
day_of_year — Порядковый номер дня в году (1–365). (U)Int* или Float* или Decimal

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

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

Примеры

Дата из года, месяца и дня

SELECT makeDate(2023, 2, 28) AS date;

┌───────date─┐
│ 2023-02-28 │
└────────────┘

Дата по году и номеру дня в году

SELECT makeDate(2023, 42) AS date;

┌───────date─┐
│ 2023-02-11 │
└────────────┘

makeDate32

Появилась в версии: v22.6

Создаёт значение типа Date32 на основе одного из вариантов:

год, месяц и день
год и порядковый номер дня в году

Синтаксис

makeDate32(year, month, day)
makeDate32(year, day_of_year)

Аргументы

year — Год. (U)Int* или Float* или Decimal
month — Месяц (1–12). (U)Int* или Float* или Decimal
day — День месяца (1–31). (U)Int* или Float* или Decimal
day_of_year — День года (1–365). (U)Int* или Float* или Decimal

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

Возвращает значение Date32, построенное из переданных аргументов Date32

Примеры

Date32 из года, месяца, дня

SELECT makeDate(2023, 2, 28) AS date;

┌───────date─┐
│ 2023-02-28 │
└────────────┘

Date32 из года и номера дня в году

SELECT makeDate(2023, 42) AS date;

┌───────date─┐
│ 2023-02-11 │
└────────────┘

makeDateTime

Добавлена в версии: v22.6

Создаёт значение типа DateTime из года, месяца, дня, часа, минуты и секунды с необязательным часовым поясом.

Синтаксис

makeDateTime(year, month, day, hour, minute, second[, timezone])

Аргументы

year — Год. (U)Int* или Float* или Decimal
month — Месяц (1-12). (U)Int* или Float* или Decimal
day — День месяца (1-31). (U)Int* или Float* или Decimal
hour — Час (0-23). (U)Int* или Float* или Decimal
minute — Минута (0-59). (U)Int* или Float* или Decimal
second — Секунда (0-59). (U)Int* или Float* или Decimal
timezone — Имя часового пояса. String

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

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

Примеры

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

SELECT makeDateTime(2023, 2, 28, 17, 12, 33) AS DateTime;

┌────────────DateTime─┐
│ 2023-02-28 17:12:33 │
└─────────────────────┘

makeDateTime64

Добавлено в: v22.6

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

Синтаксис

makeDateTime64(year, month, day, hour, minute, second[, fraction[, precision[, timezone]]])

Аргументы

year — Год. (U)Int* или Float* или Decimal
month — Месяц (1–12). (U)Int* или Float* или Decimal
day — День месяца (1–31). (U)Int* или Float* или Decimal
hour — Час (0–23). (U)Int* или Float* или Decimal
minute — Минута (0–59). (U)Int* или Float* или Decimal
second — Секунда (0–59). (U)Int* или Float* или Decimal
fraction — Дробная часть секунды. (U)Int* или Float* или Decimal
precision — Точность дробной части (0–9). UInt8
timezone — Имя часового пояса. String

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

Возвращает значение DateTime64, сформированное из переданных аргументов. DateTime64

Примеры

DateTime64 из года, месяца, дня, часа, минуты и секунды

SELECT makeDateTime64(2023, 5, 15, 10, 30, 45, 779, 5);

┌─makeDateTime64(2023, 5, 15, 10, 30, 45, 779, 5)─┐
│                       2023-05-15 10:30:45.00779 │
└─────────────────────────────────────────────────┘

monthName

Впервые представлена в версии: v22.1

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

Синтаксис

monthName(datetime)

Аргументы

datetime — дата или дата со временем. Date или Date32 или DateTime или DateTime64

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

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

Примеры

Получение названия месяца из даты

WITH toDateTime('2021-04-14 11:22:33') AS date_value
SELECT monthName(date_value)

┌─monthName(date_value)─┐
│ April                 │
└───────────────────────┘

now

Введена в версии v1.1

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

Синтаксис

now([timezone])

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

Аргументы

timezone — Необязательный параметр. Название часового пояса для возвращаемого значения. String

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

Возвращает текущие дату и время. DateTime

Примеры

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

SELECT now()

┌───────────────now()─┐
│ 2020-10-17 07:42:09 │
└─────────────────────┘

Запрос с заданным часовым поясом

SELECT now('Asia/Istanbul')

┌─now('Asia/Istanbul')─┐
│  2020-10-17 10:42:23 │
└──────────────────────┘

now64

Добавлена в версии: v20.1

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

Синтаксис

now64([scale[, timezone]])

Аргументы

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

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

Возвращает текущие дату и время с точностью до долей секунды. DateTime64

Примеры

Запрос с точностью по умолчанию и пользовательской точностью

SELECT now64(), now64(9, 'Asia/Istanbul')

┌─────────────────now64()─┬─────now64(9, 'Asia/Istanbul')─┐
│ 2022-08-21 19:34:26.196 │ 2022-08-21 22:34:26.196542766 │
└─────────────────────────┴───────────────────────────────┘

nowInBlock

Появилась в версии: v22.8

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

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

Синтаксис

nowInBlock([timezone])

Аргументы

timezone — Необязательный параметр. Имя часового пояса для возвращаемого значения. String

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

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

Примеры

Отличие от функции now()

SELECT
    now(),
    nowInBlock(),
    sleep(1)
FROM numbers(3)
SETTINGS max_block_size = 1
FORMAT PrettyCompactMonoBlock

┌───────────────now()─┬────────nowInBlock()─┬─sleep(1)─┐
│ 2022-08-21 19:41:19 │ 2022-08-21 19:41:19 │        0 │
│ 2022-08-21 19:41:19 │ 2022-08-21 19:41:20 │        0 │
│ 2022-08-21 19:41:19 │ 2022-08-21 19:41:21 │        0 │
└─────────────────────┴─────────────────────┴──────────┘

nowInBlock64

Добавлено в: v25.8

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

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

Синтаксис

nowInBlock([scale[, timezone]])

Аргументы

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

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

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

Примеры

Отличие от функции now64()

SELECT
    now64(),
    nowInBlock64(),
    sleep(1)
FROM numbers(3)
SETTINGS max_block_size = 1
FORMAT PrettyCompactMonoBlock

┌─────────────────now64()─┬──────────nowInBlock64()─┬─sleep(1)─┐
│ 2025-07-29 17:07:29.526 │ 2025-07-29 17:07:29.534 │        0 │
│ 2025-07-29 17:07:29.526 │ 2025-07-29 17:07:30.535 │        0 │
│ 2025-07-29 17:07:29.526 │ 2025-07-29 17:07:31.535 │        0 │
└─────────────────────────┴─────────────────────────┴──────────┘

serverTimezone

Добавлено в: v23.6

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

Синтаксис

serverTimeZone()

Псевдонимы: serverTimeZone

Аргументы

Нет.

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

Возвращает часовой пояс сервера в виде String.

Примеры

Пример использования

SELECT serverTimeZone()

┌─serverTimeZone()─┐
│ UTC              │
└──────────────────┘

subDate

Появилась в версии: v23.9

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

Синтаксис

subDate(datetime, interval)

Аргументы

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

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

Возвращает дату или дату со временем, полученную вычитанием interval из datetime. Date или Date32 или DateTime или DateTime64

Примеры

Вычесть интервал из даты

SELECT subDate(toDate('2018-01-01'), INTERVAL 3 YEAR)

┌─subDate(toDate('2018-01-01'), toIntervalYear(3))─┐
│                                       2015-01-01 │
└──────────────────────────────────────────────────┘

subtractDays

Введена в: v1.1

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

Синтаксис

subtractDays(datetime, num)

Аргументы

datetime — дата или дата со временем, от которой вычитается указанное количество дней. Date или Date32 или DateTime или DateTime64 или String
num — количество дней, на которое нужно уменьшить дату. (U)Int* или Float*

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

Возвращает datetime минус num дней — значение типа Date или Date32 или DateTime или DateTime64

Примеры

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

WITH
    toDate('2024-01-01') AS date,
    toDateTime('2024-01-01 00:00:00') AS date_time,
    '2024-01-01 00:00:00' AS date_time_string
SELECT
    subtractDays(date, 31) AS subtract_days_with_date,
    subtractDays(date_time, 31) AS subtract_days_with_date_time,
    subtractDays(date_time_string, 31) AS subtract_days_with_date_time_string

┌─subtract_days_with_date─┬─subtract_days_with_date_time─┬─subtract_days_with_date_time_string─┐
│              2023-12-01 │          2023-12-01 00:00:00 │             2023-12-01 00:00:00.000 │
└─────────────────────────┴──────────────────────────────┴─────────────────────────────────────┘

Использование альтернативного синтаксиса INTERVAL

SELECT dateSub('1998-06-16'::Date, INTERVAL 10 day)

┌─minus(CAST('⋯valDay(10))─┐
│               1998-06-06 │
└──────────────────────────┘

subtractHours

Добавлено в: v1.1

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

Синтаксис

subtractHours(datetime, num)

Аргументы

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

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

Возвращает значение datetime за вычетом num часов — DateTime или DateTime64(3)

Примеры

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

WITH
    toDate('2024-01-01') AS date,
    toDateTime('2024-01-01 00:00:00') AS date_time,
    '2024-01-01 00:00:00' AS date_time_string
SELECT
    subtractHours(date, 12) AS subtract_hours_with_date,
    subtractHours(date_time, 12) AS subtract_hours_with_date_time,
    subtractHours(date_time_string, 12) AS subtract_hours_with_date_time_string

┌─subtract_hours_with_date─┬─subtract_hours_with_date_time─┬─subtract_hours_with_date_time_string─┐
│      2023-12-31 12:00:00 │           2023-12-31 12:00:00 │              2023-12-31 12:00:00.000 │
└──────────────────────────┴───────────────────────────────┴──────────────────────────────────────┘

Использование альтернативного синтаксиса INTERVAL

SELECT dateSub('1998-06-16'::Date, INTERVAL 10 hour)

┌─minus(CAST('⋯alHour(10))─┐
│      1998-06-15 14:00:00 │
└──────────────────────────┘

subtractInterval

Введена в версии: v22.11

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

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

Синтаксис

subtractInterval(interval_1, interval_2)

Аргументы

interval_1 — Первый интервал или кортеж интервалов. Interval или Tuple(Interval)
interval_2 — Второй интервал, который нужно обратить по знаку. Interval

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

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

Примеры

Вычитание интервалов

SELECT subtractInterval(INTERVAL 1 DAY, INTERVAL 1 MONTH);
SELECT subtractInterval((INTERVAL 1 DAY, INTERVAL 1 YEAR), INTERVAL 1 MONTH);
SELECT subtractInterval(INTERVAL 2 DAY, INTERVAL 1 DAY);

┌─subtractInterval(toIntervalDay(1), toIntervalMonth(1))─┐
│ (1,-1)                                                 │
└────────────────────────────────────────────────────────┘
┌─subtractInterval((toIntervalDay(1), toIntervalYear(1)), toIntervalMonth(1))─┐
│ (1,1,-1)                                                                    │
└─────────────────────────────────────────────────────────────────────────────┘
┌─subtractInterval(toIntervalDay(2), toIntervalDay(1))─┐
│ (1)                                                  │
└──────────────────────────────────────────────────────┘

subtractMicroseconds

Появилась в версии: v22.6

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

Синтаксис

subtractMicroseconds(datetime, num)

Аргументы

datetime — дата и время, из которых нужно вычесть указанное количество микросекунд. DateTime или DateTime64 или String
num — количество микросекунд, которое нужно вычесть. (U)Int* или Float*

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

Возвращает datetime минус num микросекунд, результат типа DateTime64

Примеры

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

WITH
    toDateTime('2024-01-01 00:00:00') AS date_time,
    '2024-01-01 00:00:00' AS date_time_string
SELECT
    subtractMicroseconds(date_time, 1000000) AS subtract_microseconds_with_date_time,
    subtractMicroseconds(date_time_string, 1000000) AS subtract_microseconds_with_date_time_string

┌─subtract_microseconds_with_date_time─┬─subtract_microseconds_with_date_time_string─┐
│           2023-12-31 23:59:59.000000 │                  2023-12-31 23:59:59.000000 │
└──────────────────────────────────────┴─────────────────────────────────────────────┘

Использование альтернативного синтаксиса INTERVAL

SELECT dateSub('1998-06-16'::DateTime, INTERVAL 10 microsecond)

┌─minus(CAST('1⋯osecond(10))─┐
│ 1998-06-15 23:59:59.999990 │
└────────────────────────────┘

subtractMilliseconds

Добавлена в версии: v22.6

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

Синтаксис

subtractMilliseconds(datetime, num)

Аргументы

datetime — дата и время, из которых нужно вычесть указанное количество миллисекунд. DateTime или DateTime64 или String
num — количество миллисекунд, на которое нужно уменьшить значение. (U)Int* или Float*

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

Возвращает значение datetime минус num миллисекунд типа DateTime64

Примеры

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

WITH
    toDateTime('2024-01-01 00:00:00') AS date_time,
    '2024-01-01 00:00:00' AS date_time_string
SELECT
    subtractMilliseconds(date_time, 1000) AS subtract_milliseconds_with_date_time,
    subtractMilliseconds(date_time_string, 1000) AS subtract_milliseconds_with_date_time_string

┌─subtract_milliseconds_with_date_time─┬─subtract_milliseconds_with_date_time_string─┐
│              2023-12-31 23:59:59.000 │                     2023-12-31 23:59:59.000 │
└──────────────────────────────────────┴─────────────────────────────────────────────┘

Использование альтернативного синтаксиса INTERVAL

SELECT dateSub('1998-06-16'::DateTime, INTERVAL 10 millisecond)

┌─minus(CAST('⋯second(10))─┐
│  1998-06-15 23:59:59.990 │
└──────────────────────────┘

subtractMinutes

Добавлена в версии: v1.1

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

Синтаксис

subtractMinutes(datetime, num)

Аргументы

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

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

Возвращает datetime за вычетом num минут типа DateTime или DateTime64(3)

Примеры

Вычитание минут из значений разных типов даты

WITH
    toDate('2024-01-01') AS date,
    toDateTime('2024-01-01 00:00:00') AS date_time,
    '2024-01-01 00:00:00' AS date_time_string
SELECT
    subtractMinutes(date, 30) AS subtract_minutes_with_date,
    subtractMinutes(date_time, 30) AS subtract_minutes_with_date_time,
    subtractMinutes(date_time_string, 30) AS subtract_minutes_with_date_time_string

┌─subtract_minutes_with_date─┬─subtract_minutes_with_date_time─┬─subtract_minutes_with_date_time_string─┐
│        2023-12-31 23:30:00 │             2023-12-31 23:30:00 │                2023-12-31 23:30:00.000 │
└────────────────────────────┴─────────────────────────────────┴────────────────────────────────────────┘

Использование альтернативного синтаксиса для INTERVAL

SELECT dateSub('1998-06-16'::Date, INTERVAL 10 minute)

┌─minus(CAST('⋯Minute(10))─┐
│      1998-06-15 23:50:00 │
└──────────────────────────┘

subtractMonths

Введена в версии v1.1

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

Синтаксис

subtractMonths(datetime, num)

Аргументы

datetime — дата или дата со временем, из которой нужно вычесть указанное количество месяцев. Date или Date32 или DateTime или DateTime64 или String
num — количество месяцев, на которое уменьшается значение datetime. (U)Int* или Float*

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

Возвращает значение datetime, уменьшенное на num месяцев. Date или Date32 или DateTime или DateTime64

Примеры

Вычитание месяцев для разных типов дат

WITH
    toDate('2024-01-01') AS date,
    toDateTime('2024-01-01 00:00:00') AS date_time,
    '2024-01-01 00:00:00' AS date_time_string
SELECT
    subtractMonths(date, 1) AS subtract_months_with_date,
    subtractMonths(date_time, 1) AS subtract_months_with_date_time,
    subtractMonths(date_time_string, 1) AS subtract_months_with_date_time_string

┌─subtract_months_with_date─┬─subtract_months_with_date_time─┬─subtract_months_with_date_time_string─┐
│                2023-12-01 │            2023-12-01 00:00:00 │               2023-12-01 00:00:00.000 │
└───────────────────────────┴────────────────────────────────┴───────────────────────────────────────┘

Использование альтернативного синтаксиса INTERVAL

SELECT dateSub('1998-06-16'::Date, INTERVAL 10 month)

┌─minus(CAST('⋯lMonth(10))─┐
│               1997-08-16 │
└──────────────────────────┘

subtractNanoseconds

Появилась в версии: v20.1

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

Синтаксис

subtractNanoseconds(datetime, num)

Аргументы

datetime — дата и время, из которых нужно вычесть заданное количество наносекунд. DateTime или DateTime64 или String
num — количество наносекунд, которые нужно вычесть. (U)Int* или Float*

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

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

Примеры

Вычитание наносекунд из значений разных типов даты и времени

WITH
    toDateTime('2024-01-01 00:00:00') AS date_time,
    '2024-01-01 00:00:00' AS date_time_string
SELECT
    subtractNanoseconds(date_time, 1000) AS subtract_nanoseconds_with_date_time,
    subtractNanoseconds(date_time_string, 1000) AS subtract_nanoseconds_with_date_time_string

┌─subtract_nanoseconds_with_date_time─┬─subtract_nanoseconds_with_date_time_string─┐
│       2023-12-31 23:59:59.999999000 │              2023-12-31 23:59:59.999999000 │
└─────────────────────────────────────┴────────────────────────────────────────────┘

Использование альтернативного синтаксиса INTERVAL

SELECT dateSub('1998-06-16'::DateTime, INTERVAL 10 nanosecond)

┌─minus(CAST('19⋯anosecond(10))─┐
│ 1998-06-15 23:59:59.999999990 │
└───────────────────────────────┘

subtractQuarters

Добавлена в: v20.1

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

Синтаксис

subtractQuarters(datetime, num)

Аргументы

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

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

Возвращает значение datetime, уменьшенное на num кварталов. Date или Date32 или DateTime или DateTime64

Примеры

Вычитание кварталов из значений разных типов дат

WITH
    toDate('2024-01-01') AS date,
    toDateTime('2024-01-01 00:00:00') AS date_time,
    '2024-01-01 00:00:00' AS date_time_string
SELECT
    subtractQuarters(date, 1) AS subtract_quarters_with_date,
    subtractQuarters(date_time, 1) AS subtract_quarters_with_date_time,
    subtractQuarters(date_time_string, 1) AS subtract_quarters_with_date_time_string

┌─subtract_quarters_with_date─┬─subtract_quarters_with_date_time─┬─subtract_quarters_with_date_time_string─┐
│                  2023-10-01 │              2023-10-01 00:00:00 │                 2023-10-01 00:00:00.000 │
└─────────────────────────────┴──────────────────────────────────┴─────────────────────────────────────────┘

Использование альтернативного синтаксиса INTERVAL

SELECT dateSub('1998-06-16'::Date, INTERVAL 10 quarter)

┌─minus(CAST('1⋯Quarter(10))─┐
│                1996-09-16 │
└───────────────────────────┘

subtractSeconds

Введена в версии: v1.1

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

Синтаксис

subtractSeconds(datetime, num)

Аргументы

datetime — дата или дата со временем, из которой вычитается указанное количество секунд. Date или Date32 или DateTime или DateTime64 или String
num — количество секунд, на которое нужно уменьшить значение datetime. (U)Int* или Float*

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

Возвращает datetime, уменьшенное на num секунд, типа DateTime или DateTime64(3)

Примеры

Вычитание секунд из разных типов дат

WITH
    toDate('2024-01-01') AS date,
    toDateTime('2024-01-01 00:00:00') AS date_time,
    '2024-01-01 00:00:00' AS date_time_string
SELECT
    subtractSeconds(date, 60) AS subtract_seconds_with_date,
    subtractSeconds(date_time, 60) AS subtract_seconds_with_date_time,
    subtractSeconds(date_time_string, 60) AS subtract_seconds_with_date_time_string

┌─subtract_seconds_with_date─┬─subtract_seconds_with_date_time─┬─subtract_seconds_with_date_time_string─┐
│        2023-12-31 23:59:00 │             2023-12-31 23:59:00 │                2023-12-31 23:59:00.000 │
└────────────────────────────┴─────────────────────────────────┴────────────────────────────────────────┘

Использование альтернативного синтаксиса для INTERVAL

SELECT dateSub('1998-06-16'::Date, INTERVAL 10 second)

┌─minus(CAST('⋯Second(10))─┐
│      1998-06-15 23:59:50 │
└──────────────────────────┘

subtractTupleOfIntervals

Появилась в версии: v22.11

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

Синтаксис

subtractTupleOfIntervals(datetime, intervals)

Аргументы

datetime — дата или дата со временем, из которой нужно вычесть интервалы. Date или Date32 или DateTime или DateTime64
intervals — кортеж интервалов, которые нужно вычесть из datetime. Tuple(Interval)

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

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

Примеры

Вычитание кортежа интервалов из даты

WITH toDate('2018-01-01') AS date SELECT subtractTupleOfIntervals(date, (INTERVAL 1 DAY, INTERVAL 1 YEAR))

┌─subtractTupl⋯alYear(1)))─┐
│               2016-12-31 │
└──────────────────────────┘

subtractWeeks

Появилась в версии: v1.1

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

Синтаксис

subtractWeeks(datetime, num)

Аргументы

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

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

Возвращает значение datetime, уменьшенное на num недель. Тип результата: Date или Date32 или DateTime или DateTime64

Примеры

Вычитание недель из значений разных типов даты

WITH
    toDate('2024-01-01') AS date,
    toDateTime('2024-01-01 00:00:00') AS date_time,
    '2024-01-01 00:00:00' AS date_time_string
SELECT
    subtractWeeks(date, 1) AS subtract_weeks_with_date,
    subtractWeeks(date_time, 1) AS subtract_weeks_with_date_time,
    subtractWeeks(date_time_string, 1) AS subtract_weeks_with_date_time_string

┌─subtract_weeks_with_date─┬─subtract_weeks_with_date_time─┬─subtract_weeks_with_date_time_string─┐
│               2023-12-25 │           2023-12-25 00:00:00 │              2023-12-25 00:00:00.000 │
└──────────────────────────┴───────────────────────────────┴──────────────────────────────────────┘

Использование альтернативного синтаксиса INTERVAL

SELECT dateSub('1998-06-16'::Date, INTERVAL 10 week)

┌─minus(CAST('⋯alWeek(10))─┐
│               1998-04-07 │
└──────────────────────────┘

subtractYears

Добавлена в: v1.1

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

Синтаксис

subtractYears(datetime, num)

Аргументы

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

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

Возвращает datetime минус num лет — значение типа Date, Date32, DateTime или DateTime64.

Примеры

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

WITH
    toDate('2024-01-01') AS date,
    toDateTime('2024-01-01 00:00:00') AS date_time,
    '2024-01-01 00:00:00' AS date_time_string
SELECT
    subtractYears(date, 1) AS subtract_years_with_date,
    subtractYears(date_time, 1) AS subtract_years_with_date_time,
    subtractYears(date_time_string, 1) AS subtract_years_with_date_time_string

┌─subtract_years_with_date─┬─subtract_years_with_date_time─┬─subtract_years_with_date_time_string─┐
│               2023-01-01 │           2023-01-01 00:00:00 │              2023-01-01 00:00:00.000 │
└──────────────────────────┴───────────────────────────────┴──────────────────────────────────────┘

Использование альтернативного синтаксиса INTERVAL

SELECT dateSub('1998-06-16'::Date, INTERVAL 10 year)

┌─minus(CAST('⋯alYear(10))─┐
│               1988-06-16 │
└──────────────────────────┘

timeDiff

Добавлена в версии: v23.4

Возвращает разницу в секундах между двумя датами или датами со значениями времени. Разница вычисляется как enddate - startdate.

Эта функция эквивалентна dateDiff('second', startdate, enddate).

Для вычисления разницы во времени в других единицах (часах, днях, месяцах и т. д.) используйте функцию dateDiff.

Синтаксис

timeDiff(startdate, enddate)

Аргументы

startdate — Первое значение времени, вычитаемое из второго (вычитаемое). Date, Date32, DateTime или DateTime64
enddate — Второе значение времени, из которого выполняется вычитание (уменьшаемое). Date, Date32, DateTime или DateTime64

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

Возвращает разницу между enddate и startdate, выраженную в секундах. Int64

Примеры

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

SELECT timeDiff(toDateTime('2018-01-01 22:00:00'), toDateTime('2018-01-02 23:00:00')) AS res

┌───res─┐
│ 90000 │
└───────┘

Вычислить разницу во времени и перевести её в часы

SELECT timeDiff(toDateTime('2018-01-01 22:00:00'), toDateTime('2018-01-02 23:00:00')) / 3600 AS hours

┌─hours─┐
│    25 │
└───────┘

Эквивалент dateDiff в секундах

SELECT
    timeDiff(toDateTime('2021-12-29'), toDateTime('2022-01-01')) AS time_diff_result,
    dateDiff('second', toDateTime('2021-12-29'), toDateTime('2022-01-01')) AS date_diff_result

┌─time_diff_result─┬─date_diff_result─┐
│           259200 │           259200 │
└──────────────────┴──────────────────┘

timeSlot

Добавлено в: v1.1

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

Примечание

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

Синтаксис

timeSlot(time[, time_zone])

Аргументы

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

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

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

Примеры

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

SELECT timeSlot(toDateTime('2000-01-02 03:04:05', 'UTC'))

┌─timeSlot(toDateTime('2000-01-02 03:04:05', 'UTC'))─┐
│                                2000-01-02 03:00:00 │
└────────────────────────────────────────────────────┘

timeSlots

Появилась в версии v1.1

Для временного интервала, начинающегося в StartTime и продолжающегося Duration секунд, функция возвращает массив моментов времени — точки внутри этого интервала, округлённые вниз до шага Size в секундах. Параметр Size является необязательным и по умолчанию равен 1800 (30 минут).

Это нужно, например, при поиске просмотров страниц в соответствующей сессии.

Для DateTime64 масштаб (scale) возвращаемого значения может отличаться от масштаба StartTime. Берётся наибольший масштаб среди всех переданных аргументов.

Синтаксис

timeSlots(StartTime, Duration[, Size])

Аргументы

StartTime — начальное время интервала. DateTime или DateTime64
Duration — длительность интервала в секундах. UInt32 или DateTime64
Size — необязательный параметр. Размер временных слотов в секундах. Значение по умолчанию — 1800 (30 минут). UInt32 или DateTime64

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

Возвращает массив DateTime/DateTime64 (тип возвращаемого значения соответствует типу StartTime). Для DateTime64 масштаб возвращаемого значения может отличаться от масштаба StartTime — берётся максимальный масштаб среди всех переданных аргументов. Array(DateTime) или Array(DateTime64)

Примеры

Создание временных слотов для интервала

SELECT timeSlots(toDateTime('2012-01-01 12:20:00'), toUInt32(600));
SELECT timeSlots(toDateTime('1980-12-12 21:01:02', 'UTC'), toUInt32(600), 299);
SELECT timeSlots(toDateTime64('1980-12-12 21:01:02.1234', 4, 'UTC'), toDecimal64(600.1, 1), toDecimal64(299, 0))

┌─timeSlots(toDateTime('2012-01-01 12:20:00'), toUInt32(600))─┐
│ ['2012-01-01 12:00:00','2012-01-01 12:30:00']               │
└─────────────────────────────────────────────────────────────┘
┌─timeSlots(toDateTime('1980-12-12 21:01:02', 'UTC'), toUInt32(600), 299)─┐
│ ['1980-12-12 20:56:13','1980-12-12 21:01:12','1980-12-12 21:06:11']     │
└─────────────────────────────────────────────────────────────────────────┘
┌─timeSlots(toDateTime64('1980-12-12 21:01:02.1234', 4, 'UTC'), toDecimal64(600.1, 1), toDecimal64(299, 0))─┐
│ ['1980-12-12 20:56:13.0000','1980-12-12 21:01:12.0000','1980-12-12 21:06:11.0000']                        │
└───────────────────────────────────────────────────────────────────────────────────────────────────────────┘

timestamp

Введена в версии: v23.9

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

Синтаксис

timestamp(expr[, expr_time])

Аргументы

expr — дата или дата и время. String
expr_time — необязательный параметр. Время, добавляемое к приведённому значению. String

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

Возвращает приведённое значение expr или expr с добавленным временем типа DateTime64(6)

Примеры

Преобразование строкового значения даты в DateTime64(6)

SELECT timestamp('2023-12-31') AS ts;

┌─────────────────────────ts─┐
│ 2023-12-31 00:00:00.000000 │
└────────────────────────────┘

Добавить время к строке даты

SELECT timestamp('2023-12-31 12:00:00', '12:00:00.11') AS ts;

┌─────────────────────────ts─┐
│ 2024-01-01 00:00:00.110000 │
└────────────────────────────┘

timezone

Добавлено в версии: v21.4

Возвращает имя часового пояса текущей сессии или преобразует смещение часового пояса или имя часового пояса в каноническое имя часового пояса.

Синтаксис

timezone()

Псевдонимы: timeZone

Аргументы

Отсутствуют.

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

Возвращает каноническое имя часового пояса в виде типа String

Примеры

Пример использования

SELECT timezone()

┌─timezone()───────┐
│ Europe/Amsterdam │
└──────────────────┘

timezoneOf

Впервые появилась в: v21.4

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

Синтаксис

timeZoneOf(datetime)

Псевдонимы: timeZoneOf

Аргументы

datetime — значение типа DateTime или DateTime64
timezone — необязательный параметр. Имя часового пояса, в который нужно преобразовать часовой пояс значения datetime. String

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

Возвращает имя часового пояса для datetime в формате String

Примеры

Пример использования

SELECT timezoneOf(now());

┌─timezoneOf(now())─┐
│ Europe/Amsterdam  │
└───────────────────┘

timezoneOffset

Введена в версии v21.6

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

Синтаксис

timeZoneOffset(datetime)

Псевдонимы: timeZoneOffset

Аргументы

datetime — значение типа DateTime, для которого нужно получить смещение часового пояса: DateTime или DateTime64

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

Возвращает смещение относительно UTC в секундах Int32

Примеры

Пример использования

SELECT toDateTime('2021-04-21 10:20:30', 'America/New_York') AS Time,
toTypeName(Time) AS Type,
timeZoneOffset(Time) AS Offset_in_seconds,
(Offset_in_seconds / 3600) AS Offset_in_hours;

┌────────────────Time─┬─Type─────────────────────────┬─Offset_in_seconds─┬─Offset_in_hours─┐
│ 2021-04-21 10:20:30 │ DateTime('America/New_York') │            -14400 │              -4 │
└─────────────────────┴──────────────────────────────┴───────────────────┴─────────────────┘

toDayOfMonth

Появилась в версии v1.1

Возвращает день месяца (1–31) для значения типа Date или DateTime.

Синтаксис

toDayOfMonth(datetime)

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

Аргументы

datetime — дата или дата и время, из которых нужно получить день месяца. Date или Date32 или DateTime или DateTime64

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

Возвращает номер дня месяца для заданной даты/времени UInt8

Примеры

Пример использования

SELECT toDayOfMonth(toDateTime('2023-04-21 10:20:30'))

┌─toDayOfMonth(toDateTime('2023-04-21 10:20:30'))─┐
│                                              21 │
└─────────────────────────────────────────────────┘

toDayOfWeek

Впервые появилась в: v1.1

Возвращает номер дня недели для значения типа Date или DateTime.

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

Mode	Первый день недели	Диапазон
0	Monday	1-7: Monday = 1, Tuesday = 2, ..., Sunday = 7
1	Monday	0-6: Monday = 0, Tuesday = 1, ..., Sunday = 6
2	Sunday	0-6: Sunday = 0, Monday = 1, ..., Saturday = 6
3	Sunday	1-7: Sunday = 1, Monday = 2, ..., Saturday = 7

Синтаксис

toDayOfWeek(datetime[, mode[, timezone]])

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

Аргументы

datetime — дата или дата со временем, для которой нужно получить день недели. Date или Date32 или DateTime или DateTime64
mode — необязательный параметр. Целое число, задающее режим недели (0–3). По умолчанию — 0, если параметр не указан. UInt8
timezone — необязательный параметр. Часовой пояс, используемый для преобразования. String

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

Возвращает день недели для заданных Date или DateTime в виде значения типа UInt8.

Примеры

Пример использования

-- Следующая дата — 21 апреля 2023 года, это была пятница:
SELECT
    toDayOfWeek(toDateTime('2023-04-21')),
    toDayOfWeek(toDateTime('2023-04-21'), 1)

┌─toDayOfWeek(toDateTime('2023-04-21'))─┬─toDayOfWeek(toDateTime('2023-04-21'), 1)─┐
│                                     5 │                                        4 │
└───────────────────────────────────────┴──────────────────────────────────────────┘

toDayOfYear

Появилась в версии: v18.4

Возвращает порядковый номер дня в году (1–366) для значения типа Date или DateTime.

Синтаксис

toDayOfYear(datetime)

Псевдонимы: DAYOFYEAR

Аргументы

datetime — дата или дата и время, для которой требуется получить порядковый номер дня года. Date, Date32, DateTime или DateTime64

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

Возвращает порядковый номер дня года для заданного значения типа Date или DateTime в виде UInt16

Примеры

Пример использования

SELECT toDayOfYear(toDateTime('2023-04-21 10:20:30'))

┌─toDayOfYear(toDateTime('2023-04-21 10:20:30'))─┐
│                                            111 │
└────────────────────────────────────────────────┘

toDaysSinceYearZero

Добавлено в версии: v23.9

Для заданной даты возвращает количество дней, прошедших с 1 января 0000 в пролептическом григорианском календаре, определённом стандартом ISO 8601.

Вычисление совпадает с функцией TO_DAYS в MySQL.

Синтаксис

toDaysSinceYearZero(date[, time_zone])

Псевдонимы: TO_DAYS

Аргументы

date — Дата или дата со временем, для которой нужно вычислить количество дней, прошедших с нулевого года. Date или Date32 или DateTime или DateTime64
time_zone — Часовой пояс. String

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

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

Примеры

Вычисление количества дней с нулевого года

SELECT toDaysSinceYearZero(toDate('2023-09-08'))

┌─toDaysSinceYearZero(toDate('2023-09-08')))─┐
│                                     713569 │
└────────────────────────────────────────────┘

toHour

Добавлена в версии: v1.1

Возвращает часовую часть (0–23) значения DateTime или DateTime64.

Синтаксис

toHour(datetime)

Псевдонимы: HOUR

Аргументы

datetime — Дата и время, из которых нужно получить час. DateTime или DateTime64

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

Возвращает час (0–23) из datetime. UInt8

Примеры

Пример использования

SELECT toHour(toDateTime('2023-04-21 10:20:30'))

┌─toHour(toDateTime('2023-04-21 10:20:30'))─┐
│                                        10 │
└───────────────────────────────────────────┘

toISOYear

Введена в версии: v18.4

Преобразует дату или дату со временем в номер года по стандарту ISO.

Синтаксис

toISOYear(datetime)

Аргументы

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

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

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

Примеры

Получение номера года по ISO из значений даты

SELECT
toISOYear(toDate('2024/10/02')) as year1,
toISOYear(toDateTime('2024-10-02 01:30:00')) as year2

┌─week1─┬─week2─┐
│    40 │    40 │
└───────┴───────┘

toLastDayOfMonth

Впервые представлена в: v1.1

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

Примечание

Тип возвращаемого значения можно настроить с помощью параметра enable_extended_results_for_datetime_functions.

Синтаксис

toLastDayOfMonth(value)

Псевдонимы: LAST_DAY

Аргументы

value — дата или дата со временем, которую необходимо округлить вверх до последнего дня месяца. Date или Date32 или DateTime или DateTime64

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

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

Примеры

Округление до последнего дня месяца

SELECT toLastDayOfMonth(toDateTime('2023-04-21 10:20:30'))

┌─toLastDayOfMonth(toDateTime('2023-04-21 10:20:30'))─┐
│                                          2023-04-30 │
└─────────────────────────────────────────────────────┘

toLastDayOfWeek

Введена в версии: v23.5

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

Примечание

Тип возвращаемого значения можно настроить с помощью параметра enable_extended_results_for_datetime_functions.

Синтаксис

toLastDayOfWeek(datetime[, mode[, timezone]])

Аргументы

datetime — дата или дата со временем для преобразования. Date или DateTime или Date32 или DateTime64
mode — определяет первый день недели, как описано в функции toWeek(). По умолчанию 0. UInt8
timezone — необязательный параметр. Часовой пояс, используемый для преобразования. Если не указан, используется часовой пояс сервера. String

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

Возвращает дату ближайшей субботы или воскресенья, начиная с указанной даты (включительно), в зависимости от режима. Date или Date32 или DateTime или DateTime64

Примеры

Округление вверх до ближайшей субботы или воскресенья

SELECT
    toLastDayOfWeek(toDateTime('2023-04-21 10:20:30')), /* пятница */
    toLastDayOfWeek(toDateTime('2023-04-21 10:20:30'), 1), /* пятница */
    toLastDayOfWeek(toDate('2023-04-23')), /* воскресенье */
    toLastDayOfWeek(toDate('2023-04-23'), 1) /* воскресенье */
FORMAT Vertical

Строка 1:
──────
toLastDayOfWeek(toDateTime('2023-04-21 10:20:30')):      2023-04-23
toLastDayOfWeek(toDateTime('2023-04-21 10:20:30'), 1):   2023-04-22
toLastDayOfWeek(toDate('2023-04-23')):                   2023-04-23
toLastDayOfWeek(toDate('2023-04-23'), 1):                2023-04-23

toMillisecond

Добавлена в: v24.2

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

Синтаксис

toMillisecond(datetime)

Псевдонимы: MILLISECOND

Аргументы

datetime — дата и время, из которых нужно получить миллисекунду. DateTime или DateTime64

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

Возвращает миллисекунду в минуте (0–59) из datetime. UInt16

Примеры

Пример использования

SELECT toMillisecond(toDateTime64('2023-04-21 10:20:30.456', 3));

┌──toMillisecond(toDateTime64('2023-04-21 10:20:30.456', 3))─┐
│                                                        456 │
└────────────────────────────────────────────────────────────┘

toMinute

Впервые представлен в: v1.1

Возвращает минутную часть (0–59) значения Date или DateTime.

Синтаксис

toMinute(datetime)

Псевдонимы: MINUTE

Аргументы

datetime — значение даты и времени, из которого нужно получить минуту. DateTime или DateTime64

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

Возвращает минуту часа (0–59) из datetime. UInt8

Примеры

Пример использования

SELECT toMinute(toDateTime('2023-04-21 10:20:30'))

┌─toMinute(toDateTime('2023-04-21 10:20:30'))─┐
│                                          20 │
└─────────────────────────────────────────────┘

toModifiedJulianDay

Появилась в версии v21.1

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

Синтаксис

toModifiedJulianDay(date)

Аргументы

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

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

Возвращает число модифицированного юлианского дня. Int32

Примеры

Преобразование даты в число модифицированного юлианского дня

SELECT toModifiedJulianDay('2020-01-01')

┌─toModifiedJulianDay('2020-01-01')─┐
│                             58849 │
└───────────────────────────────────┘

toModifiedJulianDayOrNull

Введена в: v21.1

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

Синтаксис

toModifiedJulianDayOrNull(date)

Аргументы

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

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

Возвращает номер модифицированного юлианского дня для корректной даты date, в противном случае — null. Nullable(Int32)

Примеры

Преобразование даты в модифицированный юлианский день с обработкой значений null

SELECT toModifiedJulianDayOrNull('2020-01-01');
SELECT toModifiedJulianDayOrNull('0000-00-00'); -- недопустимая дата, возвращает NULL

┌─toModifiedJu⋯020-01-01')─┐
│                    58849 │
└──────────────────────────┘
┌─toModifiedJu⋯000-00-00')─┐
│                     ᴺᵁᴸᴸ │
└──────────────────────────┘

toMonday

Добавлена в: v1.1

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

Примечание

Тип возвращаемого значения можно настроить с помощью параметра enable_extended_results_for_datetime_functions.

Синтаксис

toMonday(value)

Аргументы

value — Дата или дата со временем, которую нужно округлить в меньшую сторону до понедельника недели. Date или Date32 или DateTime или DateTime64

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

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

Примеры

Округление даты в меньшую сторону до понедельника недели

SELECT
toMonday(toDateTime('2023-04-21 10:20:30')), -- Пятница
toMonday(toDate('2023-04-24'));              -- Уже понедельник

┌─toMonday(toDateTime('2023-04-21 10:20:30'))─┬─toMonday(toDate('2023-04-24'))─┐
│                                  2023-04-17 │                     2023-04-24 │
└─────────────────────────────────────────────┴────────────────────────────────┘

toMonth

Добавлена в версии: v1.1

Возвращает номер месяца (1–12) из значения типа Date или DateTime.

Синтаксис

toMonth(datetime)

Псевдонимы: MONTH

Аргументы

datetime — Дата или дата и время, из которой нужно получить месяц. Date или Date32 или DateTime или DateTime64

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

Возвращает месяц из указанной даты/времени в виде значения типа UInt8

Примеры

Пример использования

SELECT toMonth(toDateTime('2023-04-21 10:20:30'))

┌─toMonth(toDateTime('2023-04-21 10:20:30'))─┐
│                                          4 │
└────────────────────────────────────────────┘

toMonthNumSinceEpoch

Добавлено в: v25.3

Возвращает количество месяцев, прошедших с 1970 года.

Синтаксис

toMonthNumSinceEpoch(date)

Аргументы

date — дата или дата и время. Date или DateTime или DateTime64

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

Положительное целое число

Примеры

Пример

SELECT toMonthNumSinceEpoch(toDate('2024-10-01'))

toQuarter

Появилась в версии: v1.1

Возвращает квартал года (1–4) для заданного значения Date или DateTime.

Синтаксис

toQuarter(datetime)

Синонимы: QUARTER

Аргументы

datetime — дата или дата и время, для которой определяется квартал года. Date или Date32 или DateTime или DateTime64

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

Возвращает квартал года для указанной даты/времени в виде значения типа UInt8

Примеры

Пример использования

SELECT toQuarter(toDateTime('2023-04-21 10:20:30'))

┌─toQuarter(toDateTime('2023-04-21 10:20:30'))─┐
│                                            2 │
└──────────────────────────────────────────────┘

toRelativeDayNum

Появилась в: v1.1

Преобразует дату или дату со временем в количество дней, прошедших с некоторого фиксированного момента в прошлом. Точная точка отсчёта является деталью реализации, поэтому эта функция не предназначена для самостоятельного использования. Основное назначение функции — вычисление разницы в днях между двумя датами или датами со временем, например, toRelativeDayNum(dt1) - toRelativeDayNum(dt2).

Синтаксис

toRelativeDayNum(date)

Аргументы

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

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

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

Примеры

Получение относительных номеров дней

SELECT toRelativeDayNum(toDate('2023-04-01')) - toRelativeDayNum(toDate('2023-01-01'))

┌─minus(toRela⋯3-01-01')))─┐
│                       90 │
└──────────────────────────┘

toRelativeHourNum

Введена в версии v1.1

Преобразует дату или дату со временем в количество часов, прошедших с некоторого фиксированного момента в прошлом. Точная точка во времени является деталью реализации, поэтому эту функцию не предполагается использовать самостоятельно. Основное назначение функции — вычислять разницу в часах между двумя датами или датами со временем, например, toRelativeHourNum(dt1) - toRelativeHourNum(dt2).

Синтаксис

toRelativeHourNum(date)

Аргументы

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

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

Возвращает количество часов, прошедших с фиксированной точки в прошлом. UInt32

Примеры

Получение относительных значений часа

SELECT toRelativeHourNum(toDateTime('2023-01-01 12:00:00')) - toRelativeHourNum(toDateTime('2023-01-01 00:00:00')) AS hours_difference

┌─hours_difference─┐
│               12 │
└──────────────────┘

toRelativeMinuteNum

Введена в версии: v1.1

Преобразует дату или дату со временем в количество минут, прошедших с некоторого фиксированного момента в прошлом. Точный момент времени является деталью реализации, поэтому эту функцию не предполагается использовать самостоятельно, в отрыве от других. Основное назначение функции — вычисление разницы в минутах между двумя датами или датами со временем, например, toRelativeMinuteNum(dt1) - toRelativeMinuteNum(dt2).

Синтаксис

toRelativeMinuteNum(date)

Аргументы

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

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

Возвращает количество минут, прошедших с фиксированной точки отсчёта в прошлом. UInt32

Примеры

Получение относительных номеров минут

SELECT toRelativeMinuteNum(toDateTime('2023-01-01 00:30:00')) - toRelativeMinuteNum(toDateTime('2023-01-01 00:00:00')) AS minutes_difference

┌─minutes_difference─┐
│                 30 │
└────────────────────┘

toRelativeMonthNum

Появилась в версии: v1.1

Преобразует дату или дату со временем в количество месяцев, прошедших с некоторого фиксированного момента в прошлом. Точный момент времени является деталью реализации, поэтому эта функция не предназначена для самостоятельного использования. Основное назначение функции — вычислять разницу в месяцах между двумя датами или датами со временем, например, toRelativeMonthNum(dt1) - toRelativeMonthNum(dt2).

Синтаксис

toRelativeMonthNum(date)

Аргументы

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

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

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

Примеры

Получение относительных номеров месяцев

SELECT toRelativeMonthNum(toDate('2023-04-01')) - toRelativeMonthNum(toDate('2023-01-01')) AS months_difference

┌─months_difference─┐
│                 3 │
└───────────────────┘

toRelativeQuarterNum

Введена в: v1.1

Преобразует дату или дату со временем в количество кварталов, прошедших с некоторого фиксированного момента в прошлом. Точная точка во времени является деталью реализации, поэтому эта функция не предназначена для использования сама по себе. Основное назначение функции — вычислять разницу в кварталах между двумя датами или датами со временем, например, toRelativeQuarterNum(dt1) - toRelativeQuarterNum(dt2).

Синтаксис

toRelativeQuarterNum(date)

Аргументы

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

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

Возвращает число кварталов, прошедших с фиксированной точки отсчёта в прошлом. UInt32

Примеры

Получение относительных номеров кварталов

SELECT toRelativeQuarterNum(toDate('2023-04-01')) - toRelativeQuarterNum(toDate('2023-01-01')) AS quarters_difference

┌─quarters_difference─┐
│                   1 │
└─────────────────────┘

toRelativeSecondNum

Добавлена в версии v1.1

Преобразует дату или дату со временем в количество секунд, прошедших с некоторого фиксированного момента в прошлом. Точная точка во времени является деталью реализации, поэтому эта функция не предназначена для самостоятельного использования. Основное назначение функции — вычислять разницу в секундах между двумя датами или датами со временем, например, toRelativeSecondNum(dt1) - toRelativeSecondNum(dt2).

Синтаксис

toRelativeSecondNum(date)

Аргументы

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

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

Возвращает количество секунд, прошедших от фиксированной точки отсчёта в прошлом. UInt32

Примеры

Получение относительных значений секунд

SELECT toRelativeSecondNum(toDateTime('2023-01-01 00:01:00')) - toRelativeSecondNum(toDateTime('2023-01-01 00:00:00')) AS seconds_difference

┌─seconds_difference─┐
│                 60 │
└────────────────────┘

toRelativeWeekNum

Добавлена в: v1.1

Преобразует дату или дату со временем в количество недель, прошедших с некоторого фиксированного момента в прошлом. Точный момент времени относится к деталям реализации, поэтому эта функция не предназначена для самостоятельного применения. Основное назначение функции — вычислять разницу в неделях между двумя датами или датами со временем, например, toRelativeWeekNum(dt1) - toRelativeWeekNum(dt2).

Синтаксис

toRelativeWeekNum(date)

Аргументы

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

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

Возвращает количество недель, прошедших с фиксированной точки отсчёта в прошлом. UInt32

Примеры

Получение относительных номеров недель

SELECT toRelativeWeekNum(toDate('2023-01-08')) - toRelativeWeekNum(toDate('2023-01-01')) AS weeks_difference

┌─weeks_difference─┐
│                1 │
└──────────────────┘

toRelativeYearNum

Введена в версии: v1.1

Преобразует дату или дату со временем в количество лет, прошедших с некоторого фиксированного момента в прошлом. Точный момент времени является деталью реализации, поэтому эту функцию не следует использовать самостоятельно. Основное назначение функции — вычисление разницы в годах между двумя датами или датами со временем, например: toRelativeYearNum(dt1) - toRelativeYearNum(dt2).

Синтаксис

toRelativeYearNum(date)

Аргументы

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

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

Возвращает число лет, прошедших с фиксированной точки отсчёта в прошлом. UInt16

Примеры

Получение относительного номера года

SELECT toRelativeYearNum('2010-10-01'::DateTime) - toRelativeYearNum('2000-01-01'::DateTime)

┌─minus(toRela⋯ateTime')))─┐
│                       10 │
└──────────────────────────┘

toSecond

Появилась в версии: v1.1

Возвращает компонент секунд (0–59) значения типа DateTime или DateTime64.

Синтаксис

toSecond(datetime)

Псевдонимы: SECOND

Аргументы

datetime — дата и время, из которых нужно получить секунду. DateTime или DateTime64

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

Возвращает секунду в минуте (0–59) из datetime. UInt8

Примеры

Пример использования

SELECT toSecond(toDateTime('2023-04-21 10:20:30'))

┌─toSecond(toDateTime('2023-04-21 10:20:30'))─┐
│                                          30 │
└─────────────────────────────────────────────┘

toStartOfDay

Добавлена в версии v1.1

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

Примечание

Тип возвращаемого значения можно настроить с помощью параметра enable_extended_results_for_datetime_functions.

Синтаксис

toStartOfDay(datetime)

Аргументы

datetime — дата или дата со временем, которую нужно округлить. Date или DateTime

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

Возвращает дату со временем, округлённую вниз до начала дня. Date или DateTime или Date32 или DateTime64

Примеры

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

SELECT toStartOfDay(toDateTime('2023-04-21 10:20:30'))

┌─toStartOfDay(toDateTime('2023-04-21 10:20:30'))─┐
│                             2023-04-21 00:00:00 │
└─────────────────────────────────────────────────┘

toStartOfFifteenMinutes

Добавлена в версии v1.1

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

Примечание

Тип возвращаемого значения можно настроить с помощью параметра enable_extended_results_for_datetime_functions.

Синтаксис

toStartOfFifteenMinutes(datetime)

Аргументы

datetime — дата или дата со временем для округления. DateTime или DateTime64

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

Возвращает дату со временем, округлённую до начала ближайшего пятнадцатиминутного интервала DateTime или DateTime64

Примеры

Пример

SELECT
    toStartOfFifteenMinutes(toDateTime('2023-04-21 10:17:00')),
    toStartOfFifteenMinutes(toDateTime('2023-04-21 10:20:00')),
    toStartOfFifteenMinutes(toDateTime('2023-04-21 10:23:00'))
FORMAT Vertical

Строка 1:
──────
toStartOfFifteenMinutes(toDateTime('2023-04-21 10:17:00')): 2023-04-21 10:15:00
toStartOfFifteenMinutes(toDateTime('2023-04-21 10:20:00')): 2023-04-21 10:15:00
toStartOfFifteenMinutes(toDateTime('2023-04-21 10:23:00')): 2023-04-21 10:15:00

toStartOfFiveMinutes

Функция появилась в версии: v22.6

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

Примечание

Тип возвращаемого значения можно настроить с помощью настройки enable_extended_results_for_datetime_functions.

Синтаксис

toStartOfFiveMinutes(datetime)

Псевдонимы: toStartOfFiveMinute

Аргументы

datetime — дата и время, которые нужно округлить. DateTime или DateTime64

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

Возвращает дату и время, округлённые до начала ближайшего пятиминутного интервала — DateTime или DateTime64

Примеры

Пример

SELECT
    toStartOfFiveMinutes(toDateTime('2023-04-21 10:17:00')),
    toStartOfFiveMinutes(toDateTime('2023-04-21 10:20:00')),
    toStartOfFiveMinutes(toDateTime('2023-04-21 10:23:00'))
FORMAT Vertical

Строка 1:
──────
toStartOfFiveMinutes(toDateTime('2023-04-21 10:17:00')): 2023-04-21 10:15:00
toStartOfFiveMinutes(toDateTime('2023-04-21 10:20:00')): 2023-04-21 10:20:00
toStartOfFiveMinutes(toDateTime('2023-04-21 10:23:00')): 2023-04-21 10:20:00

toStartOfHour

Добавлена в: v1.1

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

Примечание

Тип возвращаемого значения можно настроить с помощью параметра enable_extended_results_for_datetime_functions.

Синтаксис

toStartOfHour(datetime)

Аргументы

datetime — Дата и время для округления. DateTime или DateTime64

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

Возвращает дату и время, округлённые в меньшую сторону до начала часа. DateTime или DateTime64

Примеры

Округление в меньшую сторону до начала часа

SELECT
    toStartOfHour(toDateTime('2023-04-21 10:20:30'));

┌─────────────────res─┬─toTypeName(res)─┐
│ 2023-04-21 10:00:00 │ DateTime        │
└─────────────────────┴─────────────────┘

toStartOfISOYear

Впервые представлена в: v1.1

Округляет дату или дату со временем вниз до первого дня ISO-года, который может отличаться от календарного года. См. ISO week date.

Примечание

Тип возвращаемого значения можно настроить с помощью параметра enable_extended_results_for_datetime_functions.

Синтаксис

toStartOfISOYear(value)

Аргументы

value — дата или дата и время, которые нужно округлить вниз до первого дня ISO‑года. Date, Date32, DateTime или DateTime64

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

Возвращает первый день ISO‑года для указанной даты или даты и времени. Date

Примеры

Округление вниз до первого дня ISO‑года

SELECT toStartOfISOYear(toDateTime('2023-04-21 10:20:30'))

┌─toStartOfISOYear(toDateTime('2023-04-21 10:20:30'))─┐
│                                          2023-01-02 │
└─────────────────────────────────────────────────────┘

toStartOfInterval

Введена в версии: v20.1

Эта функция обобщает другие функции семейства 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).

Вычисление выполняется относительно определённых опорных моментов времени:

Interval	Start
YEAR	year 0
QUARTER	1900 Q1
MONTH	1900 January
WEEK	1970, 1st week (01-05)
DAY	1970-01-01
HOUR	(*)
MINUTE	1970-01-01 00:00:00
SECOND	1970-01-01 00:00:00
MILLISECOND	1970-01-01 00:00:00
MICROSECOND	1970-01-01 00:00:00
NANOSECOND	1970-01-01 00:00:00
(*) интервалы по часам являются особым случаем: вычисление всегда выполняется относительно 00:00:00 (полуночи) текущих суток. Поэтому полезны только
значения часов в диапазоне от 1 до 23.

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

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

Синтаксис

toStartOfInterval(value, INTERVAL x unit[, time_zone])
toStartOfInterval(value, INTERVAL x unit[, origin[, time_zone]])

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

Аргументы

value — Значение даты или даты и времени для округления вниз. Date или DateTime или DateTime64
x — Числовое значение длины интервала. - unit — Единица интервала: YEAR, QUARTER, MONTH, WEEK, DAY, HOUR, MINUTE, SECOND, MILLISECOND, MICROSECOND, NANOSECOND. - time_zone — Необязательный параметр. Название часового пояса в виде строки. - origin — Необязательный параметр. Начальная точка отсчёта для вычисления (только для второй перегрузки).

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

Возвращает начало интервала, содержащего исходное значение. DateTime

Примеры

Базовое округление по интервалам

SELECT toStartOfInterval(toDateTime('2023-01-15 14:30:00'), INTERVAL 1 MONTH)

┌─toStartOfInt⋯alMonth(1))─┐
│               2023-01-01 │
└──────────────────────────┘

Использование отправной точки

SELECT toStartOfInterval(toDateTime('2023-01-01 14:45:00'), INTERVAL 1 MINUTE, toDateTime('2023-01-01 14:35:30'))

┌─toStartOfInt⋯14:35:30'))─┐
│      2023-01-01 14:44:30 │
└──────────────────────────┘

toStartOfMicrosecond

Появилась в версии: v22.6

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

Синтаксис

toStartOfMicrosecond(datetime[, timezone])

Аргументы

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

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

Исходное значение в формате DateTime64 с точностью до субмикросекунд

Примеры

Запрос без указания часового пояса

WITH toDateTime64('2020-01-01 10:20:30.999999999', 9) AS dt64
SELECT toStartOfMicrosecond(dt64);

┌────toStartOfMicrosecond(dt64)─┐
│ 2020-01-01 10:20:30.999999000 │
└───────────────────────────────┘

Запрос с указанием часового пояса

WITH toDateTime64('2020-01-01 10:20:30.999999999', 9) AS dt64
SELECT toStartOfMicrosecond(dt64, 'Asia/Istanbul');

┌─toStartOfMicrosecond(dt64, 'Asia/Istanbul')─┐
│               2020-01-01 12:20:30.999999000 │
└─────────────────────────────────────────────┘

toStartOfMillisecond

Введена в версии: v22.6

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

Синтаксис

toStartOfMillisecond(datetime[, timezone])

Аргументы

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

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

Исходное значение с субмиллисекундной точностью. DateTime64

Примеры

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

WITH toDateTime64('2020-01-01 10:20:30.999999999', 9) AS dt64
SELECT toStartOfMillisecond(dt64);

┌────toStartOfMillisecond(dt64)─┐
│ 2020-01-01 10:20:30.999000000 │
└───────────────────────────────┘

Запрос с учётом часового пояса

WITH toDateTime64('2020-01-01 10:20:30.999999999', 9) AS dt64
SELECT toStartOfMillisecond(dt64, 'Asia/Istanbul');

┌─toStartOfMillisecond(dt64, 'Asia/Istanbul')─┐
│               2020-01-01 12:20:30.999000000 │
└─────────────────────────────────────────────┘

toStartOfMinute

Добавлена в версии: v1.1

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

Примечание

Тип возвращаемого значения можно настроить с помощью настройки enable_extended_results_for_datetime_functions.

Синтаксис

toStartOfMinute(datetime)

Аргументы

datetime — Дата и время, которые нужно округлить. DateTime или DateTime64

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

Возвращает дату и время, округлённые вниз до начала минуты. DateTime или DateTime64

Примеры

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

SELECT
    toStartOfMinute(toDateTime('2023-04-21 10:20:30')),
    toStartOfMinute(toDateTime64('2023-04-21 10:20:30.5300', 8))
FORMAT Vertical

Строка 1:
──────
toStartOfMinute(toDateTime('2023-04-21 10:20:30')):           2023-04-21 10:20:00
toStartOfMinute(toDateTime64('2023-04-21 10:20:30.5300', 8)): 2023-04-21 10:20:00

toStartOfMonth

Впервые представлена в: v1.1

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

Примечание

Тип возвращаемого значения можно настроить с помощью параметра enable_extended_results_for_datetime_functions.

Синтаксис

toStartOfMonth(value)

Аргументы

value — дата или дата со временем, которую нужно округлить вниз до первого дня месяца. Date или Date32 или DateTime или DateTime64

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

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

Примеры

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

SELECT toStartOfMonth(toDateTime('2023-04-21 10:20:30'))

┌─toStartOfMonth(toDateTime('2023-04-21 10:20:30'))─┐
│                                        2023-04-01 │
└───────────────────────────────────────────────────┘

toStartOfNanosecond

Впервые представлена в версии v22.6

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

Синтаксис

toStartOfNanosecond(datetime[, timezone])

Аргументы

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

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

Входное значение с наносекундной точностью. DateTime64

Примеры

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

WITH toDateTime64('2020-01-01 10:20:30.999999999', 9) AS dt64
SELECT toStartOfNanosecond(dt64);

┌─────toStartOfNanosecond(dt64)─┐
│ 2020-01-01 10:20:30.999999999 │
└───────────────────────────────┘

Запрос с учётом часового пояса

WITH toDateTime64('2020-01-01 10:20:30.999999999', 9) AS dt64
SELECT toStartOfNanosecond(dt64, 'Asia/Istanbul');

┌─toStartOfNanosecond(dt64, 'Asia/Istanbul')─┐
│              2020-01-01 12:20:30.999999999 │
└────────────────────────────────────────────┘

toStartOfQuarter

Добавлено в: v1.1

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

Примечание

Тип возвращаемого значения можно настроить установкой параметра enable_extended_results_for_datetime_functions.

Синтаксис

toStartOfQuarter(value)

Аргументы

value — Дата или дата со временем, которую нужно округлить вниз до первого дня квартала. Date или Date32 или DateTime или DateTime64

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

Возвращает первый день квартала для заданной даты или даты со временем. Date

Примеры

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

SELECT toStartOfQuarter(toDateTime('2023-04-21 10:20:30'))

┌─toStartOfQuarter(toDateTime('2023-04-21 10:20:30'))─┐
│                                          2023-04-01 │
└─────────────────────────────────────────────────────┘

toStartOfSecond

Функция введена в версии: v20.5

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

Синтаксис

toStartOfSecond(datetime[, timezone])

Аргументы

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

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

Возвращает исходное значение без долей секунды. DateTime64

Примеры

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

WITH toDateTime64('2020-01-01 10:20:30.999', 3) AS dt64
SELECT toStartOfSecond(dt64);

┌───toStartOfSecond(dt64)─┐
│ 2020-01-01 10:20:30.000 │
└─────────────────────────┘

Запрос с учётом часового пояса

WITH toDateTime64('2020-01-01 10:20:30.999', 3) AS dt64
SELECT toStartOfSecond(dt64, 'Asia/Istanbul');

┌─toStartOfSecond(dt64, 'Asia/Istanbul')─┐
│                2020-01-01 13:20:30.000 │
└────────────────────────────────────────┘

toStartOfTenMinutes

Появилась в версии: v20.1

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

Примечание

Тип возвращаемого значения можно настроить с помощью параметра enable_extended_results_for_datetime_functions.

Синтаксис

toStartOfTenMinutes(datetime)

Аргументы

datetime — дата и время, значение типа DateTime или DateTime64

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

Возвращает дату и время, округлённые до начала ближайшего десятиминутного интервала, в виде значения типа DateTime или DateTime64

Примеры

Пример

SELECT
    toStartOfTenMinutes(toDateTime('2023-04-21 10:17:00')),
    toStartOfTenMinutes(toDateTime('2023-04-21 10:20:00')),
    toStartOfTenMinutes(toDateTime('2023-04-21 10:23:00'))
FORMAT Vertical

Строка 1:
──────
toStartOfTenMinutes(toDateTime('2023-04-21 10:17:00')): 2023-04-21 10:10:00
toStartOfTenMinutes(toDateTime('2023-04-21 10:20:00')): 2023-04-21 10:20:00
toStartOfTenMinutes(toDateTime('2023-04-21 10:23:00')): 2023-04-21 10:20:00

toStartOfWeek

Добавлена в версии v20.1

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

Примечание

Тип возвращаемого значения можно настроить с помощью параметра enable_extended_results_for_datetime_functions.

Синтаксис

toStartOfWeek(datetime[, mode[, timezone]])

Аргументы

datetime — Дата или дата со временем для преобразования. Date или DateTime или Date32 или DateTime64
mode — Определяет первый день недели, как описано в функции toWeek(). По умолчанию — 0. UInt8
timezone — Часовой пояс, используемый для преобразования. Если не указан, используется часовой пояс сервера. String

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

Возвращает дату ближайшего воскресенья или понедельника, приходящуюся на указанную дату или предшествующую ей, в зависимости от режима Date или Date32 или DateTime или DateTime64

Примеры

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

SELECT
        toStartOfWeek(toDateTime('2023-04-21 10:20:30')), /* пятница */
        toStartOfWeek(toDateTime('2023-04-21 10:20:30'), 1), /* пятница */
        toStartOfWeek(toDate('2023-04-24')), /* понедельник */
        toStartOfWeek(toDate('2023-04-24'), 1) /* понедельник */
    FORMAT Vertical

Строка 1:
    ──────
    toStartOfWeek(toDateTime('2023-04-21 10:20:30')):      2023-04-17
    toStartOfWeek(toDateTime('2023-04-21 10:20:30'), 1):   2023-04-17
    toStartOfWeek(toDate('2023-04-24')):                   2023-04-24
    toStartOfWeek(toDate('2023-04-24'), 1):                2023-04-24

toStartOfYear

Добавлена в: v1.1

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

Примечание

Тип возвращаемого значения можно настроить с помощью параметра enable_extended_results_for_datetime_functions.

Синтаксис

toStartOfYear(value)

Аргументы

value — Дата или дата со временем, которую нужно округлить вниз. Date или Date32 или DateTime или DateTime64

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

Возвращает первый день года для заданной даты/времени в формате Date

Примеры

Округление вниз до первого дня года

SELECT toStartOfYear(toDateTime('2023-04-21 10:20:30'))

┌─toStartOfYear(toDateTime('2023-04-21 10:20:30'))─┐
│                                       2023-01-01 │
└──────────────────────────────────────────────────┘

toTimeWithFixedDate

Введена в версии: v1.1

Извлекает временную компоненту из даты или даты со временем. Возвращаемый результат представляет собой смещение от фиксированной точки во времени, в данный момент 1970-01-02, но конкретная точка во времени является деталью реализации и может измениться в будущем.

Поэтому toTime не следует использовать самостоятельно. Основное назначение функции — вычислять разницу во времени между двумя датами или датами со временем, например, toTime(dt1) - toTime(dt2).

Синтаксис

toTime(date[, timezone])

Аргументы

date — Дата, которую нужно преобразовать во время. Date или DateTime или DateTime64
timezone — Необязательный аргумент. Часовой пояс для возвращаемого значения. String

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

Возвращает временную составляющую даты или даты со временем в виде смещения от фиксированной точки во времени (на данный момент выбрана 1970-01-02). DateTime

Примеры

Вычисление разницы во времени между двумя датами

SELECT toTime('2025-06-15 12:00:00'::DateTime) - toTime('2024-05-10 11:00:00'::DateTime) AS result, toTypeName(result)

┌─result─┬─toTypeName(result)─┐
│   3600 │ Int32              │
└────────┴────────────────────┘

toTimezone

Добавлена в: v1.1

Преобразует DateTime или DateTime64 в указанную часовую зону. Внутреннее значение данных (количество секунд Unix) не изменяется. Изменяются только атрибут часовой зоны значения и его строковое представление.

Синтаксис

toTimeZone(datetime, timezone)

Псевдонимы: toTimeZone

Аргументы

date — значение для преобразования. DateTime или DateTime64
timezone — имя целевого часового пояса. String

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

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

Примеры

Пример использования

SELECT toDateTime('2019-01-01 00:00:00', 'UTC') AS time_utc,
toTypeName(time_utc) AS type_utc,
toInt32(time_utc) AS int32utc,
toTimeZone(time_utc, 'Asia/Yekaterinburg') AS time_yekat,
toTypeName(time_yekat) AS type_yekat,
toInt32(time_yekat) AS int32yekat,
toTimeZone(time_utc, 'US/Samoa') AS time_samoa,
toTypeName(time_samoa) AS type_samoa,
toInt32(time_samoa) AS int32samoa
FORMAT Vertical;

Строка 1:
──────
time_utc:   2019-01-01 00:00:00
type_utc:   DateTime('UTC')
int32utc:   1546300800
time_yekat: 2019-01-01 05:00:00
type_yekat: DateTime('Asia/Yekaterinburg')
int32yekat: 1546300800
time_samoa: 2018-12-31 13:00:00
type_samoa: DateTime('US/Samoa')
int32samoa: 1546300800

toUTCTimestamp

Добавлена в: v23.8

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

Синтаксис

toUTCTimestamp(datetime, time_zone)

Псевдонимы: to_utc_timestamp

Аргументы

datetime — Константное значение или выражение типа дата или дата и время. DateTime или DateTime64
time_zone — Константное значение или выражение строкового типа, представляющее часовой пояс. String

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

Возвращает дату или дату и время в часовом поясе UTC. DateTime или DateTime64

Примеры

Преобразование часового пояса в UTC

SELECT toUTCTimestamp(toDateTime('2023-03-16'), 'Asia/Shanghai')

┌─toUTCTimestamp(toDateTime('2023-03-16'), 'Asia/Shanghai')─┐
│                                     2023-03-15 16:00:00 │
└─────────────────────────────────────────────────────────┘

toUnixTimestamp

Добавлено в версии: v1.1

Преобразует String, Date или DateTime в метку времени Unix (количество секунд с 1970-01-01 00:00:00 UTC) типа UInt32.

Синтаксис

toUnixTimestamp(date[, timezone])

Аргументы

date — значение для преобразования. Date или Date32 или DateTime или DateTime64 или String
timezone — необязательный параметр. Часовой пояс, используемый для преобразования. Если не указан, используется часовой пояс сервера. String

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

Возвращает метку времени Unix. UInt32

Примеры

Пример использования

SELECT
'2017-11-05 08:07:47' AS dt_str,
toUnixTimestamp(dt_str) AS from_str,
toUnixTimestamp(dt_str, 'Asia/Tokyo') AS from_str_tokyo,
toUnixTimestamp(toDateTime(dt_str)) AS from_datetime,
toUnixTimestamp(toDateTime64(dt_str, 0)) AS from_datetime64,
toUnixTimestamp(toDate(dt_str)) AS from_date,
toUnixTimestamp(toDate32(dt_str)) AS from_date32
FORMAT Vertical;

Строка 1:
──────
dt_str:          2017-11-05 08:07:47
from_str:        1509869267
from_str_tokyo:  1509836867
from_datetime:   1509869267
from_datetime64: 1509869267
from_date:       1509840000
from_date32:     1509840000

toWeek

Добавлена в версии: v20.1

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

Функция совместимости toISOWeek() эквивалентна вызову toWeek(date,3).

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

Mode	Первый день недели	Диапазон	Неделя 1 — это первая неделя ...
0	Sunday	0-53	с воскресеньем в этом году
1	Monday	0-53	с 4 или более днями в этом году
2	Sunday	1-53	с воскресеньем в этом году
3	Monday	1-53	с 4 или более днями в этом году
4	Sunday	0-53	с 4 или более днями в этом году
5	Monday	0-53	с понедельником в этом году
6	Sunday	1-53	с 4 или более днями в этом году
7	Monday	1-53	с понедельником в этом году
8	Sunday	1-53	содержащая 1 января
9	Monday	1-53	содержащая 1 января

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

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

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

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

Синтаксис

toWeek(datetime[, mode[, time_zone]])

Псевдонимы: week

Аргументы

datetime — дата или дата со временем, из которой нужно получить номер недели. Date или DateTime
mode — необязательный параметр. Режим 0–9 определяет первый день недели и диапазон номера недели. Значение по умолчанию — 0.
time_zone — необязательный параметр. Часовой пояс. String

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

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

Примеры

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

SELECT toDate('2016-12-27') AS date, toWeek(date) AS week0, toWeek(date,1) AS week1, toWeek(date,9) AS week9

┌───────date─┬─week0─┬─week1─┬─week9─┐
│ 2016-12-27 │    52 │    52 │     1 │
└────────────┴───────┴───────┴───────┘

toYYYYMM

Добавлено в: v1.1

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

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

Синтаксис

toYYYYMM(datetime[, timezone])

Аргументы

datetime — дата или дата со временем для преобразования. Date или Date32 или DateTime или DateTime64
timezone — необязательный аргумент. Часовой пояс для преобразования. Если указан, часовой пояс должен быть строковой константой. String

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

Возвращает число типа UInt32, содержащее год и номер месяца (YYYY * 100 + MM). UInt32

Примеры

Преобразование текущей даты в формат YYYYMM

SELECT toYYYYMM(now(), 'US/Eastern')

┌─toYYYYMM(now(), 'US/Eastern')─┐
│                        202303 │
└───────────────────────────────┘

toYYYYMMDD

Добавлена в версии: v1.1

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

Синтаксис

toYYYYMMDD(datetime[, timezone])

Аргументы

datetime — Дата или дата со временем для преобразования. Date или Date32 или DateTime или DateTime64
timezone — Необязательный параметр. Часовой пояс, используемый для преобразования. Если указан, часовой пояс должен быть строковой константой. String

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

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

Примеры

Преобразование текущей даты в формат YYYYMMDD

SELECT toYYYYMMDD(now(), 'US/Eastern')

┌─toYYYYMMDD(now(), 'US/Eastern')─┐
│                        20230302 │
└─────────────────────────────────┘

toYYYYMMDDhhmmss

Введена в: v1.1

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

Синтаксис

toYYYYMMDDhhmmss(datetime[, timezone])

Аргументы

datetime — дата или дата со временем для преобразования. Date или Date32 или DateTime или DateTime64
timezone — необязательный параметр. Часовой пояс, используемый при преобразовании. Если он указан, часовой пояс должен быть строковой константой. String

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

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

Примеры

Преобразование текущей даты и времени в формат YYYYMMDDhhmmss

SELECT toYYYYMMDDhhmmss(now(), 'US/Eastern')

┌─toYYYYMMDDhhmmss(now(), 'US/Eastern')─┐
│                        20230302112209 │
└───────────────────────────────────────┘

toYear

Добавлена в версии v1.1

Возвращает компонент года (н. э.) значения типа Date или DateTime.

Синтаксис

toYear(datetime)

Псевдонимы: YEAR

Аргументы

datetime — дата или дата и время, из которых нужно получить год. Date или Date32, или DateTime, или DateTime64

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

Возвращает год для заданного значения типов Date или DateTime в виде UInt16

Примеры

Пример использования

SELECT toYear(toDateTime('2023-04-21 10:20:30'))

┌─toYear(toDateTime('2023-04-21 10:20:30'))─┐
│                                     2023  │
└───────────────────────────────────────────┘

toYearNumSinceEpoch

Добавлена в версии: v25.3

Возвращает количество лет, прошедших с 1970 года.

Синтаксис

toYearNumSinceEpoch(date)

Аргументы

date — Дата или дата и время для преобразования. Date или DateTime или DateTime64

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

Целое положительное число

Примеры

Пример

SELECT toYearNumSinceEpoch(toDate('2024-10-01'))

toYearWeek

Введена в: v20.1

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

Аргумент mode работает так же, как аргумент mode у функции toWeek().

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

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

Синтаксис

toYearWeek(datetime[, mode[, timezone]])

Псевдонимы: yearweek

Аргументы

datetime — дата или дата и время, для которой нужно получить год и номер недели. Date или DateTime
mode — необязательный параметр. Режим 0–9 определяет первый день недели и диапазон номеров недель. По умолчанию 0.
timezone — необязательный параметр. Часовой пояс. String

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

Возвращает год и номер недели в виде одного целочисленного значения. UInt32

Примеры

Получение комбинаций год-неделя с различными режимами

SELECT toDate('2016-12-27') AS date, toYearWeek(date) AS yearWeek0, toYearWeek(date,1) AS yearWeek1, toYearWeek(date,9) AS yearWeek9, toYearWeek(toDate('2022-01-01')) AS prev_yearWeek

┌───────date─┬─yearWeek0─┬─yearWeek1─┬─yearWeek9─┬─prev_yearWeek─┐
│ 2016-12-27 │    201652 │    201652 │    201701 │        202152 │
└────────────┴───────────┴───────────┴───────────┴───────────────┘

today

Добавлена в v1.1

Возвращает текущую дату на момент анализа запроса. То же, что toDate(now()).

Синтаксис

today()

Псевдонимы: curdate, current_date

Аргументы

Отсутствуют.

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

Возвращает текущую дату Date

Примеры

Пример использования

SELECT today() AS today, curdate() AS curdate, current_date() AS current_date FORMAT Pretty

┏━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━━━┓
┃      today ┃    curdate ┃ current_date ┃
┡━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━━━┩
│ 2025-03-03 │ 2025-03-03 │   2025-03-03 │
└────────────┴────────────┴──────────────┘

yesterday

Введена в: v1.1

Не принимает аргументов и возвращает вчерашнюю дату на одном из этапов анализа запроса.

Синтаксис

yesterday()

Аргументы

Нет.

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

Возвращает дату за вчерашний день. Date

Примеры

Получение вчерашней даты

SELECT yesterday();
SELECT today() - 1;

┌─yesterday()─┐
│  2025-06-09 │
└─────────────┘
┌─minus(today(), 1)─┐
│        2025-06-09 │
└───────────────────┘

UTCTimestamp​

YYYYMMDDToDate​

YYYYMMDDToDate32​

YYYYMMDDhhmmssToDateTime​

YYYYMMDDhhmmssToDateTime64​

addDate​

addDays​

addHours​

addInterval​

addMicroseconds​

addMilliseconds​

addMinutes​

addMonths​

addNanoseconds​

addQuarters​

addSeconds​

addTupleOfIntervals​

addWeeks​

addYears​

age​

changeDay​

changeHour​

changeMinute​

changeMonth​

changeSecond​

changeYear​

dateDiff​

dateName​

dateTrunc​

formatDateTime​

formatDateTimeInJodaSyntax​

fromDaysSinceYearZero​

fromDaysSinceYearZero32​

fromModifiedJulianDay​

fromModifiedJulianDayOrNull​

fromUTCTimestamp​

fromUnixTimestamp​

fromUnixTimestampInJodaSyntax​

makeDate​

makeDate32​

makeDateTime​

makeDateTime64​

monthName​

now​

now64​

nowInBlock​

nowInBlock64​

serverTimezone​

subDate​

subtractDays​

subtractHours​

subtractInterval​

subtractMicroseconds​

subtractMilliseconds​

subtractMinutes​

subtractMonths​

subtractNanoseconds​

subtractQuarters​

subtractSeconds​

subtractTupleOfIntervals​

subtractWeeks​

subtractYears​

timeDiff​

timeSlot​

timeSlots​

timestamp​

timezone​

timezoneOf​

timezoneOffset​

toDayOfMonth​

toDayOfWeek​

toDayOfYear​

toDaysSinceYearZero​

toHour​

toISOYear​

toLastDayOfMonth​

toLastDayOfWeek​

toMillisecond​

toMinute​

toModifiedJulianDay​

UTCTimestamp

YYYYMMDDToDate

YYYYMMDDToDate32

YYYYMMDDhhmmssToDateTime

YYYYMMDDhhmmssToDateTime64

addDate

addDays

addHours

addInterval

addMicroseconds

addMilliseconds

addMinutes

addMonths

addNanoseconds

addQuarters

addSeconds

addTupleOfIntervals

addWeeks

addYears

age

changeDay

changeHour

changeMinute

changeMonth

changeSecond

changeYear

dateDiff

dateName

dateTrunc

formatDateTime

formatDateTimeInJodaSyntax

fromDaysSinceYearZero

fromDaysSinceYearZero32

fromModifiedJulianDay

fromModifiedJulianDayOrNull

fromUTCTimestamp

fromUnixTimestamp

fromUnixTimestampInJodaSyntax

makeDate

makeDate32

makeDateTime

makeDateTime64

monthName

now

now64

nowInBlock

nowInBlock64

serverTimezone

subDate

subtractDays

subtractHours

subtractInterval

subtractMicroseconds

subtractMilliseconds

subtractMinutes

subtractMonths

subtractNanoseconds

subtractQuarters

subtractSeconds

subtractTupleOfIntervals

subtractWeeks

subtractYears

timeDiff

timeSlot

timeSlots

timestamp

timezone

timezoneOf

timezoneOffset

toDayOfMonth

toDayOfWeek

toDayOfYear

toDaysSinceYearZero

toHour

toISOYear

toLastDayOfMonth

toLastDayOfWeek

toMillisecond

toMinute

toModifiedJulianDay