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

В данном документе приведены функции и операторы, которые работают с типами данных даты и времени.

Операторы#

Оператор	Пример	Результат
`+`	`date '2012-08-08' + interval '2' day`	`2012-08-10`
`+`	`time '01:00' + interval '3' hour`	`04:00:00.000`
`+`	`timestamp '2012-08-08 01:00' + interval '29' hour`	`2012-08-09 06:00:00.000`
`+`	`timestamp '2012-10-31 01:00' + interval '1' month`	`2012-11-30 01:00:00.000`
`+`	`interval '2' day + interval '3' hour`	`2 03:00:00.000`
`+`	`interval '3' year + interval '5' month`	`3-5`
`-`	`date '2012-08-08' - interval '2' day`	`2012-08-06`
`-`	`time '01:00' - interval '3' hour`	`22:00:00.000`
`-`	`timestamp '2012-08-08 01:00' - interval '29' hour`	`2012-08-06 20:00:00.000`
`-`	`timestamp '2012-10-31 01:00' - interval '1' month`	`2012-09-30 01:00:00.000`
`-`	`interval '2' day - interval '3' hour`	`1 21:00:00.000`
`-`	`interval '3' year - interval '5' month`	`2-7`

Изменение часового пояса#

Оператор AT TIME ZONE устанавливает часовой пояс.

Поддерживаемые типы данных: TIME, TIME WITH TIME ZONE, TIMESTAMP, TIMESTAMP WITH TIME ZONE.

Смещение часового пояса зависит от даты. Для типов TIMESTAMP и TIMESTAMP WITH TIME ZONE смещение будет рассчитано относительно даты, указанной в значении. Для типов TIME и TIME смещение будет рассчитано относительно текущей даты.

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

SELECT timestamp '2012-10-31';
-- 2012-10-31 00:00:00.000

SELECT timestamp '2012-10-31' AT TIME ZONE 'America/Los_Angeles';
-- 2012-10-31 00:00:00.000 America/Los_Angeles

SELECT time '01:00';
-- 01:00:00

SELECT time '01:00' AT TIME ZONE 'America/Los_Angeles';
-- 01:00:00 America/Los_Angeles

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

SELECT timestamp '2012-10-31 01:00 UTC';
-- 2012-10-31 01:00:00.000 UTC

SELECT timestamp '2012-10-31 01:00 UTC' AT TIME ZONE 'America/Los_Angeles';
-- 2012-10-30 18:00:00.000 America/Los_Angeles

Общие функции#

current_date -> date: Возвращает текущую дату на момент начала запроса.

current_time -> time(3) with timezone: Возвращает текущее время с часовым поясом на момент начала запроса с точностью до секунды.

current_timestamp -> timestamp(3) with timezone: Возвращает текущую метку времени с часовым поясом на момент начала запроса с точностью до секунды.

current_timestamp(p) → timestamp(p) with timezone

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

SELECT current_timestamp(6);
-- 2020-06-24 08:25:31.759993 America/Los_Angeles

current_timezone() → varchar#: Возвращает текущий часовой пояс в формате IANA (например, America/Los_Angeles) или как фиксированное смещение относительно UTC (например, +08:35).

date(x) → date#: Псевдоним для CAST(x AS date).

date_trunc(unit, x) → [same as input]#

Возвращает метку времени x, усеченную до единиц измерения, указанных в unit:

SELECT date_trunc('day' , TIMESTAMP '2022-10-20 05:10:00');
-- 2022-10-20 00:00:00.000

SELECT date_trunc('month' , TIMESTAMP '2022-10-20 05:10:00');
-- 2022-10-01 00:00:00.000

SELECT date_trunc('year', TIMESTAMP '2022-10-20 05:10:00');
-- 2022-01-01 00:00:00.000

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

Единица	Пример
`millisecond`	`2001-08-22 03:04:05.000`
`second`	`2001-08-22 03:04:05.000`
`minute`	`2001-08-22 03:04:00.000`
`hour`	`2001-08-22 03:00:00.000`
`day`	`2001-08-22 00:00:00.000`
`week`	`2001-08-20 00:00:00.000`
`month`	`2001-08-01 00:00:00.000`
`quarter`	`2001-07-01 00:00:00.000`
`year`	`2001-01-01 00:00:00.000`

last_day_of_month(x) → date#: Возвращает последний день месяца.

from_iso8601_timestamp(string) → timestamp(3) with time zone#

Преобразует строку в формате ISO 8601 в timestamp(3) with time zone. Время по умолчанию равно 00:00:00.000. Часовой пояс по умолчанию равен часовому поясу текущей сессии:

