Перейти к содержимому
Последнее обновление

Управление часовыми поясами

Doris поддерживает настройку часовых поясов. В этом документе описаны назначение параметров часовых поясов в Doris, способы их просмотра и настройки, влияние часового пояса на функции и типы данных, обработка летнего времени и рекомендации по работе с данными, зависящими от часового пояса.

Сценарии применения​

СценарийОписание
Инициализация кластераНастройка time_zone после развертывания с учетом расположения бизнеса или единого стандарта
Загрузка данных из разных часовых поясовЗагрузка данных с указанием часового пояса или без него с помощью Stream Load, Broker Load и аналогичных способов
Согласование результатов функцийНастройка часового пояса для значений, возвращаемых такими функциями, как NOW(), CURTIME() и FROM_UNIXTIME
Обработка летнего времениРабота с именованными часовыми поясами, предусматривающими переход на летнее время, например America/Los_Angeles
Обновление данных о часовых поясахОбновление данных о часовых поясах на машинах BE после выпуска новой версии tzdata организацией IANA

Основные понятия​

В Doris есть два параметра, связанных с часовыми поясами:

ПараметрМожно изменитьОписание
system_time_zoneНетАвтоматически задается системой при запуске сервера на основе локального часового пояса машины. После установки изменить его нельзя.
time_zoneДаТекущий часовой пояс кластера. При запуске кластера совпадает с system_time_zone и остается неизменным, пока его не изменят вручную.

Просмотр и настройка часового пояса​

Просмотр текущего часового пояса​

Чтобы просмотреть переменные, связанные с часовыми поясами, выполните следующий оператор SQL:

show variables like '%time_zone%';

Настройка часового пояса​

Измените time_zone с помощью оператора SET:

SET [global] time_zone = 'Asia/Shanghai';
  • Без ключевого слова global: изменение действует только в текущем сеансе.
  • С ключевым словом global: FE Doris сохраняет параметр, и изменение действует для всех последующих новых сеансов.

Источник данных о часовых поясах​

Данные о часовых поясах включают названия часовых поясов, соответствующие смещения времени, переходы на летнее время и другую информацию. На машине BE эти данные берутся из каталога, возвращаемого командой TZDIR. Если команда не поддерживается, источником служит каталог /usr/share/zoneinfo.

Форматы значений часового пояса​

Значения часового пояса можно задавать в нескольких форматах. Doris полностью поддерживает следующие стандартные форматы:

ТипПримерОписание
Стандартный именованный часовой поясAsia/Shanghai, America/Los_Angeles, Etc/GMT+3Берется из локальных данных о часовых поясах
Стандартный формат смещения+02:30, -10:00Нестандартные смещения, например +12:03, не поддерживаются
Сокращенное обозначение часового поясаGMT, UTCЭквивалентно часовому поясу +00:00
Сокращенное обозначение часового поясаCSTЭквивалентно часовому поясу Asia/Shanghai
Одна буква ZZОбозначает часовой пояс Zulu, эквивалентный часовому поясу +00:00

Кроме того, регистр букв при разборе не учитывается.

Примечание

Из-за различий в реализации некоторые способы загрузки в настоящее время поддерживают и другие форматы. В производственных средах нельзя полагаться на форматы, не перечисленные здесь. Их поведение может измениться в любой момент. Следите за соответствующими обновлениями в журнале изменений каждого выпуска.

Влияние часового пояса​

Влияние на функции​

Часовой пояс влияет на значения, возвращаемые функциями времени, такими как NOW() и CURTIME(), а также на значения времени, отображаемые в SHOW LOAD и SHOW BACKENDS.

Однако он не влияет на значения LESS THAN для столбцов секционирования временных типов в CREATE TABLE и на отображаемые значения данных, хранящихся в типах DATE, DATETIME или TIMESTAMP_NS.

Функции, на которые влияет часовой пояс:

ФункцияПоведение
FROM_UNIXTIMEПринимает временную метку UTC и возвращает дату и время в часовом поясе, заданном переменной сеанса Doris time_zone. Например, если time_zone имеет значение CST, функция FROM_UNIXTIME(0) возвращает 1970-01-01 08:00:00.
UNIX_TIMESTAMPПринимает дату и время и возвращает временную метку UTC с учетом часового пояса, заданного переменной сеанса Doris time_zone. Например, если time_zone имеет значение CST, функция UNIX_TIMESTAMP('1970-01-01 08:00:00') возвращает 0.
CURTIMEВозвращает текущее время в часовом поясе, заданном переменной сеанса Doris time_zone.
NOWВозвращает текущую дату и время в часовом поясе, заданном переменной сеанса Doris time_zone.
CONVERT_TZПреобразует дату и время из одного указанного часового пояса в другой.

Влияние на временные типы​

Типы DATE / DATETIME / TIMESTAMP_NS​

