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

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

Пример

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

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

UTCTimestamp

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

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

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

Синтаксис

UTCTimestamp()

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

Аргументы

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

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

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

Примеры

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

SELECT UTCTimestamp()

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

YYYYMMDDToDate

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

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

Синтаксис

YYYYMMDDToDate(YYYYMMDD)

Аргументы

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

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

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

Примеры

Пример

SELECT YYYYMMDDToDate(20230911);

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

YYYYMMDDToDate32

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

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

Синтаксис

YYYYMMDDToDate32(YYYYMMDD)

Аргументы

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

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

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

Примеры

Пример

SELECT YYYYMMDDToDate32(20000507);

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

YYYYMMDDhhmmssToDateTime

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

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

Синтаксис

YYYYMMDDhhmmssToDateTime(YYYYMMDDhhmmss[, timezone])

Аргументы

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

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

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

Примеры

Пример

SELECT YYYYMMDDToDateTime(20230911131415);

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

YYYYMMDDhhmmssToDateTime64

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

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

Синтаксис

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

Аргументы

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

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

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

Примеры

Пример

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

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

addDate

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

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

Синтаксис

addDate(datetime, interval)

Аргументы

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

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

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

Примеры

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

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

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

addDays

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

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

Синтаксис

addDays(datetime, num)

Аргументы

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

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

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

Примеры

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

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

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

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

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

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

addHours

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

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

Синтаксис

addHours(datetime, num)

Аргументы

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

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

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

Примеры

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

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

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

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

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

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

addInterval

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

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

Примечание

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

Синтаксис

addInterval(interval_1, interval_2)

Аргументы

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

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

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

Примеры

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

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

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

addMicroseconds

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

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

Синтаксис

addMicroseconds(datetime, num)

Аргументы

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

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

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

Примеры

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

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

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

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

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

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

addMilliseconds

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

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

Синтаксис

addMilliseconds(datetime, num)

Аргументы

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

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

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

Примеры

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

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

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

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

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

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

addMinutes

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

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

Синтаксис

addMinutes(datetime, num)

Аргументы

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

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

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

Примеры

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

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

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

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

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

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

addMonths

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

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

Синтаксис

addMonths(datetime, num)

Аргументы

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

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

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

Примеры

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

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

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

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

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

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

addNanoseconds

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

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

Синтаксис

addNanoseconds(datetime, num)

Аргументы

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

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

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

Примеры

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

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

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

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

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

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

addQuarters

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

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

Синтаксис

addQuarters(datetime, num)

Аргументы

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

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

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

Примеры

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

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

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

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

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

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

addSeconds

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

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

Синтаксис

addSeconds(datetime, num)

Аргументы

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

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

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

Примеры

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

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

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

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

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

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

addTupleOfIntervals

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

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

Синтаксис

addTupleOfIntervals(datetime, intervals)

Аргументы

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

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

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

Примеры

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

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

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

addWeeks

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

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

Синтаксис

addWeeks(datetime, num)

Аргументы

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

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

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

Примеры

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

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

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

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

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

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

addYears

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

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

Синтаксис

addYears(datetime, num)

Аргументы

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

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

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

Примеры

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

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

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

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

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

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

age

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

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

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

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

Синтаксис

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

Аргументы

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

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

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

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

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

Примеры

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

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

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

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

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

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

changeDay

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

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

Синтаксис

changeDay(date_or_datetime, value)

Аргументы

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

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

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

Примеры

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

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

2024-01-15 00:00:00

changeHour

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

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

Синтаксис

changeHour(date_or_datetime, value)

Аргументы

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

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

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

Примеры

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

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

2024-01-01 05:00:00

changeMinute

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

Изменяет минутную часть значения типа date или date time.

Синтаксис

changeMinute(date_or_datetime, value)

Аргументы

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

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

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

Примеры

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

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

2024-01-01 12:45:00

changeMonth

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

Изменяет месячную часть значения типа 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(единица, дата_начала, дата_окончания[, часовой_пояс])

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

Аргументы

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

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

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

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

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

Примеры

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

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

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

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

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

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

dateName

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

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

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

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

Синтаксис

dateName(date_part, date[, timezone])

Аргументы

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

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

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

Примеры

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

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

┌─dateName('year', date_value)─┬─dateName('month', date_value)─┬─dateName('day', date_value)─┐
│ 2021                         │ Апрель                        │ 14                          │
└──────────────────────────────┴───────────────────────────────┴─────────────────────────────┘