SELECT from_iso8601_timestamp('2020-05-11');
-- 2020-05-11 00:00:00.000 America/Vancouver

SELECT from_iso8601_timestamp('2020-05-11T11:15:05');
-- 2020-05-11 11:15:05.000 America/Vancouver

SELECT from_iso8601_timestamp('2020-05-11T11:15:05.055+01:00');
-- 2020-05-11 11:15:05.055 +01:00

from_iso8601_timestamp_nanos(string) → timestamp(9) with time zone#

Преобразует строку в формате ISO 8601 в timestamp(9) with time zone. Время по умолчанию равно 00:00:00.000. Часовой пояс по умолчанию равен часовому поясу текущей сессии:

SELECT from_iso8601_timestamp_nanos('2020-05-11T11:15:05');
-- 2020-05-11 11:15:05.000000000 America/Vancouver

SELECT from_iso8601_timestamp_nanos('2020-05-11T11:15:05.123456789+01:00');
-- 2020-05-11 11:15:05.123456789 +01:00

from_iso8601_date(string) → date#

Преобразует строку в формате ISO 8601 в date. Значением может быть календарная дата, год и неделя, или год и день:

SELECT from_iso8601_date('2020-05-11');
-- 2020-05-11

SELECT from_iso8601_date('2020-W10');
-- 2020-03-02

SELECT from_iso8601_date('2020-123');
-- 2020-05-02

at_timezone(timestamp(p), zone) → timestamp(p) with time zone#

Возвращает временную метку, указанную в timestamp, с часовым поясом, преобразованным из часового пояса сессии в часовой пояс, указанный в zone с точностью p. В следующем примере часовой пояс сессии установлен на America/New_York, что на три часа опережает часовой пояс America/Los_Angeles:

SELECT current_timezone()
-- America/New_York

SELECT at_timezone(TIMESTAMP '2022-11-01 09:08:07.321', 'America/Los_Angeles')
-- 2022-11-01 06:08:07.321 America/Los_Angeles

with_timezone(timestamp(p), zone) → timestamp(p) with time zone#

Возвращает временную метку timestamp к заданному в zone часовому поясу с точностью p:

SELECT current_timezone()
-- America/New_York

SELECT with_timezone(TIMESTAMP '2022-11-01 09:08:07.321', 'America/Los_Angeles')
-- 2022-11-01 09:08:07.321 America/Los_Angeles

from_unixtime(unixtime) → timestamp(3) with time zone#: Преобразует количество секунд, прошедших с 1970-01-01 00:00:00 UTC, указанное в unixtime, к timestamp(3) with time zone. Результат будет возвращен в часовой зоне текущей сессии.

from_unixtime(unixtime, zone) → timestamp(3) with time zone: Преобразует количество секунд, прошедших с 1970-01-01 00:00:00 UTC, указанное в unixtime, к timestamp(3) with time zone. Результат будет возвращен в часовой зоне zone.

from_unixtime(unixtime, hours, minutes) → timestamp(3) with time zone: Преобразует количество секунд, прошедших с 1970-01-01 00:00:00 UTC, указанное в unixtime, к timestamp(3) with time zone. Результат будет возвращен с учетом смещения, заданного в offset_hours и offset_minutes.

from_unixtime_nanos(unixtime) → timestamp(9) with time zone#

Преобразует количество секунд, прошедших с 1970-01-01 00:00:00 UTC, указанное в unixtime, к timestamp(9) with time zone. Результат будет возвращен в часовой зоне текущей сессии:

SELECT from_unixtime_nanos(100);
-- 1970-01-01 00:00:00.000000100 UTC

SELECT from_unixtime_nanos(DECIMAL '1234');
-- 1970-01-01 00:00:00.000001234 UTC

SELECT from_unixtime_nanos(DECIMAL '1234.499');
-- 1970-01-01 00:00:00.000001234 UTC

SELECT from_unixtime_nanos(DECIMAL '-1234');
-- 1969-12-31 23:59:59.999998766 UTC

human_readable_seconds(double) → varchar#

Преобразует значение seconds в текстовую строку, содержащую weeks, days, hours, minutes, и seconds:

SELECT human_readable_seconds(96);
-- 1 minute, 36 seconds

SELECT human_readable_seconds(3762);
-- 1 hour, 2 minutes, 42 seconds

SELECT human_readable_seconds(56363463);
-- 93 weeks, 1 day, 8 hours, 31 minutes, 3 seconds

localtime -> time(3): Возвращает текущее время на момент начала запроса.

localtimestamp -> timestamp(3): Возвращает текущую временную метку на момент начала запроса.