Для типов DATE, DATETIME и TIMESTAMP_NS поддерживается преобразование часовых поясов при загрузке данных. Тип TIMESTAMP_NS хранит значения без учета часового пояса по тем же правилам, что и DATETIME, сохраняя при этом девять знаков дробной части секунды:

  • Данные с указанием часового пояса: например, если задано значение 2020-12-12 12:12:12+08:00, а заголовок Stream Load timezone имеет значение +00:00, в Doris фактически сохраняется значение 2020-12-12 04:12:12.
  • Данные без указания часового пояса: например, значение 2020-12-12 12:12:12 трактуется как абсолютное время, и преобразование не выполняется.

Тип TIMESTAMPTZ​

Тип TIMESTAMPTZ также поддерживает преобразование часовых поясов при загрузке данных: входное значение времени всегда преобразуется в UTC (всемирное координированное время), а при выводе применяется часовой пояс текущего сеанса.

  • Данные с указанием часового пояса: например, для значения 2020-12-12 12:12:12+08:00 Doris использует при преобразовании указанную информацию о часовом поясе.
  • Данные без указания часового пояса: например, для значения 2020-12-12 12:12:12 Doris использует при преобразовании настройку часового пояса текущего сеанса.

Значение time_zone текущего сеанса влияет на вывод данных типа TIMESTAMPTZ. Например, если в текущем сеансе задано time_zone="+08:00", а значение типа TIMESTAMPTZ равно 2020-12-12 12:12:12+08:00, изменение time_zone меняет выводимое значение:

set time_zone = "+08:00";

select * from tz_test;
+---------------------------+
| tz                        |
+---------------------------+
| 2020-12-12 12:12:12+08:00 |
+---------------------------+

set time_zone = "+07:00";

select * from tz_test;
+---------------------------+
| tz                        |
+---------------------------+
| 2020-12-12 11:12:12+07:00 |
+---------------------------+

Летнее время​

Летнее время означает, что фактическое смещение именованного часового пояса меняется в определенный период дат.

Например, в часовом поясе America/Los_Angeles ежегодно предусмотрен один период летнего времени, который начинается примерно в марте и заканчивается примерно в ноябре. При переходе на летнее время в марте фактическое смещение America/Los_Angeles меняется с -08:00 на -07:00. При окончании летнего времени в ноябре оно меняется обратно с -07:00 на -08:00.

Если вы не хотите использовать летнее время, задайте для time_zone значение -08:00 вместо America/Los_Angeles.

Рекомендации​

Работа с данными, зависящими от часового пояса​

При работе с часовыми поясами нужно учитывать три основных фактора:

  1. Часовой пояс кластера: переменная сеанса time_zone.
  2. Часовой пояс загрузки: заголовок timezone, задаваемый при загрузке через Stream Load, Broker Load и аналогичными способами.
  3. Часовой пояс данных: литерал часового пояса в данных, например +08:00 в 2023-12-12 08:00:00+08:00.

В настоящее время Doris поддерживает загрузку данных из любого часового пояса. Поскольку временные типы, такие как DATETIME и TIMESTAMP_NS, не содержат внутри себя информацию о часовом поясе, а сохраненные данные после загрузки не меняются при изменении часового пояса, загружаемые в Doris временные данные делятся на две категории:

  1. Абсолютное время

    Абсолютное время означает, что сценарий использования данных не зависит от часового пояса. При загрузке таких данных не добавляйте суффикс часового пояса. Данные сохраняются без изменений.

  2. Время в определенном часовом поясе

    Время в определенном часовом поясе означает, что сценарий использования данных зависит от часового пояса. При загрузке таких данных добавляйте суффикс нужного часового пояса. В процессе загрузки данные преобразуются в часовой пояс, заданный параметром кластера Doris time_zone или заголовком timezone в Stream Load или Broker Load.

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

Пример оператора INSERT​

Doris > select @@time_zone;
+---------------+
| @@time_zone   |
+---------------+
| Asia/Shanghai |
+---------------+

Doris > insert into dt values('2020-12-12 12:12:12+02:00'); --- The ingested data specifies the time zone as +02:00

Doris > select * from dt;
+---------------------+
| dt                  |
+---------------------+
| 2020-12-12 18:12:12 | --- Converted to the Doris cluster time zone Asia/Shanghai. Subsequent ingestion and queries must keep this time zone.
+---------------------+

Doris > set time_zone = 'America/Los_Angeles';

Doris > select * from dt;
+---------------------+
| dt                  |
+---------------------+
| 2020-12-12 18:12:12 | --- If time_zone is changed, the time value does not change, and its meaning at query time becomes inconsistent.
+---------------------+

Пример Stream Load​

При загрузке с помощью Stream Load, Broker Load и аналогичных способов преобразование часовых поясов можно выполнить, задав заголовок timezone. Например:

cat dt.csv
2020-12-12 12:12:12+02:00

