メインコンテンツまでスキップ

タイムゾーン

Dorisはカスタムタイムゾーン設定をサポートしています

基本概念​

Doris内には以下の2つのタイムゾーン関連パラメータが存在します：

  • system_time_zone：サーバー起動時に、マシンで設定されたタイムゾーンに応じて自動的に設定され、設定後は変更できません。
  • time_zone：クラスターの現在のタイムゾーン。この変数はクラスター開始時にsystem_time_zoneと同じに設定され、ユーザーが手動で変更しない限り、再び変更されることはありません。

具体的な操作​

  1. SHOW VARIABLES LIKE '% time_zone%'

    現在のタイムゾーン関連設定を表示

  2. SET [global] time_zone = 'Asia/Shanghai';

    このコマンドはセッションレベルでタイムゾーンを設定します。globalキーワードが使用された場合、Doris FEはパラメータを永続化し、以降のすべての新しいセッションで有効になります。

データソース​

タイムゾーンデータには、タイムゾーンの名前、対応する時差、およびサマータイムの変更が含まれます。BEが配置されているマシンでは、データのソースはTZDIRコマンドによって返されるディレクトリです。サポートされていない場合は、/usr/share/zoneinfoディレクトリです。

タイムゾーンの影響​

1. 関数​

NOW()やCURTIME()などの時間関数によって表示される値、およびshow load、show backendsの時間値が含まれます。

ただし、create tableの時間型パーティション列のless than値や、date/datetime型として格納された値の表示には影響しません。

タイムゾーンの影響を受ける関数：

  • FROM_UNIXTIME：UTCタイムスタンプを指定して、Dorisセッションtime_zoneで指定されたタイムゾーンでの日付と時刻を返します。例えば、time_zoneがCSTの場合、FROM_UNIXTIME(0)は1970-01-01 08:00:00を返します。

  • UNIX_TIMESTAMP：日付と時刻を指定して、Dorisセッションtime_zoneで指定されたタイムゾーンでのUTCタイムスタンプを返します。例えば、time_zoneがCSTの場合、UNIX_TIMESTAMP('1970-01-01 08:00:00')は0を返します。

  • CURTIME：現在のDorisセッションtime_zoneで指定されたタイムゾーンの時刻を返します。

  • NOW：現在のDorisセッションtime_zoneで指定されたタイムゾーンの日付と時刻を返します。

  • CONVERT_TZ：指定されたタイムゾーンから別のタイムゾーンにdatetimeを変換します。

2. 時間型の値​

DATEとDATETIME型について、データインポート時のタイムゾーン変換をサポートしています。

  • データにタイムゾーンが含まれている場合、例えば「2020-12-12 12:12:12+08:00」で現在のDoris time_zone = +00:00の場合、データはDorisにインポートされ、実際の値は「2020-12-12 04:12:12」になります。

  • データにタイムゾーンが含まれていない場合、例えば「2020-12-12 12:12:12」の場合、時刻は絶対時刻と見なされ、変換は行われません。

3. サマータイム​

サマータイムは本質的に、特定の日付で変更される名前付きタイムゾーンの実際の時差です。

例えば、America/Los_Angelesタイムゾーンには、毎年おおよそ3月と11月に開始および終了するサマータイム調整が含まれています。つまり、America/Los_Angelesの実際のタイムゾーンオフセットは、3月のサマータイム開始時に-08:00から-07:00に変更され、11月のサマータイム終了時に-07:00から-08:00に変更されます。 サマータイムを有効にしたくない場合は、America/Los_Angelesの代わりにtime_zoneを-08:00に設定してください。

使用方法​

タイムゾーン値は様々な形式で指定できます。以下の標準形式がDorisでよくサポートされています：

  1. 標準の名前付きタイムゾーン形式、例えば「Asia/Shanghai」、「America/Los_Angeles」。この形式はこのマシンのタイムゾーンデータに由来します。「Etc/GMT+3」なども、このカテゴリに属します。

  2. 標準のオフセット形式、例えば「+02:30」、「-10:00」。（「+12:03」などの特殊なオフセットはサポートされていません）

  3. 省略されたタイムゾーン形式、現在以下のもののみサポート：

    1. 「GMT」、「UTC」、「+00:00」タイムゾーンと同等

    2. 「CST」、「Asia/Shanghai」タイムゾーンと同等

  4. Zuluタイムゾーンを表す単一文字Z、「+00:00」タイムゾーンと同等

