Функции Timestamp с часовым поясом

В этом разделе описаны функции и операторы для проверки и изменения значений TIMESTAMP WITH TIME ZONE (или TIMESTAMPTZ).

Несмотря на название, эти значения не хранят часовой пояс — только момент времени, как TIMESTAMP. Вместо этого они запрашивают, чтобы момент времени был помещён в ячейку и отформатирован с использованием текущего часового пояса.

Поддержка часовых поясов не встроена, но может быть обеспечена расширением, таким как расширение ICU, поставляемое с DuckDB.

В примерах ниже предполагается, что текущий часовой пояс — America/Los_Angeles по григорианскому календарю.

Встроенные функции Timestamp с часовым поясом

В таблице ниже показаны доступные скалярные функции для значений TIMESTAMPTZ. Поскольку эти функции не включают группировку или отображение, они всегда доступны.

Название	Описание
`current_timestamp`	Текущая дата и время (начало текущей транзакции).
`get_current_timestamp()`	Текущая дата и время (начало текущей транзакции).
`greatest(timestamptz, timestamptz)`	Позже из двух временных меток.
`isfinite(timestamptz)`	Возвращает true, если метка времени с часовым поясом конечна, иначе — false.
`isinf(timestamptz)`	Возвращает true, если метка времени с часовым поясом бесконечна, иначе — false.
`least(timestamptz, timestamptz)`	Раньше из двух временных меток.
`now()`	Текущая дата и время (начало текущей транзакции).
`transaction_timestamp()`	Текущая дата и время (начало текущей транзакции).

`current_timestamp`

Описание	Текущая дата и время (начало текущей транзакции).
Пример	`current_timestamp`
Результат	`2022-10-08 12:44:46.122-07`

`get_current_timestamp()`

Описание	Текущая дата и время (начало текущей транзакции).
Пример	`get_current_timestamp()`
Результат	`2022-10-08 12:44:46.122-07`

`greatest(timestamptz, timestamptz)`

Описание	Позже из двух временных меток.
Пример	`greatest(TIMESTAMPTZ '1992-09-20 20:38:48', TIMESTAMPTZ '1992-03-22 01:02:03.1234')`
Результат	`1992-09-20 20:38:48-07`

`isfinite(timestamptz)`

Описание	Возвращает true, если метка времени с часовым поясом конечна, иначе — false.
Пример	`isfinite(TIMESTAMPTZ '1992-03-07')`
Результат	`true`

`isinf(timestamptz)`

Описание	Возвращает true, если метка времени с часовым поясом бесконечна, иначе — false.
Пример	`isinf(TIMESTAMPTZ '-infinity')`
Результат	`true`

`least(timestamptz, timestamptz)`

Описание	Раньше из двух временных меток.
Пример	`least(TIMESTAMPTZ '1992-09-20 20:38:48', TIMESTAMPTZ '1992-03-22 01:02:03.1234')`
Результат	`1992-03-22 01:02:03.1234-08`

`now()`

Описание	Текущая дата и время (начало текущей транзакции).
Пример	`now()`
Результат	`2022-10-08 12:44:46.122-07`

`transaction_timestamp()`

Описание	Текущая дата и время (начало текущей транзакции).
Пример	`transaction_timestamp()`
Результат	`2022-10-08 12:44:46.122-07`

Строки Timestamp с часовым поясом

Без загруженного расширения часового пояса, значения TIMESTAMPTZ будут преобразовываться в строки и обратно с использованием обозначения смещения. Это позволит вам правильно указать момент времени без доступа к информации о часовом поясе. Для обеспечения переносимости значения TIMESTAMPTZ всегда будут отображаться с использованием смещения GMT:

SELECT '2022-10-08 13:13:34-07'::TIMESTAMPTZ;

2022-10-08 20:13:34+00

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

SELECT '2022-10-08 13:13:34 Europe/Amsterdam'::TIMESTAMPTZ::VARCHAR;

2022-10-08 04:13:34-07 -- the offset will differ based on your local time zone

Операторы ICU Timestamp с часовым поясом

В таблице ниже показаны доступные математические операторы для значений TIMESTAMP WITH TIME ZONE, предоставленные расширением ICU.

