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

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

Операторы#

Оператор

Пример

Результат

+

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 поддерживает следующие единицы измерения:

Единица

Пример

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().