dateTrunc

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

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

Синтаксис

dateTrunc(unit, datetime[, timezone])

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

Аргументы

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

Единица	Совместимость
`nanosecond`	Поддерживается только для DateTime64
`microsecond`	Поддерживается только для DateTime64
`millisecond`	Поддерживается только для DateTime64
`second`
`minute`
`hour`
`day`
`week`
`month`
`quarter`
`year`
`String`

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

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

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

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

Примеры

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

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

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

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

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

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

formatDateTime

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

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

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

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

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

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

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

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

Синтаксис

formatDateTime(datetime, format[, timezone])

Синонимы: DATE_FORMAT

Аргументы

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

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

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

Примеры

Форматирование даты с плейсхолдером года

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

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

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

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

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

Формат с указанием часового пояса

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

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

formatDateTimeInJodaSyntax

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

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

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

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

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

Placeholder	Описание	Представление	Примеры
G	эра	текст	AD
C	век эры (>=0)	число	20
Y	год эры (>=0)	год	1996
x	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

Примеры

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

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

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

fromDaysSinceYearZero

Введено в версии v23.11

Для заданного количества дней, прошедших с 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 — номер модифицированного юлианского дня. (U)Int*

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

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

Примеры

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

SELECT fromModifiedJulianDay(58849)

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

fromModifiedJulianDayOrNull

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

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

Синтаксис

fromModifiedJulianDayOrNull(day)

Аргументы

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

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

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

Примеры

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

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

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

fromUTCTimestamp

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

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

Синтаксис

fromUTCTimestamp(datetime, time_zone)

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

Аргументы

datetime — константа типа дата или дата со временем либо выражение. DateTime или DateTime64
time_zone — константа типа String или выражение, задающее часовой пояс. 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. В этом случае используется стиль формата datetime из MySQL.

Синтаксис

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

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

Аргументы

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

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

При вызове с одним аргументом возвращает значение DateTime, соответствующее временной метке, при вызове с двумя или тремя аргументами — строку String. DateTime или String

Примеры

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

SELECT fromUnixTimestamp(423543535)

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

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

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

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

fromUnixTimestampInJodaSyntax

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

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

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

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

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

Синтаксис

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

Аргументы

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

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

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

Примеры

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

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

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

makeDate

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

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

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

Синтаксис

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

Аргументы

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

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

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

Примеры

Дата по году, месяцу и дню

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

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

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

SELECT makeDate(2023, 42) AS date;

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

makeDate32

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

Создаёт Date32 из:

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

Синтаксис

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

Аргументы

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

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

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

Примеры

Date32 по году, месяцу и дню

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

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

Date32 из года и дня года

SELECT makeDate(2023, 42) AS date;

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

makeDateTime

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

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

Синтаксис

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

Аргументы

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

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

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

Примеры

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

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

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

makeDateTime64

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

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

Синтаксис

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

Аргументы

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

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

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

Примеры

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

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

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

monthName

Появился в версии: v22.1

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

Синтаксис

monthName(datetime)

Аргументы

datetime — Дата или дата и время. Date или Date32 или DateTime или DateTime64

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

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

Примеры

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

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

┌─monthName(date_value)─┐
│ Апрель                │
└───────────────────────┘

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. Если функция выполняется в контексте распределённой таблицы, она формирует обычный столбец со значениями, соответствующими каждому шарду. В противном случае она возвращает константное значение.

Синтаксис

serverTimeZone()

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

Аргументы

Нет.

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

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

Примеры

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

SELECT serverTimeZone()

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

subDate

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

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

Синтаксис

subDate(datetime, interval)

Аргументы

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

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

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

Примеры

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

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

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

subtractDays

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

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

Синтаксис

subtractDays(datetime, num)

Аргументы

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

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

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

Примеры

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

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

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

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

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

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

subtractHours

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

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

Синтаксис

subtractHours(datetime, num)

Аргументы

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

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

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

Примеры

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

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

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

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

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

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

subtractInterval

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

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

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

Синтаксис

subtractInterval(interval_1, interval_2)

Аргументы

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

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

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

Примеры

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

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

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

subtractMicroseconds

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

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

Синтаксис

subtractMicroseconds(datetime, num)

Аргументы

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

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

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

Примеры

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

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 дата,
    toDateTime('2024-01-01 00:00:00') AS дата_время,
    '2024-01-01 00:00:00' AS строка_даты_времени