Оператор	Описание	Пример	Результат
`+`	сложение `INTERVAL`	`TIMESTAMPTZ '1992-03-22 01:02:03' + INTERVAL 5 DAY`	`1992-03-27 01:02:03`
`-`	вычитание `TIMESTAMPTZ`	`TIMESTAMPTZ '1992-03-27' - TIMESTAMPTZ '1992-03-22'`	`5 days`
`-`	вычитание `INTERVAL`	`TIMESTAMPTZ '1992-03-27 01:02:03' - INTERVAL 5 DAY`	`1992-03-22 01:02:03`

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

Функции ICU Timestamp с часовым поясом

В таблице ниже показаны скалярные функции, предоставленные ICU для значений TIMESTAMP WITH TIME ZONE.

Имя	Описание
`age(timestamptz, timestamptz)`	Вычитает аргументы, результатом является разница во времени между двумя метками времени.
`age(timestamptz)`	Вычитает из текущей даты.
`date_diff(part, startdate, enddate)`	Количество границ разбиения разбиения между метками времени.
`date_part([part, ...], timestamptz)`	Получить указанные подполя в виде `struct`. Список должен быть постоянным.
`date_part(part, timestamptz)`	Получить подполе (эквивалентно extract).
`date_sub(part, startdate, enddate)`	Количество полных разбиений между метками времени.
`date_trunc(part, timestamptz)`	Округлить до указанной точности.
`datediff(part, startdate, enddate)`	Псевдоним для date_diff. Количество границ разбиения разбиения между метками времени.
`datepart([part, ...], timestamptz)`	Псевдоним для date_part. Получить указанные подполя в виде `struct`. Список должен быть постоянным.
`datepart(part, timestamptz)`	Псевдоним для date_part. Получить подполе (эквивалентно extract).
`datesub(part, startdate, enddate)`	Псевдоним для date_sub. Количество полных разбиений между метками времени.
`datetrunc(part, timestamptz)`	Псевдоним для date_trunc. Округлить до указанной точности.
`epoch_ms(timestamptz)`	Преобразует timestamptz в миллисекунды с эпохи.
`epoch_ns(timestamptz)`	Преобразует timestamptz в наносекунды с эпохи.
`epoch_us(timestamptz)`	Преобразует timestamptz в микросекунды с эпохи.
`extract(field FROM timestamptz)`	Получить подполе из `TIMESTAMP WITH TIME ZONE`.
`last_day(timestamptz)`	Последний день месяца.
`make_timestamptz(bigint, bigint, bigint, bigint, bigint, double, string)`	`TIMESTAMP WITH TIME ZONE` для заданных частей и часового пояса.
`make_timestamptz(bigint, bigint, bigint, bigint, bigint, double)`	`TIMESTAMP WITH TIME ZONE` для заданных частей в текущем часовом поясе.
`make_timestamptz(microseconds)`	`TIMESTAMP WITH TIME ZONE` для заданных µс с эпохи.
`strftime(timestamptz, format)`	Преобразует значение `TIMESTAMP WITH TIME ZONE` в строку в соответствии со строкой формата.
`strptime(text, format)`	Преобразует строку в `TIMESTAMP WITH TIME ZONE` в соответствии со строкой формата, если `%Z` указано.
`time_bucket(bucket_width, timestamptz[, offset])`	Округляет `timestamptz` до указанного интервала `bucket_width`. Ведра смещены на `offset` интервал.
`time_bucket(bucket_width, timestamptz[, origin])`	Округляет `timestamptz` до указанного интервала `bucket_width`. Ведра выровнены относительно `origin` timestamptz. `origin` по умолчанию составляет 2000-01-03 00:00:00+00 для ведер, не включающих интервал месяца или года, и 2000-01-01 00:00:00+00 для ведер месяца и года.
`time_bucket(bucket_width, timestamptz[, timezone])`	Округляет `timestamptz` до указанного интервала `bucket_width`. Начало и конец ведра рассчитываются с использованием `timezone`. `timezone` — строка и по умолчанию равна UTC.

`age(timestamptz, timestamptz)`

Описание	Вычитает аргументы, результатом является разница во времени между двумя метками времени.
Пример	`age(TIMESTAMPTZ '2001-04-10', TIMESTAMPTZ '1992-09-20')`
Результат	`8 years 6 months 20 days`

