日時データ型 - 時系列 - ClickHouse Documentation

時系列データを効果的に管理するには、日付・時刻型がひととおり揃っていることが不可欠です。ClickHouse は、まさにそれを提供します。コンパクトな日付表現からナノ秒精度の高精度なタイムスタンプまで、これらの型は、ストレージ効率とさまざまな時系列アプリケーションにおける実用上の要件を両立できるよう設計されています。過去の金融データ、IoT センサーの測定値、将来の日時が設定されたイベントなど、どのようなデータを扱う場合でも、ClickHouse の日付・時刻型は、さまざまな時間データのユースケースに対応するために必要な柔軟性を提供します。サポートされる型の幅が広いため、ユースケースで求められる精度を維持しながら、ストレージ容量とクエリ性能の両方を最適化できます。

Date 型は、ほとんどの場合に十分です。この型は日付の格納に 2 バイトを使用し、範囲は [1970-01-01, 2149-06-06] に制限されます。
Date32 は、より広い日付範囲をカバーします。日付の格納に 4 バイトを使用し、範囲は [1900-01-01, 2299-12-31] に制限されます
DateTime は、date time 値を秒精度で格納し、範囲は [1970-01-01 00:00:00, 2106-02-07 06:28:15] です。値ごとに 4 バイトを使用します。
より高い精度が必要な場合は、DateTime64 を使用できます。これにより、最大ナノ秒精度で時刻を格納でき、範囲は [1900-01-01 00:00:00, 2299-12-31 23:59:59.99999999] です。値ごとに 8 バイトを使用します。

では、さまざまな日付型を格納するテーブルを作成してみましょう。

CREATE TABLE dates
(
    `date` Date,
    `wider_date` Date32,
    `datetime` DateTime,
    `precise_datetime` DateTime64(3),
    `very_precise_datetime` DateTime64(9)
)
ENGINE = MergeTree
ORDER BY tuple();

現在時刻を返すには now() 関数を使用できます。指定した精度で取得するには、最初の引数で精度を指定して now64() を使用します。

INSERT INTO dates 
SELECT now(), 
       now()::Date32 + toIntervalYear(100),
       now(), 
       now64(3), 
       now64(9) + toIntervalYear(200);

これにより、カラムの型に応じて各カラムに時刻が設定されます。

SELECT * FROM dates
FORMAT Vertical;

行 1:
──────
date:                  2025-03-12
wider_date:            2125-03-12
datetime:              2025-03-12 11:39:07
precise_datetime:      2025-03-12 11:39:07.196
very_precise_datetime: 2025-03-12 11:39:07.196724000

Time と Time64 型

日付の部分を含まない時刻の値を保存する必要がある場合、ClickHouse では Time 型と Time64 型を使用できます。これらはバージョン 25.6 で導入されました。繰り返し実行されるスケジュール、日次パターン、あるいは日付と時刻の部分を分けて扱うのが適切なケースの表現に役立ちます。

Time と Time64 を使用するには、次の設定を有効にする必要があります: SET enable_time_time64_type = 1;これらの型はバージョン 25.6 で導入されました

Time 型は、時・分・秒を秒精度で格納します。内部的には符号付き 32 ビット整数として保存され、[-999:59:59, 999:59:59] の範囲をサポートするため、24 時間を超える値も扱えます。これは、経過時間を追跡する場合や、1 日の範囲を超える値になる算術演算を行う場合に便利です。秒未満の精度が必要な場合、Time64 は設定可能な小数秒付きの時刻を、符号付き Decimal64 値として格納します。小数点以下の桁数を定義するための精度パラメータ (0～9) を受け付けます。一般的な精度の値は、3 (ミリ秒) 、6 (マイクロ秒) 、9 (ナノ秒) です。 Time と Time64 はどちらもタイムゾーンをサポートしません。これらは、地域的な文脈を持たない純粋な時刻の値を表します。時刻カラムを持つテーブルを作成してみましょう:

SET enable_time_time64_type = 1;

CREATE TABLE time_examples
(
    `event_id` UInt8,
    `basic_time` Time,
    `precise_time` Time64(3)
)
ENGINE = MergeTree
ORDER BY event_id;

文字列リテラルまたは数値を使って時刻値を挿入できます。Time では、数値は 00:00:00 からの秒数として解釈されます。Time64 では、数値は 00:00:00 からの秒数として解釈され、小数部はカラムの精度に応じて解釈されます：

INSERT INTO time_examples VALUES 
    (1, '14:30:25', '14:30:25.123'),
    (2, 52225, 52225.456),
    (3, '26:11:10', '26:11:10.789');  -- 24時間を超える値は正規化される

SELECT * FROM time_examples ORDER BY event_id;