SELECT
    subtractMonths(дата, 1) AS вычитание_месяцев_из_даты,
    subtractMonths(дата_время, 1) AS вычитание_месяцев_из_даты_времени,
    subtractMonths(строка_даты_времени, 1) AS вычитание_месяцев_из_строки_даты_времени

┌─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 дата,
    toDateTime('2024-01-01 00:00:00') AS дата_время,
    '2024-01-01 00:00:00' AS строка_даты_времени
SELECT
    subtractWeeks(дата, 1) AS вычитание_недель_из_даты,
    subtractWeeks(дата_время, 1) AS вычитание_недель_из_даты_времени,
    subtractWeeks(строка_даты_времени, 1) AS вычитание_недель_из_строки_даты_времени

┌─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 вычитание_лет_из_даты,
    subtractYears(date_time, 1) AS вычитание_лет_из_даты_времени,
    subtractYears(date_time_string, 1) AS вычитание_лет_из_строки_даты_времени

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

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

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

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

timeDiff

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

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

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

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

Синтаксис

timeDiff(startdate, enddate)

Аргументы

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

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

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

Примеры

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

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

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

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

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

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

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

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

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

timeSlot

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

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

Примечание

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

Синтаксис

timeSlot(time[, time_zone])

Аргументы

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

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

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

Примеры

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

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

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

timeSlots

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

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

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

Для DateTime64 масштаб возвращаемого значения может отличаться от масштаба 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, преобразованное к типу DateTime64(6), или expr с добавленным временем.

Примеры

Преобразование строки с датой в 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.

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

Примеры

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

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

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

toDayOfYear

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

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

Синтаксис

toDayOfYear(datetime)

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

Аргументы

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

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

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

Примеры

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

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

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

toDaysSinceYearZero

Впервые представлен в: v23.9

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

Расчёт выполняется так же, как в функции 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 │
└───────────────────────────────────────────┘

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

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

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

Примеры

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

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

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

toMillisecond

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

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

Синтаксис

toMillisecond(datetime)

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

Аргументы

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

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

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

Примеры

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

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

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

toMinute

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

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

Синтаксис

toMinute(datetime)

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

Аргументы

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

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

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

Примеры

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

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

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

toModifiedJulianDay

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

Преобразует дату в пролептическом григорианском календаре в текстовом формате YYYY-MM-DD в номер модифицированного юлианского дня типа Int32. Функция поддерживает даты от 0000-01-01 до 9999-12-31. Вызывает исключение, если аргумент не может быть интерпретирован как дата или дата недопустима.

Синтаксис

toModifiedJulianDay(date)

Аргументы

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

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

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

Примеры

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

SELECT toModifiedJulianDay('2020-01-01')

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

toModifiedJulianDayOrNull

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

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

Синтаксис

toModifiedJulianDayOrNull(date)

Аргументы

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

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

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

Примеры

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

SELECT toModifiedJulianDayOrNull('2020-01-01');
SELECT toModifiedJulianDayOrNull('0000-00-00'); -- некорректная дата, возвращает NULL

┌─toModifiedJu⋯020-01-01')─┐
│                    58849 │
└──────────────────────────┘
┌─toModifiedJu⋯000-00-00')─┐
│                     ᴺᵁᴸᴸ │
└──────────────────────────┘

toMonday

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

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

Примечание

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

Синтаксис

toMonday(value)

Аргументы

value — дата или дата со временем, которые нужно округлить вниз до понедельника соответствующей недели. Date или Date32 или DateTime или DateTime64

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

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

Примеры

Округление вниз до понедельника недели

SELECT
toMonday(toDateTime('2023-04-21 10:20:30')), -- Пятница
toMonday(toDate('2023-04-24'));              -- Уже понедельник

┌─toMonday(toDateTime('2023-04-21 10:20:30'))─┬─toMonday(toDate('2023-04-24'))─┐
│                                  2023-04-17 │                     2023-04-24 │
└─────────────────────────────────────────────┴────────────────────────────────┘

toMonth

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

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

Синтаксис

toMonth(datetime)

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

Аргументы

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

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

Возвращает месяц из указанной даты/времени в виде значения типа UInt8.

Примеры

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

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

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

toMonthNumSinceEpoch

Появилась в версии: v25.3

Возвращает количество месяцев, прошедших с 1970 года

Синтаксис