`age(timestamptz)`

Описание	Вычитает из текущей даты.
Пример	`age(TIMESTAMP '1992-09-20')`
Результат	`29 years 1 month 27 days 12:39:00.844`

`date_diff(part, startdate, enddate)`

Описание	Количество границ разбиения разбиения между метками времени.
Пример	`date_diff('hour', TIMESTAMPTZ '1992-09-30 23:59:59', TIMESTAMPTZ '1992-10-01 01:58:00')`
Результат	`2`

`date_part([part, ...], timestamptz)`

Описание	Получить указанные подполя в виде `struct`. Список должен быть постоянным.
Пример	`date_part(['year', 'month', 'day'], TIMESTAMPTZ '1992-09-20 20:38:40-07')`
Результат	`{year: 1992, month: 9, day: 20}`

`date_part(part, timestamptz)`

Описание	Получить подполе (эквивалентно extract).
Пример	`date_part('minute', TIMESTAMPTZ '1992-09-20 20:38:40')`
Результат	`38`

`date_sub(part, startdate, enddate)`

Описание	Количество полных разделов между временными метками.
Пример	`date_sub('hour', TIMESTAMPTZ '1992-09-30 23:59:59', TIMESTAMPTZ '1992-10-01 01:58:00')`
Результат	`1`

`date_trunc(part, timestamptz)`

Описание	Округляет до указанной точности.
Пример	`date_trunc('hour', TIMESTAMPTZ '1992-09-20 20:38:40')`
Результат	`1992-09-20 20:00:00`

`datediff(part, startdate, enddate)`

Описание	Псевдоним для date_diff. Количество границ разделов между временными метками.
Пример	`datediff('hour', TIMESTAMPTZ '1992-09-30 23:59:59', TIMESTAMPTZ '1992-10-01 01:58:00')`
Результат	`2`

`datepart([part, ...], timestamptz)`

Описание	Псевдоним для date_part. Получает перечисленные подполя как `struct`. Список должен быть постоянным.
Пример	`datepart(['year', 'month', 'day'], TIMESTAMPTZ '1992-09-20 20:38:40-07')`
Результат	`{year: 1992, month: 9, day: 20}`

`datepart(part, timestamptz)`

Описание	Псевдоним для date_part. Получает подполе (эквивалентно extract).
Пример	`datepart('minute', TIMESTAMPTZ '1992-09-20 20:38:40')`
Результат	`38`

`datesub(part, startdate, enddate)`

Описание	Псевдоним для date_sub. Количество полных разделов между временными метками.
Пример	`datesub('hour', TIMESTAMPTZ '1992-09-30 23:59:59', TIMESTAMPTZ '1992-10-01 01:58:00')`
Результат	`1`

`datetrunc(part, timestamptz)`

Описание	Псевдоним функции date_trunc. Обрезает до указанной точности.
Пример	`datetrunc('hour', TIMESTAMPTZ '1992-09-20 20:38:40')`
Результат	`1992-09-20 20:00:00`

`epoch_ms(timestamptz)`

Описание	Преобразует timestamptz в миллисекунды с момента эпохи.
Пример	`epoch_ms('2022-11-07 08:43:04.123456+00'::TIMESTAMPTZ);`
Результат	`1667810584123`

`epoch_ns(timestamptz)`

Описание	Преобразует timestamptz в наносекунды с момента эпохи.
Пример	`epoch_ns('2022-11-07 08:43:04.123456+00'::TIMESTAMPTZ);`
Результат	`1667810584123456000`

`epoch_us(timestamptz)`

Описание	Преобразует timestamptz в микросекунды с момента эпохи.
Пример	`epoch_us('2022-11-07 08:43:04.123456+00'::TIMESTAMPTZ);`
Результат	`1667810584123456`

`extract(field FROM timestamptz)`

Описание	Получение подполя из `TIMESTAMP WITH TIME ZONE`.
Пример	`extract('hour' FROM TIMESTAMPTZ '1992-09-20 20:38:48')`
Результат	`20`

`last_day(timestamptz)`

Описание	Последний день месяца.
Пример	`last_day(TIMESTAMPTZ '1992-03-22 01:02:03.1234')`
Результат	`1992-03-31`

`make_timestamptz(bigint, bigint, bigint, bigint, bigint, double, string)`

Описание	`TIMESTAMP WITH TIME ZONE` для заданных частей и часового пояса.
Пример	`make_timestamptz(1992, 9, 20, 15, 34, 27.123456, 'CET')`
Результат	`1992-09-20 06:34:27.123456-07`

`make_timestamptz(bigint, bigint, bigint, bigint, bigint, double)`

Описание	`TIMESTAMP WITH TIME ZONE` для заданных частей в текущем часовом поясе.
Пример	`make_timestamptz(1992, 9, 20, 13, 34, 27.123456)`
Результат	`1992-09-20 13:34:27.123456-07`

`make_timestamptz(microseconds)`

Описание	`TIMESTAMP WITH TIME ZONE` для заданных мкс с момента эпохи.
Пример	`make_timestamptz(1667810584123456)`
Результат	`2022-11-07 16:43:04.123456-08`

`strftime(timestamptz, format)`

Описание	Преобразование значения `TIMESTAMP WITH TIME ZONE` в строку в соответствии со строкой форматирования формата.
Пример	`strftime(timestamptz '1992-01-01 20:38:40', '%a, %-d %B %Y - %I:%M:%S %p')`
Результат	`Wed, 1 January 1992 - 08:38:40 PM`

`strptime(text, format)`

Описание	Преобразование строки в `TIMESTAMP WITH TIME ZONE` в соответствии со строкой форматирования формата, если `%Z` указано.
Пример	`strptime('Wed, 1 January 1992 - 08:38:40 PST', '%a, %-d %B %Y - %H:%M:%S %Z')`
Результат	`1992-01-01 08:38:40-08`

`time_bucket(bucket_width, timestamptz[, offset])`

Описание	Обрезка `timestamptz` по указанному интервалу `bucket_width`. Ведра смещены на интервал `offset`.
Пример	`time_bucket(INTERVAL '10 minutes', TIMESTAMPTZ '1992-04-20 15:26:00-07', INTERVAL '5 minutes')`
Результат	`1992-04-20 15:25:00-07`

`time_bucket(bucket_width, timestamptz[, origin])`

Описание	Обрезка `timestamptz` по указанному интервалу `bucket_width`. Ведра выровнены относительно `origin` timestamptz. `origin` по умолчанию 2000-01-03 00:00:00+00 для ведер, не включающих интервал месяца или года, и 2000-01-01 00:00:00+00 для ведер месяца и года.
Пример	`time_bucket(INTERVAL '2 weeks', TIMESTAMPTZ '1992-04-20 15:26:00-07', TIMESTAMPTZ '1992-04-01 00:00:00-07')`
Результат	`1992-04-15 00:00:00-07`

`time_bucket(bucket_width, timestamptz[, timezone])`

Описание	Обрезка `timestamptz` по указанному интервалу `bucket_width`. Начало и конец ведер рассчитываются с использованием `timezone`. `timezone` - строка, по умолчанию UTC.
Пример	`time_bucket(INTERVAL '2 days', TIMESTAMPTZ '1992-04-20 15:26:00-07', 'Europe/Berlin')`
Результат	`1992-04-19 15:00:00-07`

Также существуют специализированные функции извлечения подполей.

Функции таблиц ICU Timestamp

В таблице ниже показаны доступные функции таблиц для типов TIMESTAMP WITH TIME ZONE.

Имя	Описание
`generate_series(timestamptz, timestamptz, interval)`	Генерирует таблицу временных меток в замкнутом интервале (включая начальную и конечную временные метки), с шагом интервала.
`range(timestamptz, timestamptz, interval)`	Генерирует таблицу временных меток в полуоткрытом интервале (включая начальную временную метку, но не включая конечную), с шагом интервала.

Бесконечные значения не допускаются в качестве границ функций таблиц.

`generate_series(timestamptz, timestamptz, interval)`

Описание	Генерирует таблицу временных меток в замкнутом интервале (включая начальную и конечную временные метки), с шагом интервала.
Пример	`generate_series(TIMESTAMPTZ '2001-04-10', TIMESTAMPTZ '2001-04-11', INTERVAL 30 MINUTE)`

`range(timestamptz, timestamptz, interval)`

Описание	Генерирует таблицу временных меток в полуоткрытом интервале (включая начальную временную метку, но не включая конечную), с шагом интервала.
Пример	`range(TIMESTAMPTZ '2001-04-10', TIMESTAMPTZ '2001-04-11', INTERVAL 30 MINUTE)`

Функции ICU Timestamp без часового пояса

В таблице ниже показаны предоставляемые ICU скалярные функции, которые работают с обычными TIMESTAMP значениями. Эти функции предполагают, что TIMESTAMP является «локальным временем».

Локальное время фактически представляет собой способ кодирования значений частей из часового пояса в одно значение. Их следует использовать с осторожностью, так как полученные значения могут содержать пробелы и неоднозначности благодаря переходу на летнее время. Часто ту же функциональность можно реализовать более надёжно, используя struct вариант функции date_part.

Имя	Описание
`current_localtime()`	Возвращает `TIME` с GMT-биновыми значениями, соответствующими местному времени в текущем часовом поясе.
`current_localtimestamp()`	Возвращает `TIMESTAMP` с GMT-биновыми значениями, соответствующими локальной дате и времени в текущем часовом поясе.
`localtime`	Синоним вызова функции `current_localtime()` .
`localtimestamp`	Синоним вызова функции `current_localtimestamp()` .
`timezone(text, timestamp)`	Используйте части даты timestamp в GMT для построения timestamp в заданном часовом поясе. По сути, аргумент — это «локальное» время.
`timezone(text, timestamptz)`	Используйте части даты timestamp в заданном часовом поясе для построения timestamp. По сути, результат — «локальное» время.

`current_localtime()`

Описание	Возвращает `TIME`, значения GMT-бинов которого соответствуют местному времени в текущей часовой зоне.
Пример	`current_localtime()`
Результат	`08:47:56.497`

`current_localtimestamp()`

Описание	Возвращает `TIMESTAMP`, значения GMT-бинов которого соответствуют местной дате и времени в текущей часовой зоне.
Пример	`current_localtimestamp()`
Результат	`2022-12-17 08:47:56.497`

`localtime`

Описание	Синоним вызова функции `current_localtime()`.
Пример	`localtime`
Результат	`08:47:56.497`

`localtimestamp`

Описание	Синоним вызова функции `current_localtimestamp()`.
Пример	`localtimestamp`
Результат	`2022-12-17 08:47:56.497`

`timezone(text, timestamp)`

Описание	Используйте части даты временной метки в формате GMT для построения временной метки в заданной часовой зоне. По сути, аргумент — это «локальное» время.
Пример	`timezone('America/Denver', TIMESTAMP '2001-02-16 20:38:40')`
Результат	`2001-02-16 19:38:40-08`

`timezone(text, timestamptz)`

Описание	Используйте части даты временной метки в заданной часовой зоне для построения временной метки. По сути, результат — «локальное» время.
Пример	`timezone('America/Denver', TIMESTAMPTZ '2001-02-16 20:38:40-05')`
Результат	`2001-02-16 18:38:40`

В часовой зоне

Синтаксис AT TIME ZONE — это синтаксический сахар для функции (с двумя аргументами) timezone, перечисленной выше:

SELECT TIMESTAMP '2001-02-16 20:38:40' AT TIME ZONE 'America/Denver' AS ts;

2001-02-16 19:38:40-08

SELECT TIMESTAMP WITH TIME ZONE '2001-02-16 20:38:40-05' AT TIME ZONE 'America/Denver' AS ts;

2001-02-16 18:38:40

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

SELECT TIMESTAMP '2001-02-16 20:38:40-05' AT TIME ZONE '0200' AS ts;

Not implemented Error: Unknown TimeZone '0200'

Бесконечности

Функции, примененные к бесконечным датам, вернут либо те же бесконечные даты (например, greatest), либо NULL (например, date_part) в зависимости от того, что «имеет смысл». В общем случае, если функция должна проверить части бесконечного временного значения, результатом будет NULL.

Календари

Расширение ICU также поддерживает негрегорианские календари. Если такой календарь является текущим, то операции отображения и разбиения на бины будут использовать этот календарь.