localtimestamp(p)

Возвращает текущую временную метку на момент начала запроса с заданной точностью p:

SELECT localtimestamp(6);
-- 2020-06-10 15:55:23.383628

now() → timestamp(3) with time zone#: Псевдоним для current_timestamp.

to_iso8601(x) → varchar#: Форматирует x как строку ISO 8601. Значение x может быть типа date, timestamp или timestamp with time zone.

to_milliseconds(interval) → bigint#: Возвращает interval day to second в миллисекундах.

to_unixtime(timestamp) → double#: Возвращает timestamp как количество секунд, прошедших с 1970-01-01 00:00:00 UTC.

Примечание

Следующие функции не используют круглые скобки:

current_date
current_time
current_timestamp
localtime
localtimestamp

Интервальные функции#

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

Единица	Описание
`millisecond`	Миллисекунды
`second`	Секунды
`minute`	Минуты
`hour`	Часы
`day`	Дни
`week`	Недели
`month`	Месяцы
`quarter`	Кварталы
`year`	Годы

date_add(unit, value, timestamp) → [same as input]#

Добавляет интервал value типа unit к timestamp:

SELECT date_add('second', 86, TIMESTAMP '2020-03-01 00:00:00');
-- 2020-03-01 00:01:26.000

SELECT date_add('hour', 9, TIMESTAMP '2020-03-01 00:00:00');
-- 2020-03-01 09:00:00.000

Для вычитания передайте отрицательное значение интервала:

SELECT date_add('day', -1, TIMESTAMP '2020-03-01 00:00:00 UTC');
-- 2020-02-29 00:00:00.000 UTC

date_diff(unit, timestamp1, timestamp2) → bigint#

Возвращает timestamp2 - timestamp1, выраженный в unit:

SELECT date_diff('second', TIMESTAMP '2020-03-01 00:00:00', TIMESTAMP '2020-03-02 00:00:00');
-- 86400

SELECT date_diff('hour', TIMESTAMP '2020-03-01 00:00:00 UTC', TIMESTAMP '2020-03-02 00:00:00 UTC');
-- 24

SELECT date_diff('day', DATE '2020-03-01', DATE '2020-03-02');
-- 1

SELECT date_diff('second', TIMESTAMP '2020-06-01 12:30:45.000000000', TIMESTAMP '2020-06-02 12:30:45.123456789');
-- 86400

SELECT date_diff('millisecond', TIMESTAMP '2020-06-01 12:30:45.000000000', TIMESTAMP '2020-06-02 12:30:45.123456789');
-- 86400123

parse_duration(string) → interval#

Парсит string формата value unit на интервал, где value - это дробное число значений unit:

SELECT parse_duration('42.8ms');
-- 0 00:00:00.043

SELECT parse_duration('3.81 d');
-- 3 19:26:24.000

SELECT parse_duration('5m');
-- 0 00:05:00.000

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

Единица	Описание
`ns`	Наносекунды
`us`	Микросекунды
`ms`	Миллисекунды
`s`	Секунды
`m`	Минуты
`h`	Часы
`d`	Дни

Форматирование и парсинг (MySQL)#

Функции в этом разделе используют строку формата, совместимую с функциями MySQL date_format и date_parse.

Спецификатор	Описание
`%a`	Сокращенное название дня недели (`Sun` .. `Sat`)
`%b`	Сокращенное название месяца (`Jan` .. `Dec`)
`%c`	Месяц, числовой (`1` .. `12`)
`%D`	День месяца с английским суффиксом (`0th`, `1st`, `2nd`, `3rd`, …)
`%d`	День месяца, числовой (`01` .. `31`)
`%e`	День месяца, числовой (`1` .. `31`)
`%f`	Доля секунды (1 - 6 цифры для печати: `000000` .. `999000`; 1 - 9 цифры для разбора: `0` .. `999999999`)
`%H`	Час (`00` .. `23`)
`%h`	Час (`01` .. `12`)
`%I`	Час (`01` .. `12`)
`%i`	Минуты, числовой (`00` .. `59`)
`%j`	День года (`001` .. `366`)
`%k`	Час (`0` .. `23`)
`%l`	Час (`1` .. `12`)
`%M`	Название месяца (`January` .. `December`)
`%m`	Месяц, числовой (`01` .. `12`)
`%p`	`AM` или `PM`
`%r`	Время суток, 12-часовой формат (эквивалентно `%h:%i:%s %p`)
`%S`	Секунды (`00` .. `59`)
`%s`	Секунды (`00` .. `59`)
`%T`	Время суток, 24-часовой формат (эквивалентно `%H:%i:%s`)
`%U`	Неделя (`00` .. `53`), где понедельник - первый день недели
`%u`	Неделя (`00` .. `53`), где понедельник - первый день недели
`%V`	Неделя (`01` .. `53`), где воскресенье - первый день недели; используется совместно с `%X`
`%v`	Неделя (`01` .. `53`), где понедельник - первый день недели; используется совместно с `%x`
`%W`	Название дня недели (`Sunday` .. `Saturday`)
`%w`	День недели (`0` .. `6`), где воскресенье - первый день недели; не поддерживается, используйте `day_of_week()` (использует `1-7` вместо `0-6`).
`%X`	Год недели, где воскресенье - первый день недели, числовой, четырехзначный; используется совместно с `%V`
`%x`	Год недели, где понедельник - первый день недели, числовой, четырехзначный; используется совместно с `%v`
`%Y`	Год, числовой, четыре цифры
`%y`	Год, числовой (две цифры); предполагает диапазон `1970` .. `2069`, поэтому «70» даст в результате `1970`, а «69» даст `2069`
`%%`	Литеральный символ `%`
`%x`	`x`, для любого `x`, не указанного выше