toMonthNumSinceEpoch(date)

Аргументы

date — Дата или значение даты и времени. Date или DateTime или DateTime64

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

Положительное целое число

Примеры

Пример

SELECT toMonthNumSinceEpoch(toDate('2024-10-01'))

toQuarter

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

Возвращает квартал года (1–4) для заданного значения Date или DateTime.

Синтаксис

toQuarter(datetime)

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

Аргументы

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

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

Возвращает квартал года для указанной даты/времени в виде значения типа UInt8

Примеры

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

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

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

toRelativeDayNum

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

Преобразует дату или дату со временем в количество дней, прошедших с определённого фиксированного момента в прошлом. Точная точка во времени является деталями реализации, поэтому эту функцию не следует использовать самостоятельно. Основное назначение функции — вычислять разницу в днях между двумя датами или датами со временем, например, toRelativeDayNum(dt1) - toRelativeDayNum(dt2).

Синтаксис

toRelativeDayNum(date)

Аргументы

date — дата или дата и время. Date или DateTime или DateTime64

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

Возвращает количество дней, прошедших с фиксированной точки отсчёта в прошлом. UInt32

Примеры

Получение относительных номеров дней

SELECT toRelativeDayNum(toDate('2023-04-01')) - toRelativeDayNum(toDate('2023-01-01'))

┌─minus(toRela⋯3-01-01')))─┐
│                       90 │
└──────────────────────────┘

toRelativeHourNum

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

Преобразует дату или дату со временем в количество часов, прошедших с некоторого фиксированного момента в прошлом. Точный момент времени является деталью реализации, поэтому эта функция не предназначена для самостоятельного применения. Основное назначение функции — вычисление разницы в часах между двумя датами или датами со временем, например, toRelativeHourNum(dt1) - toRelativeHourNum(dt2).

Синтаксис

toRelativeHourNum(date)

Аргументы

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

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

Возвращает количество часов, прошедшее с фиксированной точки отсчёта в прошлом. UInt32

Примеры

Получение относительных номеров часов

SELECT toRelativeHourNum(toDateTime('2023-01-01 12:00:00')) - toRelativeHourNum(toDateTime('2023-01-01 00:00:00')) AS hours_difference

┌─hours_difference─┐
│               12 │
└──────────────────┘

toRelativeMinuteNum

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

Преобразует дату или дату со временем в количество минут, прошедших с некоторого фиксированного момента в прошлом. Точная точка во времени является деталью реализации, поэтому эту функцию не следует использовать отдельно. Основное назначение функции — вычислять разницу в минутах между двумя датами или датами со временем, например: toRelativeMinuteNum(dt1) - toRelativeMinuteNum(dt2).

Синтаксис

toRelativeMinuteNum(date)

Аргументы

date — дата или дата и время. Date или DateTime или DateTime64

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

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

Примеры

Получение относительного номера минуты

SELECT toRelativeMinuteNum(toDateTime('2023-01-01 00:30:00')) - toRelativeMinuteNum(toDateTime('2023-01-01 00:00:00')) AS minutes_difference

┌─minutes_difference─┐
│                 30 │
└────────────────────┘

toRelativeMonthNum

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

Преобразует дату или дату со временем в количество месяцев, прошедших с некоторого фиксированного момента в прошлом. Точная точка во времени является деталью реализации, поэтому эту функцию не следует использовать отдельно. Основное назначение функции — вычисление разницы в месяцах между двумя датами или датами со временем, например: toRelativeMonthNum(dt1) - toRelativeMonthNum(dt2).

Синтаксис

toRelativeMonthNum(date)

Аргументы

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

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

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

Примеры

Получение относительных номеров месяцев

SELECT toRelativeMonthNum(toDate('2023-04-01')) - toRelativeMonthNum(toDate('2023-01-01')) AS months_difference

┌─months_difference─┐
│                 3 │
└───────────────────┘

toRelativeQuarterNum

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

Преобразует дату или дату со временем в количество кварталов, прошедших с некоторого фиксированного момента в прошлом. Точная точка во времени является деталью реализации, поэтому эта функция не предназначена для самостоятельного использования. Основное назначение функции — вычислять разницу в кварталах между двумя датами или датами со временем, например, toRelativeQuarterNum(dt1) - toRelativeQuarterNum(dt2).

Синтаксис

toRelativeQuarterNum(date)

Аргументы

date — дата или дата и время. Date или DateTime или DateTime64

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

Возвращает количество кварталов, прошедших с фиксированной точки отсчёта в прошлом. UInt32

Примеры

Получение относительных номеров кварталов

SELECT toRelativeQuarterNum(toDate('2023-04-01')) - toRelativeQuarterNum(toDate('2023-01-01')) AS разница_кварталов

┌─quarters_difference─┐
│                   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─┐
│                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]])

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

