> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-86180b7b.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
> Документация по функциям для работы с датой и временем
# Функции для работы с датой и временем
Большинство функций в этом разделе принимают необязательный аргумент — часовой пояс, например `Europe/Amsterdam`. В этом случае используется указанный часовой пояс, а не локальный (по умолчанию).
**Пример**
```sql theme={null}
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
```
```text theme={null}
┌────────────────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 │
└─────────────────────┴────────────┴────────────┴─────────────────────┘
```
Для совместимости со стандартом SQL следующие функции — `NOW`, `CURRENT_TIMESTAMP`, `TODAY` и `CURRENT_DATE` — можно использовать без скобок.
{/*AUTOGENERATED_START*/}
## UTCTimestamp
Добавленный в: v22.11.0
Возвращает текущие дату и время на этапе анализа запроса. Функция является константным выражением.
Эта функция возвращает тот же результат, что и `now('UTC')`. Она была добавлена только для поддержки MySQL. Предпочтительно использовать [`now`](#now).
**Синтаксис**
```sql theme={null}
UTCTimestamp()
```
**Псевдонимы**: `UTC_timestamp`
**Аргументы**
* Нет.
**Возвращаемое значение**
Возвращает текущие дату и время на этапе анализа запроса. [`DateTime`](/ru/reference/data-types/datetime)
**Примеры**
**Получение текущей временной метки UTC**
```sql title=Query theme={null}
SELECT UTCTimestamp()
```
```response title=Response theme={null}
┌──────UTCTimestamp()─┐
│ 2024-05-28 08:32:09 │
└─────────────────────┘
```
## YYYYMMDDToDate
Добавленный в: v23.9.0
Преобразует число, содержащее год, месяц и день, в `Date`.
Эта функция обратна функции [`toYYYYMMDD()`](/ru/reference/functions/regular-functions/date-time-functions#toYYYYMMDD).
Результат не определён, если входное значение не кодирует корректное значение `Date`.
**Синтаксис**
```sql theme={null}
YYYYMMDDToDate(YYYYMMDD)
```
**Аргументы**
* `YYYYMMDD` — число, содержащее год, месяц и день. [`(U)Int*`](/ru/reference/data-types/int-uint) или [`Float*`](/ru/reference/data-types/float) или [`Decimal`](/ru/reference/data-types/decimal)
**Возвращаемое значение**
Возвращает значение типа `Date`, сформированное из переданных аргументов [`Date`](/ru/reference/data-types/date)
**Примеры**
**Пример**
```sql title=Query theme={null}
SELECT YYYYMMDDToDate(20230911);
```
```response title=Response theme={null}
┌─toYYYYMMDD(20230911)─┐
│ 2023-09-11 │
└──────────────────────┘
```
## YYYYMMDDToDate32
Добавленный в: v23.9.0
Преобразует число, содержащее год, месяц и день, в `Date32`.
Эта функция является обратной для [`toYYYYMMDD()`](/ru/reference/functions/regular-functions/date-time-functions#toYYYYMMDD).
Результат не определён, если входное значение не кодирует корректное значение `Date32`.
**Синтаксис**
```sql theme={null}
YYYYMMDDToDate32(YYYYMMDD)
```
**Аргументы**
* `YYYYMMDD` — число, содержащее год, месяц и день. [`(U)Int*`](/ru/reference/data-types/int-uint) или [`Float*`](/ru/reference/data-types/float), или [`Decimal`](/ru/reference/data-types/decimal)
**Возвращаемое значение**
Возвращает значение `Date32` из указанных аргументов [`Date32`](/ru/reference/data-types/date32)
**Примеры**
**Пример**
```sql title=Query theme={null}
SELECT YYYYMMDDToDate32(20000507);
```
```response title=Response theme={null}
┌─YYYYMMDDToDate32(20000507)─┐
│ 2000-05-07 │
└────────────────────────────┘
```
## YYYYMMDDhhmmssToDateTime
Добавленный в: v23.9.0
Преобразует число, содержащее год, месяц, день, час, минуту и секунду, в `DateTime`.
Эта функция является обратной к функции [`toYYYYMMDDhhmmss()`](/ru/reference/functions/regular-functions/date-time-functions#toYYYYMMDDhhmmss).
Результат не определён, если входное значение не кодирует корректное значение `DateTime`.
**Синтаксис**
```sql theme={null}
YYYYMMDDhhmmssToDateTime(YYYYMMDDhhmmss[, timezone])
```
**Аргументы**
* `YYYYMMDDhhmmss` — Число, содержащее год, месяц, день, час, минуту и секунду. [`(U)Int*`](/ru/reference/data-types/int-uint) или [`Float*`](/ru/reference/data-types/float) или [`Decimal`](/ru/reference/data-types/decimal)
* `timezone` — Название часового пояса. [`String`](/ru/reference/data-types/string)
**Возвращаемое значение**
Возвращает значение `DateTime` из указанных аргументов [`DateTime`](/ru/reference/data-types/datetime)
**Примеры**
**Пример**
```sql title=Query theme={null}
SELECT YYYYMMDDToDateTime(20230911131415);
```
```response title=Response theme={null}
┌──────YYYYMMDDhhmmssToDateTime(20230911131415)─┐
│ 2023-09-11 13:14:15 │
└───────────────────────────────────────────────┘
```
## YYYYMMDDhhmmssToDateTime64
Добавленный в: v23.9.0
Преобразует число, содержащее год, месяц, день, час, минуту и секунду, в `DateTime64`.
Эта функция является обратной по отношению к функции [`toYYYYMMDDhhmmss()`](/ru/reference/functions/regular-functions/date-time-functions#toYYYYMMDDhhmmss).
Результат не определён, если входное значение не кодирует допустимое значение `DateTime64`.
**Синтаксис**
```sql theme={null}
YYYYMMDDhhmmssToDateTime64(YYYYMMDDhhmmss[, precision[, timezone]])
```
**Аргументы**
* `YYYYMMDDhhmmss` — Число, содержащее год, месяц, день, часы, минуты и секунды. [`(U)Int*`](/ru/reference/data-types/int-uint) или [`Float*`](/ru/reference/data-types/float) или [`Decimal`](/ru/reference/data-types/decimal)
* `precision` — Точность дробной части (0-9). [`UInt8`](/ru/reference/data-types/int-uint)
* `timezone` — Название часового пояса. [`String`](/ru/reference/data-types/string)
**Возвращаемое значение**
Возвращает значение `DateTime64` на основе переданных аргументов [`DateTime64`](/ru/reference/data-types/datetime64)
**Примеры**
**Пример**
```sql title=Query theme={null}
SELECT YYYYMMDDhhmmssToDateTime64(20230911131415, 3, 'Asia/Istanbul');
```
```response title=Response theme={null}
┌─YYYYMMDDhhmm⋯/Istanbul')─┐
│ 2023-09-11 13:14:15.000 │
└──────────────────────────┘
```
## addDate
Добавленный в: v23.9.0
Добавляет интервал времени к указанной дате, дате и времени либо к дате или дате и времени, представленным в виде строки.
Если в результате сложения получается значение, выходящее за пределы допустимого диапазона типа данных, результат не определён.
**Синтаксис**
```sql theme={null}
addDate(datetime, interval)
```
**Аргументы**
* `datetime` — дата или дата и время, к которым добавляется `interval`. [`Date`](/ru/reference/data-types/date) или [`Date32`](/ru/reference/data-types/date32) или [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64) или [`String`](/ru/reference/data-types/string)
* `interval` — интервал, который нужно добавить. [`Interval`](/ru/reference/data-types/int-uint)
**Возвращаемое значение**
Возвращает дату или дату и время, полученные в результате добавления `interval` к `datetime`. [`Date`](/ru/reference/data-types/date) или [`Date32`](/ru/reference/data-types/date32) или [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64)
**Примеры**
**Добавление интервала к дате**
```sql title=Query theme={null}
SELECT addDate(toDate('2018-01-01'), INTERVAL 3 YEAR)
```
```response title=Response theme={null}
┌─addDate(toDa⋯valYear(3))─┐
│ 2021-01-01 │
└──────────────────────────┘
```
## addDays
Добавленный в: v1.1.0
Добавляет указанное количество дней к дате, дате и времени или строковому представлению даты либо даты и времени.
**Синтаксис**
```sql theme={null}
addDays(datetime, num)
```
**Аргументы**
* `datetime` — дата или дата и время, к которым нужно добавить указанное количество дней. [`Date`](/ru/reference/data-types/date) или [`Date32`](/ru/reference/data-types/date32) или [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64) или [`String`](/ru/reference/data-types/string)
* `num` — количество дней, которое нужно добавить. [`(U)Int*`](/ru/reference/data-types/int-uint) или [`Float*`](/ru/reference/data-types/float)
**Возвращаемое значение**
Возвращает значение `datetime` с добавленными `num` днями. [`Date`](/ru/reference/data-types/date) или [`Date32`](/ru/reference/data-types/date32) или [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64)
**Примеры**
**Добавление дней к значениям разных типов даты**
```sql title=Query theme={null}
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
```
```response title=Response theme={null}
┌─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**
```sql title=Query theme={null}
SELECT dateAdd('1998-06-16'::Date, INTERVAL 10 day)
```
```response title=Response theme={null}
┌─plus(CAST('1⋯valDay(10))─┐
│ 1998-06-26 │
└──────────────────────────┘
```
## addHours
Добавленный в: v1.1.0
Добавляет указанное количество часов к дате, дате и времени или строковому представлению даты или даты и времени.
**Синтаксис**
```sql theme={null}
addHours(datetime, num)
```
**Аргументы**
* `datetime` — дата или дата и время, к которым нужно добавить указанное количество часов. [`Date`](/ru/reference/data-types/date) или [`Date32`](/ru/reference/data-types/date32) или [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64) или [`String`](/ru/reference/data-types/string)
* `num` — количество часов, которое нужно добавить. [`(U)Int*`](/ru/reference/data-types/int-uint) или [`Float*`](/ru/reference/data-types/float)
**Возвращаемое значение**
Возвращает `datetime` с добавленными `num` часами. [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64(3)`](/ru/reference/data-types/datetime64)
**Примеры**
**Добавление часов к различным типам дат**
```sql title=Query theme={null}
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
```
```response title=Response theme={null}
┌─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**
```sql title=Query theme={null}
SELECT dateAdd('1998-06-16'::Date, INTERVAL 10 hour)
```
```response title=Response theme={null}
┌─plus(CAST('1⋯alHour(10))─┐
│ 1998-06-16 10:00:00 │
└──────────────────────────┘
```
## addInterval
Добавленный в: v22.11.0
Добавляет интервал к другому интервалу или кортежу интервалов.
Интервалы одного и того же типа будут объединены в один интервал. Например, если переданы `toIntervalDay(1)` и `toIntervalDay(2)`, результатом будет `(3)`, а не `(1,1)`.
**Синтаксис**
```sql theme={null}
addInterval(interval_1, interval_2)
```
**Аргументы**
* `interval_1` — Первый интервал или кортеж интервалов. [`Interval`](/ru/reference/data-types/int-uint) или [`Tuple(Interval)`](/ru/reference/data-types/tuple)
* `interval_2` — Второй добавляемый интервал. [`Interval`](/ru/reference/data-types/int-uint)
**Возвращаемое значение**
Возвращает кортеж интервалов [`Tuple(Interval)`](/ru/reference/data-types/tuple)
**Примеры**
**Добавление интервалов**
```sql title=Query theme={null}
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)
```
```response title=Response theme={null}
┌─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.0
Добавляет указанное количество микросекунд к значению типа «дата и время» или к дате и времени, представленным в виде строки.
**Синтаксис**
```sql theme={null}
addMicroseconds(datetime, num)
```
**Аргументы**
* `datetime` — Дата и время, к которым нужно добавить указанное количество микросекунд. [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64) или [`String`](/ru/reference/data-types/string)
* `num` — Количество добавляемых микросекунд. [`(U)Int*`](/ru/reference/data-types/int-uint) или [`Float*`](/ru/reference/data-types/float)
**Возвращаемое значение**
Возвращает `date_time`, увеличенное на `num` микросекунд [`DateTime64`](/ru/reference/data-types/datetime64)
**Примеры**
**Добавление микросекунд к различным типам даты и времени**
```sql title=Query theme={null}
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
```
```response title=Response theme={null}
┌─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**
```sql title=Query theme={null}
SELECT dateAdd('1998-06-16'::DateTime, INTERVAL 10 microsecond)
```
```response title=Response theme={null}
┌─plus(CAST('19⋯osecond(10))─┐
│ 1998-06-16 00:00:00.000010 │
└────────────────────────────┘
```
## addMilliseconds
Добавленный в: v22.6.0
Добавляет указанное количество миллисекунд к значению типа дата и время или к значению даты и времени, представленному в виде строки.
**Синтаксис**
```sql theme={null}
addMilliseconds(datetime, num)
```
**Аргументы**
* `datetime` — Дата и время, к которым нужно добавить указанное количество миллисекунд. [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64) или [`String`](/ru/reference/data-types/string)
* `num` — Количество миллисекунд, которое нужно добавить. [`(U)Int*`](/ru/reference/data-types/int-uint) или [`Float*`](/ru/reference/data-types/float)
**Возвращаемое значение**
Возвращает `datetime` с добавлением `num` миллисекунд. [`DateTime64`](/ru/reference/data-types/datetime64)
**Примеры**
**Добавление миллисекунд к различным типам даты и времени**
```sql title=Query theme={null}
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
```
```response title=Response theme={null}
┌─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**
```sql title=Query theme={null}
SELECT dateAdd('1998-06-16'::DateTime, INTERVAL 10 millisecond)
```
```response title=Response theme={null}
┌─plus(CAST('1⋯second(10))─┐
│ 1998-06-16 00:00:00.010 │
└──────────────────────────┘
```
## addMinutes
Добавленный в: v1.1.0
Добавляет указанное количество минут к дате, дате и времени или дате либо дате и времени, представленным в виде строки.
**Синтаксис**
```sql theme={null}
addMinutes(datetime, num)
```
**Аргументы**
* `datetime` — дата или дата и время, к которым добавляется указанное количество минут. [`Date`](/ru/reference/data-types/date) или [`Date32`](/ru/reference/data-types/date32) или [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64) или [`String`](/ru/reference/data-types/string)
* `num` — количество минут для добавления. [`(U)Int*`](/ru/reference/data-types/int-uint) или [`Float*`](/ru/reference/data-types/float)
**Возвращаемое значение**
Возвращает `datetime` с добавленными `num` минутами. [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64(3)`](/ru/reference/data-types/datetime64)
**Примеры**
**Добавление минут к различным типам дат**
```sql title=Query theme={null}
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
```
```response title=Response theme={null}
┌─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**
```sql title=Query theme={null}
SELECT dateAdd('1998-06-16'::Date, INTERVAL 10 minute)
```
```response title=Response theme={null}
┌─plus(CAST('1⋯Minute(10))─┐
│ 1998-06-16 00:10:00 │
└──────────────────────────┘
```
## addMonths
Добавленный в: v1.1.0
Добавляет указанное количество месяцев к дате, дате и времени или строковому представлению даты либо даты и времени.
**Синтаксис**
```sql theme={null}
addMonths(datetime, num)
```
**Аргументы**
* `datetime` — дата или дата и время, к которым добавляется указанное количество месяцев. [`Date`](/ru/reference/data-types/date) или [`Date32`](/ru/reference/data-types/date32) или [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64) или [`String`](/ru/reference/data-types/string)
* `num` — количество добавляемых месяцев. [`(U)Int*`](/ru/reference/data-types/int-uint) или [`Float*`](/ru/reference/data-types/float)
**Возвращаемое значение**
Возвращает значение `datetime` плюс `num` месяцев. [`Date`](/ru/reference/data-types/date) или [`Date32`](/ru/reference/data-types/date32) или [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64)
**Примеры**
**Добавление месяцев к разным типам дат**
```sql title=Query theme={null}
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
```
```response title=Response theme={null}
┌─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**
```sql title=Query theme={null}
SELECT dateAdd('1998-06-16'::Date, INTERVAL 10 month)
```
```response title=Response theme={null}
┌─plus(CAST('1⋯lMonth(10))─┐
│ 1999-04-16 │
└──────────────────────────┘
```
## addNanoseconds
Добавленный в: v22.6.0
Добавляет указанное количество наносекунд к значению типа «дата и время» или к дате и времени, заданным строкой.
**Синтаксис**
```sql theme={null}
addNanoseconds(datetime, num)
```
**Аргументы**
* `datetime` — Дата и время, к которым нужно добавить указанное количество наносекунд. [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64) или [`String`](/ru/reference/data-types/string)
* `num` — Количество добавляемых наносекунд. [`(U)Int*`](/ru/reference/data-types/int-uint) или [`Float*`](/ru/reference/data-types/float)
**Возвращаемое значение**
Возвращает `datetime` с добавленными `num` наносекундами [`DateTime64`](/ru/reference/data-types/datetime64)
**Примеры**
**Добавление наносекунд к различным типам даты и времени**
```sql title=Query theme={null}
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
```
```response title=Response theme={null}
┌─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**
```sql title=Query theme={null}
SELECT dateAdd('1998-06-16'::DateTime, INTERVAL 1000 nanosecond)
```
```response title=Response theme={null}
┌─plus(CAST('199⋯osecond(1000))─┐
│ 1998-06-16 00:00:00.000001000 │
└───────────────────────────────┘
```
## addQuarters
Добавленный в: v20.1.0
Добавляет указанное количество кварталов к дате, дате и времени или строковому представлению даты либо даты и времени.
**Синтаксис**
```sql theme={null}
addQuarters(datetime, num)
```
**Аргументы**
* `datetime` — Дата или дата и время, к которым нужно добавить указанное количество кварталов. [`Date`](/ru/reference/data-types/date) или [`Date32`](/ru/reference/data-types/date32) или [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64) или [`String`](/ru/reference/data-types/string)
* `num` — Количество кварталов, которое нужно добавить. [`(U)Int*`](/ru/reference/data-types/int-uint) или [`Float*`](/ru/reference/data-types/float)
**Возвращаемое значение**
Возвращает `datetime` с добавленными `num` кварталами. [`Date`](/ru/reference/data-types/date) или [`Date32`](/ru/reference/data-types/date32) или [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64)
**Примеры**
**Добавление кварталов к значениям разных типов дат**
```sql title=Query theme={null}
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
```
```response title=Response theme={null}
┌─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**
```sql title=Query theme={null}
SELECT dateAdd('1998-06-16'::Date, INTERVAL 10 quarter)
```
```response title=Response theme={null}
┌─plus(CAST('1⋯uarter(10))─┐
│ 2000-12-16 │
└──────────────────────────┘
```
## addSeconds
Добавленный в: v1.1.0
Добавляет указанное количество секунд к дате, дате и времени или к строковому представлению даты либо даты и времени.
**Синтаксис**
```sql theme={null}
addSeconds(datetime, num)
```
**Аргументы**
* `datetime` — Дата или дата и время, к которым добавляется указанное количество секунд. [`Date`](/ru/reference/data-types/date) или [`Date32`](/ru/reference/data-types/date32) или [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64) или [`String`](/ru/reference/data-types/string)
* `num` — Количество добавляемых секунд. [`(U)Int*`](/ru/reference/data-types/int-uint) или [`Float*`](/ru/reference/data-types/float)
**Возвращаемое значение**
Возвращает `datetime` с добавленными `num` секундами. [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64(3)`](/ru/reference/data-types/datetime64)
**Примеры**
**Добавление секунд к различным типам дат**
```sql title=Query theme={null}
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
```
```response title=Response theme={null}
┌─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**
```sql title=Query theme={null}
SELECT dateAdd('1998-06-16'::Date, INTERVAL 10 second)
```
```response title=Response theme={null}
┌─dateAdd('1998-06-16'::Date, INTERVAL 10 second)─┐
│ 1998-06-16 00:00:10 │
└─────────────────────────────────────────────────┘
```
## addTupleOfIntervals
Добавленный в: v22.11.0
Последовательно добавляет кортеж интервалов к дате или дате и времени.
**Синтаксис**
```sql theme={null}
addTupleOfIntervals(datetime, intervals)
```
**Аргументы**
* `datetime` — дата или дата и время, к которым нужно добавить интервалы. [`Date`](/ru/reference/data-types/date) или [`Date32`](/ru/reference/data-types/date32) или [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64)
* `intervals` — кортеж интервалов, которые нужно добавить к `datetime`. [`Tuple(Interval)`](/ru/reference/data-types/tuple)
**Возвращаемое значение**
Возвращает `date` с добавленными `intervals`: [`Date`](/ru/reference/data-types/date) или [`Date32`](/ru/reference/data-types/date32) или [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64)
**Примеры**
**Добавление кортежа интервалов к дате**
```sql title=Query theme={null}
WITH toDate('2018-01-01') AS date
SELECT addTupleOfIntervals(date, (INTERVAL 1 DAY, INTERVAL 1 MONTH, INTERVAL 1 YEAR))
```
```response title=Response theme={null}
┌─addTupleOfIntervals(date, (toIntervalDay(1), toIntervalMonth(1), toIntervalYear(1)))─┐
│ 2019-02-02 │
└──────────────────────────────────────────────────────────────────────────────────────┘
```
## addWeeks
Добавленный в: v1.1.0
Добавляет указанное количество недель к дате, дате и времени или дате либо дате и времени, представленным в виде строки.
**Синтаксис**
```sql theme={null}
addWeeks(datetime, num)
```
**Аргументы**
* `datetime` — дата или дата и время, к которым нужно добавить указанное количество недель. [`Date`](/ru/reference/data-types/date) или [`Date32`](/ru/reference/data-types/date32) или [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64) или [`String`](/ru/reference/data-types/string)
* `num` — количество недель, которое нужно добавить. [`(U)Int*`](/ru/reference/data-types/int-uint) или [`Float*`](/ru/reference/data-types/float)
**Возвращаемое значение**
Возвращает значение `datetime` с добавленными `num` неделями. [`Date`](/ru/reference/data-types/date) или [`Date32`](/ru/reference/data-types/date32) или [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64)
**Примеры**
**Добавление недель к разным типам дат**
```sql title=Query theme={null}
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
```
```response title=Response theme={null}
┌─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**
```sql title=Query theme={null}
SELECT dateAdd('1998-06-16'::Date, INTERVAL 10 week)
```
```response title=Response theme={null}
┌─plus(CAST('1⋯alWeek(10))─┐
│ 1998-08-25 │
└──────────────────────────┘
```
## addYears
Добавленный в: v1.1.0
Добавляет указанное количество лет к дате, дате и времени или строковому представлению даты либо даты и времени.
**Синтаксис**
```sql theme={null}
addYears(datetime, num)
```
**Аргументы**
* `datetime` — Дата или дата и время, к которым нужно добавить указанное количество лет. [`Date`](/ru/reference/data-types/date) или [`Date32`](/ru/reference/data-types/date32) или [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64) или [`String`](/ru/reference/data-types/string)
* `num` — Количество добавляемых лет. [`(U)Int*`](/ru/reference/data-types/int-uint) или [`Float*`](/ru/reference/data-types/float)
**Возвращаемое значение**
Возвращает значение `datetime` с добавленными `num` годами. [`Date`](/ru/reference/data-types/date) или [`Date32`](/ru/reference/data-types/date32) или [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64)
**Примеры**
**Добавление лет к различным типам дат**
```sql title=Query theme={null}
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
```
```response title=Response theme={null}
┌─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**
```sql title=Query theme={null}
SELECT dateAdd('1998-06-16'::Date, INTERVAL 10 year)
```
```response title=Response theme={null}
┌─plus(CAST('1⋯alYear(10))─┐
│ 2008-06-16 │
└──────────────────────────┘
```
## age
Добавленный в: v23.1.0
Возвращает компонент указанной единицы в разнице между `startdate` и `enddate`.
Разница вычисляется с точностью до 1 наносекунды.
Например, разница между 2021-12-29 и 2022-01-01 составляет 3 дня для единицы day,
0 месяцев для единицы month и 0 лет для единицы year.
В качестве альтернативы age см. функцию [`dateDiff`](#dateDiff).
**Синтаксис**
```sql theme={null}
age('unit', startdate, enddate[, timezone])
```
**Аргументы**
* `unit` — Тип интервала результата.
| Единица | Возможные значения |
| ----------- | ---------------------------------------- |
| nanosecond | `nanosecond`, `nanoseconds`, `ns` |
| microsecond | `microsecond`, `microseconds`, `us`, `u` |
| millisecond | `millisecond`, `milliseconds`, `ms` |
| second | `second`, `seconds`, `ss`, `s` |
| minute | `minute`, `minutes`, `mi`, `n` |
| hour | `hour`, `hours`, `hh`, `h` |
| day | `day`, `days`, `dd`, `d` |
| week | `week`, `weeks`, `wk`, `ww` |
| month | `month`, `months`, `mm`, `m` |
| quarter | `quarter`, `quarters`, `qq`, `q` |
| year | `year`, `years`, `yyyy`, `yy` |
* `startdate` — Первое значение времени для вычитания (вычитаемое). [`Date`](/ru/reference/data-types/date) или [`Date32`](/ru/reference/data-types/date32) или [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64)
* `enddate` — Второе значение времени, из которого вычитается первое (уменьшаемое). [`Date`](/ru/reference/data-types/date) или [`Date32`](/ru/reference/data-types/date32) или [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64)
* `timezone` — Необязательно. Название часового пояса. Если указано, применяется и к startdate, и к enddate. Если не указано, используются часовые пояса startdate и enddate. Если они не совпадают, результат не определён. [`String`](/ru/reference/data-types/string)
**Возвращаемое значение**
Возвращает разность между enddate и startdate, выраженную в единицах unit. [`Int32`](/ru/reference/data-types/int-uint)
**Примеры**
**Расчёт возраста в часах**
```sql title=Query theme={null}
SELECT age('hour', toDateTime('2018-01-01 22:30:00'), toDateTime('2018-01-02 23:00:00'))
```
```response title=Response theme={null}
┌─age('hour', toDateTime('2018-01-01 22:30:00'), toDateTime('2018-01-02 23:00:00'))─┐
│ 24 │
└───────────────────────────────────────────────────────────────────────────────────┘
```
**Расчет возраста в разных единицах**
```sql title=Query theme={null}
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
```
```response title=Response theme={null}
┌──────────e─┬──────────s─┬─day_age─┬─month_age─┬─year_age─┐
│ 2022-01-01 │ 2021-12-29 │ 3 │ 0 │ 0 │
└────────────┴────────────┴─────────┴───────────┴──────────┘
```
## changeDay
Добавленный в: v24.7.0
Изменяет компонент дня в значении типа Date или DateTime.
**Синтаксис**
```sql theme={null}
changeDay(date_or_datetime, value)
```
**Аргументы**
* `date_or_datetime` — Значение, которое нужно изменить. [`Date`](/ru/reference/data-types/date) или [`Date32`](/ru/reference/data-types/date32) или [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64)
* `value` — Новое значение. [`(U)Int*`](/ru/reference/data-types/int-uint)
**Возвращаемое значение**
Возвращает значение того же типа, что и `date_or_datetime`, с изменённым значением часа. [`Date`](/ru/reference/data-types/date) или [`Date32`](/ru/reference/data-types/date32) или [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64)
**Примеры**
**Пример использования**
```sql title=Query theme={null}
SELECT changeDay('2024-01-31'::DateTime, 15)
```
```response title=Response theme={null}
2024-01-15 00:00:00
```
## changeHour
Добавленный в: v24.7.0
Изменяет компонент часа в значении типа Date или DateTime.
**Синтаксис**
```sql theme={null}
changeHour(date_or_datetime, value)
```
**Аргументы**
* `date_or_datetime` — Значение, которое требуется изменить. [`Date`](/ru/reference/data-types/date) или [`Date32`](/ru/reference/data-types/date32) или [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64)
* `value` — Новое значение. [`(U)Int*`](/ru/reference/data-types/int-uint)
**Возвращаемое значение**
Возвращает значение того же типа, что и `date_or_datetime`, с изменённым компонентом часа. [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64)
**Примеры**
**Пример использования**
```sql title=Query theme={null}
SELECT changeHour('2024-01-01 12:00:00'::DateTime, 5)
```
```response title=Response theme={null}
2024-01-01 05:00:00
```
## changeMinute
Добавленный в: v24.7.0
Изменяет компонент минут в значении `Date или DateTime`.
**Синтаксис**
```sql theme={null}
changeMinute(date_or_datetime, value)
```
**Аргументы**
* `date_or_datetime` — Значение, которое нужно изменить. [`Date`](/ru/reference/data-types/date) или [`Date32`](/ru/reference/data-types/date32) или [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64)
* `value` — Новое значение. [`(U)Int*`](/ru/reference/data-types/int-uint)
**Возвращаемое значение**
Возвращает значение того же типа, что и `date_or_datetime`, с изменённым значением минут. [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64)
**Примеры**
**Пример использования**
```sql title=Query theme={null}
SELECT changeMinute('2024-01-01 12:30:00'::DateTime, 45)
```
```response title=Response theme={null}
2024-01-01 12:45:00
```
## changeMonth
Добавленный в: v24.7.0
Изменяет компонент месяца в значении типа Date или DateTime.
**Синтаксис**
```sql theme={null}
changeMonth(date_or_datetime, value)
```
**Аргументы**
* `date_or_datetime` — Значение, которое требуется изменить. [`Date`](/ru/reference/data-types/date) или [`Date32`](/ru/reference/data-types/date32) или [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64)
* `value` — Новое значение. [`(U)Int*`](/ru/reference/data-types/int-uint)
**Возвращаемое значение**
Возвращает значение того же типа, что и `date_or_datetime`, с изменённым компонентом месяца. [`Date`](/ru/reference/data-types/date) или [`Date32`](/ru/reference/data-types/date32) или [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64)
**Примеры**
**Пример использования**
```sql title=Query theme={null}
SELECT changeMonth('2024-01-01'::DateTime, 12)
```
```response title=Response theme={null}
2024-12-01 00:00:00
```
## changeSecond
Добавленный в: v24.7.0
Изменяет значение секунд в Date или DateTime.
**Синтаксис**
```sql theme={null}
changeSecond(date_or_datetime, value)
```
**Аргументы**
* `date_or_datetime` — Значение, которое нужно изменить. [`Date`](/ru/reference/data-types/date) или [`Date32`](/ru/reference/data-types/date32) или [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64)
* `value` — Новое значение. [`(U)Int*`](/ru/reference/data-types/int-uint)
**Возвращаемое значение**
Возвращает значение того же типа, что и `date_or_datetime`, с изменённым значением секунд. [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64)
**Примеры**
**Пример использования**
```sql title=Query theme={null}
SELECT changeSecond('2024-01-01 12:30:45'::DateTime, 15)
```
```response title=Response theme={null}
2024-01-01 12:30:15
```
## changeYear
Добавленный в: v24.7.0
Изменяет год у значения типа Date или DateTime.
**Синтаксис**
```sql theme={null}
changeYear(date_or_datetime, value)
```
**Аргументы**
* `date_or_datetime` — Значение, которое нужно изменить. [`Date`](/ru/reference/data-types/date) или [`Date32`](/ru/reference/data-types/date32) или [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64)
* `value` — Новое значение. [`(U)Int*`](/ru/reference/data-types/int-uint)
**Возвращаемое значение**
Возвращает значение того же типа, что и `date_or_datetime`, с изменённым компонентом года. [`Date`](/ru/reference/data-types/date) или [`Date32`](/ru/reference/data-types/date32) или [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64)
**Примеры**
**Пример использования**
```sql title=Query theme={null}
SELECT changeYear('2024-01-01'::DateTime, 2023)
```
```response title=Response theme={null}
2023-01-01 00:00:00
```
## dateDiff
Добавленный в: v23.4.0
Возвращает количество границ указанной единицы `unit`, пересечённых между `startdate` и `enddate`.
Разница вычисляется с использованием относительных единиц. Например, разница между 2021-12-29 и 2022-01-01 составляет 3 дня для единицы day
(см. [`toRelativeDayNum`](#toRelativeDayNum)), 1 месяц для единицы month (см. [`toRelativeMonthNum`](#toRelativeMonthNum)) и 1 год для единицы year
(см. [`toRelativeYearNum`](#toRelativeYearNum)).
Если указана единица `week`, то `dateDiff` считает, что недели начинаются в понедельник.
Обратите внимание, что это поведение отличается от функции `toWeek()`, в которой недели по умолчанию начинаются в воскресенье.
В качестве альтернативы `dateDiff` см. функцию [`age`](#age).
**Синтаксис**
```sql theme={null}
dateDiff(unit, startdate, enddate[, timezone])
```
**Псевдонимы**: `timestampDiff`, `TIMESTAMP_DIFF`, `DATE_DIFF`, `date_diff`, `timestamp_diff`
**Аргументы**
* `unit` — Тип интервала, в котором выражается результат.
| Unit | Возможные значения |
| ----------- | ---------------------------------------- |
| nanosecond | `nanosecond`, `nanoseconds`, `ns` |
| microsecond | `microsecond`, `microseconds`, `us`, `u` |
| millisecond | `millisecond`, `milliseconds`, `ms` |
| second | `second`, `seconds`, `ss`, `s` |
| minute | `minute`, `minutes`, `mi`, `n` |
| hour | `hour`, `hours`, `hh`, `h` |
| day | `day`, `days`, `dd`, `d` |
| week | `week`, `weeks`, `wk`, `ww` |
| month | `month`, `months`, `mm`, `m` |
| quarter | `quarter`, `quarters`, `qq`, `q` |
| year | `year`, `years`, `yyyy`, `yy` |
* `startdate` — Первое значение времени, которое вычитается (вычитаемое). [`Date`](/ru/reference/data-types/date) или [`Date32`](/ru/reference/data-types/date32) или [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64)
* `enddate` — Второе значение времени, из которого выполняется вычитание (уменьшаемое). [`Date`](/ru/reference/data-types/date) или [`Date32`](/ru/reference/data-types/date32) или [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64)
* `timezone` — Необязательно. Имя часового пояса. Если указано, оно применяется и к `startdate`, и к `enddate`. Если не указано, используются часовые пояса `startdate` и `enddate`. Если они различаются, результат не определён. [`String`](/ru/reference/data-types/string)
**Возвращаемое значение**
Возвращает разницу между `enddate` и `startdate`, выраженную в `unit`. [`Int64`](/ru/reference/data-types/int-uint)
**Примеры**
**Расчёт разницы между датами в часах**
```sql title=Query theme={null}
SELECT dateDiff('hour', toDateTime('2018-01-01 22:00:00'), toDateTime('2018-01-02 23:00:00')) AS res
```
```response title=Response theme={null}
┌─res─┐
│ 25 │
└─────┘
```
**Вычислить разницу между датами в разных единицах**
```sql title=Query theme={null}
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
```
```response title=Response theme={null}
┌──────────e─┬──────────s─┬─day_diff─┬─month_diff─┬─year_diff─┐
│ 2022-01-01 │ 2021-12-29 │ 3 │ 1 │ 1 │
└────────────┴────────────┴──────────┴────────────┴───────────┘
```
## dateName
Добавленный в: v21.7.0
Возвращает указанную часть даты.
Возможные значения:
* 'year'
* 'quarter'
* 'month'
* 'week'
* 'dayofyear'
* 'day'
* 'weekday'
* 'hour'
* 'minute'
* 'second'
**Синтаксис**
```sql theme={null}
dateName(date_part, date[, timezone])
```
**Аргументы**
* `date_part` — Часть даты, которую требуется извлечь. [`String`](/ru/reference/data-types/string)
* `datetime` — Значение типа дата или дата и время. [`Date`](/ru/reference/data-types/date) или [`Date32`](/ru/reference/data-types/date32) или [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64)
* `timezone` — Необязательно. Часовой пояс. [`String`](/ru/reference/data-types/string)
**Возвращаемое значение**
Возвращает указанную часть даты. [`String`](/ru/reference/data-types/string)
**Примеры**
**Извлечение различных частей даты**
```sql title=Query theme={null}
WITH toDateTime('2021-04-14 11:22:33') AS date_value
SELECT
dateName('year', date_value),
dateName('month', date_value),
dateName('day', date_value)
```
```response title=Response theme={null}
┌─dateName('year', date_value)─┬─dateName('month', date_value)─┬─dateName('day', date_value)─┐
│ 2021 │ April │ 14 │
└──────────────────────────────┴───────────────────────────────┴─────────────────────────────┘
```
## dateTrunc
Добавленный в: v20.8.0
Обрезает значение даты и времени до указанной части даты.
**Синтаксис**
```sql theme={null}
dateTrunc(unit, datetime[, timezone])
```
**Псевдонимы**: `DATE_TRUNC`
**Аргументы**
* `unit` —
Тип интервала, до которого нужно усечь результат. Возможные значения: `nanosecond` (только DateTime64), `microsecond` (только DateTime64), `millisecond` (только DateTime64), `second`, `minute`, `hour`, `day`, `week`, `month`, `quarter`, `year`.
[`String`](/ru/reference/data-types/string)
* `datetime` — Дата и время. [`Date`](/ru/reference/data-types/date) или [`Date32`](/ru/reference/data-types/date32) или [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64)
* `timezone` — Необязательно. Имя часового пояса для возвращаемого значения даты и времени. Если не указан, функция использует часовой пояс параметра `datetime`. [`String`](/ru/reference/data-types/string)
**Возвращаемое значение**
Возвращает усечённое значение даты и времени.
| Аргумент unit | Аргумент `datetime` | Тип возвращаемого значения |
| --------------------------- | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| Год, квартал, месяц, неделя | `Date32` или `DateTime64` или `Date` или `DateTime` | [`Date32`](/ru/reference/data-types/date32) или [`Date`](/ru/reference/data-types/date) |
| День, час, минута, секунда | `Date32`, `DateTime64`, `Date` или `DateTime` | [`DateTime64`](/ru/reference/data-types/datetime64) или [`DateTime`](/ru/reference/data-types/datetime) |
| Миллисекунда, микросекунда, | Любой | [`DateTime64`](/ru/reference/data-types/datetime64) |
| Наносекунда | | со scale 3, 6 или 9 |
**Примеры**
**Усечение без указания часового пояса**
```sql title=Query theme={null}
SELECT now(), dateTrunc('hour', now());
```
```response title=Response theme={null}
┌───────────────now()─┬─dateTrunc('hour', now())──┐
│ 2020-09-28 10:40:45 │ 2020-09-28 10:00:00 │
└─────────────────────┴───────────────────────────┘
```
**Усечение с указанием часового пояса**
```sql title=Query theme={null}
SELECT now(), dateTrunc('hour', now(), 'Asia/Istanbul');
```
```response title=Response theme={null}
┌───────────────now()─┬─dateTrunc('hour', now(), 'Asia/Istanbul')──┐
│ 2020-09-28 10:46:26 │ 2020-09-28 13:00:00 │
└─────────────────────┴────────────────────────────────────────────┘
```
## formatDateTime
Добавленный в: v1.1.0
Форматирует дату или дату и время в соответствии с заданной строкой формата. `format` — константное выражение, поэтому для одного результирующего столбца нельзя использовать несколько форматов.
`formatDateTime` использует стиль форматирования даты и времени MySQL, см. [документацию MySQL](https://dev.mysql.com/doc/refman/8.0/en/date-and-time-functions.html#function_date-format).
Обратная операция для этой функции — [`parseDateTime`](/ru/reference/functions/regular-functions/type-conversion-functions#parseDateTime).
С помощью полей замены можно задать шаблон результирующей строки.
Столбец примера в таблице ниже показывает результат форматирования для `2018-01-02 22:33:44`.
**Поля замены:**
| Placeholder | Description | Example |
| ----------- | --------------------------------------------------------------- | ---------- |
| %a | сокращённое название дня недели (Mon-Sun) | Mon |
| %b | сокращённое название месяца (Jan-Dec) | Jan |
| %c | месяц в виде целого числа (01-12) | 01 |
| %C | год, разделённый на 100 и усечённый до целого числа (00-99) | 20 |
| %d | день месяца с ведущим нулём (01-31) | 02 |
| %D | краткая дата в формате MM/DD/YY, эквивалентно %m/%d/%y | 01/02/18 |
| %e | день месяца с дополнением пробелом (1-31) | 2 |
| %f | дробная часть секунды | 123456 |
| %F | краткая дата в формате YYYY-MM-DD, эквивалентно %Y-%m-%d | 2018-01-02 |
| %g | двузначный год по ISO 8601 | 18 |
| %G | четырёхзначный год для номера недели по ISO | 2018 |
| %h | час в 12-часовом формате (01-12) | 09 |
| %H | час в 24-часовом формате (00-23) | 22 |
| %i | минуты (00-59) | 33 |
| %I | час в 12-часовом формате (01-12) | 10 |
| %j | день года (001-366) | 002 |
| %k | час в 24-часовом формате (00-23) | 14 |
| %l | час в 12-часовом формате (01-12) | 09 |
| %m | месяц в виде целого числа (01-12) | 01 |
| %M | полное название месяца (January-December) | January |
| %n | символ новой строки | |
| %p | обозначение AM или PM | PM |
| %Q | квартал (1-4) | 1 |
| %r | время в 12-часовом формате HH:MM AM/PM, эквивалентно %h:%i %p | 10:30 PM |
| %R | время в 24-часовом формате HH:MM, эквивалентно %H:%i | 22:33 |
| %s | секунды (00-59) | 44 |
| %S | секунды (00-59) | 44 |
| %t | символ горизонтальной табуляции | |
| %T | время в формате ISO 8601 (HH:MM:SS), эквивалентно %H:%i:%S | 22:33:44 |
| %u | день недели по ISO 8601 в виде числа, где понедельник = 1 (1-7) | 2 |
| %V | номер недели по ISO 8601 (01-53) | 01 |
| %w | день недели в виде целого числа, где воскресенье = 0 (0-6) | 2 |
| %W | полное название дня недели (Monday-Sunday) | Monday |
| %y | год, последние две цифры (00-99) | 18 |
| %Y | год | 2018 |
| %z | смещение относительно UTC в формате +HHMM или -HHMM | -0500 |
| %% | знак % | % |
* В версиях ClickHouse до v23.4 `%f` выводит один ноль (0), если форматируемое значение имеет тип Date, Date32 или DateTime (у которых нет дробной части секунд) либо DateTime64 с точностью 0.
* В версиях ClickHouse до v25.1 `%f` выводит столько цифр, сколько указано в scale типа DateTime64, вместо фиксированных 6 цифр.
* В версиях ClickHouse до v23.4 `%M` выводит минуты (00-59) вместо полного названия месяца (January-December).
**Синтаксис**
```sql theme={null}
formatDateTime(datetime, format[, timezone])
```
**Псевдонимы**: `DATE_FORMAT`
**Аргументы**
* `datetime` — Значение Date или DateTime для форматирования. [`Date`](/ru/reference/data-types/date) or [`Date32`](/ru/reference/data-types/date32) or [`DateTime`](/ru/reference/data-types/datetime) or [`DateTime64`](/ru/reference/data-types/datetime64)
* `format` — Строка формата с полями подстановки. [`String`](/ru/reference/data-types/string)
* `timezone` — Необязательно. Имя часового пояса для форматируемого времени. [`String`](/ru/reference/data-types/string)
**Возвращаемое значение**
Возвращает значение даты и времени в указанном формате. [`String`](/ru/reference/data-types/string)
**Примеры**
**Форматирование даты с плейсхолдером года**
```sql title=Query theme={null}
SELECT formatDateTime(toDate('2010-01-04'), '%g')
```
```response title=Response theme={null}
┌─formatDateTime(toDate('2010-01-04'), '%g')─┐
│ 10 │
└────────────────────────────────────────────┘
```
**Форматирование DateTime64 с долями секунды**
```sql title=Query theme={null}
SELECT formatDateTime(toDateTime64('2010-01-04 12:34:56.123456', 7), '%f')
```
```response title=Response theme={null}
┌─formatDateTime(toDateTime64('2010-01-04 12:34:56.123456', 7), '%f')─┐
│ 1234560 │
└─────────────────────────────────────────────────────────────────────┘
```
**Формат с часовым поясом**
```sql title=Query theme={null}
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
```
```response title=Response theme={null}
┌──────────────────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.0
Похожа на `formatDateTime`, но форматирует дату и время в стиле Joda, а не MySQL. См. [документацию Joda Time](https://joda-time.sourceforge.net/apidocs/org/joda/time/format/DateTimeFormat.html).
Обратной операцией для этой функции является [`parseDateTimeInJodaSyntax`](/ru/reference/functions/regular-functions/type-conversion-functions#parseDateTimeInJodaSyntax).
С помощью полей замены можно задать шаблон результирующей строки.
**Поля замены:**
| Заполнитель | Описание | Представление | Примеры |
| ----------- | ----------------------------------------------------- | ------------- | -------------------------- |
| G | эра | текст | AD |
| C | век эры (>=0) | число | 20 |
| Y | год эры (>=0) | год | 1996 |
| x | год нумерации недель (пока не поддерживается) | год | 1996 |
| w | неделя года нумерации недель (пока не поддерживается) | число | 27 |
| e | день недели | число | 2 |
| E | день недели | текст | Tuesday; Tue |
| y | год | год | 1996 |
| D | день года | число | 189 |
| M | месяц года | месяц | July; Jul; 07 |
| d | день месяца | число | 10 |
| a | половина дня | текст | PM |
| K | час половины дня (0\~11) | число | 0 |
| h | час половины дня по циферблату (1\~12) | число | 12 |
| H | час дня (0\~23) | число | 0 |
| k | час дня по циферблату (1\~24) | число | 24 |
| m | минута часа | число | 30 |
| s | секунда минуты | число | 55 |
| S | доля секунды | число | 978 |
| z | часовой пояс | текст | Eastern Standard Time; EST |
| Z | смещение часового пояса | зона | -0800; -0812 |
| ' | экранирование текста | разделитель | |
| '' | одинарная кавычка | литерал | ' |
**Синтаксис**
```sql theme={null}
formatDateTimeInJodaSyntax(datetime, format[, timezone])
```
**Аргументы**
* `datetime` — Date или DateTime для форматирования. [`DateTime`](/ru/reference/data-types/datetime) или [`Date`](/ru/reference/data-types/date) или [`Date32`](/ru/reference/data-types/date32) или [`DateTime64`](/ru/reference/data-types/datetime64)
* `format` — Строка формата с полями замены в стиле Joda. [`String`](/ru/reference/data-types/string)
* `timezone` — Необязательно. Имя часового пояса для форматируемых даты и времени. [`String`](/ru/reference/data-types/string)
**Возвращаемое значение**
Возвращает значения даты и времени в соответствии с указанным форматом. [`String`](/ru/reference/data-types/string)
**Примеры**
**Форматирование datetime с помощью синтаксиса Joda**
```sql title=Query theme={null}
SELECT formatDateTimeInJodaSyntax(toDateTime('2010-01-04 12:34:56'), 'yyyy-MM-dd HH:mm:ss')
```
```response title=Response theme={null}
┌─formatDateTimeInJodaSyntax(toDateTime('2010-01-04 12:34:56'), 'yyyy-MM-dd HH:mm:ss')─┐
│ 2010-01-04 12:34:56 │
└─────────────────────────────────────────────────────────────────────────────────────────┘
```
## fromDaysSinceYearZero
Добавленный в: v23.11.0
Для заданного числа дней, прошедших с [1 January 0000](https://en.wikipedia.org/wiki/Year_zero), возвращает соответствующую дату в [пролептическом григорианском календаре по ISO 8601](https://en.wikipedia.org/wiki/Gregorian_calendar#Proleptic_Gregorian_calendar).
Вычисление выполняется так же, как в функции MySQL `FROM_DAYS()`. Результат не определён, если его нельзя представить в пределах типа [Date](/ru/reference/data-types/date).
**Синтаксис**
```sql theme={null}
fromDaysSinceYearZero(days)
```
**Псевдонимы**: `FROM_DAYS`
**Аргументы**
* `days` — Количество дней, прошедших с нулевого года. [`UInt32`](/ru/reference/data-types/int-uint)
**Возвращаемое значение**
Возвращает дату, соответствующую числу дней, прошедших с нулевого года. [`Date`](/ru/reference/data-types/date)
**Примеры**
**Преобразование числа дней с нулевого года в даты**
```sql title=Query theme={null}
SELECT
fromDaysSinceYearZero(739136) AS date1,
fromDaysSinceYearZero(toDaysSinceYearZero(toDate('2023-09-08'))) AS date2
```
```response title=Response theme={null}
┌──────date1─┬──────date2─┐
│ 2023-09-08 │ 2023-09-08 │
└────────────┴────────────┘
```
## fromDaysSinceYearZero32
Добавленный в: v23.11.0
Для заданного числа дней, прошедших с [1 January 0000](https://en.wikipedia.org/wiki/Year_zero), возвращает соответствующую дату в [пролептическом григорианском календаре по ISO 8601](https://en.wikipedia.org/wiki/Gregorian_calendar#Proleptic_Gregorian_calendar).
Вычисление выполняется так же, как в функции MySQL `FROM_DAYS()`. Результат не определён, если его нельзя представить в пределах типа [`Date32`](/ru/reference/data-types/date32).
**Синтаксис**
```sql theme={null}
fromDaysSinceYearZero32(days)
```
**Аргументы**
* `days` — Количество дней, прошедших с начала нулевого года. [`UInt32`](/ru/reference/data-types/int-uint)
**Возвращаемое значение**
Возвращает дату, соответствующую числу дней, прошедших с начала нулевого года. [`Date32`](/ru/reference/data-types/date32)
**Примеры**
**Преобразование дней с начала нулевого года в даты**
```sql title=Query theme={null}
SELECT
fromDaysSinceYearZero32(739136) AS date1,
fromDaysSinceYearZero32(toDaysSinceYearZero(toDate('2023-09-08'))) AS date2
```
```response title=Response theme={null}
┌──────date1─┬──────date2─┐
│ 2023-09-08 │ 2023-09-08 │
└────────────┴────────────┘
```
## fromModifiedJulianDay
Добавленный в: v21.1.0
Преобразует число [модифицированного юлианского дня](https://en.wikipedia.org/wiki/Julian_day#Variants) в дату [пролептического григорианского календаря](https://en.wikipedia.org/wiki/Proleptic_Gregorian_calendar) в текстовом формате `YYYY-MM-DD`. Функция поддерживает номера дней от `-678941` до `2973483` (что соответствует датам 0000-01-01 и 9999-12-31 соответственно). Если номер дня выходит за пределы поддерживаемого диапазона, генерируется исключение.
**Синтаксис**
```sql theme={null}
fromModifiedJulianDay(day)
```
**Аргументы**
* `day` — номер модифицированного юлианского дня. [`(U)Int*`](/ru/reference/data-types/int-uint)
**Возвращаемое значение**
Возвращает дату в текстовом виде. [`String`](/ru/reference/data-types/string)
**Примеры**
**Преобразование модифицированного юлианского дня в дату**
```sql title=Query theme={null}
SELECT fromModifiedJulianDay(58849)
```
```response title=Response theme={null}
┌─fromModifiedJulianDay(58849)─┐
│ 2020-01-01 │
└──────────────────────────────┘
```
## fromModifiedJulianDayOrNull
Добавленный в: v21.1.0
Аналогично [`fromModifiedJulianDay()`](#fromModifiedJulianDay), но вместо вызова исключения возвращает `NULL`.
**Синтаксис**
```sql theme={null}
fromModifiedJulianDayOrNull(day)
```
**Аргументы**
* `day` — номер модифицированного юлианского дня. [`(U)Int*`](/ru/reference/data-types/int-uint)
**Возвращаемое значение**
Возвращает дату в текстовом виде для корректного аргумента `day`, в противном случае — `null`. [`Nullable(String)`](/ru/reference/data-types/nullable)
**Примеры**
**Преобразование модифицированного юлианского дня в дату с обработкой `null`**
```sql title=Query theme={null}
SELECT fromModifiedJulianDayOrNull(58849);
SELECT fromModifiedJulianDayOrNull(60000000); -- некорректный аргумент, возвращает NULL
```
```response title=Response theme={null}
┌─fromModified⋯Null(58849)─┐
│ 2020-01-01 │
└──────────────────────────┘
┌─fromModified⋯l(60000000)─┐
│ ᴺᵁᴸᴸ │
└──────────────────────────┘
```
## fromUTCTimestamp
Добавленный в: v22.1.0
Преобразует значение типа дата или дата и время из часового пояса UTC в значение типа дата или дата и время в указанном часовом поясе. Эта функция в основном предназначена для совместимости с Apache Spark и аналогичными фреймворками.
**Синтаксис**
```sql theme={null}
fromUTCTimestamp(datetime, time_zone)
```
**Псевдонимы**: `from_utc_timestamp`
**Аргументы**
* `datetime` — Константное значение даты или даты и времени либо выражение. [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64)
* `time_zone` — Константное значение типа String или выражение, задающее часовой пояс. [`String`](/ru/reference/data-types/string)
**Возвращаемое значение**
Возвращает DateTime/DateTime64 в указанном часовом поясе. [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64)
**Примеры**
**Преобразование времени из часового пояса UTC в указанный часовой пояс**
```sql title=Query theme={null}
SELECT fromUTCTimestamp(toDateTime64('2023-03-16 10:00:00', 3), 'Asia/Shanghai')
```
```response title=Response theme={null}
┌─fromUTCTimestamp(toDateTime64('2023-03-16 10:00:00',3), 'Asia/Shanghai')─┐
│ 2023-03-16 18:00:00.000 │
└─────────────────────────────────────────────────────────────────────────┘
```
## fromUnixTimestamp
Добавленный в: v20.8.0
Эта функция преобразует Unix-временную метку в календарную дату и время суток.
Ее можно вызвать двумя способами:
* Если передан один аргумент типа [`Integer`](/ru/reference/data-types/int-uint), функция возвращает значение типа [`DateTime`](/ru/reference/data-types/datetime), то есть ведет себя как [`toDateTime`](/ru/reference/functions/regular-functions/type-conversion-functions#toDateTime).
* Если переданы два или три аргумента, где первый аргумент — значение типа [`Integer`](/ru/reference/data-types/int-uint), [`Date`](/ru/reference/data-types/date), [`Date32`](/ru/reference/data-types/date32), [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64), второй аргумент — константная строка формата, а третий аргумент — необязательная константная строка часового пояса, функция возвращает значение типа [`String`](/ru/reference/data-types/string), то есть ведет себя как [`formatDateTime`](#formatDateTime).
В этом случае используется [стиль форматирования datetime из MySQL](https://dev.mysql.com/doc/refman/8.0/en/date-and-time-functions.html#function_date-format).
**Синтаксис**
```sql theme={null}
fromUnixTimestamp(timestamp)
fromUnixTimestamp(timestamp[, format[, timezone]])
```
**Псевдонимы**: `FROM_UNIXTIME`
**Аргументы**
* `timestamp` — Unix-временная метка или значение типа date/дата и время. [`(U)Int*`](/ru/reference/data-types/int-uint) или [`Date`](/ru/reference/data-types/date) или [`Date32`](/ru/reference/data-types/date32) или [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64)
* `format` — Необязательно. Константная строка формата для форматирования вывода. [`String`](/ru/reference/data-types/string)
* `timezone` — Необязательно. Константная строка часового пояса. [`String`](/ru/reference/data-types/string)
**Возвращаемое значение**
Возвращает `DateTime`, если вызвана с одним аргументом, или `String`, если вызвана с двумя или тремя аргументами. [`DateTime`](/ru/reference/data-types/datetime) или [`String`](/ru/reference/data-types/string)
**Примеры**
**Преобразование Unix-временной метки в DateTime**
```sql title=Query theme={null}
SELECT fromUnixTimestamp(423543535)
```
```response title=Response theme={null}
┌─fromUnixTimestamp(423543535)─┐
│ 1983-06-04 10:58:55 │
└──────────────────────────────┘
```
**Преобразование Unix-временной метки с указанием формата**
```sql title=Query theme={null}
SELECT fromUnixTimestamp(1234334543, '%Y-%m-%d %R:%S') AS DateTime
```
```response title=Response theme={null}
┌─DateTime────────────┐
│ 2009-02-11 14:42:23 │
└─────────────────────┘
```
## fromUnixTimestampInJodaSyntax
Добавленный в: v23.1.0
Эта функция преобразует Unix-временную метку в календарную дату и время суток.
Её можно вызвать двумя способами:
Если передан один аргумент типа [`Integer`](/ru/reference/data-types/int-uint), функция возвращает значение типа [`DateTime`](/ru/reference/data-types/datetime), то есть ведёт себя как [`toDateTime`](/ru/reference/functions/regular-functions/type-conversion-functions#toDateTime).
Если переданы два или три аргумента, где первый аргумент — значение типа [`Integer`](/ru/reference/data-types/int-uint), [`Date`](/ru/reference/data-types/date), [`Date32`](/ru/reference/data-types/date32), [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64), второй аргумент — константная строка формата, а третий — необязательная константная строка с часовым поясом, функция возвращает значение типа [`String`](/ru/reference/data-types/string), то есть ведёт себя как [`formatDateTimeInJodaSyntax`](#formatDateTimeInJodaSyntax). В этом случае используется [стиль форматирования даты и времени Joda](https://joda-time.sourceforge.net/apidocs/org/joda/time/format/DateTimeFormat.html).
**Синтаксис**
```sql theme={null}
fromUnixTimestampInJodaSyntax(timestamp)
fromUnixTimestampInJodaSyntax(timestamp, format[, timezone])
```
**Аргументы**
* `timestamp` — Unix-временная метка или значение даты и времени. [`(U)Int*`](/ru/reference/data-types/int-uint) или [`Date`](/ru/reference/data-types/date) или [`Date32`](/ru/reference/data-types/date32) или [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64)
* `format` — Необязательно. Константная строка формата в синтаксисе Joda для форматирования вывода. [`String`](/ru/reference/data-types/string)
* `timezone` — Необязательно. Константная строка часового пояса. [`String`](/ru/reference/data-types/string)
**Возвращаемое значение**
Возвращает дату и время при вызове с одним аргументом или строку при вызове с двумя или тремя аргументами.} [`DateTime`](/ru/reference/data-types/datetime) или [`String`](/ru/reference/data-types/string)
**Примеры**
**Преобразование Unix-временной метки в формате Joda**
```sql title=Query theme={null}
SELECT fromUnixTimestampInJodaSyntax(1234334543, 'yyyy-MM-dd HH:mm:ss', 'UTC') AS DateTime
```
```response title=Response theme={null}
┌─DateTime────────────┐
│ 2009-02-11 06:42:23 │
└─────────────────────┘
```
## makeDate
Добавленный в: v22.6.0
Создаёт `Date` на основе:
* года, месяца и дня
* года и порядкового дня в году
**Синтаксис**
```sql theme={null}
makeDate(year, month, day)
makeDate(year, day_of_year)
```
**Аргументы**
* `year` — Номер года. [`(U)Int*`](/ru/reference/data-types/int-uint) или [`Float*`](/ru/reference/data-types/float) или [`Decimal`](/ru/reference/data-types/decimal)
* `month` — Номер месяца (1-12). [`(U)Int*`](/ru/reference/data-types/int-uint) или [`Float*`](/ru/reference/data-types/float) или [`Decimal`](/ru/reference/data-types/decimal)
* `day` — День месяца (1-31). [`(U)Int*`](/ru/reference/data-types/int-uint) или [`Float*`](/ru/reference/data-types/float) или [`Decimal`](/ru/reference/data-types/decimal)
* `day_of_year` — Порядковый день года (1-365). [`(U)Int*`](/ru/reference/data-types/int-uint) или [`Float*`](/ru/reference/data-types/float) или [`Decimal`](/ru/reference/data-types/decimal)
**Возвращаемое значение**
Возвращает значение типа `Date`, сформированное из указанных аргументов [`Date`](/ru/reference/data-types/date)
**Примеры**
**Date из года, месяца и дня**
```sql title=Query theme={null}
SELECT makeDate(2023, 2, 28) AS date;
```
```response title=Response theme={null}
┌───────date─┐
│ 2023-02-28 │
└────────────┘
```
**Дата по году и дню года**
```sql title=Query theme={null}
SELECT makeDate(2023, 42) AS date;
```
```response title=Response theme={null}
┌───────date─┐
│ 2023-02-11 │
└────────────┘
```
## makeDate32
Добавленный в: v22.6.0
Создаёт `Date32`, используя:
* год, месяц и день
* год и день года
**Синтаксис**
```sql theme={null}
makeDate32(year, month, day)
makeDate32(year, day_of_year)
```
**Аргументы**
* `year` — Номер года. [`(U)Int*`](/ru/reference/data-types/int-uint) или [`Float*`](/ru/reference/data-types/float) или [`Decimal`](/ru/reference/data-types/decimal)
* `month` — Номер месяца (1-12). [`(U)Int*`](/ru/reference/data-types/int-uint) или [`Float*`](/ru/reference/data-types/float) или [`Decimal`](/ru/reference/data-types/decimal)
* `day` — День в месяце (1-31). [`(U)Int*`](/ru/reference/data-types/int-uint) или [`Float*`](/ru/reference/data-types/float) или [`Decimal`](/ru/reference/data-types/decimal)
* `day_of_year` — День года (1-365). [`(U)Int*`](/ru/reference/data-types/int-uint) или [`Float*`](/ru/reference/data-types/float) или [`Decimal`](/ru/reference/data-types/decimal)
**Возвращаемое значение**
Возвращает значение `Date32`, созданное на основе переданных аргументов [`Date32`](/ru/reference/data-types/date32)
**Примеры**
**Date32 из года, месяца и дня**
```sql title=Query theme={null}
SELECT makeDate(2023, 2, 28) AS date;
```
```response title=Response theme={null}
┌───────date─┐
│ 2023-02-28 │
└────────────┘
```
**Date32 из года и номера дня в году**
```sql title=Query theme={null}
SELECT makeDate(2023, 42) AS date;
```
```response title=Response theme={null}
┌───────date─┐
│ 2023-02-11 │
└────────────┘
```
## makeDateTime
Добавленный в: v22.6.0
Создаёт значение `DateTime` из года, месяца, дня, часа, минуты и секунды с необязательным часовым поясом.
**Синтаксис**
```sql theme={null}
makeDateTime(year, month, day, hour, minute, second[, timezone])
```
**Аргументы**
* `year` — Год. [`(U)Int*`](/ru/reference/data-types/int-uint) или [`Float*`](/ru/reference/data-types/float) или [`Decimal`](/ru/reference/data-types/decimal)
* `month` — Номер месяца (1-12). [`(U)Int*`](/ru/reference/data-types/int-uint) или [`Float*`](/ru/reference/data-types/float) или [`Decimal`](/ru/reference/data-types/decimal)
* `day` — День месяца (1-31). [`(U)Int*`](/ru/reference/data-types/int-uint) или [`Float*`](/ru/reference/data-types/float) или [`Decimal`](/ru/reference/data-types/decimal)
* `hour` — Час (0-23). [`(U)Int*`](/ru/reference/data-types/int-uint) или [`Float*`](/ru/reference/data-types/float) или [`Decimal`](/ru/reference/data-types/decimal)
* `minute` — Минута (0-59). [`(U)Int*`](/ru/reference/data-types/int-uint) или [`Float*`](/ru/reference/data-types/float) или [`Decimal`](/ru/reference/data-types/decimal)
* `second` — Секунда (0-59). [`(U)Int*`](/ru/reference/data-types/int-uint) или [`Float*`](/ru/reference/data-types/float) или [`Decimal`](/ru/reference/data-types/decimal)
* `timezone` — Имя часового пояса. [`String`](/ru/reference/data-types/string)
**Возвращаемое значение**
Возвращает значение `DateTime`, сформированное из указанных аргументов [`DateTime`](/ru/reference/data-types/datetime)
**Примеры**
**DateTime из года, месяца, дня, часа, минуты и секунды**
```sql title=Query theme={null}
SELECT makeDateTime(2023, 2, 28, 17, 12, 33) AS DateTime;
```
```response title=Response theme={null}
┌────────────DateTime─┐
│ 2023-02-28 17:12:33 │
└─────────────────────┘
```
## makeDateTime64
Добавленный в: v22.6.0
Создаёт `DateTime64` из года, месяца, дня, часа, минуты и секунды с необязательной дробной частью, точностью и часовым поясом.
**Синтаксис**
```sql theme={null}
makeDateTime64(year, month, day, hour, minute, second[, fraction[, precision[, timezone]]])
```
**Аргументы**
* `year` — Номер года. [`(U)Int*`](/ru/reference/data-types/int-uint) или [`Float*`](/ru/reference/data-types/float) или [`Decimal`](/ru/reference/data-types/decimal)
* `month` — Номер месяца (1-12). [`(U)Int*`](/ru/reference/data-types/int-uint) или [`Float*`](/ru/reference/data-types/float) или [`Decimal`](/ru/reference/data-types/decimal)
* `day` — День месяца (1-31). [`(U)Int*`](/ru/reference/data-types/int-uint) или [`Float*`](/ru/reference/data-types/float) или [`Decimal`](/ru/reference/data-types/decimal)
* `hour` — Час (0-23). [`(U)Int*`](/ru/reference/data-types/int-uint) или [`Float*`](/ru/reference/data-types/float) или [`Decimal`](/ru/reference/data-types/decimal)
* `minute` — Минута (0-59). [`(U)Int*`](/ru/reference/data-types/int-uint) или [`Float*`](/ru/reference/data-types/float) или [`Decimal`](/ru/reference/data-types/decimal)
* `second` — Секунда (0-59). [`(U)Int*`](/ru/reference/data-types/int-uint) или [`Float*`](/ru/reference/data-types/float) или [`Decimal`](/ru/reference/data-types/decimal)
* `fraction` — Дробная часть секунды. [`(U)Int*`](/ru/reference/data-types/int-uint) или [`Float*`](/ru/reference/data-types/float) или [`Decimal`](/ru/reference/data-types/decimal)
* `precision` — Точность дробной части (0-9). [`UInt8`](/ru/reference/data-types/int-uint)
* `timezone` — Имя часового пояса. [`String`](/ru/reference/data-types/string)
**Возвращаемое значение**
Возвращает значение `DateTime64`, сформированное из указанных аргументов [`DateTime64`](/ru/reference/data-types/datetime64)
**Примеры**
**DateTime64 из года, месяца, дня, часа, минуты, секунды**
```sql title=Query theme={null}
SELECT makeDateTime64(2023, 5, 15, 10, 30, 45, 779, 5);
```
```response title=Response theme={null}
┌─makeDateTime64(2023, 5, 15, 10, 30, 45, 779, 5)─┐
│ 2023-05-15 10:30:45.00779 │
└─────────────────────────────────────────────────┘
```
## monthName
Добавленный в: v22.1.0
Возвращает название месяца в виде строки из значения типа «дата» или «дата и время».
**Синтаксис**
```sql theme={null}
monthName(datetime)
```
**Аргументы**
* `datetime` — дата или дата и время. [`Date`](/ru/reference/data-types/date) или [`Date32`](/ru/reference/data-types/date32), или [`DateTime`](/ru/reference/data-types/datetime), или [`DateTime64`](/ru/reference/data-types/datetime64)
**Возвращаемое значение**
Возвращает название месяца. [`String`](/ru/reference/data-types/string)
**Примеры**
**Получить название месяца из даты**
```sql title=Query theme={null}
WITH toDateTime('2021-04-14 11:22:33') AS date_value
SELECT monthName(date_value)
```
```response title=Response theme={null}
┌─monthName(date_value)─┐
│ April │
└───────────────────────┘
```
## now
Добавленный в: v1.1.0
Возвращает текущие дату и время на момент анализа запроса. Эта функция является константным выражением.
**Синтаксис**
```sql theme={null}
now([timezone])
```
**Псевдонимы**: `current_timestamp`
**Аргументы**
* `timezone` — Необязательный. Имя часового пояса для возвращаемого значения. [`String`](/ru/reference/data-types/string)
**Возвращаемое значение**
Возвращает текущие дату и время. [`DateTime`](/ru/reference/data-types/datetime)
**Примеры**
**Запрос без указания часового пояса**
```sql title=Query theme={null}
SELECT now()
```
```response title=Response theme={null}
┌───────────────now()─┐
│ 2020-10-17 07:42:09 │
└─────────────────────┘
```
**Запрос с указанным часовым поясом**
```sql title=Query theme={null}
SELECT now('Asia/Istanbul')
```
```response title=Response theme={null}
┌─now('Asia/Istanbul')─┐
│ 2020-10-17 10:42:23 │
└──────────────────────┘
```
**Стандартный синтаксис SQL без скобок**
```sql title=Query theme={null}
SELECT NOW, CURRENT_TIMESTAMP
```
```response title=Response theme={null}
┌─────────────────NOW─┬───CURRENT_TIMESTAMP─┐
│ 2020-10-17 07:42:19 │ 2020-10-17 07:42:19 │
└─────────────────────┴─────────────────────┘
```
## now64
Добавленный в: v20.1.0
Возвращает текущие дату и время с точностью до долей секунды в момент анализа запроса. Функция является константным выражением.
**Синтаксис**
```sql theme={null}
now64([scale[, timezone]])
```
**Аргументы**
* `scale` — Необязательный. Размер шага (точность): 10^-precision секунды. Допустимый диапазон: \[0 : 9]. Обычно используются значения 3 (по умолчанию) — миллисекунды, 6 — микросекунды, 9 — наносекунды. [`UInt8`](/ru/reference/data-types/int-uint)
* `timezone` — Необязательный. Название часового пояса для возвращаемого значения. [`String`](/ru/reference/data-types/string)
**Возвращаемое значение**
Возвращает текущие дату и время с точностью до долей секунды. [`DateTime64`](/ru/reference/data-types/datetime64)
**Примеры**
**Запрос со стандартной и пользовательской точностью**
```sql title=Query theme={null}
SELECT now64(), now64(9, 'Asia/Istanbul')
```
```response title=Response theme={null}
┌─────────────────now64()─┬─────now64(9, 'Asia/Istanbul')─┐
│ 2022-08-21 19:34:26.196 │ 2022-08-21 22:34:26.196542766 │
└─────────────────────────┴───────────────────────────────┘
```
## nowInBlock
Добавленный в: v22.8.0
Возвращает текущие дату и время на момент обработки каждого блока данных. В отличие от функции [`now`](#now), это не константное выражение, и при длительном выполнении запроса возвращаемое значение будет различаться в разных блоках.
Эту функцию имеет смысл использовать для генерации текущего времени в длительно выполняющихся запросах `INSERT SELECT`.
**Синтаксис**
```sql theme={null}
nowInBlock([timezone])
```
**Аргументы**
* `timezone` — Необязательный параметр. Имя часового пояса для возвращаемого значения. [`String`](/ru/reference/data-types/string)
**Возвращаемое значение**
Возвращает текущие дату и время на момент обработки каждого блока данных. [`DateTime`](/ru/reference/data-types/datetime)
**Примеры**
**Отличие от функции now()**
```sql title=Query theme={null}
SELECT
now(),
nowInBlock(),
sleep(1)
FROM numbers(3)
SETTINGS max_block_size = 1
FORMAT PrettyCompactMonoBlock
```
```response title=Response theme={null}
┌───────────────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.0
Возвращает текущие дату и время в миллисекундах на момент обработки каждого блока данных. В отличие от функции [now64](#now64), это не константное выражение, и при длительно выполняющихся запросах возвращаемое значение будет различаться в разных блоках.
Эту функцию имеет смысл использовать для генерации текущего времени в длительно выполняющихся запросах INSERT SELECT.
**Синтаксис**
```sql theme={null}
nowInBlock64([scale[, timezone]])
```
**Аргументы**
* `scale` — Необязательный. Размер шага (precision): 10^-precision секунды. Допустимый диапазон: \[0 : 9]. Обычно используются значения 3 (по умолчанию) (миллисекунды), 6 (микросекунды), 9 (наносекунды). [`UInt8`](/ru/reference/data-types/int-uint)
* `timezone` — Необязательный. Имя часового пояса для возвращаемого значения. [`String`](/ru/reference/data-types/string)
**Возвращаемое значение**
Возвращает текущие дату и время на момент обработки каждого блока данных с точностью до долей секунды. [`DateTime64`](/ru/reference/data-types/datetime64)
**Примеры**
**Отличие от функции now64()**
```sql title=Query theme={null}
SELECT
now64(),
nowInBlock64(),
sleep(1)
FROM numbers(3)
SETTINGS max_block_size = 1
FORMAT PrettyCompactMonoBlock
```
```response title=Response theme={null}
┌─────────────────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.0
Возвращает часовой пояс сервера, то есть значение настройки [`timezone`](/ru/reference/settings/server-settings/settings#timezone).
Если функция выполняется в контексте distributed таблицы, она создаёт обычный столбец со значениями для каждого сегмента. В противном случае она возвращает константное значение.
**Синтаксис**
```sql theme={null}
serverTimezone()
```
**Псевдонимы**: `serverTimeZone`
**Аргументы**
* Нет.
**Возвращаемое значение**
Возвращает часовой пояс сервера в виде [`String`](/ru/reference/data-types/string)
**Примеры**
**Пример использования**
```sql title=Query theme={null}
SELECT serverTimeZone()
```
```response title=Response theme={null}
┌─serverTimeZone()─┐
│ UTC │
└──────────────────┘
```
## subDate
Добавленный в: v23.9.0
Вычитает интервал времени из указанной даты, даты и времени или даты либо даты и времени в строковом формате.
Если в результате вычитания получается значение, выходящее за пределы типа данных, результат не определён.
**Синтаксис**
```sql theme={null}
subDate(datetime, interval)
```
**Аргументы**
* `datetime` — Дата или дата и время, из которого вычитается `interval`. [`Date`](/ru/reference/data-types/date) or [`Date32`](/ru/reference/data-types/date32) or [`DateTime`](/ru/reference/data-types/datetime) or [`DateTime64`](/ru/reference/data-types/datetime64)
* `interval` — Интервал, который нужно вычесть. [`Interval`](/ru/reference/data-types/int-uint)
**Возвращаемое значение**
Возвращает дату или дату и время, полученные в результате вычитания `interval` из `datetime`. [`Date`](/ru/reference/data-types/date) or [`Date32`](/ru/reference/data-types/date32) or [`DateTime`](/ru/reference/data-types/datetime) or [`DateTime64`](/ru/reference/data-types/datetime64)
**Примеры**
**Вычитание интервала из даты**
```sql title=Query theme={null}
SELECT subDate(toDate('2018-01-01'), INTERVAL 3 YEAR)
```
```response title=Response theme={null}
┌─subDate(toDate('2018-01-01'), toIntervalYear(3))─┐
│ 2015-01-01 │
└──────────────────────────────────────────────────┘
```
## subtractDays
Добавленный в: v1.1.0
Вычитает указанное количество дней из даты, даты и времени или даты либо даты и времени в строковом формате.
**Синтаксис**
```sql theme={null}
subtractDays(datetime, num)
```
**Аргументы**
* `datetime` — дата или дата и время, из которых вычитается указанное количество дней. [`Date`](/ru/reference/data-types/date) или [`Date32`](/ru/reference/data-types/date32) или [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64) или [`String`](/ru/reference/data-types/string)
* `num` — количество дней, которое нужно вычесть. [`(U)Int*`](/ru/reference/data-types/int-uint) или [`Float*`](/ru/reference/data-types/float)
**Возвращаемое значение**
Возвращает значение `datetime` за вычетом `num` дней [`Date`](/ru/reference/data-types/date) или [`Date32`](/ru/reference/data-types/date32) или [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64)
**Примеры**
**Вычитание дней из значений разных типов даты**
```sql title=Query theme={null}
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
```
```response title=Response theme={null}
┌─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**
```sql title=Query theme={null}
SELECT dateSub('1998-06-16'::Date, INTERVAL 10 day)
```
```response title=Response theme={null}
┌─minus(CAST('⋯valDay(10))─┐
│ 1998-06-06 │
└──────────────────────────┘
```
## subtractHours
Добавленный в: v1.1.0
Вычитает указанное количество часов из даты, даты и времени или даты либо даты и времени в строковом формате.
**Синтаксис**
```sql theme={null}
subtractHours(datetime, num)
```
**Аргументы**
* `datetime` — Дата или дата и время, из которой нужно вычесть указанное количество часов. [`Date`](/ru/reference/data-types/date) или [`Date32`](/ru/reference/data-types/date32) или [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64) или [`String`](/ru/reference/data-types/string)
* `num` — Количество часов, которое нужно вычесть. [`(U)Int*`](/ru/reference/data-types/int-uint) или [`Float*`](/ru/reference/data-types/float)
**Возвращаемое значение**
Возвращает значение `datetime` за вычетом `num` часов: [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64(3)`](/ru/reference/data-types/datetime64)
**Примеры**
**Вычитание часов из значений разных типов даты**
```sql title=Query theme={null}
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
```
```response title=Response theme={null}
┌─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**
```sql title=Query theme={null}
SELECT dateSub('1998-06-16'::Date, INTERVAL 10 hour)
```
```response title=Response theme={null}
┌─minus(CAST('⋯alHour(10))─┐
│ 1998-06-15 14:00:00 │
└──────────────────────────┘
```
## subtractInterval
Добавленный в: v22.11.0
Добавляет отрицательный интервал к другому интервалу или кортежу интервалов.
Примечание: интервалы одного и того же типа объединяются в один интервал. Например, если переданы `toIntervalDay(2)` и `toIntervalDay(1)`,
то результатом будет `(1)`, а не `(2,1)`.
**Синтаксис**
```sql theme={null}
subtractInterval(interval_1, interval_2)
```
**Аргументы**
* `interval_1` — Первый интервал или кортеж интервалов. [`Interval`](/ru/reference/data-types/int-uint) или [`Tuple(Interval)`](/ru/reference/data-types/tuple)
* `interval_2` — Второй интервал с противоположным знаком. [`Interval`](/ru/reference/data-types/int-uint)
**Возвращаемое значение**
Возвращает кортеж интервалов [`Tuple(T)`](/ru/reference/data-types/tuple)
**Примеры**
**Вычитание интервалов**
```sql title=Query theme={null}
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);
```
```response title=Response theme={null}
┌─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.0
Вычитает указанное количество микросекунд из значения типа дата и время или из даты и времени, представленных в виде строки.
**Синтаксис**
```sql theme={null}
subtractMicroseconds(datetime, num)
```
**Аргументы**
* `datetime` — Значение даты и времени, из которого нужно вычесть указанное количество микросекунд. [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64) или [`String`](/ru/reference/data-types/string)
* `num` — Количество микросекунд, которое нужно вычесть. [`(U)Int*`](/ru/reference/data-types/int-uint) или [`Float*`](/ru/reference/data-types/float)
**Возвращаемое значение**
Возвращает `datetime` за вычетом `num` микросекунд. [`DateTime64`](/ru/reference/data-types/datetime64)
**Примеры**
**Вычитание микросекунд из значений разных типов даты и времени**
```sql title=Query theme={null}
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
```
```response title=Response theme={null}
┌─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**
```sql title=Query theme={null}
SELECT dateSub('1998-06-16'::DateTime, INTERVAL 10 microsecond)
```
```response title=Response theme={null}
┌─minus(CAST('1⋯osecond(10))─┐
│ 1998-06-15 23:59:59.999990 │
└────────────────────────────┘
```
## subtractMilliseconds
Добавленный в: v22.6.0
Вычитает указанное количество миллисекунд из значения типа «дата и время» или из даты и времени, представленных в виде строки.
**Синтаксис**
```sql theme={null}
subtractMilliseconds(datetime, num)
```
**Аргументы**
* `datetime` — Дата и время, из которых нужно вычесть указанное количество миллисекунд. [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64), либо [`String`](/ru/reference/data-types/string)
* `num` — Количество миллисекунд для вычитания. [`(U)Int*`](/ru/reference/data-types/int-uint) или [`Float*`](/ru/reference/data-types/float)
**Возвращаемое значение**
Возвращает значение `datetime` за вычетом `num` миллисекунд. [`DateTime64`](/ru/reference/data-types/datetime64)
**Примеры**
**Вычитание миллисекунд из различных типов даты и времени**
```sql title=Query theme={null}
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
```
```response title=Response theme={null}
┌─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**
```sql title=Query theme={null}
SELECT dateSub('1998-06-16'::DateTime, INTERVAL 10 millisecond)
```
```response title=Response theme={null}
┌─minus(CAST('⋯second(10))─┐
│ 1998-06-15 23:59:59.990 │
└──────────────────────────┘
```
## subtractMinutes
Добавленный в: v1.1.0
Вычитает указанное количество минут из даты, даты и времени или из строки, представляющей дату либо дату и время.
**Синтаксис**
```sql theme={null}
subtractMinutes(datetime, num)
```
**Аргументы**
* `datetime` — дата или дата и время, из которых нужно вычесть указанное количество минут. [`Date`](/ru/reference/data-types/date) или [`Date32`](/ru/reference/data-types/date32) или [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64) или [`String`](/ru/reference/data-types/string)
* `num` — количество минут, которое нужно вычесть. [`(U)Int*`](/ru/reference/data-types/int-uint) или [`Float*`](/ru/reference/data-types/float)
**Возвращаемое значение**
Возвращает значение `datetime` за вычетом `num` минут. [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64(3)`](/ru/reference/data-types/datetime64)
**Примеры**
**Вычитание минут из значений разных типов даты**
```sql title=Query theme={null}
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
```
```response title=Response theme={null}
┌─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**
```sql title=Query theme={null}
SELECT dateSub('1998-06-16'::Date, INTERVAL 10 minute)
```
```response title=Response theme={null}
┌─minus(CAST('⋯Minute(10))─┐
│ 1998-06-15 23:50:00 │
└──────────────────────────┘
```
## subtractMonths
Добавленный в: v1.1.0
Вычитает указанное количество месяцев из даты, даты и времени или строки с датой либо датой и временем.
**Синтаксис**
```sql theme={null}
subtractMonths(datetime, num)
```
**Аргументы**
* `datetime` — дата или дата и время, из которых нужно вычесть указанное количество месяцев. [`Date`](/ru/reference/data-types/date) или [`Date32`](/ru/reference/data-types/date32) или [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64) или [`String`](/ru/reference/data-types/string)
* `num` — количество месяцев, которое нужно вычесть. [`(U)Int*`](/ru/reference/data-types/int-uint) или [`Float*`](/ru/reference/data-types/float)
**Возвращаемое значение**
Возвращает `datetime` минус `num` месяцев. [`Date`](/ru/reference/data-types/date) или [`Date32`](/ru/reference/data-types/date32) или [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64)
**Примеры**
**Вычитание месяцев из различных типов дат**
```sql title=Query theme={null}
WITH
toDate('2024-01-01') AS date,
toDateTime('2024-01-01 00:00:00') AS date_time,
'2024-01-01 00:00:00' AS date_time_string
SELECT
subtractMonths(date, 1) AS subtract_months_with_date,
subtractMonths(date_time, 1) AS subtract_months_with_date_time,
subtractMonths(date_time_string, 1) AS subtract_months_with_date_time_string
```
```response title=Response theme={null}
┌─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**
```sql title=Query theme={null}
SELECT dateSub('1998-06-16'::Date, INTERVAL 10 month)
```
```response title=Response theme={null}
┌─minus(CAST('⋯lMonth(10))─┐
│ 1997-08-16 │
└──────────────────────────┘
```
## subtractNanoseconds
Добавленный в: v20.1.0
Вычитает указанное количество наносекунд из значения типа «дата и время» или из даты и времени, представленных в виде строки.
**Синтаксис**
```sql theme={null}
subtractNanoseconds(datetime, num)
```
**Аргументы**
* `datetime` — дата и время, из которых нужно вычесть указанное количество наносекунд. [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64), или [`String`](/ru/reference/data-types/string)
* `num` — количество наносекунд, которое нужно вычесть. [`(U)Int*`](/ru/reference/data-types/int-uint) или [`Float*`](/ru/reference/data-types/float)
**Возвращаемое значение**
Возвращает `datetime` за вычетом `num` наносекунд. [`DateTime64`](/ru/reference/data-types/datetime64)
**Примеры**
**Вычитание наносекунд из значений разных типов даты и времени**
```sql title=Query theme={null}
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
```
```response title=Response theme={null}
┌─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**
```sql title=Query theme={null}
SELECT dateSub('1998-06-16'::DateTime, INTERVAL 10 nanosecond)
```
```response title=Response theme={null}
┌─minus(CAST('19⋯anosecond(10))─┐
│ 1998-06-15 23:59:59.999999990 │
└───────────────────────────────┘
```
## subtractQuarters
Добавленный в: v20.1.0
Вычитает указанное количество кварталов из даты, даты и времени или даты либо даты и времени, представленных в виде строки.
**Синтаксис**
```sql theme={null}
subtractQuarters(datetime, num)
```
**Аргументы**
* `datetime` — дата или дата и время, из которых нужно вычесть указанное количество кварталов. [`Date`](/ru/reference/data-types/date) or [`Date32`](/ru/reference/data-types/date32) or [`DateTime`](/ru/reference/data-types/datetime) or [`DateTime64`](/ru/reference/data-types/datetime64) or [`String`](/ru/reference/data-types/string)
* `num` — количество кварталов, которое нужно вычесть. [`(U)Int*`](/ru/reference/data-types/int-uint) or [`Float*`](/ru/reference/data-types/float)
**Возвращаемое значение**
Возвращает значение `datetime` за вычетом `num` кварталов [`Date`](/ru/reference/data-types/date) or [`Date32`](/ru/reference/data-types/date32) or [`DateTime`](/ru/reference/data-types/datetime) or [`DateTime64`](/ru/reference/data-types/datetime64)
**Примеры**
**Вычитание кварталов для разных типов дат**
```sql title=Query theme={null}
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
```
```response title=Response theme={null}
┌─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**
```sql title=Query theme={null}
SELECT dateSub('1998-06-16'::Date, INTERVAL 10 quarter)
```
```response title=Response theme={null}
┌─minus(CAST('1⋯Quarter(10))─┐
│ 1996-09-16 │
└───────────────────────────┘
```
## subtractSeconds
Добавленный в: v1.1.0
Вычитает указанное количество секунд из даты, даты и времени или даты либо даты и времени, представленных в виде строки.
**Синтаксис**
```sql theme={null}
subtractSeconds(datetime, num)
```
**Аргументы**
* `datetime` — Дата или дата и время, из которых вычитается указанное количество секунд. [`Date`](/ru/reference/data-types/date) или [`Date32`](/ru/reference/data-types/date32) или [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64) или [`String`](/ru/reference/data-types/string)
* `num` — Количество секунд, которое нужно вычесть. [`(U)Int*`](/ru/reference/data-types/int-uint) или [`Float*`](/ru/reference/data-types/float)
**Возвращаемое значение**
Возвращает `datetime` за вычетом `num` секунд. [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64(3)`](/ru/reference/data-types/datetime64)
**Примеры**
**Вычитание секунд из различных типов дат**
```sql title=Query theme={null}
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
```
```response title=Response theme={null}
┌─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**
```sql title=Query theme={null}
SELECT dateSub('1998-06-16'::Date, INTERVAL 10 second)
```
```response title=Response theme={null}
┌─minus(CAST('⋯Second(10))─┐
│ 1998-06-15 23:59:50 │
└──────────────────────────┘
```
## subtractTupleOfIntervals
Добавленный в: v22.11.0
Последовательно вычитает кортеж интервалов из даты или даты и времени.
**Синтаксис**
```sql theme={null}
subtractTupleOfIntervals(datetime, intervals)
```
**Аргументы**
* `datetime` — Дата или дата и время, из которых нужно вычесть интервалы. [`Date`](/ru/reference/data-types/date) или [`Date32`](/ru/reference/data-types/date32) или [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64)
* `intervals` — Кортеж интервалов, которые нужно вычесть из `datetime`. [`Tuple(Interval)`](/ru/reference/data-types/tuple)
**Возвращаемое значение**
Возвращает `date`, из которого вычтены `intervals`: [`Date`](/ru/reference/data-types/date) или [`Date32`](/ru/reference/data-types/date32) или [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64)
**Примеры**
**Вычитание кортежа интервалов из даты**
```sql title=Query theme={null}
WITH toDate('2018-01-01') AS date SELECT subtractTupleOfIntervals(date, (INTERVAL 1 DAY, INTERVAL 1 YEAR))
```
```response title=Response theme={null}
┌─subtractTupl⋯alYear(1)))─┐
│ 2016-12-31 │
└──────────────────────────┘
```
## subtractWeeks
Добавленный в: v1.1.0
Вычитает указанное количество недель из даты, даты и времени или даты/даты и времени, представленных в виде строки.
**Синтаксис**
```sql theme={null}
subtractWeeks(datetime, num)
```
**Аргументы**
* `datetime` — дата или дата и время, из которых нужно вычесть указанное количество недель. [`Date`](/ru/reference/data-types/date) или [`Date32`](/ru/reference/data-types/date32) или [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64) или [`String`](/ru/reference/data-types/string)
* `num` — количество недель, которое нужно вычесть. [`(U)Int*`](/ru/reference/data-types/int-uint) или [`Float*`](/ru/reference/data-types/float)
**Возвращаемое значение**
Возвращает `datetime` минус `num` недель. [`Date`](/ru/reference/data-types/date) или [`Date32`](/ru/reference/data-types/date32) или [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64)
**Примеры**
**Вычитание недель из значений разных типов даты**
```sql title=Query theme={null}
WITH
toDate('2024-01-01') AS date,
toDateTime('2024-01-01 00:00:00') AS date_time,
'2024-01-01 00:00:00' AS date_time_string
SELECT
subtractWeeks(date, 1) AS subtract_weeks_with_date,
subtractWeeks(date_time, 1) AS subtract_weeks_with_date_time,
subtractWeeks(date_time_string, 1) AS subtract_weeks_with_date_time_string
```
```response title=Response theme={null}
┌─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**
```sql title=Query theme={null}
SELECT dateSub('1998-06-16'::Date, INTERVAL 10 week)
```
```response title=Response theme={null}
┌─minus(CAST('⋯alWeek(10))─┐
│ 1998-04-07 │
└──────────────────────────┘
```
## subtractYears
Добавленный в: v1.1.0
Вычитает указанное количество лет из даты, даты и времени или даты либо даты и времени в строковом формате.
**Синтаксис**
```sql theme={null}
subtractYears(datetime, num)
```
**Аргументы**
* `datetime` — дата или дата и время, из которых нужно вычесть указанное количество лет. [`Date`](/ru/reference/data-types/date) или [`Date32`](/ru/reference/data-types/date32) или [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64) или [`String`](/ru/reference/data-types/string)
* `num` — количество лет, которое нужно вычесть. [`(U)Int*`](/ru/reference/data-types/int-uint) или [`Float*`](/ru/reference/data-types/float)
**Возвращаемое значение**
Возвращает `datetime` за вычетом `num` лет. [`Date`](/ru/reference/data-types/date) или [`Date32`](/ru/reference/data-types/date32) или [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64)
**Примеры**
**Вычитание лет из разных типов дат**
```sql title=Query theme={null}
WITH
toDate('2024-01-01') AS date,
toDateTime('2024-01-01 00:00:00') AS date_time,
'2024-01-01 00:00:00' AS date_time_string
SELECT
subtractYears(date, 1) AS subtract_years_with_date,
subtractYears(date_time, 1) AS subtract_years_with_date_time,
subtractYears(date_time_string, 1) AS subtract_years_with_date_time_string
```
```response title=Response theme={null}
┌─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**
```sql title=Query theme={null}
SELECT dateSub('1998-06-16'::Date, INTERVAL 10 year)
```
```response title=Response theme={null}
┌─minus(CAST('⋯alYear(10))─┐
│ 1988-06-16 │
└──────────────────────────┘
```
## timeDiff
Добавленный в: v23.4.0
Возвращает разницу между двумя датами или значениями даты и времени в секундах.
Разница вычисляется как `enddate` - `startdate`.
Эта функция эквивалентна `dateDiff('second', startdate, enddate)`.
Чтобы вычислить разницу во времени в других единицах (часах, днях, месяцах и т. д.), используйте функцию [`dateDiff`](#dateDiff).
**Синтаксис**
```sql theme={null}
timeDiff(startdate, enddate)
```
**Аргументы**
* `startdate` — Первое значение времени, которое вычитается (вычитаемое). [`Date`](/ru/reference/data-types/date) или [`Date32`](/ru/reference/data-types/date32) или [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64)
* `enddate` — Второе значение времени, из которого вычитается первое (уменьшаемое). [`Date`](/ru/reference/data-types/date) или [`Date32`](/ru/reference/data-types/date32) или [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64)
**Возвращаемое значение**
Возвращает разницу между `enddate` и `startdate`, выраженную в секундах. [`Int64`](/ru/reference/data-types/int-uint)
**Примеры**
**Вычисление разницы во времени в секундах**
```sql title=Query theme={null}
SELECT timeDiff(toDateTime('2018-01-01 22:00:00'), toDateTime('2018-01-02 23:00:00')) AS res
```
```response title=Response theme={null}
┌───res─┐
│ 90000 │
└───────┘
```
**Рассчитать разницу во времени и перевести в часы**
```sql title=Query theme={null}
SELECT timeDiff(toDateTime('2018-01-01 22:00:00'), toDateTime('2018-01-02 23:00:00')) / 3600 AS hours
```
```response title=Response theme={null}
┌─hours─┐
│ 25 │
└───────┘
```
**Эквивалентно dateDiff в секундах**
```sql title=Query theme={null}
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
```
```response title=Response theme={null}
┌─time_diff_result─┬─date_diff_result─┐
│ 259200 │ 259200 │
└──────────────────┴──────────────────┘
```
## timeSlot
Добавленный в: v1.1.0
Округляет время до начала получасового интервала.
Хотя эта функция может принимать в качестве аргумента значения расширенных типов `Date32` и `DateTime64`,
передача ей времени вне обычного диапазона (с 1970 по 2149 год для `Date` / до 2106 года для `DateTime`) приведет к неверным результатам.
**Синтаксис**
```sql theme={null}
timeSlot(time[, time_zone])
```
**Аргументы**
* `time` — Время, которое нужно округлить до начала получасового интервала. [`DateTime`](/ru/reference/data-types/datetime) или [`Date32`](/ru/reference/data-types/date32) или [`DateTime64`](/ru/reference/data-types/datetime64)
* `time_zone` — Необязательно. Константное значение типа String или выражение, задающее часовой пояс. [`String`](/ru/reference/data-types/string)
**Возвращаемое значение**
Возвращает время, округлённое до начала получасового интервала. [`DateTime`](/ru/reference/data-types/datetime)
**Примеры**
**Округление времени до получасового интервала**
```sql title=Query theme={null}
SELECT timeSlot(toDateTime('2000-01-02 03:04:05', 'UTC'))
```
```response title=Response theme={null}
┌─timeSlot(toDateTime('2000-01-02 03:04:05', 'UTC'))─┐
│ 2000-01-02 03:00:00 │
└────────────────────────────────────────────────────┘
```
## timeSlots
Добавленный в: v1.1.0
Для интервала времени, начинающегося в `StartTime` и длящегося `Duration` секунд, возвращает массив моментов времени, состоящий из точек этого интервала, округлённых вниз с шагом `Size` секунд. `Size` — необязательный параметр, по умолчанию равный 1800 (30 минутам).
Это необходимо, например, при поиске просмотров страниц в соответствующем сеансе.
Для `DateTime64` масштаб возвращаемого значения может отличаться от масштаба `StartTime`. Используется наибольший масштаб среди всех переданных аргументов.
**Синтаксис**
```sql theme={null}
timeSlots(StartTime, Duration[, Size])
```
**Аргументы**
* `StartTime` — Время начала интервала. [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64)
* `Duration` — Длительность интервала в секундах. [`UInt32`](/ru/reference/data-types/int-uint) или [`DateTime64`](/ru/reference/data-types/datetime64)
* `Size` — Необязательно. Размер временных слотов в секундах. По умолчанию — 1800 (30 минут). [`UInt32`](/ru/reference/data-types/int-uint) или [`DateTime64`](/ru/reference/data-types/datetime64)
**Возвращаемое значение**
Возвращает массив значений DateTime/DateTime64 (тип возвращаемого значения соответствует типу `StartTime`). Для DateTime64 масштаб возвращаемого значения может отличаться от масштаба `StartTime` — берется наибольший масштаб среди всех переданных аргументов. [`Array(DateTime)`](/ru/reference/data-types/array) или [`Array(DateTime64)`](/ru/reference/data-types/array)
**Примеры**
**Генерация временных слотов для интервала**
```sql title=Query theme={null}
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))
```
```response title=Response theme={null}
┌─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'] │
└───────────────────────────────────────────────────────────────────────────────────────────────────────────┘
```
## временная метка
Добавленный в: v23.9.0
Преобразует первый аргумент `expr` в тип [`DateTime64(6)`](/ru/reference/data-types/datetime64).
Если указан второй аргумент `expr_time`, к преобразованному значению будет добавлено указанное время.
**Синтаксис**
```sql theme={null}
timestamp(expr[, expr_time])
```
**Аргументы**
* `expr` — Дата или дата и время. [`String`](/ru/reference/data-types/string)
* `expr_time` — Необязательно. Время, которое будет добавлено к преобразованному значению. [`String`](/ru/reference/data-types/string)
**Возвращаемое значение**
Возвращает преобразованное значение `expr` или `expr` с добавленным временем в формате [`DateTime64(6)`](/ru/reference/data-types/datetime64)
**Примеры**
**Преобразование строки даты в DateTime64(6)**
```sql title=Query theme={null}
SELECT timestamp('2023-12-31') AS ts;
```
```response title=Response theme={null}
┌─────────────────────────ts─┐
│ 2023-12-31 00:00:00.000000 │
└────────────────────────────┘
```
**Добавить время к строке с датой**
```sql title=Query theme={null}
SELECT timestamp('2023-12-31 12:00:00', '12:00:00.11') AS ts;
```
```response title=Response theme={null}
┌─────────────────────────ts─┐
│ 2024-01-01 00:00:00.110000 │
└────────────────────────────┘
```
## timezone
Добавленный в: v21.4.0
Возвращает имя часового пояса текущего сеанса или преобразует смещение либо название часового пояса в каноническое имя часового пояса.
**Синтаксис**
```sql theme={null}
timezone()
```
**Псевдонимы**: `timeZone`
**Аргументы**
* Нет.
**Возвращаемое значение**
Возвращает каноническое имя часового пояса в виде [`String`](/ru/reference/data-types/string)
**Примеры**
**Пример использования**
```sql title=Query theme={null}
SELECT timezone()
```
```response title=Response theme={null}
┌─timezone()───────┐
│ Europe/Amsterdam │
└──────────────────┘
```
## timezoneOf
Добавленный в: v21.4.0
Возвращает название часового пояса для значения [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64).
**Синтаксис**
```sql theme={null}
timezoneOf(datetime)
```
**Псевдонимы**: `timeZoneOf`
**Аргументы**
* `datetime` — Значение типа [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64)
* `timezone` — Необязательно. Имя часового пояса, в который нужно преобразовать значение `datetime`. [`String`](/ru/reference/data-types/string)
**Возвращаемое значение**
Возвращает имя часового пояса для `datetime`. [`String`](/ru/reference/data-types/string)
**Примеры**
**Пример использования**
```sql title=Query theme={null}
SELECT timezoneOf(now());
```
```response title=Response theme={null}
┌─timezoneOf(now())─┐
│ Europe/Amsterdam │
└───────────────────┘
```
## timezoneOffset
Добавленный в: v21.6.0
Возвращает смещение часового пояса относительно [UTC](https://en.wikipedia.org/wiki/Coordinated_Universal_Time) в секундах.
Функция учитывает переход на летнее время и исторические изменения часового пояса для указанных даты и времени.
**Синтаксис**
```sql theme={null}
timezoneOffset(datetime)
```
**Псевдонимы**: `timeZoneOffset`
**Аргументы**
* `datetime` — значение `DateTime`, для которого требуется получить смещение часового пояса. [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64)
**Возвращаемое значение**
Возвращает смещение относительно UTC в секундах [`Int32`](/ru/reference/data-types/int-uint)
**Примеры**
**Пример использования**
```sql title=Query theme={null}
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;
```
```response title=Response theme={null}
┌────────────────Time─┬─Type─────────────────────────┬─Offset_in_seconds─┬─Offset_in_hours─┐
│ 2021-04-21 10:20:30 │ DateTime('America/New_York') │ -14400 │ -4 │
└─────────────────────┴──────────────────────────────┴───────────────────┴─────────────────┘
```
## toDayOfMonth
Добавленный в: v1.1.0
Возвращает день месяца (1–31) из значения типа `Date` или `DateTime`.
**Синтаксис**
```sql theme={null}
toDayOfMonth(datetime)
```
**Псевдонимы**: `DAY`, `DAYOFMONTH`
**Аргументы**
* `datetime` — Дата или дата и время, из которых извлекается день месяца. [`Date`](/ru/reference/data-types/date) или [`Date32`](/ru/reference/data-types/date32) или [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64)
**Возвращаемое значение**
Возвращает день месяца для указанной даты/времени [`UInt8`](/ru/reference/data-types/int-uint)
**Примеры**
**Пример использования**
```sql title=Query theme={null}
SELECT toDayOfMonth(toDateTime('2023-04-21 10:20:30'))
```
```response title=Response theme={null}
┌─toDayOfMonth(toDateTime('2023-04-21 10:20:30'))─┐
│ 21 │
└─────────────────────────────────────────────────┘
```
## toDayOfWeek
Добавленный в: v1.1.0
Возвращает номер дня недели для значения `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 |
**Синтаксис**
```sql theme={null}
toDayOfWeek(datetime[, mode[, timezone]])
```
**Псевдонимы**: `DAYOFWEEK`
**Аргументы**
* `datetime` — Дата или дата и время, для которых нужно определить день недели. [`Date`](/ru/reference/data-types/date) или [`Date32`](/ru/reference/data-types/date32) или [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64)
* `mode` — Необязательный параметр. Целое число, задающее режим недели (0-3). Если не указан, по умолчанию используется 0. [`UInt8`](/ru/reference/data-types/int-uint)
* `timezone` — Необязательный параметр. Часовой пояс, используемый для преобразования. [`String`](/ru/reference/data-types/string)
**Возвращаемое значение**
Возвращает день недели для указанного `Date` или `DateTime`. [`UInt8`](/ru/reference/data-types/int-uint)
**Примеры**
**Пример использования**
```sql title=Query theme={null}
-- Следующая дата — 21 апреля 2023 года, это пятница:
SELECT
toDayOfWeek(toDateTime('2023-04-21')),
toDayOfWeek(toDateTime('2023-04-21'), 1)
```
```response title=Response theme={null}
┌─toDayOfWeek(toDateTime('2023-04-21'))─┬─toDayOfWeek(toDateTime('2023-04-21'), 1)─┐
│ 5 │ 4 │
└───────────────────────────────────────┴──────────────────────────────────────────┘
```
## toDayOfYear
Добавленный в: v18.4.0
Возвращает номер дня в году (1–366) для значения типа `Date` или `DateTime`.
**Синтаксис**
```sql theme={null}
toDayOfYear(datetime)
```
**Псевдонимы**: `DAYOFYEAR`
**Аргументы**
* `datetime` — дата или дата и время, из которых нужно получить день года. [`Date`](/ru/reference/data-types/date) или [`Date32`](/ru/reference/data-types/date32) или [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64)
**Возвращаемое значение**
Возвращает день года для указанного значения Date или DateTime [`UInt16`](/ru/reference/data-types/int-uint)
**Примеры**
**Пример использования**
```sql title=Query theme={null}
SELECT toDayOfYear(toDateTime('2023-04-21 10:20:30'))
```
```response title=Response theme={null}
┌─toDayOfYear(toDateTime('2023-04-21 10:20:30'))─┐
│ 111 │
└────────────────────────────────────────────────┘
```
## toDaysInMonth
Добавленный в: v26.3.0
Возвращает количество дней в месяце для значения типа `Date` или `DateTime`.
Возвращаемое значение находится в диапазоне от 28 до 31.
**Синтаксис**
```sql theme={null}
toDaysInMonth(datetime)
```
**Аргументы**
* `datetime` — Дата или дата и время, для которых нужно получить количество дней в месяце. [`Date`](/ru/reference/data-types/date) или [`Date32`](/ru/reference/data-types/date32) или [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64)
**Возвращаемое значение**
Возвращает количество дней в месяце для указанной даты/времени. [`UInt8`](/ru/reference/data-types/int-uint)
**Примеры**
**Пример использования**
```sql title=Query theme={null}
SELECT toDaysInMonth(toDate('2023-02-01')), toDaysInMonth(toDate('2024-02-01')), toDaysInMonth(toDate('2023-01-01'))
```
```response title=Response theme={null}
┌─toDaysInMonth(toDate('2023-02-01'))─┬─toDaysInMonth(toDate('2024-02-01'))─┬─toDaysInMonth(toDate('2023-01-01'))─┐
│ 28 │ 29 │ 31 │
└─────────────────────────────────────┴─────────────────────────────────────┴─────────────────────────────────────┘
```
## toDaysSinceYearZero
Добавленный в: v23.9.0
Для указанной даты возвращает количество дней, прошедших с [1 января 0000](https://en.wikipedia.org/wiki/Year_zero) по
[пролептическому григорианскому календарю, определённому стандартом ISO 8601](https://en.wikipedia.org/wiki/Gregorian_calendar#Proleptic_Gregorian_calendar).
Вычисление выполняется так же, как в функции MySQL [`TO_DAYS`](https://dev.mysql.com/doc/refman/8.0/en/date-and-time-functions.html#function_to-days).
**Синтаксис**
```sql theme={null}
toDaysSinceYearZero(date[, time_zone])
```
**Псевдонимы**: `TO_DAYS`
**Аргументы**
* `date` — Дата или дата и время, для которых вычисляется количество дней с начала нулевого года. [`Date`](/ru/reference/data-types/date) или [`Date32`](/ru/reference/data-types/date32) или [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64)
* `time_zone` — Часовой пояс. [`String`](/ru/reference/data-types/string)
**Возвращаемое значение**
Возвращает количество дней, прошедших с даты `0000-01-01`. [`UInt32`](/ru/reference/data-types/int-uint)
**Примеры**
**Вычислить количество дней с начала нулевого года**
```sql title=Query theme={null}
SELECT toDaysSinceYearZero(toDate('2023-09-08'))
```
```response title=Response theme={null}
┌─toDaysSinceYearZero(toDate('2023-09-08')))─┐
│ 713569 │
└────────────────────────────────────────────┘
```
## toHour
Добавленный в: v1.1.0
Возвращает часовой компонент (0–23) значения `DateTime` или `DateTime64`.
**Синтаксис**
```sql theme={null}
toHour(datetime)
```
**Псевдонимы**: `HOUR`
**Аргументы**
* `datetime` — дата и время, из которых нужно получить час. [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64)
**Возвращаемое значение**
Возвращает час (0–23) для `datetime`. [`UInt8`](/ru/reference/data-types/int-uint)
**Примеры**
**Пример использования**
```sql title=Query theme={null}
SELECT toHour(toDateTime('2023-04-21 10:20:30'))
```
```response title=Response theme={null}
┌─toHour(toDateTime('2023-04-21 10:20:30'))─┐
│ 10 │
└───────────────────────────────────────────┘
```
## toISOWeek
Добавленный в: v20.1.0
Возвращает номер недели по ISO для значения типа дата или дата и время.
Это функция совместимости, эквивалентная `toWeek(date, 3)`.
Недели ISO начинаются в понедельник, а первая неделя года включает 4 января.
Согласно ISO 8601, номера недель находятся в диапазоне от 1 до 53.
Обратите внимание, что для дат вблизи начала или конца года может возвращаться номер недели предыдущего или следующего года. Например,
29 декабря 2025 года возвращает неделю 1, поскольку эта дата попадает в первую неделю, включающую 4 января 2026 года.
**Синтаксис**
```sql theme={null}
toISOWeek(datetime[, timezone])
```
**Аргументы**
* `datetime` — Дата или дата и время, для которых нужно получить номер недели по ISO. [`Date`](/ru/reference/data-types/date) или [`DateTime`](/ru/reference/data-types/datetime) или [`Date32`](/ru/reference/data-types/date32) или [`DateTime64`](/ru/reference/data-types/datetime64)
* `timezone` — Необязательно. Часовой пояс. [`String`](/ru/reference/data-types/string)
**Возвращаемое значение**
Возвращает номер недели по ISO в соответствии со стандартом ISO 8601. Возвращает число от 1 до 53. [`UInt8`](/ru/reference/data-types/int-uint)
**Примеры**
**Получение номеров недель по ISO**
```sql title=Query theme={null}
SELECT toDate('2016-12-27') AS date, toISOWeek(date) AS isoWeek
```
```response title=Response theme={null}
┌───────date─┬─isoWeek─┐
│ 2016-12-27 │ 52 │
└────────────┴─────────┘
```
**ISO-неделя может относиться к другому году**
```sql title=Query theme={null}
SELECT toDate('2025-12-29') AS date, toISOWeek(date) AS isoWeek, toYear(date) AS year
```
```response title=Response theme={null}
┌───────date─┬─isoWeek─┬─year─┐
│ 2025-12-29 │ 1 │ 2025 │
└────────────┴─────────┴──────┘
```
## toISOYear
Добавленный в: v18.4.0
Преобразует дату или дату и время в номер года по ISO.
**Синтаксис**
```sql theme={null}
toISOYear(datetime)
```
**Аргументы**
* `datetime` — Значение типа дата или дата и время. [`Date`](/ru/reference/data-types/date) или [`Date32`](/ru/reference/data-types/date32) или [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64)
**Возвращаемое значение**
Возвращает входное значение, преобразованное в номер года по ISO. [`UInt16`](/ru/reference/data-types/int-uint)
**Примеры**
**Получение года по ISO из значений даты**
```sql title=Query theme={null}
SELECT
toISOYear(toDate('2024/10/02')) as year1,
toISOYear(toDateTime('2024-10-02 01:30:00')) as year2
```
```response title=Response theme={null}
┌─week1─┬─week2─┐
│ 40 │ 40 │
└───────┴───────┘
```
## toLastDayOfMonth
Добавленный в: v1.1.0
Округляет дату или дату и время до последнего дня месяца.
Возвращаемый тип можно настроить с помощью параметра [`enable_extended_results_for_datetime_functions`](/ru/reference/settings/session-settings#enable_extended_results_for_datetime_functions).
**Синтаксис**
```sql theme={null}
toLastDayOfMonth(value)
```
**Псевдонимы**: `LAST_DAY`
**Аргументы**
* `value` — дата или дата и время, которые нужно округлить вверх до последнего дня месяца. [`Date`](/ru/reference/data-types/date) или [`Date32`](/ru/reference/data-types/date32) или [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64)
**Возвращаемое значение**
Возвращает дату последнего дня месяца для указанной даты или даты и времени. [`Date`](/ru/reference/data-types/date)
**Примеры**
**Округлить вверх до последнего дня месяца**
```sql title=Query theme={null}
SELECT toLastDayOfMonth(toDateTime('2023-04-21 10:20:30'))
```
```response title=Response theme={null}
┌─toLastDayOfMonth(toDateTime('2023-04-21 10:20:30'))─┐
│ 2023-04-30 │
└─────────────────────────────────────────────────────┘
```
## toLastDayOfWeek
Добавленный в: v23.5.0
Округляет дату или дату и время до ближайшей субботы или воскресенья в большую сторону.
Возвращаемый тип можно настроить параметром [`enable_extended_results_for_datetime_functions`](/ru/reference/settings/session-settings#enable_extended_results_for_datetime_functions).
**Синтаксис**
```sql theme={null}
toLastDayOfWeek(datetime[, mode[, timezone]])
```
**Аргументы**
* `datetime` — Дата или дата и время для преобразования. [`Date`](/ru/reference/data-types/date) или [`DateTime`](/ru/reference/data-types/datetime) или [`Date32`](/ru/reference/data-types/date32) или [`DateTime64`](/ru/reference/data-types/datetime64)
* `mode` — Определяет первый день недели, как описано в функции `toWeek()`. По умолчанию — `0`. [`UInt8`](/ru/reference/data-types/int-uint)
* `timezone` — Необязательно. Часовой пояс, используемый для преобразования. Если не указан, используется часовой пояс сервера. [`String`](/ru/reference/data-types/string)
**Возвращаемое значение**
Возвращает дату ближайшей субботы или воскресенья, совпадающую с указанной датой или следующую за ней, в зависимости от режима. [`Date`](/ru/reference/data-types/date) или [`Date32`](/ru/reference/data-types/date32)
**Примеры**
**Округление вверх до ближайшей субботы или воскресенья**
```sql title=Query theme={null}
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
```
```response title=Response theme={null}
Строка 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
Возвращает миллисекундную составляющую (0–999) значения `DateTime` или `DateTime64`.
**Синтаксис**
```sql theme={null}
toMillisecond(datetime)
```
**Псевдонимы**: `MILLISECOND`
**Аргументы**
* `datetime` — дата и время, из которых извлекается миллисекунда. [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64)
**Возвращаемое значение**
Возвращает миллисекунду в пределах минуты (0 - 59) для `datetime`. [`UInt16`](/ru/reference/data-types/int-uint)
**Примеры**
**Пример использования**
```sql title=Query theme={null}
SELECT toMillisecond(toDateTime64('2023-04-21 10:20:30.456', 3));
```
```response title=Response theme={null}
┌──toMillisecond(toDateTime64('2023-04-21 10:20:30.456', 3))─┐
│ 456 │
└────────────────────────────────────────────────────────────┘
```
## toMinute
Добавленный в: v1.1.0
Возвращает значение минут (0–59) для `Date` или `DateTime`.
**Синтаксис**
```sql theme={null}
toMinute(datetime)
```
**Псевдонимы**: `MINUTE`
**Аргументы**
* `datetime` — дата и время, из которых нужно получить минуты. [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64)
**Возвращаемое значение**
Возвращает минуты в часе (0 - 59) для `datetime`. [`UInt8`](/ru/reference/data-types/int-uint)
**Примеры**
**Пример использования**
```sql title=Query theme={null}
SELECT toMinute(toDateTime('2023-04-21 10:20:30'))
```
```response title=Response theme={null}
┌─toMinute(toDateTime('2023-04-21 10:20:30'))─┐
│ 20 │
└─────────────────────────────────────────────┘
```
## toModifiedJulianDay
Добавленный в: v21.1.0
Преобразует дату [пролептического григорианского календаря](https://en.wikipedia.org/wiki/Proleptic_Gregorian_calendar) в текстовом формате `YYYY-MM-DD` в номер [модифицированного юлианского дня](https://en.wikipedia.org/wiki/Julian_day#Variants) типа `Int32`. Эта функция поддерживает даты от `0000-01-01` до `9999-12-31`. Она вызывает исключение, если аргумент не удаётся разобрать как дату или если дата недопустима.
**Синтаксис**
```sql theme={null}
toModifiedJulianDay(date)
```
**Аргументы**
* `date` — Дата в виде строки. [`String`](/ru/reference/data-types/string) или [`FixedString`](/ru/reference/data-types/fixedstring)
**Возвращаемое значение**
Возвращает число модифицированного юлианского дня. [`Int32`](/ru/reference/data-types/int-uint)
**Примеры**
**Преобразование даты в модифицированный юлианский день**
```sql title=Query theme={null}
SELECT toModifiedJulianDay('2020-01-01')
```
```response title=Response theme={null}
┌─toModifiedJulianDay('2020-01-01')─┐
│ 58849 │
└───────────────────────────────────┘
```
## toModifiedJulianDayOrNull
Добавленный в: v21.1.0
Аналогично [`toModifiedJulianDay()`](#toModifiedJulianDay), но вместо генерации исключений возвращает `NULL`.
**Синтаксис**
```sql theme={null}
toModifiedJulianDayOrNull(date)
```
**Аргументы**
* `date` — дата в текстовом формате. [`String`](/ru/reference/data-types/string) или [`FixedString`](/ru/reference/data-types/fixedstring)
**Возвращаемое значение**
Возвращает номер модифицированного юлианского дня для корректного значения `date`, в противном случае — `null`. [`Nullable(Int32)`](/ru/reference/data-types/nullable)
**Примеры**
**Преобразование даты в модифицированный юлианский день с обработкой `null`**
```sql title=Query theme={null}
SELECT toModifiedJulianDayOrNull('2020-01-01');
SELECT toModifiedJulianDayOrNull('0000-00-00'); -- некорректная дата, возвращает NULL
```
```response title=Response theme={null}
┌─toModifiedJu⋯020-01-01')─┐
│ 58849 │
└──────────────────────────┘
┌─toModifiedJu⋯000-00-00')─┐
│ ᴺᵁᴸᴸ │
└──────────────────────────┘
```
## toMonday
Добавленный в: v1.1.0
Округляет дату или дату и время вниз до понедельника той же недели. Возвращает дату.
Возвращаемый тип можно настроить с помощью параметра [`enable_extended_results_for_datetime_functions`](/ru/reference/settings/session-settings#enable_extended_results_for_datetime_functions).
**Синтаксис**
```sql theme={null}
toMonday(value)
```
**Аргументы**
* `value` — дата или дата и время, которые нужно округлить вниз до понедельника соответствующей недели. [`Date`](/ru/reference/data-types/date) или [`Date32`](/ru/reference/data-types/date32) или [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64)
**Возвращаемое значение**
Возвращает дату понедельника той же недели для указанной даты или даты и времени. [`Date`](/ru/reference/data-types/date)
**Примеры**
**Округлить вниз до понедельника недели**
```sql title=Query theme={null}
SELECT
toMonday(toDateTime('2023-04-21 10:20:30')), -- Пятница
toMonday(toDate('2023-04-24')); -- Уже понедельник
```
```response title=Response theme={null}
┌─toMonday(toDateTime('2023-04-21 10:20:30'))─┬─toMonday(toDate('2023-04-24'))─┐
│ 2023-04-17 │ 2023-04-24 │
└─────────────────────────────────────────────┴────────────────────────────────┘
```
## toMonth
Добавленный в: v1.1.0
Возвращает номер месяца (1–12) из значения `Date` или `DateTime`.
**Синтаксис**
```sql theme={null}
toMonth(datetime)
```
**Псевдонимы**: `MONTH`
**Аргументы**
* `datetime` — Дата или дата и время, из которых нужно получить месяц. [`Date`](/ru/reference/data-types/date) или [`Date32`](/ru/reference/data-types/date32) или [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64)
**Возвращаемое значение**
Возвращает месяц для указанной даты или даты и времени [`UInt8`](/ru/reference/data-types/int-uint)
**Примеры**
**Пример использования**
```sql title=Query theme={null}
SELECT toMonth(toDateTime('2023-04-21 10:20:30'))
```
```response title=Response theme={null}
┌─toMonth(toDateTime('2023-04-21 10:20:30'))─┐
│ 4 │
└────────────────────────────────────────────┘
```
## toMonthNumSinceEpoch
Добавленный в: v25.3.0
Возвращает количество месяцев, прошедших с начала 1970 года
**Синтаксис**
```sql theme={null}
toMonthNumSinceEpoch(date)
```
**Аргументы**
* `date` — дата или дата и время. [`Date`](/ru/reference/data-types/date) или [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64)
**Возвращаемое значение**
Положительное целое число
**Примеры**
**Пример**
```sql title=Query theme={null}
SELECT toMonthNumSinceEpoch(toDate('2024-10-01'))
```
```response title=Response theme={null}
657
```
## toQuarter
Добавленный в: v1.1.0
Возвращает номер квартала года (1–4) для указанного значения `Date` или `DateTime`.
**Синтаксис**
```sql theme={null}
toQuarter(datetime)
```
**Псевдонимы**: `QUARTER`
**Аргументы**
* `datetime` — дата или дата и время, для которых нужно получить квартал года. [`Date`](/ru/reference/data-types/date) или [`Date32`](/ru/reference/data-types/date32) или [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64)
**Возвращаемое значение**
Возвращает квартал года для указанной даты/времени [`UInt8`](/ru/reference/data-types/int-uint)
**Примеры**
**Пример использования**
```sql title=Query theme={null}
SELECT toQuarter(toDateTime('2023-04-21 10:20:30'))
```
```response title=Response theme={null}
┌─toQuarter(toDateTime('2023-04-21 10:20:30'))─┐
│ 2 │
└──────────────────────────────────────────────┘
```
## toRelativeDayNum
Добавленный в: v1.1.0
Преобразует дату или дату и время в количество дней, прошедших с некоторой фиксированной точки в прошлом.
Точный момент времени является деталью реализации, поэтому эту функцию не предполагается использовать самостоятельно.
Основное назначение функции — вычислять разницу в днях между двумя датами или датой и временем, например, `toRelativeDayNum(dt1) - toRelativeDayNum(dt2)`.
**Синтаксис**
```sql theme={null}
toRelativeDayNum(date)
```
**Аргументы**
* `date` — Дата или дата и время. [`Date`](/ru/reference/data-types/date) или [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64)
**Возвращаемое значение**
Возвращает количество дней от фиксированной точки отсчета в прошлом. [`UInt32`](/ru/reference/data-types/int-uint)
**Примеры**
**Вычисление относительных номеров дней**
```sql title=Query theme={null}
SELECT toRelativeDayNum(toDate('2023-04-01')) - toRelativeDayNum(toDate('2023-01-01'))
```
```response title=Response theme={null}
┌─minus(toRela⋯3-01-01')))─┐
│ 90 │
└──────────────────────────┘
```
## toRelativeHourNum
Добавленный в: v1.1.0
Преобразует дату или дату и время в количество часов, прошедших с некоторого фиксированного момента в прошлом.
Точный момент времени является деталью реализации, поэтому эту функцию не предполагается использовать автономно.
Основное назначение функции — вычисление разницы в часах между двумя датами или датами и временем, например, `toRelativeHourNum(dt1) - toRelativeHourNum(dt2)`.
**Синтаксис**
```sql theme={null}
toRelativeHourNum(date)
```
**Аргументы**
* `date` — Дата или дата и время. [`Date`](/ru/reference/data-types/date) или [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64)
**Возвращаемое значение**
Возвращает число часов с фиксированной точки отсчета в прошлом. [`UInt32`](/ru/reference/data-types/int-uint)
**Примеры**
**Получить относительные номера часов**
```sql title=Query theme={null}
SELECT toRelativeHourNum(toDateTime('2023-01-01 12:00:00')) - toRelativeHourNum(toDateTime('2023-01-01 00:00:00')) AS hours_difference
```
```response title=Response theme={null}
┌─hours_difference─┐
│ 12 │
└──────────────────┘
```
## toRelativeMinuteNum
Добавленный в: v1.1.0
Преобразует дату или дату и время в количество минут, прошедших с некоторого фиксированного момента в прошлом.
Точный момент времени является деталью реализации, поэтому эту функцию не следует использовать автономно.
Основное назначение функции — вычисление разницы в минутах между двумя датами или датами и временем, например, `toRelativeMinuteNum(dt1) - toRelativeMinuteNum(dt2)`.
**Синтаксис**
```sql theme={null}
toRelativeMinuteNum(date)
```
**Аргументы**
* `date` — Дата или дата и время. [`Date`](/ru/reference/data-types/date) или [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64)
**Возвращаемое значение**
Возвращает количество минут от фиксированной точки отсчета в прошлом. [`UInt32`](/ru/reference/data-types/int-uint)
**Примеры**
**Получение относительных номеров минут**
```sql title=Query theme={null}
SELECT toRelativeMinuteNum(toDateTime('2023-01-01 00:30:00')) - toRelativeMinuteNum(toDateTime('2023-01-01 00:00:00')) AS minutes_difference
```
```response title=Response theme={null}
┌─minutes_difference─┐
│ 30 │
└────────────────────┘
```
## toRelativeMonthNum
Добавленный в: v1.1.0
Преобразует дату или дату и время в число месяцев, прошедших с некоторой фиксированной точки в прошлом.
Точная точка во времени является деталью реализации, поэтому эту функцию не предполагается использовать автономно.
Основное назначение функции — вычисление разницы в месяцах между двумя датами или значениями типа «дата и время», например, `toRelativeMonthNum(dt1) - toRelativeMonthNum(dt2)`.
**Синтаксис**
```sql theme={null}
toRelativeMonthNum(date)
```
**Аргументы**
* `date` — дата или дата и время. [`Date`](/ru/reference/data-types/date) или [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64)
**Возвращаемое значение**
Возвращает количество месяцев от фиксированной точки отсчёта в прошлом. [`UInt32`](/ru/reference/data-types/int-uint)
**Примеры**
**Получение относительных номеров месяцев**
```sql title=Query theme={null}
SELECT toRelativeMonthNum(toDate('2023-04-01')) - toRelativeMonthNum(toDate('2023-01-01')) AS months_difference
```
```response title=Response theme={null}
┌─months_difference─┐
│ 3 │
└───────────────────┘
```
## toRelativeQuarterNum
Добавленный в: v1.1.0
Преобразует дату или дату и время в количество кварталов, прошедших с некоторого фиксированного момента в прошлом.
Точный момент времени является деталью реализации, поэтому эту функцию не предполагается использовать автономно.
Основное назначение функции — вычисление разницы в кварталах между двумя датами или датами и временем, например, `toRelativeQuarterNum(dt1) - toRelativeQuarterNum(dt2)`.
**Синтаксис**
```sql theme={null}
toRelativeQuarterNum(date)
```
**Аргументы**
* `date` — Дата или дата и время. [`Date`](/ru/reference/data-types/date) или [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64)
**Возвращаемое значение**
Возвращает количество кварталов, прошедших с фиксированной точки отсчёта в прошлом. [`UInt32`](/ru/reference/data-types/int-uint)
**Примеры**
**Получение относительных номеров кварталов**
```sql title=Query theme={null}
SELECT toRelativeQuarterNum(toDate('2023-04-01')) - toRelativeQuarterNum(toDate('2023-01-01')) AS quarters_difference
```
```response title=Response theme={null}
┌─quarters_difference─┐
│ 1 │
└─────────────────────┘
```
## toRelativeSecondNum
Добавленный в: v1.1.0
Преобразует дату или дату и время в количество секунд, прошедших с некоторой фиксированной точки в прошлом.
Точная точка во времени является деталью реализации, поэтому эту функцию не предполагается использовать автономно.
Основное назначение функции — вычислять разницу в секундах между двумя датами или значениями даты и времени, например, `toRelativeSecondNum(dt1) - toRelativeSecondNum(dt2)`.
**Синтаксис**
```sql theme={null}
toRelativeSecondNum(date)
```
**Аргументы**
* `date` — Дата или дата и время. [`Date`](/ru/reference/data-types/date) or [`DateTime`](/ru/reference/data-types/datetime) or [`DateTime64`](/ru/reference/data-types/datetime64)
**Возвращаемое значение**
Возвращает число секунд от фиксированной точки отсчёта в прошлом. [`UInt32`](/ru/reference/data-types/int-uint)
**Примеры**
**Получение относительных номеров секунд**
```sql title=Query theme={null}
SELECT toRelativeSecondNum(toDateTime('2023-01-01 00:01:00')) - toRelativeSecondNum(toDateTime('2023-01-01 00:00:00')) AS seconds_difference
```
```response title=Response theme={null}
┌─seconds_difference─┐
│ 60 │
└────────────────────┘
```
## toRelativeWeekNum
Добавленный в: v1.1.0
Преобразует дату или дату и время в количество недель, прошедших с некоторого фиксированного момента в прошлом.
Точный момент времени является деталью реализации, поэтому эту функцию не предполагается использовать автономно.
Основное назначение функции — вычисление разницы в неделях между двумя датами или значениями даты и времени, например, `toRelativeWeekNum(dt1) - toRelativeWeekNum(dt2)`.
**Синтаксис**
```sql theme={null}
toRelativeWeekNum(date)
```
**Аргументы**
* `date` — Дата или дата и время. [`Date`](/ru/reference/data-types/date) или [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64)
**Возвращаемое значение**
Возвращает количество недель, прошедших с фиксированной точки отсчета в прошлом. [`UInt32`](/ru/reference/data-types/int-uint)
**Примеры**
**Получение относительных номеров недель**
```sql title=Query theme={null}
SELECT toRelativeWeekNum(toDate('2023-01-08')) - toRelativeWeekNum(toDate('2023-01-01')) AS weeks_difference
```
```response title=Response theme={null}
┌─weeks_difference─┐
│ 1 │
└──────────────────┘
```
## toRelativeYearNum
Добавленный в: v1.1.0
Преобразует дату или дату и время в количество лет, прошедших с некоторой фиксированной точки в прошлом.
Точный момент времени является деталью реализации, поэтому эту функцию не предполагается использовать
автономно. Основное назначение функции — вычисление разницы в годах между двумя датами или значениями типа дата и время, например, `toRelativeYearNum(dt1) - toRelativeYearNum(dt2)`.
**Синтаксис**
```sql theme={null}
toRelativeYearNum(date)
```
**Аргументы**
* `date` — Дата или дата и время. [`Date`](/ru/reference/data-types/date) или [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64)
**Возвращаемое значение**
Возвращает количество лет от фиксированной точки отсчета в прошлом. [`UInt16`](/ru/reference/data-types/int-uint)
**Примеры**
**Получение относительного номера года**
```sql title=Query theme={null}
SELECT toRelativeYearNum('2010-10-01'::DateTime) - toRelativeYearNum('2000-01-01'::DateTime)
```
```response title=Response theme={null}
┌─minus(toRela⋯ateTime')))─┐
│ 10 │
└──────────────────────────┘
```
## toSecond
Добавленный в: v1.1.0
Возвращает секундную составляющую (0-59) значения `DateTime` или `DateTime64`.
**Синтаксис**
```sql theme={null}
toSecond(datetime)
```
**Псевдонимы**: `SECOND`
**Аргументы**
* `datetime` — дата и время, из которых нужно получить секунду. [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64)
**Возвращаемое значение**
Возвращает секунду минуты (0 - 59) для `datetime`. [`UInt8`](/ru/reference/data-types/int-uint)
**Примеры**
**Пример использования**
```sql title=Query theme={null}
SELECT toSecond(toDateTime('2023-04-21 10:20:30'))
```
```response title=Response theme={null}
┌─toSecond(toDateTime('2023-04-21 10:20:30'))─┐
│ 30 │
└─────────────────────────────────────────────┘
```
## toStartOfDay
Добавленный в: v1.1.0
Округляет дату и время вниз до начала дня.
Возвращаемый тип можно настроить с помощью параметра [`enable_extended_results_for_datetime_functions`](/ru/reference/settings/session-settings#enable_extended_results_for_datetime_functions).
**Синтаксис**
```sql theme={null}
toStartOfDay(datetime)
```
**Аргументы**
* `datetime` — Дата или дата и время, которые нужно округлить. [`Date`](/ru/reference/data-types/date) или [`DateTime`](/ru/reference/data-types/datetime)
**Возвращаемое значение**
Возвращает дату и время, округлённые вниз до начала дня. [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64)
**Примеры**
**Округление вниз до начала дня**
```sql title=Query theme={null}
SELECT toStartOfDay(toDateTime('2023-04-21 10:20:30'))
```
```response title=Response theme={null}
┌─toStartOfDay(toDateTime('2023-04-21 10:20:30'))─┐
│ 2023-04-21 00:00:00 │
└─────────────────────────────────────────────────┘
```
## toStartOfFifteenMinutes
Добавленный в: v1.1.0
Округляет дату и время в меньшую сторону до начала пятнадцатиминутного интервала.
Возвращаемый тип можно настроить с помощью параметра [`enable_extended_results_for_datetime_functions`](/ru/reference/settings/session-settings#enable_extended_results_for_datetime_functions).
**Синтаксис**
```sql theme={null}
toStartOfFifteenMinutes(datetime)
```
**Аргументы**
* `datetime` — Дата или дата и время, которое нужно округлить. [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64)
**Возвращаемое значение**
Возвращает дату и время, округлённые до начала ближайшего пятнадцатиминутного интервала. [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64)
**Примеры**
**Пример**
```sql title=Query theme={null}
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
```
```response title=Response theme={null}
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.0
Округляет дату и время вниз до начала ближайшего пятиминутного интервала.
Возвращаемый тип можно настроить с помощью параметра [`enable_extended_results_for_datetime_functions`](/ru/reference/settings/session-settings#enable_extended_results_for_datetime_functions).
**Синтаксис**
```sql theme={null}
toStartOfFiveMinutes(datetime)
```
**Псевдонимы**: `toStartOfFiveMinute`
**Аргументы**
* `datetime` — дата и время, которые нужно округлить. [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64)
**Возвращаемое значение**
Возвращает дату и время, округлённые к началу ближайшего пятиминутного интервала. [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64)
**Примеры**
**Пример**
```sql title=Query theme={null}
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
```
```response title=Response theme={null}
Строка 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.0
Округляет дату и время вниз до начала часа.
Возвращаемый тип можно настроить параметром [`enable_extended_results_for_datetime_functions`](/ru/reference/settings/session-settings#enable_extended_results_for_datetime_functions).
**Синтаксис**
```sql theme={null}
toStartOfHour(datetime)
```
**Аргументы**
* `datetime` — Дата и время, которое нужно округлить. [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64)
**Возвращаемое значение**
Возвращает дату и время, округлённые до начала часа. [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64)
**Примеры**
**Округление до начала часа**
```sql title=Query theme={null}
SELECT
toStartOfHour(toDateTime('2023-04-21 10:20:30'));
```
```response title=Response theme={null}
┌─────────────────res─┬─toTypeName(res)─┐
│ 2023-04-21 10:00:00 │ DateTime │
└─────────────────────┴─────────────────┘
```
## toStartOfISOYear
Добавленный в: v1.1.0
Округляет дату или дату и время вниз до первого дня ISO-года, который может не совпадать с обычным календарным годом. См. [дату недели по ISO](https://en.wikipedia.org/wiki/ISO_week_date).
Возвращаемый тип можно настроить с помощью параметра [`enable_extended_results_for_datetime_functions`](/ru/reference/settings/session-settings#enable_extended_results_for_datetime_functions).
**Синтаксис**
```sql theme={null}
toStartOfISOYear(value)
```
**Аргументы**
* `value` — дата или дата и время, которые нужно округлить вниз до первого дня года по ISO. [`Date`](/ru/reference/data-types/date) или [`Date32`](/ru/reference/data-types/date32) или [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64)
**Возвращаемое значение**
Возвращает первый день года по ISO для указанной даты или даты и времени. [`Date`](/ru/reference/data-types/date)
**Примеры**
**Округлить вниз до первого дня года по ISO**
```sql title=Query theme={null}
SELECT toStartOfISOYear(toDateTime('2023-04-21 10:20:30'))
```
```response title=Response theme={null}
┌─toStartOfISOYear(toDateTime('2023-04-21 10:20:30'))─┐
│ 2023-01-02 │
└─────────────────────────────────────────────────────┘
```
## toStartOfInterval
Добавленный в: v20.1.0
Эта функция обобщает остальные функции `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. | |
Если указан unit `WEEK`, `toStartOfInterval` считает, что недели начинаются с понедельника. Обратите внимание, что это поведение отличается от поведения функции `toStartOfWeek`, в которой недели по умолчанию начинаются с воскресенья.
Вторая перегрузка имитирует функцию `time_bucket()` из TimescaleDB и, соответственно, функцию `date_bin()` из PostgreSQL.
**Синтаксис**
```sql theme={null}
toStartOfInterval(value, INTERVAL x unit[, time_zone])
toStartOfInterval(value, INTERVAL x unit[, origin[, time_zone]])
```
**Псевдонимы**: `time_bucket`, `date_bin`
**Аргументы**
* `value` — Значение типа дата или дата и время, которое нужно округлить вниз. [`Date`](/ru/reference/data-types/date) или [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64)
* `x` — Число, задающее длину интервала. - `unit` — Единица интервала: YEAR, QUARTER, MONTH, WEEK, DAY, HOUR, MINUTE, SECOND, MILLISECOND, MICROSECOND, NANOSECOND. - `time_zone` — Необязательно. Имя часового пояса в виде строки. - `origin` — Необязательно. Точка отсчёта для вычисления (только для второй перегрузки).
**Возвращаемое значение**
Возвращает начало интервала, в который попадает входное значение. [`DateTime`](/ru/reference/data-types/datetime)
**Примеры**
**Базовое округление по интервалу**
```sql title=Query theme={null}
SELECT toStartOfInterval(toDateTime('2023-01-15 14:30:00'), INTERVAL 1 MONTH)
```
```response title=Response theme={null}
┌─toStartOfInt⋯alMonth(1))─┐
│ 2023-01-01 │
└──────────────────────────┘
```
**Использование начальной точки**
```sql title=Query theme={null}
SELECT toStartOfInterval(toDateTime('2023-01-01 14:45:00'), INTERVAL 1 MINUTE, toDateTime('2023-01-01 14:35:30'))
```
```response title=Response theme={null}
┌─toStartOfInt⋯14:35:30'))─┐
│ 2023-01-01 14:44:30 │
└──────────────────────────┘
```
## toStartOfMicrosecond
Добавленный в: v22.6.0
Округляет дату и время вниз до начала микросекунды.
**Синтаксис**
```sql theme={null}
toStartOfMicrosecond(datetime[, timezone])
```
**Аргументы**
* `datetime` — Дата и время. [`DateTime64`](/ru/reference/data-types/datetime64)
* `timezone` — Необязательно. Часовой пояс для возвращаемого значения. Если не указан, функция использует часовой пояс параметра `value`. [`String`](/ru/reference/data-types/string)
**Возвращаемое значение**
Исходное значение с субмикросекундами [`DateTime64`](/ru/reference/data-types/datetime64)
**Примеры**
**Запрос без часового пояса**
```sql title=Query theme={null}
WITH toDateTime64('2020-01-01 10:20:30.999999999', 9) AS dt64
SELECT toStartOfMicrosecond(dt64);
```
```response title=Response theme={null}
┌────toStartOfMicrosecond(dt64)─┐
│ 2020-01-01 10:20:30.999999000 │
└───────────────────────────────┘
```
**Запрос с указанием часового пояса**
```sql title=Query theme={null}
WITH toDateTime64('2020-01-01 10:20:30.999999999', 9) AS dt64
SELECT toStartOfMicrosecond(dt64, 'Asia/Istanbul');
```
```response title=Response theme={null}
┌─toStartOfMicrosecond(dt64, 'Asia/Istanbul')─┐
│ 2020-01-01 12:20:30.999999000 │
└─────────────────────────────────────────────┘
```
## toStartOfMillisecond
Добавленный в: v22.6.0
Округляет дату и время вниз до начала миллисекунды.
**Синтаксис**
```sql theme={null}
toStartOfMillisecond(datetime[, timezone])
```
**Аргументы**
* `datetime` — Дата и время. [`DateTime64`](/ru/reference/data-types/datetime64)
* `timezone` — Необязательный. Часовой пояс для возвращаемого значения. Если не указан, функция использует часовой пояс параметра `value`. [`String`](/ru/reference/data-types/string)
**Возвращаемое значение**
Входное значение с долями миллисекунды. [`DateTime64`](/ru/reference/data-types/datetime64)
**Примеры**
**Запрос без часового пояса**
```sql title=Query theme={null}
WITH toDateTime64('2020-01-01 10:20:30.999999999', 9) AS dt64
SELECT toStartOfMillisecond(dt64);
```
```response title=Response theme={null}
┌────toStartOfMillisecond(dt64)─┐
│ 2020-01-01 10:20:30.999000000 │
└───────────────────────────────┘
```
**Запрос с указанием часового пояса**
```sql title=Query theme={null}
WITH toDateTime64('2020-01-01 10:20:30.999999999', 9) AS dt64
SELECT toStartOfMillisecond(dt64, 'Asia/Istanbul');
```
```response title=Response theme={null}
┌─toStartOfMillisecond(dt64, 'Asia/Istanbul')─┐
│ 2020-01-01 12:20:30.999000000 │
└─────────────────────────────────────────────┘
```
## toStartOfMinute
Добавленный в: v1.1.0
Округляет дату и время вниз до начала минуты.
Возвращаемый тип можно задать с помощью настройки [`enable_extended_results_for_datetime_functions`](/ru/reference/settings/session-settings#enable_extended_results_for_datetime_functions).
**Синтаксис**
```sql theme={null}
toStartOfMinute(datetime)
```
**Аргументы**
* `datetime` — дата и время, которое нужно округлить. [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64)
**Возвращаемое значение**
Возвращает дату и время, округлённые до начала минуты. [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64)
**Примеры**
**Округление до начала минуты**
```sql title=Query theme={null}
SELECT
toStartOfMinute(toDateTime('2023-04-21 10:20:30')),
toStartOfMinute(toDateTime64('2023-04-21 10:20:30.5300', 8))
FORMAT Vertical
```
```response title=Response theme={null}
Строка 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.0
Округляет дату или дату и время вниз до первого дня месяца.
Возвращаемый тип можно настроить с помощью параметра [`enable_extended_results_for_datetime_functions`](/ru/reference/settings/session-settings#enable_extended_results_for_datetime_functions).
**Синтаксис**
```sql theme={null}
toStartOfMonth(value)
```
**Аргументы**
* `value` — дата или дата и время, которые нужно округлить до первого дня месяца. [`Date`](/ru/reference/data-types/date) или [`Date32`](/ru/reference/data-types/date32) или [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64)
**Возвращаемое значение**
Возвращает первый день месяца для указанной даты или даты и времени. [`Date`](/ru/reference/data-types/date)
**Примеры**
**Округление до первого дня месяца**
```sql title=Query theme={null}
SELECT toStartOfMonth(toDateTime('2023-04-21 10:20:30'))
```
```response title=Response theme={null}
┌─toStartOfMonth(toDateTime('2023-04-21 10:20:30'))─┐
│ 2023-04-01 │
└───────────────────────────────────────────────────┘
```
## toStartOfNanosecond
Добавленный в: v22.6.0
Округляет дату и время вниз до начала наносекунды.
**Синтаксис**
```sql theme={null}
toStartOfNanosecond(datetime[, timezone])
```
**Аргументы**
* `datetime` — Дата и время. [`DateTime64`](/ru/reference/data-types/datetime64)
* `timezone` — Необязательно. Часовой пояс возвращаемого значения. Если не указан, функция использует часовой пояс параметра `value`. [`String`](/ru/reference/data-types/string)
**Возвращаемое значение**
Исходное значение с наносекундами. [`DateTime64`](/ru/reference/data-types/datetime64)
**Примеры**
**Запрос без часового пояса**
```sql title=Query theme={null}
WITH toDateTime64('2020-01-01 10:20:30.999999999', 9) AS dt64
SELECT toStartOfNanosecond(dt64);
```
```response title=Response theme={null}
┌─────toStartOfNanosecond(dt64)─┐
│ 2020-01-01 10:20:30.999999999 │
└───────────────────────────────┘
```
**Запрос с указанием часового пояса**
```sql title=Query theme={null}
WITH toDateTime64('2020-01-01 10:20:30.999999999', 9) AS dt64
SELECT toStartOfNanosecond(dt64, 'Asia/Istanbul');
```
```response title=Response theme={null}
┌─toStartOfNanosecond(dt64, 'Asia/Istanbul')─┐
│ 2020-01-01 12:20:30.999999999 │
└────────────────────────────────────────────┘
```
## toStartOfQuarter
Добавленный в: v1.1.0
Округляет дату или дату и время вниз до первого дня квартала. Первый день квартала — это 1 января, 1 апреля, 1 июля или 1 октября.
Возвращаемый тип можно настроить с помощью параметра [`enable_extended_results_for_datetime_functions`](/ru/reference/settings/session-settings#enable_extended_results_for_datetime_functions).
**Синтаксис**
```sql theme={null}
toStartOfQuarter(value)
```
**Аргументы**
* `value` — Дата или дата и время, которое нужно округлить вниз до первого дня квартала. [`Date`](/ru/reference/data-types/date) или [`Date32`](/ru/reference/data-types/date32) или [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64)
**Возвращаемое значение**
Возвращает первый день квартала для указанной даты или даты и времени. [`Date`](/ru/reference/data-types/date)
**Примеры**
**Округление вниз до первого дня квартала**
```sql title=Query theme={null}
SELECT toStartOfQuarter(toDateTime('2023-04-21 10:20:30'))
```
```response title=Response theme={null}
┌─toStartOfQuarter(toDateTime('2023-04-21 10:20:30'))─┐
│ 2023-04-01 │
└─────────────────────────────────────────────────────┘
```
## toStartOfSecond
Добавленный в: v20.5.0
Округляет дату и время до начала секунды.
**Синтаксис**
```sql theme={null}
toStartOfSecond(datetime[, timezone])
```
**Аргументы**
* `datetime` — Дата и время, у которых нужно отбросить доли секунды. [`DateTime64`](/ru/reference/data-types/datetime64)
* `timezone` — Необязательный. Часовой пояс для возвращаемого значения. Если не указан, функция использует часовой пояс параметра `value`. [`String`](/ru/reference/data-types/string)
**Возвращаемое значение**
Возвращает входное значение без долей секунды. [`DateTime64`](/ru/reference/data-types/datetime64)
**Примеры**
**Запрос без часового пояса**
```sql title=Query theme={null}
WITH toDateTime64('2020-01-01 10:20:30.999', 3) AS dt64
SELECT toStartOfSecond(dt64);
```
```response title=Response theme={null}
┌───toStartOfSecond(dt64)─┐
│ 2020-01-01 10:20:30.000 │
└─────────────────────────┘
```
**Запрос с указанием часового пояса**
```sql title=Query theme={null}
WITH toDateTime64('2020-01-01 10:20:30.999', 3) AS dt64
SELECT toStartOfSecond(dt64, 'Asia/Istanbul');
```
```response title=Response theme={null}
┌─toStartOfSecond(dt64, 'Asia/Istanbul')─┐
│ 2020-01-01 13:20:30.000 │
└────────────────────────────────────────┘
```
## toStartOfTenMinutes
Добавленный в: v20.1.0
Округляет дату и время вниз до начала ближайшего интервала в десять минут.
Возвращаемый тип можно настроить с помощью параметра [`enable_extended_results_for_datetime_functions`](/ru/reference/settings/session-settings#enable_extended_results_for_datetime_functions).
**Синтаксис**
```sql theme={null}
toStartOfTenMinutes(datetime)
```
**Аргументы**
* `datetime` — Дата и время. [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64)
**Возвращаемое значение**
Возвращает дату и время, округлённые до начала ближайшего десятиминутного интервала. [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64)
**Примеры**
**Пример**
```sql title=Query theme={null}
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
```
```response title=Response theme={null}
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.0
Округляет дату или дату и время вниз до ближайшего воскресенья или понедельника.
Возвращаемый тип можно настроить с помощью параметра [`enable_extended_results_for_datetime_functions`](/ru/reference/settings/session-settings#enable_extended_results_for_datetime_functions).
**Синтаксис**
```sql theme={null}
toStartOfWeek(datetime[, mode[, timezone]])
```
**Аргументы**
* `datetime` — дата или дата и время для преобразования. [`Date`](/ru/reference/data-types/date) или [`DateTime`](/ru/reference/data-types/datetime) или [`Date32`](/ru/reference/data-types/date32) или [`DateTime64`](/ru/reference/data-types/datetime64)
* `mode` — определяет первый день недели, как описано для функции `toWeek()`. Значение по умолчанию — `0`. [`UInt8`](/ru/reference/data-types/int-uint)
* `timezone` — часовой пояс, используемый для преобразования. Если не указан, используется часовой пояс сервера. [`String`](/ru/reference/data-types/string)
**Возвращаемое значение**
Возвращает дату ближайшего воскресенья или понедельника, не превышающую указанную дату, в зависимости от режима. [`Date`](/ru/reference/data-types/date) или [`Date32`](/ru/reference/data-types/date32)
**Примеры**
**Округление вниз до ближайшего воскресенья или понедельника**
```sql title=Query theme={null}
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
```
```response title=Response theme={null}
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.0
Округляет дату или дату и время вниз до первого дня года. Возвращает значение типа `Date`.
Возвращаемый тип можно настроить с помощью параметра [`enable_extended_results_for_datetime_functions`](/ru/reference/settings/session-settings#enable_extended_results_for_datetime_functions).
**Синтаксис**
```sql theme={null}
toStartOfYear(value)
```
**Аргументы**
* `value` — Дата или дата и время для округления вниз. [`Date`](/ru/reference/data-types/date) или [`Date32`](/ru/reference/data-types/date32) или [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64)
**Возвращаемое значение**
Возвращает первый день года для заданной даты/времени [`Date`](/ru/reference/data-types/date)
**Примеры**
**Округление вниз до первого дня года**
```sql title=Query theme={null}
SELECT toStartOfYear(toDateTime('2023-04-21 10:20:30'))
```
```response title=Response theme={null}
┌─toStartOfYear(toDateTime('2023-04-21 10:20:30'))─┐
│ 2023-01-01 │
└──────────────────────────────────────────────────┘
```
## toTimeWithFixedDate
Добавленный в: v1.1.0
Извлекает компонент времени из значения даты или даты и времени.
Возвращаемый результат представляет собой смещение относительно фиксированной точки во времени, сейчас это `1970-01-02`,
но точная точка во времени является деталью реализации и в будущем может измениться.
Поэтому `toTime` не следует использовать автономно.
Основное назначение функции — вычисление разницы во времени между двумя датами или значениями даты и времени, например: `toTime(dt1) - toTime(dt2)`.
**Синтаксис**
```sql theme={null}
toTimeWithFixedDate(date[, timezone])
```
**Аргументы**
* `date` — Дата для преобразования в значение времени. [`Date`](/ru/reference/data-types/date) или [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64)
* `timezone` — Необязательно. Часовой пояс для возвращаемого значения. [`String`](/ru/reference/data-types/string)
**Возвращаемое значение**
Возвращает компонент времени даты или даты и времени в виде смещения относительно фиксированного момента времени (сейчас это 1970-01-02). [`DateTime`](/ru/reference/data-types/datetime)
**Примеры**
**Вычисление разницы во времени между двумя датами**
```sql title=Query theme={null}
SELECT toTimeWithFixedDate('2025-06-15 12:00:00'::DateTime) - toTimeWithFixedDate('2024-05-10 11:00:00'::DateTime) AS result, toTypeName(result)
```
```response title=Response theme={null}
┌─result─┬─toTypeName(result)─┐
│ 3600 │ Int32 │
└────────┴────────────────────┘
```
## toTimezone
Добавленный в: v1.1.0
Преобразует `DateTime` или `DateTime64` в указанный часовой пояс.
Внутреннее значение (число unix-секунд) данных не изменяется.
Изменяются только атрибут часового пояса значения и его строковое представление.
**Синтаксис**
```sql theme={null}
toTimezone(datetime, timezone)
```
**Псевдонимы**: `toTimeZone`
**Аргументы**
* `date` — Значение для преобразования. [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64)
* `timezone` — Имя целевого часового пояса. [`String`](/ru/reference/data-types/string)
**Возвращаемое значение**
Возвращает ту же временную метку, что и входное значение, но с указанным часовым поясом. [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64)
**Примеры**
**Пример использования**
```sql title=Query theme={null}
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;
```
```response title=Response theme={null}
Строка 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.0
Преобразует значение типа дата или дата и время из одного часового пояса во временную метку UTC. Эта функция в первую очередь предназначена для совместимости с Apache Spark и аналогичными фреймворками.
**Синтаксис**
```sql theme={null}
toUTCTimestamp(datetime, time_zone)
```
**Псевдонимы**: `to_utc_timestamp`
**Аргументы**
* `datetime` — Константное значение типа «дата или дата и время» либо выражение. [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64)
* `time_zone` — Константное значение строкового типа либо выражение, задающее часовой пояс. [`String`](/ru/reference/data-types/string)
**Возвращаемое значение**
Возвращает дату или дату и время в часовом поясе UTC. [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64)
**Примеры**
**Преобразование в UTC**
```sql title=Query theme={null}
SELECT toUTCTimestamp(toDateTime('2023-03-16'), 'Asia/Shanghai')
```
```response title=Response theme={null}
┌─toUTCTimestamp(toDateTime('2023-03-16'), 'Asia/Shanghai')─┐
│ 2023-03-15 16:00:00 │
└─────────────────────────────────────────────────────────┘
```
## toUnixTimestamp
Добавленный в: v1.1.0
Преобразует `String`, `Date` или `DateTime` в Unix-временную метку (`UInt32`; количество секунд с `1970-01-01 00:00:00 UTC`).
**Синтаксис**
```sql theme={null}
toUnixTimestamp(date[, timezone])
```
**Аргументы**
* `date` — Значение для преобразования. [`Date`](/ru/reference/data-types/date) или [`Date32`](/ru/reference/data-types/date32) или [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64) или [`String`](/ru/reference/data-types/string)
* `timezone` — Необязательно. Часовой пояс для преобразования. Если не указан, используется часовой пояс сервера. [`String`](/ru/reference/data-types/string)
**Возвращаемое значение**
Возвращает Unix-временную метку. [`UInt32`](/ru/reference/data-types/int-uint)
**Примеры**
**Пример использования**
```sql title=Query theme={null}
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;
```
```response title=Response theme={null}
строка 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.0
Эта функция возвращает номер недели для даты или datetime. Форма `toWeek()` с двумя аргументами позволяет указать, начинается ли неделя
в воскресенье или в понедельник, а также должен ли возвращаемый номер находиться в диапазоне от `0` до `53` или от `1` до `53`.
[`toISOWeek()`](#toWeek) — функция совместимости, эквивалентная `toWeek(date,3)`.
В следующей таблице описано, как работает аргумент mode.
| Mode | Первый день недели | Диапазон | Неделя 1 — это первая неделя ... |
| ---- | ------------------ | -------- | --------------------------------- |
| 0 | Воскресенье | 0-53 | с воскресеньем в этом году |
| 1 | Понедельник | 0-53 | как минимум с 4 днями в этом году |
| 2 | Воскресенье | 1-53 | с воскресеньем в этом году |
| 3 | Понедельник | 1-53 | как минимум с 4 днями в этом году |
| 4 | Воскресенье | 0-53 | как минимум с 4 днями в этом году |
| 5 | Понедельник | 0-53 | с понедельником в этом году |
| 6 | Воскресенье | 1-53 | как минимум с 4 днями в этом году |
| 7 | Понедельник | 1-53 | с понедельником в этом году |
| 8 | Воскресенье | 1-53 | содержит 1 января |
| 9 | Понедельник | 1-53 | содержит 1 января |
Для значений mode со смыслом "как минимум с 4 днями в этом году" недели нумеруются в соответствии с ISO 8601:1988:
* Если неделя, содержащая 1 января, включает 4 или более дней нового года, то это неделя 1.
* В противном случае это последняя неделя предыдущего года, а следующая неделя — неделя 1.
Для значений mode со смыслом "содержит 1 января" неделя, содержащая 1 января, считается неделей 1.
Не имеет значения, сколько дней нового года она содержит, даже если только один.
То есть если последняя неделя декабря содержит 1 января следующего года, она будет неделей 1 следующего года.
Первый аргумент также можно указать как [`String`](/ru/reference/data-types/string) в формате, поддерживаемом [`parseDateTime64BestEffort()`](/ru/reference/functions/regular-functions/type-conversion-functions#parseDateTime64BestEffort). Поддержка строковых аргументов существует только из соображений совместимости с MySQL, которая требуется некоторым сторонним инструментам. Поскольку в будущем поддержка строковых аргументов может зависеть от новых настроек совместимости с MySQL, а разбор строк в целом работает медленно, рекомендуется её не использовать.
**Синтаксис**
```sql theme={null}
toWeek(datetime[, mode[, time_zone]])
```
**Псевдонимы**: `week`
**Аргументы**
* `datetime` — Дата или дата и время, для которых нужно получить номер недели. [`Date`](/ru/reference/data-types/date) или [`DateTime`](/ru/reference/data-types/datetime)
* `mode` — Необязательно. Режим от `0` до `9` определяет первый день недели и диапазон номеров недель. По умолчанию `0`. - `time_zone` — Необязательно. Часовой пояс. [`String`](/ru/reference/data-types/string)
**Возвращаемое значение**
Возвращает номер недели в соответствии с указанным режимом. [`UInt32`](/ru/reference/data-types/int-uint)
**Примеры**
**Получение номеров недель в разных режимах**
```sql title=Query theme={null}
SELECT toDate('2016-12-27') AS date, toWeek(date) AS week0, toWeek(date,1) AS week1, toWeek(date,9) AS week9
```
```response title=Response theme={null}
┌───────date─┬─week0─┬─week1─┬─week9─┐
│ 2016-12-27 │ 52 │ 52 │ 1 │
└────────────┴───────┴───────┴───────┘
```
## toYYYYMM
Добавленный в: v1.1.0
Преобразует дату или дату и время в число `UInt32`, содержащее год и номер месяца (YYYY \* 100 + MM).
Принимает второй необязательный аргумент — `timezone`. Если он указан, `timezone` должен быть строковой константой.
Эта функция является обратной к функции `YYYYMMDDToDate()`.
**Синтаксис**
```sql theme={null}
toYYYYMM(datetime[, timezone])
```
**Аргументы**
* `datetime` — дата или дата и время для преобразования. [`Date`](/ru/reference/data-types/date) или [`Date32`](/ru/reference/data-types/date32) или [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64)
* `timezone` — необязательно. Часовой пояс для преобразования. Если указан, часовой пояс должен быть строковой константой. [`String`](/ru/reference/data-types/string)
**Возвращаемое значение**
Возвращает число типа UInt32, содержащее год и номер месяца (YYYY \* 100 + MM). [`UInt32`](/ru/reference/data-types/int-uint)
**Примеры**
**Преобразование текущей даты в формат YYYYMM**
```sql title=Query theme={null}
SELECT toYYYYMM(now(), 'US/Eastern')
```
```response title=Response theme={null}
┌─toYYYYMM(now(), 'US/Eastern')─┐
│ 202303 │
└───────────────────────────────┘
```
## toYYYYMMDD
Добавленный в: v1.1.0
Преобразует дату или дату и время в число `UInt32`, содержащее год, месяц и день (YYYY \* 10000 + MM \* 100 + DD). Принимает второй необязательный аргумент `timezone`. Если он указан, `timezone` должен быть строковой константой.
**Синтаксис**
```sql theme={null}
toYYYYMMDD(datetime[, timezone])
```
**Аргументы**
* `datetime` — Дата или дата и время для преобразования. [`Date`](/ru/reference/data-types/date) или [`Date32`](/ru/reference/data-types/date32) или [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64)
* `timezone` — Необязательно. Часовой пояс, используемый при преобразовании. Если указан, часовой пояс должен быть строковой константой. [`String`](/ru/reference/data-types/string)
**Возвращаемое значение**
Возвращает число типа `UInt32`, содержащее год, месяц и день (YYYY \* 10000 + MM \* 100 + DD). [`UInt32`](/ru/reference/data-types/int-uint)
**Примеры**
**Преобразование текущей даты в формат YYYYMMDD**
```sql title=Query theme={null}
SELECT toYYYYMMDD(now(), 'US/Eastern')
```
```response title=Response theme={null}
┌─toYYYYMMDD(now(), 'US/Eastern')─┐
│ 20230302 │
└─────────────────────────────────┘
```
## toYYYYMMDDhhmmss
Добавленный в: v1.1.0
Преобразует дату или дату и время в число `UInt64`, содержащее год, месяц, день, часы, минуты и секунды (YYYY \* 10000000000 + MM \* 100000000 + DD \* 1000000 + hh \* 10000 + mm \* 100 + ss).
Принимает необязательный второй аргумент — часовой пояс. Если он указан, часовой пояс должен быть строковой константой.
**Синтаксис**
```sql theme={null}
toYYYYMMDDhhmmss(datetime[, timezone])
```
**Аргументы**
* `datetime` — Дата или дата и время для преобразования. [`Date`](/ru/reference/data-types/date) или [`Date32`](/ru/reference/data-types/date32) или [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64)
* `timezone` — Необязательно. Часовой пояс для преобразования. Если указан, часовой пояс должен быть строковой константой. [`String`](/ru/reference/data-types/string)
**Возвращаемое значение**
Возвращает число `UInt64`, содержащее год, месяц, день, час, минуту и секунду (YYYY \* 10000000000 + MM \* 100000000 + DD \* 1000000 + hh \* 10000 + mm \* 100 + ss). [`UInt64`](/ru/reference/data-types/int-uint)
**Примеры**
**Преобразование текущей даты и времени в формат YYYYMMDDhhmmss**
```sql title=Query theme={null}
SELECT toYYYYMMDDhhmmss(now(), 'US/Eastern')
```
```response title=Response theme={null}
┌─toYYYYMMDDhhmmss(now(), 'US/Eastern')─┐
│ 20230302112209 │
└───────────────────────────────────────┘
```
## toYear
Добавленный в: v1.1.0
Возвращает компонент года (н. э.) из значения `Date` или `DateTime`.
**Синтаксис**
```sql theme={null}
toYear(datetime)
```
**Псевдонимы**: `YEAR`
**Аргументы**
* `datetime` — дата или дата и время, из которых нужно получить год. [`Date`](/ru/reference/data-types/date) или [`Date32`](/ru/reference/data-types/date32) или [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64)
**Возвращаемое значение**
Возвращает год из указанного значения [`Date`](/ru/reference/data-types/date) или [`DateTime`](/ru/reference/data-types/datetime) [`UInt16`](/ru/reference/data-types/int-uint)
**Примеры**
**Пример использования**
```sql title=Query theme={null}
SELECT toYear(toDateTime('2023-04-21 10:20:30'))
```
```response title=Response theme={null}
┌─toYear(toDateTime('2023-04-21 10:20:30'))─┐
│ 2023 │
└───────────────────────────────────────────┘
```
## toYearNumSinceEpoch
Добавленный в: v25.3.0
Возвращает количество лет, прошедших с 1970 года
**Синтаксис**
```sql theme={null}
toYearNumSinceEpoch(date)
```
**Аргументы**
* `date` — Дата или дата и время, которые нужно преобразовать. [`Date`](/ru/reference/data-types/date) или [`DateTime`](/ru/reference/data-types/datetime) или [`DateTime64`](/ru/reference/data-types/datetime64)
**Возвращаемое значение**
Положительное целое число
**Примеры**
**Пример**
```sql title=Query theme={null}
SELECT toYearNumSinceEpoch(toDate('2024-10-01'))
```
```response title=Response theme={null}
54
```
## toYearWeek
Добавленный в: v20.1.0
Возвращает год и номер недели для даты. Год в результате может отличаться от года в аргументе даты для первой и последней недели года.
Аргумент mode работает так же, как аргумент mode в [`toWeek()`](/ru/reference/functions/regular-functions/date-time-functions#toWeek).
Предупреждение: номер недели, возвращаемый `toYearWeek()`, может отличаться от значения, возвращаемого `toWeek()`. `toWeek()` всегда возвращает номер недели в контексте указанного года, и если `toWeek()` возвращает `0`, `toYearWeek()` возвращает значение, соответствующее последней неделе предыдущего года. См. `prev_yearWeek` в примере ниже.
Первый аргумент также может быть указан как [`String`](/ru/reference/data-types/string) в формате, поддерживаемом [`parseDateTime64BestEffort()`](/ru/reference/functions/regular-functions/type-conversion-functions#parseDateTime64BestEffort). Поддержка строковых аргументов существует только из соображений совместимости с MySQL, которая требуется некоторым сторонним инструментам. Поскольку в будущем поддержка строковых аргументов может зависеть от новых настроек совместимости с MySQL, а разбор строк сам по себе обычно медленный, рекомендуется их не использовать.
**Синтаксис**
```sql theme={null}
toYearWeek(datetime[, mode[, timezone]])
```
**Псевдонимы**: `yearweek`
**Аргументы**
* `datetime` — дата или дата и время, для которых нужно получить год и номер недели. [`Date`](/ru/reference/data-types/date) или [`DateTime`](/ru/reference/data-types/datetime)
* `mode` — необязательно. Режим от `0` до `9` задаёт первый день недели и диапазон номеров недель. По умолчанию `0`. - `timezone` — необязательно. Часовой пояс. [`String`](/ru/reference/data-types/string)
**Возвращаемое значение**
Возвращает год и номер недели в виде одного целочисленного значения. [`UInt32`](/ru/reference/data-types/int-uint)
**Примеры**
**Получение комбинаций год-неделя для разных режимов**
```sql title=Query theme={null}
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
```
```response title=Response theme={null}
┌───────date─┬─yearWeek0─┬─yearWeek1─┬─yearWeek9─┬─prev_yearWeek─┐
│ 2016-12-27 │ 201652 │ 201652 │ 201701 │ 202152 │
└────────────┴───────────┴───────────┴───────────┴───────────────┘
```
## today
Добавленный в: v1.1.0
Возвращает текущую дату на момент анализа запроса. То же, что и `toDate(now())`.
**Синтаксис**
```sql theme={null}
today()
```
**Псевдонимы**: `curdate`, `current_date`
**Аргументы**
* Отсутствуют.
**Возвращаемое значение**
Возвращает текущую дату [`Date`](/ru/reference/data-types/date)
**Примеры**
**Пример использования**
```sql title=Query theme={null}
SELECT today() AS today, curdate() AS curdate, current_date() AS current_date FORMAT Pretty
```
```response title=Response theme={null}
┏━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━━━┓
┃ today ┃ curdate ┃ current_date ┃
┡━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━━━┩
│ 2025-03-03 │ 2025-03-03 │ 2025-03-03 │
└────────────┴────────────┴──────────────┘
```
**Синтаксис SQL без скобок по стандарту**
```sql title=Query theme={null}
SELECT TODAY, CURDATE,CURRENT_DATE
```
```response title=Response theme={null}
┏━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━━━┓
┃ TODAY ┃ CURDATE ┃ CURRENT_DATE ┃
┡━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━━━┩
│ 2025-03-04 │ 2025-03-04 │ 2025-03-04 │
└────────────┴────────────┴──────────────┘
```
## yesterday
Добавленный в: v1.1.0
Не принимает аргументов и возвращает вчерашнюю дату на одном из этапов анализа запроса.
**Синтаксис**
```sql theme={null}
yesterday()
```
**Аргументы**
* Отсутствуют.
**Возвращаемое значение**
Возвращает вчерашнюю дату. [`Date`](/ru/reference/data-types/date)
**Примеры**
**Получение вчерашней даты**
```sql title=Query theme={null}
SELECT yesterday();
SELECT today() - 1;
```
```response title=Response theme={null}
┌─yesterday()─┐
│ 2025-06-09 │
└─────────────┘
┌─minus(today(), 1)─┐
│ 2025-06-09 │
└───────────────────┘
```