Предупреждение

Следующие спецификатор в настоящее время не поддерживаются: %D %U %u %V %w %X

date_format(timestamp, format) → varchar#

Форматирует timestamp как строку, используя format:

SELECT date_format(TIMESTAMP '2022-10-20 05:10:00', '%m-%d-%Y %H');
-- 10-20-2022 05

date_parse(string, format)#

Парсит string во временную метку, используя format:

SELECT date_parse('2022/10/20/05', '%Y/%m/%d/%H');
-- 2022-10-20 05:00:00.000

Форматирование и парсинг (Java)#

Функции в этом разделе используют строку формата, совместимую с форматом DateTimeFormat JodaTime.

format_datetime(timestamp, format) → varchar#: Форматирует timestamp как строку, используя format.

parse_datetime(string, format) → timestamp with time zone#: Парсит строку во временную метку с часовым поясом, используя format.

Работа с компонентами временных типов#

extract(field FROM x) → bigint#

Возвращает field из x:

SELECT extract(YEAR FROM TIMESTAMP '2022-10-20 05:10:00');
-- 2022

Поддерживаемые поля:

Поле		Описание
`YEAR`		`year()`
`QUARTER`		`quarter()`
`MONTH`		`month()`
`WEEK`		`week()`
`DAY`		`day()`
`DAY_OF_MONTH`		`day()`
`DAY_OF_WEEK`		`day_of_week()`
`DOW`		`day_of_week()`
`DAY_OF_YEAR`		`day_of_year()`
`DOY`		`day_of_year()`
`YEAR_OF_WEEK`		`year_of_week()`
`YOW`		`year_of_week()`
`HOUR`		`hour()`
`MINUTE`		`minute()`
`SECOND`		`second()`
`TIMEZONE_HOUR`		`timezone_hour()`
`TIMEZONE_MINUTE`		`timezone_minute()`

Примечание

Эта стандартная функция SQL использует специальный синтаксис для указания аргументов.

day(x) → bigint#: Возвращает день месяца из x.

day_of_month(x) → bigint#: Псевдоним для day().

day_of_week(x) → bigint#: Возвращает день недели по стандарту ISO из x. Допустимые значения: от 1 (понедельник) до 7 (воскресенье).

day_of_year(x) → bigint#: Возвращает день года из x. Допустимые значения: от 1 до 366.

dow(x) → bigint#: Псевдоним для day_of_week().

doy(x) → bigint#: Псевдоним для day_of_year().

hour(x) → bigint#: Возвращает час дня из x. Допустимые значения: от 0 до 23.

millisecond(x) → bigint#: Возвращает миллисекунды секунды из x.

minute(x) → bigint#: Возвращает минуты часа из x.

month(x) → bigint#: Возвращает месяц года из x.

quarter(x) → bigint#: Возвращает квартал года из x. Допустимые значения: от 1 до 4.

second(x) → bigint#: Возвращает секунду минуты из x.

timezone_hour(timestamp) → bigint#: Возвращает час смещения часового пояса из timestamp.

timezone_minute(timestamp) → bigint#: Возвращает минуты смещения часового пояса из timestamp.

week(x) → bigint#: Возвращает ISO week года из x. Допустимые значения: от 1 до 53.

week_of_year(x) → bigint#: Псевдоним для week().

year(x) → bigint#: Возвращает год из x.

year_of_week(x) → bigint#: Возвращает год ISO week из x.

yow(x) → bigint#: Псевдоним для year_of_week().