Аргументы

value — Дата или дата‑время, которое нужно округлить в меньшую сторону. Date или DateTime или DateTime64
x — Число, задающее длину интервала. - unit — Единица измерения интервала: YEAR, QUARTER, MONTH, WEEK, DAY, HOUR, MINUTE, SECOND, MILLISECOND, MICROSECOND, NANOSECOND. - time_zone — Необязательный параметр. Название часового пояса в виде строки. - origin — Необязательный параметр. Точка отсчёта для вычислений (только для второй перегрузки).

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

Возвращает начало интервала, содержащего входное значение. DateTime

Примеры

Базовое округление до интервала

SELECT toStartOfInterval(toDateTime('2023-01-15 14:30:00'), INTERVAL 1 MONTH)

┌─toStartOfInt⋯alMonth(1))─┐
│               2023-01-01 │
└──────────────────────────┘

Использование исходной точки

SELECT toStartOfInterval(toDateTime('2023-01-01 14:45:00'), INTERVAL 1 MINUTE, toDateTime('2023-01-01 14:35:30'))

┌─toStartOfInt⋯14:35:30'))─┐
│      2023-01-01 14:44:30 │
└──────────────────────────┘

toStartOfMicrosecond

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

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

Синтаксис

toStartOfMicrosecond(datetime[, timezone])

Аргументы

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

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

Входное значение в формате DateTime64 с точностью до субмикросекунд

Примеры

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

WITH toDateTime64('2020-01-01 10:20:30.999999999', 9) AS dt64
SELECT toStartOfMicrosecond(dt64);

┌────toStartOfMicrosecond(dt64)─┐
│ 2020-01-01 10:20:30.999999000 │
└───────────────────────────────┘

Запрос с указанием часового пояса

WITH toDateTime64('2020-01-01 10:20:30.999999999', 9) AS dt64
SELECT toStartOfMicrosecond(dt64, 'Asia/Istanbul');

┌─toStartOfMicrosecond(dt64, 'Asia/Istanbul')─┐
│               2020-01-01 12:20:30.999999000 │
└─────────────────────────────────────────────┘

toStartOfMillisecond

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

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

Синтаксис

toStartOfMillisecond(datetime[, timezone])

Аргументы

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

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

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

Примеры

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

WITH toDateTime64('2020-01-01 10:20:30.999999999', 9) AS dt64
SELECT toStartOfMillisecond(dt64);

┌────toStartOfMillisecond(dt64)─┐
│ 2020-01-01 10:20:30.999000000 │
└───────────────────────────────┘

Запрос с учётом часового пояса

WITH toDateTime64('2020-01-01 10:20:30.999999999', 9) AS dt64
SELECT toStartOfMillisecond(dt64, 'Asia/Istanbul');

┌─toStartOfMillisecond(dt64, 'Asia/Istanbul')─┐
│               2020-01-01 12:20:30.999000000 │
└─────────────────────────────────────────────┘

toStartOfMinute

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

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

Примечание

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

Синтаксис

toStartOfMinute(datetime)

Аргументы

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

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

Возвращает дату и время, округлённые вниз до начала минуты. DateTime или DateTime64

Примеры

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

SELECT
    toStartOfMinute(toDateTime('2023-04-21 10:20:30')),
    toStartOfMinute(toDateTime64('2023-04-21 10:20:30.5300', 8))
FORMAT Vertical

Строка 1:
──────
toStartOfMinute(toDateTime('2023-04-21 10:20:30')):           2023-04-21 10:20:00
toStartOfMinute(toDateTime64('2023-04-21 10:20:30.5300', 8)): 2023-04-21 10:20:00

toStartOfMonth

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

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

Примечание

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

Синтаксис

toStartOfMonth(value)

Аргументы

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

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

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

Примеры

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

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

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

toStartOfNanosecond

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

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

Синтаксис

toStartOfNanosecond(datetime[, timezone])

Аргументы

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

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

Входное значение с точностью до наносекунд. DateTime64

