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

Большинство функций в этом разделе принимают необязательный аргумент часового пояса, например 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(). Результат не определён, если входное значение не представляет собой корректное значение типа Date.

Синтаксис

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 на основе переданных аргументов. 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 — количество кварталов, на которое увеличивается 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
    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 — Тип интервала для результата.

Единица	Допустимые значения
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

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

Синтаксис

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

Изменяет месяц в значении типа Date или DateTime.

Синтаксис

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

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

Синтаксис

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, TIMESTAMP_DIFF, DATE_DIFF, date_diff, timestamp_diff

Аргументы

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

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 — Тип интервала, до границы которого усекается результат. Возможные значения: 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		с точностью (scale) 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 использует стиль формата даты/времени MySQL, см. документацию MySQL.

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

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

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

Placeholder	Description	Example
%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 выводит столько цифр, сколько задано масштабом (scale) 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	weekyear (пока не поддерживается)	год	1996
w	номер недели в weekyear (пока не поддерживается)	число	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

Примеры

Форматирование даты и времени с использованием синтаксиса 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

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

Вычисление аналогично функции 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 — номер модифицированного юлианского дня (Modified Julian 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)

Примеры

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

SELECT fromModifiedJulianDayOrNull(58849);
SELECT fromModifiedJulianDayOrNull(60000000); -- invalid argument, returns 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 для timestamp, при вызове с двумя или тремя аргументами — строку (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

Примеры

DateTime из year, month, day, hour, minute, second

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 из year, month, day, hour, minute, second

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 — количество часов, на которое нужно уменьшить значение 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
    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 — количество месяцев, которое нужно вычесть. (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 — количество секунд, которое нужно вычесть. (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 — количество недель, которое нужно вычесть. (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 — Время, которое нужно округлить до начала интервала продолжительностью 30 минут. DateTime или Date32 или DateTime64
time_zone — Необязательный параметр. Константное значение типа String или выражение, задающее часовой пояс. String

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

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

Примеры

Округление времени до 30-минутного интервала

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 масштаб возвращаемого значения может отличаться от масштаба 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	First day of week	Range
0	Monday	1–7: понедельник = 1, вторник = 2, ..., воскресенье = 7
1	Monday	0–6: понедельник = 0, вторник = 1, ..., воскресенье = 6
2	Sunday	0–6: воскресенье = 0, понедельник = 1, ..., суббота = 6
3	Sunday	1–7: воскресенье = 1, понедельник = 2, ..., суббота = 7

Синтаксис

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

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

Аргументы

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

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

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

Примеры

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

-- The following date is April 21, 2023, which was a Friday:
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.

Расчёт выполняется так же, как и в функции MySQL TO_DAYS.

Синтаксис

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 │
└───────────────────────────────────────────┘

toISOWeek

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

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

Это функция совместимости, эквивалентная toWeek(date, 3). ISO‑недели начинаются с понедельника, а первая неделя года — это неделя, содержащая 4 января. Согласно ISO 8601, номера недель находятся в диапазоне от 1 до 53.

Обратите внимание, что даты, близкие к началу или концу года, могут возвращать номер недели из предыдущего или следующего года. Например, 29 декабря 2025 года вернёт номер недели 1, потому что эта дата попадает в первую неделю, которая содержит 4 января 2026 года.

Синтаксис

toISOWeek(datetime[, timezone])

Аргументы

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

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

Возвращает номер недели по стандарту ISO 8601. Возвращает число от 1 до 53. UInt8

Примеры

Получение номеров ISO-недель

SELECT toDate('2016-12-27') AS date, toISOWeek(date) AS isoWeek

┌───────date─┬─isoWeek─┐
│ 2016-12-27 │      52 │
└────────────┴─────────┘

ISO‑неделя может относиться к другому году

SELECT toDate('2025-12-29') AS date, toISOWeek(date) AS isoWeek, toYear(date) AS year

┌───────date─┬─isoWeek─┬─year─┐
│ 2025-12-29 │       1 │ 2025 │
└────────────┴─────────┴──────┘

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')), /* a Friday */
    toLastDayOfWeek(toDateTime('2023-04-21 10:20:30'), 1), /* a Friday */
    toLastDayOfWeek(toDate('2023-04-23')), /* a Sunday */
    toLastDayOfWeek(toDate('2023-04-23'), 1) /* a Sunday */
FORMAT Vertical

Row 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

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

Синтаксис

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'); -- invalid date, returns 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')), -- A Friday
toMonday(toDate('2023-04-24'));              -- Already a Monday

┌─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

Row 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

Row 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	год 0
QUARTER	1900 Q1
MONTH	январь 1900
WEEK	1970, 1-я неделя (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

Row 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

Row 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')), /* a Friday */
        toStartOfWeek(toDateTime('2023-04-21 10:20:30'), 1), /* a Friday */
        toStartOfWeek(toDate('2023-04-24')), /* a Monday */
        toStartOfWeek(toDate('2023-04-24'), 1) /* a Monday */
    FORMAT Vertical

Row 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;

Row 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;

Row 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	Первый день недели	Диапазон	Неделя 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 января

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

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

Для значений режима со смыслом "содержит 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​

toISOWeek​

toISOYear​

toLastDayOfMonth​

toLastDayOfWeek​

toMillisecond​

toMinute​

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

toISOWeek

toISOYear

toLastDayOfMonth

toLastDayOfWeek

toMillisecond

toMinute