┌─event_id─┬─basic_time─┬─precise_time─┐
│        1 │ 14:30:25   │ 14:30:25.123 │
│        2 │ 14:30:25   │ 14:30:25.456 │
│        3 │ 26:11:10   │ 26:11:10.789 │
└──────────┴────────────┴──────────────┘

時刻の値は自然にフィルタリングできます：

SELECT * FROM time_examples WHERE basic_time = '14:30:25';

タイムゾーン

多くのユースケースでは、タイムゾーンもあわせて保存する必要があります。タイムゾーンは、DateTime 型または DateTime64 型の最後の引数として設定できます。

CREATE TABLE dtz
(
    `id` Int8,
    `dt_1` DateTime('Europe/Berlin'),
    `dt_2` DateTime,
    `dt64_1` DateTime64(9, 'Europe/Berlin'),
    `dt64_2` DateTime64(9)
)
ENGINE = MergeTree
ORDER BY id;

DDLでタイムゾーンを定義したので、異なるタイムゾーンを使って時刻を挿入できるようになりました:

INSERT INTO dtz 
SELECT 1, 
       toDateTime('2022-12-12 12:13:14', 'America/New_York'),
       toDateTime('2022-12-12 12:13:14', 'America/New_York'),
       toDateTime64('2022-12-12 12:13:14.123456789', 9, 'America/New_York'),
       toDateTime64('2022-12-12 12:13:14.123456789', 9, 'America/New_York')
UNION ALL
SELECT 2, 
       toDateTime('2022-12-12 12:13:15'),
       toDateTime('2022-12-12 12:13:15'),
       toDateTime64('2022-12-12 12:13:15.123456789', 9),
       toDateTime64('2022-12-12 12:13:15.123456789', 9);

それでは、テーブルの中身を見てみましょう。

SELECT dt_1, dt64_1, dt_2, dt64_2
FROM dtz
FORMAT Vertical;

行 1:
──────
dt_1:   2022-12-12 18:13:14
dt64_1: 2022-12-12 18:13:14.123456789
dt_2:   2022-12-12 17:13:14
dt64_2: 2022-12-12 17:13:14.123456789

行 2:
──────
dt_1:   2022-12-12 13:13:15
dt64_1: 2022-12-12 13:13:15.123456789
dt_2:   2022-12-12 12:13:15
dt64_2: 2022-12-12 12:13:15.123456789

最初の行では、America/New_York のタイムゾーンを使用して、すべての値を挿入しました。

dt_1 と dt64_1 は、クエリ時に自動的に Europe/Berlin に変換されます。
dt_2 と dt64_2 にはタイムゾーンが指定されていなかったため、サーバーのローカルタイムゾーンが使用されます。この場合は Europe/London です。

2 行目では、タイムゾーンを指定せずにすべての値を挿入したため、サーバーのローカルタイムゾーンが使用されました。最初の行と同様に、dt_1 と dt64_1 は Europe/Berlin に変換され、dt_2 と dt64_2 はサーバーのローカルタイムゾーンを使用します。

日付と時刻の関数

ClickHouse には、異なるデータ型同士を変換するための関数も用意されています。たとえば、toDate を使って、DateTime の値を Date 型に変換できます。

SELECT
    now() AS current_time,
    toTypeName(current_time),
    toDate(current_time) AS date_only,
    toTypeName(date_only)
FORMAT Vertical;    

行 1:
──────
current_time:             2025-03-12 12:32:54
toTypeName(current_time): DateTime
date_only:                2025-03-12
toTypeName(date_only):    Date

toDateTime64 を使うと、DateTime を DateTime64 に変換できます。

SELECT
    now() AS current_time,
    toTypeName(current_time),
    toDateTime64(current_time, 3) AS date_only,
    toTypeName(date_only)
FORMAT Vertical;

行 1:
──────
current_time:             2025-03-12 12:35:01
toTypeName(current_time): DateTime
date_only:                2025-03-12 12:35:01.000
toTypeName(date_only):    DateTime64(3)

また、toDateTime を使うと、Date または DateTime64 を DateTime に戻すことができます。

SELECT
    now64() AS current_time,
    toTypeName(current_time),
    toDateTime(current_time) AS date_time1,
    toTypeName(date_time1),
    today() AS current_date,
    toTypeName(current_date),
    toDateTime(current_date) AS date_time2,
    toTypeName(date_time2)
FORMAT Vertical;

行 1:
──────
current_time:             2025-03-12 12:41:00.598
toTypeName(current_time): DateTime64(3)
date_time1:               2025-03-12 12:41:00
toTypeName(date_time1):   DateTime
current_date:             2025-03-12
toTypeName(current_date): Date
date_time2:               2025-03-12 00:00:00
toTypeName(date_time2):   DateTime

​Time と Time64 型

​タイムゾーン

​日付と時刻の関数

Time と Time64 型

タイムゾーン

日付と時刻の関数