Примеры

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

WITH toDateTime64('2020-01-01 10:20:30.999999999', 9) AS dt64
SELECT toStartOfNanosecond(dt64);

┌─────toStartOfNanosecond(dt64)─┐
│ 2020-01-01 10:20:30.999999999 │
└───────────────────────────────┘

Запрос с указанием часового пояса

WITH toDateTime64('2020-01-01 10:20:30.999999999', 9) AS dt64
SELECT toStartOfNanosecond(dt64, 'Asia/Istanbul');

┌─toStartOfNanosecond(dt64, 'Asia/Istanbul')─┐
│              2020-01-01 12:20:30.999999999 │
└────────────────────────────────────────────┘

toStartOfQuarter

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

Округляет дату или дату со временем в меньшую сторону до первого дня квартала. Первый день квартала — это либо 1 января, либо 1 апреля, либо 1 июля, либо 1 октября.

Примечание

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

Синтаксис

toStartOfQuarter(value)

Аргументы

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

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

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

Примеры

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

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

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

toStartOfSecond

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

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

Синтаксис

toStartOfSecond(datetime[, timezone])

Аргументы

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

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

Возвращает исходное значение без долей секунды. DateTime64

Примеры

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

WITH toDateTime64('2020-01-01 10:20:30.999', 3) AS dt64
SELECT toStartOfSecond(dt64);

┌───toStartOfSecond(dt64)─┐
│ 2020-01-01 10:20:30.000 │
└─────────────────────────┘

Запрос с указанием часового пояса

WITH toDateTime64('2020-01-01 10:20:30.999', 3) AS dt64
SELECT toStartOfSecond(dt64, 'Asia/Istanbul');

┌─toStartOfSecond(dt64, 'Asia/Istanbul')─┐
│                2020-01-01 13:20:30.000 │
└────────────────────────────────────────┘

toStartOfTenMinutes

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

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

Примечание

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

Синтаксис

toStartOfTenMinutes(datetime)

Аргументы

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

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

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

Примеры

Пример

SELECT
    toStartOfTenMinutes(toDateTime('2023-04-21 10:17:00')),
    toStartOfTenMinutes(toDateTime('2023-04-21 10:20:00')),
    toStartOfTenMinutes(toDateTime('2023-04-21 10:23:00'))
FORMAT Vertical

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')), /* пятница */
        toStartOfWeek(toDateTime('2023-04-21 10:20:30'), 1), /* пятница */
        toStartOfWeek(toDate('2023-04-24')), /* понедельник */
        toStartOfWeek(toDate('2023-04-24'), 1) /* понедельник */
    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;

Строка 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	First day of week	Range	Week 1 is the first week ...
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​

toISOYear​

toLastDayOfMonth​

toLastDayOfWeek​

toMillisecond​

toMinute​

toModifiedJulianDay​

UTCTimestamp

YYYYMMDDToDate

YYYYMMDDToDate32

YYYYMMDDhhmmssToDateTime

YYYYMMDDhhmmssToDateTime64

addDate

addDays

addHours

addInterval

addMicroseconds

addMilliseconds

addMinutes

addMonths

addNanoseconds

addQuarters

addSeconds

addTupleOfIntervals

addWeeks

addYears

age

changeDay

changeHour

changeMinute

changeMonth

changeSecond

changeYear

dateDiff

dateName

dateTrunc

formatDateTime

formatDateTimeInJodaSyntax

fromDaysSinceYearZero

fromDaysSinceYearZero32

fromModifiedJulianDay

fromModifiedJulianDayOrNull

fromUTCTimestamp

fromUnixTimestamp

fromUnixTimestampInJodaSyntax

makeDate

makeDate32

makeDateTime

makeDateTime64

monthName

now

now64

nowInBlock

nowInBlock64

serverTimezone

subDate

subtractDays

subtractHours

subtractInterval

subtractMicroseconds

subtractMilliseconds

subtractMinutes

subtractMonths

subtractNanoseconds

subtractQuarters

subtractSeconds

subtractTupleOfIntervals

subtractWeeks

subtractYears

timeDiff

timeSlot

timeSlots

timestamp

timezone

timezoneOf

timezoneOffset

toDayOfMonth

toDayOfWeek

toDayOfYear

toDaysSinceYearZero

toHour

toISOYear

toLastDayOfMonth

toLastDayOfWeek

toMillisecond

toMinute

toModifiedJulianDay