また、すべてのアルファベットの解析は大文字小文字を区別しません。

注意：実装の違いにより、現在Dorisではいくつかのインポートでその他の形式もサポートされています。本番環境では、ここにリストされていないこれらの形式に依存すべきではありません。それらの動作はいつでも変更される可能性がありますので、バージョン更新の関連する変更履歴に注意してください。

ベストプラクティス​

タイムゾーンに敏感なデータ​

タイムゾーンの問題は、主に3つの影響を含みます：

  1. セッション変数time_zone -- クラスタータイムゾーン

  2. インポート時に指定されるheader timezone（Stream Load、Broker Loadなど）-- インポートタイムゾーン

  3. 「2023-12-12 08:00:00+08:00」の「+08:00」のようなタイムゾーン型リテラル -- データタイムゾーン

以下のように理解できます：

Dorisは現在、様々なタイムゾーンのデータをDorisにインポートすることと互換性があります。Doris自体のDATETIMEなどの時間型にはタイムゾーン情報が含まれておらず、データはインポート後にタイムゾーンの変更によって変わることがないため、時間データがDorisにインポートされる際は、以下の2つのカテゴリに分けることができます：

  1. 絶対時刻

    絶対時刻は、それが関連付けられているデータシーンがタイムゾーンと無関係であることを意味します。この種のデータは、タイムゾーンサフィックスなしでインポートされ、そのまま格納されます。

  2. 特定のタイムゾーンでの時刻

    特定のタイムゾーンでの時刻は、それが関連付けられているデータシナリオがタイムゾーンに関連していることを意味します。この種のデータについては、特定のタイムゾーンサフィックス付きでインポートされるべきです。インポート時に、Dorisクラスターtime_zoneタイムゾーンまたはStream Load/Broker Loadで指定されたheader timezoneに変換されます。

    この種のデータは、インポート後、インポート時に指定されたタイムゾーンで絶対時刻ストレージに変換されるため、後続のインポートとクエリは、データの意味の混乱を避けるために、このタイムゾーンを維持する必要があります。

  • Insertステートメントについては、以下の例を通して説明できます：

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

    Doris > insert into dt values('2020-12-12 12:12:12+02:00'); --- The imported data specifies a time zone of +02:00

    Doris > select * from dt;
    +---------------------+
    | dt                  |
    +---------------------+
    | 2020-12-12 18:12:12 | --- Is converted to the Doris cluster time zone Asia/Shanghai, subsequent imports and queries should maintain 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 modified, the time value will not change accordingly, and its meaning during query will be confused.
    +---------------------+

  • Stream LoadやBroker Loadなどのインポート方法では、ヘッダーtimezoneを指定することでこれを実現できます。例えば、Stream Loadの場合、以下の例で説明できます：

    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 | --- Is converted to the Doris cluster time zone Asia/Shanghai, subsequent imports and queries should maintain 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. Package Managerを使用して更新する

現在のオペレーティングシステムで使用されているパッケージマネージャーに応じて、対応するコマンドを使用してタイムゾーンデータを直接更新できます：

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

この方法で更新されたデータは、システムの$TZDIR（通常はusr/share/zoneinfo）の下に配置されます。

  1. IANA time zone databaseを手動でpullする（推奨）

ほとんどのLinuxディストリビューションには、tzdataが適時に同期されないパッケージマネージャーがあります。time zoneデータの正確性が重要な場合は、定期的にIANAが公開するデータをpullすることができます：

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

次に、展開されたフォルダ内のREADMEファイルに従って、特定のzoneinfoデータを生成します。生成されたデータは$TZDIRフォルダを上書きするようにコピーする必要があります。

BEマシン上で上記のすべての操作が完了した後、対応するBEで必ず再起動して変更を有効にする必要があることに注意してください。

関連資料​

Report issue
ASF
Resources
Community
Join the community
Copyright © 2026 The Apache Software Foundation,Licensed under the Apache License, Version 2.0. Apache, Doris, Apache Doris, the Apache feather logo and the Apache Doris logo are trademarks of The Apache Software Foundation.