curl --location-trusted -u root: \
    -H "Expect:100-continue" \
    -H "strict_mode: true" \
    -H "timezone: Asia/Shanghai" \
    -T dt.csv -XPUT \
    http://127.0.0.1:8030/api/test/dt/_stream_load
Doris > select @@time_zone;
+---------------+
| @@time_zone   |
+---------------+
| Asia/Shanghai |
+---------------+

Doris > select * from dt;
+---------------------+
| dt                  |
+---------------------+
| 2020-12-12 18:12:12 | --- Converted to the Doris cluster time zone Asia/Shanghai. Subsequent ingestion and queries must keep this time zone.
+---------------------+
подсказка
  • При загрузке с помощью Stream Load, Broker Load и аналогичных способов заголовок timezone переопределяет параметр кластера Doris time_zone, поэтому при загрузке их значения должны совпадать.
  • При загрузке с помощью Stream Load, Broker Load и аналогичных способов заголовок timezone влияет на функции, используемые для преобразований в процессе загрузки.
  • Если при загрузке заголовок timezone не задан, по умолчанию используется текущий часовой пояс кластера.

Основные рекомендации​

Рекомендации
  1. Перед использованием определите, в каком часовом поясе должен работать кластер, задайте time_zone и больше не меняйте его.
  2. При загрузке задавайте заголовок timezone так, чтобы он совпадал с параметром кластера time_zone.
  3. Для абсолютного времени не добавляйте суффикс часового пояса при загрузке. Для времени с учетом часового пояса добавляйте суффикс нужного часового пояса при загрузке. После загрузки данные преобразуются в часовой пояс Doris time_zone.

Рекомендации по летнему времени​

Даты и время начала и окончания летнего времени берутся из текущего источника данных о часовых поясах и могут не совпадать в точности с официальными датами и временем, установленными в соответствующем регионе на текущий год. Эти данные поддерживает ICANN.

Чтобы поведение при переходе на летнее время соответствовало официальным правилам текущего года, убедитесь, что Doris использует последние данные о часовых поясах, опубликованные ICANN. Способ скачивания приведен ниже.

Обновление информации о часовых поясах​

Фактические данные о часовых поясах и летнем времени периодически меняются по разным причинам. IANA регулярно фиксирует эти изменения и обновляет соответствующие файлы часовых поясов. Чтобы информация о часовых поясах в Doris соответствовала последним данным IANA, используйте один из двух способов:

Способ 1: обновление с помощью менеджера пакетов​

Обновите данные о часовых поясах напрямую с помощью команды, соответствующей менеджеру пакетов вашей операционной системы:

# yum
sudo yum update tzdata
# apt
sudo apt update tzdata

Обновленные таким способом данные находятся в системном каталоге $TZDIR (обычно /usr/share/zoneinfo).

В большинстве дистрибутивов Linux данные tzdata обновляются через менеджер пакетов с задержкой. Если у вас повышенные требования к точности данных о часовых поясах, скачивайте напрямую данные, которые IANA периодически публикует:

wget https://www.iana.org/time-zones/repository/tzdb-latest.tar.lz

Затем следуйте инструкциям README в распакованной папке, чтобы создать необходимые данные zoneinfo. Скопируйте созданные данные в каталог $TZDIR, заменив существующие файлы.

Важно

После выполнения всех указанных выше операций на машине BE необходимо перезапустить соответствующий BE, чтобы изменения вступили в силу.

Часто задаваемые вопросы​

Вопрос: почему после изменения time_zone результаты запросов к уже загруженным данным неожиданно меняются?​

Такие типы, как DATETIME и TIMESTAMP_NS, не содержат внутри себя информацию о часовом поясе, а изменение часового пояса кластера после загрузки не меняет сохраненные значения. Перед использованием определите часовой пояс кластера, задайте time_zone и больше не меняйте его.

Вопрос: почему смещение времени в данных, загруженных через Stream Load, не соответствует ожиданиям?​

Заголовок timezone не совпадает с параметром кластера time_zone. Значение заголовка timezone должно совпадать с параметром кластера time_zone.

Вопрос: почему время, возвращаемое NOW(), не совпадает с местным временем?​

Параметр кластера time_zone не соответствует местному часовому поясу. Измените его с помощью SET global time_zone = 'Asia/Shanghai'.

Вопрос: почему переход на летнее время в именованном часовом поясе не соответствует правилам текущего года?​

Данные tzdata на машине BE устарели. Обновите tzdata с помощью менеджера пакетов или скачайте tzdata напрямую из IANA, затем перезапустите BE.

Вопрос: что делать, если я использую America/Los_Angeles, но не хочу включать летнее время?​

Именованные часовые пояса содержат правила перехода на летнее время. Используйте вместо них формат с фиксированным смещением, например -08:00.

Дополнительные материалы​

Report issue
На этой странице