# ConvertTimezone `convertTimezone` сдвигает метку времени в указанный часовой пояс, добавляя или вычитая нужный интервал из временной метки. | Синтаксис | Пример | |-----------------------------------------------------------------------------|------------------------------------------------------------------------------------------| | `convertTimezone(column, target, source)` | `convertTimezone("2022-12-28T12:00:00", "Canada/Pacific", "Canada/Eastern")` | | Смещает временную метку из исходного часового пояса в целевой часовой пояс. | Возвращает значение `2022-12-28T09:00:00`», отображаемое как `28 декабря 2022 г., 9:00`. | Работать с временными метками и часовыми поясами довольно непросто (легко сделать ошибки и трудно их отловить), поэтому вам следует пытаться использовать `convertTimezone` только в том случае, если интерпретация ваших данных чувствительна к временным ограничениям. Например, если вы отслеживаете вход пользователей в систему, то, вероятно, будет не очень критично, если некоторые входы в систему будут учитываться по понедельникам, а не по вторникам, с учетом временного смещения. Однако, если вы используете GlarusBI для чего-то точного, например, для уплаты налогов, то вас, вероятно, гораздо больше будет заботить разница между транзакциями, совершенными 31 декабря и 1 января. ## Параметры `column` может быть любым из: - Имя столбца метки времени, - пользовательское выражение, которое возвращает отметку времени, или - строка в формате `"YYYY-MM-DD` или `"YYYY-MM-DDTHH:MM:SS"`. `target`: - Имя часового пояса, которое вы хотите присвоить своему столбцу. `source`: - Название текущего часового пояса вашего столбца. - Требуется для столбцов или выражений с типом данных «отметка времени без часового пояса». - Необязательно для столбцов или выражений с типом данных «отметка времени с часовым поясом». – Дополнительные сведения см. в разделе [Принятые типы данных](#accepted-data-types). Мы так же поддерживаем названия часовых поясов (например, «Canada/Eastern» вместо «EST»). ## Создание пользовательских дат отчета Допустим, у вас есть данные временных рядов, хранящиеся в одном или нескольких часовых поясах (**Исходное время**). Вы хотите создать собственные отчетные даты для команды, которая находится в другом временном поясе, например, в EST. | Source Time | Team Report Time (EST) | | --------------------------- | --------------------------- | | December 28, 2022, 10:00:00 | December 28, 2022, 07:00:00 | | December 28, 2022, 21:00:00 | December 28, 2022, 19:00:00 | | December 27, 2022, 08:00:00 | December 27, 2022, 05:00:00 | Если **Исходное время** хранится как «метка времени с часовым поясом» `timestamp with time zone` или «метка времени со смещением» `timestamp with offset`, вам нужно указать только «целевой» часовой пояс: ``` convertTimezone([Source Time], 'EST') ``` Если **Исходное время** хранится как «отметка времени без часового пояса» `timestamp without time zone`, вы _должны_ указать «исходный» `source` часовой пояс (который будет зависеть от часового пояса вашей базы данных): ``` convertTimezone([Source Time], 'EST', 'UTC') ``` Обычно рекомендуется помечать столбцы `convertTimezone` именем целевого часового пояса (или добавлять целевой часовой пояс в метаданные модели). Обычно это сильно упрощает жизнь, когда кто-то интересуется, почему числа не совпадают. Если вы не получаете ожидаемых результатов: - Проверьте, правильно ли вы указали [исходный часовой пояс](#choosing-a-source-time-zone). - Спросите у администратора базы данных о «отметке времени с часовым поясом» и «отметке времени без часового пояса» (дополнительную информацию см. в разделе [Принятые типы данных](#accepted-data-types)). ### Выбор исходного часового пояса При преобразовании часовых поясов убедитесь, что вы знаете исходный часовой пояс, с которым работаете. Разные столбцы (и даже разные строки) в одной таблице, вопросе или модели могут находиться в разных «исходных» часовых поясах. | Возможный часовой пояс источника | Описание | Пример | |----------------------------------|-------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------| | Часовой пояс клиента | Часовой пояс, в котором произошло событие. | Служба веб-аналитики может собирать данные о местном часовом поясе каждого человека, посетившего ваш сайт. | | Часовой пояс базы данных | Метаданные часового пояса, которые были добавлены к отметкам времени в вашей базе данных. | Общепринятой практикой баз данных является хранение всех временных меток в формате UTC. | | Нет часового пояса | Отсутствуют метаданные часового пояса metadata | Базы данных не требуют от вас хранения временных меток с метаданными часового пояса. | | Часовой пояс отчета GlarusBI | Часовой пояс, который GlarusBI использует для отображения временных меток. | GlarusBI может отображать даты и время в формате PST, даже если даты и время хранятся в вашей базе данных в формате UTC. | Например, скажем, у вас есть таблица с одной строкой для каждого человека, посетившего ваш сайт. Трудно сказать, просто взглянув на «28 декабря 2022 г., 12:00», является ли это «сырой» отметкой времени: - хранится с использованием часового пояса вашей базы данных (обычно UTC), - хранится без метаданных часового пояса (например, если посетитель веб-сайта находится в HKT, то временная метка «28 декабря 2022 г., 12:00» может «неявно» использовать время Гонконга), - _отображается_ в часовом поясе отчета GlarusBI. Для более детальной информации смотри [Ограничения](#limitations). ## Допустимые типы данных | [Типы данных](https://www.metabase.com/learn/databases/data-types-overview#Примерs-of-data-types) | Работает с `convertTimezone` | |---------------------------------------------------------------------------------------------------| ---------------------------- | | Строка | ❌ | | Число | ❌ | | Дата/время | ✅ | | Условие | ❌ | | JSON | ❌ | Мы используем сочетания «timestamp» и «datetime», чтобы говорить о любом временном типе данных, поддерживаемом GlarusBI. Если ваши временные метки хранятся в базе данных в виде строк или чисел, администратор может [преобразовать их во временные метки](../../../data-modeling/metadata-editing.md#casting-to-a-specific-data-type) на странице 'Метаданные таблиц'. Чтобы использовать `convertTimezone`, не сталкиваясь с ошибками или надоедливыми необнаружимыми ошибками, вы должны знать, что существует несколько разновидностей типов данных `timestamp`: | Тип данных | Описание | Пример | | ----------------------------- |--------------------------------------| ---------------------------------------------------- | | `timestamp with time zone` | Знает о местонахождении. | `2022-12-28T12:00:00 AT TIME ZONE 'America/Toronto'` | | `timestamp with offset` | Знает о разнице с UTC. | `2022-12-28T12:00:00-04:00` | | `timestamp without time zone` | Нет информации о часовом поясе | `2022-12-28T12:00:00` | Обратите внимание, что первая часть метки времени указана в формате UTC (то же самое, что и GMT). Часовой пояс или смещение говорят вам, сколько времени нужно добавить или вычесть для данного часового пояса. `convertTimezone` будет работать со всеми тремя типами меток времени, но результатом `convertTimezone` всегда будет `метка времени без часового пояса`. ## Ограничения `convertTimezone` не работает со следующими базами данных: - Amazon Athena - Druid - Google Analytics - H2 - MongoDB - Presto - SparkSQL - SQLite ### Примечания об исходных часовых поясах GlarusBI отображает метки времени без информации о часовом поясе или смещении, поэтому вы должны быть очень осторожны с [исходным часовым поясом](#choosing-a-source-time-zone) при использовании `convertTimezone`. Часовой пояс отчета GlarusBI применяется только к типам данных «отметка времени с часовым поясом» `timestamp with time zone` или «отметка времени со смещением» `timestamp with offset`. Для примера: | Временная зона в вашей базе данных | Тип данных | Временная зона отчета | Отображается как | |------------------------------------------|-------------------------------|-----------------------|------------------------| | `2022-12-28T12:00:00 AT TIME ZONE 'CST'` | `timestamp with time zone` | 'Canada/Eastern' | Dec 28, 2022, 7:00 AM | | `2022-12-28T12:00:00-06:00` | `timestamp with offset` | 'Canada/Eastern' | Dec 28, 2022, 7:00 AM | | `2022-12-28T12:00:00` | `timestamp without time zone` | 'Canada/Eastern' | Dec 28, 2022, 12:00 AM | Часовой пояс отчета GlarusBI не будет применяться к выходным данным выражения `convertTimezone`. Для примера: ``` convertTimezone("2022-12-28T12:00:00 AT TIME ZONE 'Canada/Central'", "Canada/Pacific", "Canada/Central") ``` создаст необработанную «метку времени без часового пояса» `timestamp without time zone` ``` 2022-12-28T04:00:00 ``` и отображается в GlarusBI как ``` Dec 28, 2022, 4:00 AM ``` Если вы используете `convertTimezone` для `timestamp without time zone`, обязательно используйте 'UTC' в качестве часового пояса `source`, иначе выражение сместит вашу метку времени на неправильную величину. Для примера, если наша «метка времени без часового пояса» `timestamp without time zone` только «подразумевается» в CST, мы должны использовать «UTC» в качестве параметра «источник» `source`, чтобы получить тот же результат, что и выше. Например, если мы выбираем 'CST', как источник `source` часового пояса для `timestamp without time zone`: ``` convertTimezone("2022-12-28T12:00:00", "Canada/Pacific", "Canada/Central") ``` мы получим необработанную временную метку без часового пояса `timestamp without time zone` ``` 2022-12-28T10:00:00 ``` которая отобразится в GlarusBI как ``` Dec 28, 2022, 10:00 AM ``` ## Связанные функции В этом разделе рассматриваются функции и формулы, которые работают так же, как выражение `convertTimezone`, с примечаниями о том, как выбрать лучший вариант для вашего случая использования. - [SQL](#sql) - [Spreadsheets](#spreadsheets) - [Python](#python) ### SQL Когда вы запускаете вопрос с помощью [конструктора запросов](https://www.metabase.com/glossary/query_builder), GlarusBI преобразует ваши графические настройки запроса (фильтры, сводки и т. д.) в запрос и запускает этот запрос в вашей базе данных. Если наши [примеры временных меток](#creating-custom-report-dates) представляют собой «временную метку без часового пояса», хранящуюся в базе данных PostgreSQL: ```sql SELECT source_time::TIMESTAMP AT TIME ZONE 'UTC' AT TIME ZONE 'EST' AS team_report_time_est ``` то это будет аналогично выражению `convertTimezone` с параметром `source`, установленным на 'UTC': ``` convertTimezone([Source Time], "Canada/Eastern", "UTC") ``` Если `source_time` является `меткой времени с часовым поясом` `timestamp with time zone` или `меткой времени со смещением` `timestamp with offset` (например, в базе данных Snowflake), нам не нужно указывать исходный часовой пояс ```sql SELECT convert_timezone('America/Toronto', source_time) AS team_report_time_est ``` это будет аналогично выражению: ``` convertTimezone([Source Time], "Canada/Eastern") ``` Помните, что имена часовых поясов зависят от вашей базы данных. Например, Snowflake не принимает большинство сокращений часовых поясов (например, EST). ### Таблицы Если наши [временные метки образца данных](#creating-custom-report-dates) находятся в таблице, где «Исходное время» находится в столбце A, мы можем изменить его на EST, явно вычитая часы: ``` A1 - TIME(5, 0, 0) ``` получая такой же результат: ``` convertTimezone([Client Time], "Canada/Eastern") ``` ### Python Если [данные образца временной метки](#creating-custom-report-dates) хранятся в данных `pandas`, вы можете вначале преобразовать столбец **Source Time** в объект `timestamp` с часовым поясом, а затем использовать `tz_convert`, чтобы изменить часовой пояс на EST: ``` df['Source Time (UTC)'] = pd.to_timestamp(df['Source Time'], utc=True) df['Team Report Time (EST)'] = df['Source Time (UTC)'].dt.tz_convert(tz='Canada/Eastern') ``` это будет аналогично выражению `convertTimezone` ``` convertTimezone(convertTimezone([Source Time], "UTC"), "Canada/Eastern", "UTC") ``` ## Дополнительная информация - [Документация по кастомным выражениям](../expressions.md) - [Руководство по кастомным выражениям. Документация Metabase](https://www.metabase.com/learn/questions/custom-expressions) - [Анализ временных меток. Документация Metabase](https://www.metabase.com/learn/time-series/start)