convertTimezone¶
convertTimezone сдвигает метку времени в указанный часовой пояс, добавляя или вычитая нужный интервал из значения.
| Синтаксис | Пример |
|---|---|
convertTimezone(столбец, цель, источник) |
convertTimezone("2024-12-28T12:00:00", "Europe/Moscow", "Asia/Omsk") |
| Смещает метку времени из исходного часового пояса в целевой часовой пояс. | Возвращает значение 2024-12-28T09:00:00», отображаемое как 28 декабря 2024 г., 9:00 |
Работать с временны́ми метками и часовыми поясами довольно непросто (легко ошибиться и трудно найти ошибку), поэтому вам следует использовать convertTimezone только в том случае, когда интерпретация ваших данных чувствительна к временны́м ограничениям.
Например, если вы отслеживаете вход пользователей в систему, то, вероятно, будет не очень критично, если некоторые входы в систему будут учитываться по понедельникам, а не по вторникам, с учетом временно́го смещения.
Однако если вы используете Glarus BI для чего-то точного, например, для уплаты налогов, вас гораздо больше будет волновать разница между транзакциями, совершёнными 31 декабря и 1 января.
Поддерживаемые часовые пояса¶
Glarus BI поддерживает часовые пояса базы данных tz (wiki, англ.).
Параметры¶
столбец может быть:
- названием столбца с датой и временем;
- пользовательским выражением, которое возвращает дату и время;
- строкой в формате
"YYYY-MM-DDили"YYYY-MM-DDTHH:MM:SS".
цель:
- название часового пояса, в который вы хотите преобразовать значение.
источник:
- название текущего часового пояса вашего столбца;
- требуется для столбцов или выражений с типом данных «метка времени без часового пояса»;
- необязательно для столбцов или выражений с типом данных «метка времени с часовым поясом».
Дополнительные сведения см. в разделе Допустимые типы данных.
Мы поддерживаем обозначения часовых поясов из базы данных tz (wiki, англ.) (например, «Europe/Moscow» вместо «MSK»).
Создание пользовательских дат отчёта¶
Допустим, у вас есть данные временны́х рядов, хранящиеся в одном или нескольких часовых поясах (Исходное время). Вы хотите создать даты отчёта для команды, которая находится в другом часовом поясе, например, в NSK.
| Исходные дата и время | Дата отчёта команды (NSK) |
|---|---|
| 28 декабря, 2024, 10:00:00 | 28 декабря, 2024, 14:00:00 |
| 28 декабря, 2024, 21:00:00 | 29 декабря, 2024, 01:00:00 |
| 27 декабря, 2024, 08:00:00 | 27 декабря, 2024, 12:00:00 |
Если Исходное время хранится как «метка времени с часовым поясом» timestamp with time zone или «метка времени со смещением» timestamp with offset, вам нужно указать только «целевой» часовой пояс:
Если Исходное время хранится как «метка времени без часового пояса» timestamp without time zone, вы должны указать «исходный» source часовой пояс (который будет зависеть от часового пояса вашей базы данных):
Обычно рекомендуется помечать столбцы convertTimezone названием целевого часового пояса (или добавлять целевой часовой пояс в метаданные модели). Это сильно упрощает жизнь, когда кто-то интересуется, почему числа не совпадают.
Если вы не получаете ожидаемых результатов:
- проверьте, правильно ли вы указали исходный часовой пояс;
- спросите администратора базы данных о «метке времени с часовым поясом» и «метке времени без часового пояса» (дополнительную информацию см. в разделе "Допустимые типы данных").
Выбор исходного часового пояса¶
При преобразовании часовых поясов убедитесь, что вы знаете исходный часовой пояс, с которым работаете. Разные столбцы (и даже разные строки) в одной таблице, запросе или модели могут находиться в разных «исходных» часовых поясах.
| Возможный часовой пояс источника | Описание | Пример |
|---|---|---|
| Часовой пояс клиента | Часовой пояс, в котором произошло событие. | Служба веб-аналитики может собирать данные о местном часовом поясе каждого человека, посетившего ваш сайт. |
| Часовой пояс базы данных | Метаданные часового пояса, которые были добавлены к меткам времени в вашей базе данных. | Общепринятой практикой баз данных является хранение всех временны́х меток в формате UTC. |
| Нет часового пояса | Отсутствует часовой пояс в метаданных | Базы данных не требуют от вас хранения временны́х меток с метаданными часового пояса. |
| Часовой пояс отчёта Glarus BI | Часовой пояс, который Glarus BI использует для отображения временны́х меток. | Glarus BI может отображать даты и время в формате NSK, даже если дата и время хранятся в вашей базе данных в формате UTC. |
Например, у вас есть таблица посещений сайта с одной записью на каждого человека. Трудно сказать, просто взглянув на «28 декабря 2024 г., 12:00», является ли такая запись «сырой» меткой времени — она может:
- храниться с использованием часового пояса вашей базы данных (обычно UTC);
- храниться без метаданных часового пояса (например, если посетитель веб-сайта находится в NSK, то значение даты и времени «28 декабря 2024 г., 12:00» может неявно использовать время Новосибирска),
- отображаться в часовом поясе отчёта Glarus BI.
Для более детальной информации смотрите ограничения.
Допустимые типы данных¶
| Типы данных | Работает с convertTimezone |
|---|---|
| Строка | ❌ |
| Число | ❌ |
| Дата/время | ✅ |
| Условие | ❌ |
| JSON | ❌ |
Информация о типах данных приведена в разделе обучения руководства Metabase (англ.).
Мы используем сочетания «timestamp» и «datetime», чтобы говорить о любом временно́м типе данных, поддерживаемом Glarus BI.
Если ваши временны́е метки хранятся в базе данных в виде строк или чисел, администратор может преобразовать их во временны́е метки на странице 'Метаданные таблиц'.
Чтобы использовать convertTimezone, не сталкиваясь с ошибками или надоедливыми необнаружимыми ошибками, вы должны знать, что существует несколько разновидностей типов данных timestamp:
| Тип данных | Описание | Пример |
|---|---|---|
timestamp with time zone |
"Знает" о расположении. | 2024-12-28T12:00:00 AT TIME ZONE 'Asia/Omsk' |
timestamp with offset |
"Знает" о разнице с UTC. | 2024-12-28T12:00:00-04:00 |
timestamp without time zone |
"Не знает" о часовом поясе. | 2024-12-28T12:00:00 |
Обратите внимание, что первая часть метки времени указана в формате UTC (то же самое, что и GMT). Часовой пояс или смещение говорят вам, сколько времени нужно добавить или вычесть для данного часового пояса.
convertTimezone будет работать со всеми тремя типами меток времени, но результатом convertTimezone всегда будет метка времени без часового пояса.
Ограничения¶
convertTimezone не работает со следующими базами данных:
- Amazon Athena;
- Databricks;
- Druid;
- MongoDB;
- Presto;
- SparkSQL;
- SQLite;
- Metabase Sample Database.
Примечания об исходных часовых поясах¶
Glarus BI отображает метки времени без информации о часовом поясе или смещении, поэтому вы должны быть очень осторожны с исходным часовым поясом при использовании convertTimezone.
Часовой пояс отчёта Glarus BI применяется только к типам данных «метка времени с часовым поясом» timestamp with time zone или «метка времени со смещением» timestamp with offset. Например:
| Часовой пояс в вашей базе данных | Тип данных | Часовой пояс отчёта | Отображается как |
|---|---|---|---|
2024-12-28T12:00:00 AT TIME ZONE 'MSK' |
timestamp with time zone |
'Asia/Novosibirsk' | 28 дек., 2024, 8:00 утра |
2024-12-28T12:00:00+07:00 |
timestamp with offset |
'Asia/Novosibirsk' | 28 дек., 2024, 8:00 утра |
2024-12-28T12:00:00 |
timestamp without time zone |
'Asia/Novosibirsk' | 28 дек., 2024, 12:00 утра |
Часовой пояс отчёта Glarus BI не будет применяться к выходным данным выражения convertTimezone. Например:
convertTimezone("2022-12-28T12:00:00 AT TIME ZONE 'Canada/Central'", "Canada/Pacific", "Canada/Central")
создаст необработанную «метку времени без часового пояса» timestamp without time zone
и отобразится в Glarus BI как
Если вы применяете convertTimezone для timestamp without time zone, обязательно используйте 'UTC' в качестве часового пояса источника, иначе выражение сместит вашу метку времени на неправильную величину.
Если наша «метка времени без часового пояса» timestamp without time zone только «подразумевается» в NSK, мы должны использовать 'UTC' в качестве параметра источник, чтобы получить тот же результат, что и выше.
Например, если мы выбрали 'NSK', как источник часового пояса для timestamp without time zone:
то получим необработанную метку времени без часового пояса timestamp without time zone
которая отобразится в Glarus BI как
Связанные функции¶
В этом разделе рассматриваются функции и формулы, которые работают так же, как выражение convertTimezone, чтобы вы могли выбрать наиболее подходящий вариант.
SQL¶
Когда вы запускаете запрос с помощью конструктора запросов, Glarus BI преобразует ваши графические настройки запроса (фильтры, сводки и т.д.) в запрос и запускает этот запрос в вашей базе данных.
Если наши примеры временных меток представляют собой «временную метку без часового пояса», хранящуюся в базе данных PostgreSQL:
то это будет аналогично выражению convertTimezone с параметром source, установленным в 'UTC':
Если source_time является меткой времени с часовым поясом (timestamp with time zone) или меткой времени со смещением (timestamp with offset, например, в базе данных Snowflake), нам не нужно указывать исходный часовой пояс:
и это будет аналогично выражению:
Обозначения часовых поясов зависят от вашей базы данных. Например, Snowflake не принимает большинство обозначений часовых поясов (таких как NSK).
Таблицы¶
Если наши временны́е метки образца данных находятся в таблице, где «Исходное время» находится в столбце A, мы можем изменить его на NSK, явно прибавляя часы:
и получить такой же результат:
Python¶
Если данные образца временно́й метки хранятся в данных pandas, вы можете вначале преобразовать столбец Исходное время в объект timestamp с часовым поясом, а затем использовать tz_convert, чтобы изменить часовой пояс на NSK:
df['Исходное время (UTC)'] = pd.to_timestamp(df['Исходное время'], utc=True)
df['Время отчёта команды (NSK)'] = df['Исходное время (UTC)'].dt.tz_convert(tz='Asia/Novosibirsk')
и это будет аналогично выражению convertTimezone: