時系列、つまりタイムスタンプとタグ (またはラベル) に関連付けられた値の集合を格納するテーブルエンジン:

metric_name1[tag1=value1, tag2=value2, ...] = {timestamp1: value1, timestamp2: value2, ...}
metric_name2[...] = ...

構文

CREATE TABLE name [(columns)] ENGINE=TimeSeries
[SETTINGS var1=value1, ...]
[SAMPLES db.samples_table_name | [SAMPLES INNER COLUMNS (...)] [SAMPLES INNER ENGINE engine(arguments)]]
[TAGS db.tags_table_name | [TAGS INNER COLUMNS (...)] [TAGS INNER ENGINE engine(arguments)]]
[METRICS db.metrics_table_name | [METRICS INNER COLUMNS (...)] [METRICS INNER ENGINE engine(arguments)]]

使い方

まずは、すべてデフォルト設定のままで始めるのが簡単です (カラムの一覧を指定しなくても TimeSeries テーブルを作成できます) :

CREATE TABLE my_table ENGINE=TimeSeries

このテーブルは、以下のプロトコルで使用できます (サーバー設定でポートを割り当てる必要があります) :

外部カラム

TimeSeries テーブルのカラムは自動的に自動生成されます。これらは外部カラムであり、データ自体は保持せず、SELECT/INSERT のためのインターフェイスだけを提供します。実際のデータはターゲットテーブルに格納されます。外部カラムの一覧は次のとおりです。

名前	型	説明
`metric_name`	`String`	メトリクスの名前
`tags`	`Map(String, String)`	時系列のタグ (ラベル) のマップ
`time_series`	既定では `Array(Tuple(DateTime64(3), Float64))`	時系列の `(timestamp, value)` ペアの Array。タプルの timestamp と scalar 要素の型は、samples の `INNER COLUMNS` 宣言から導出できます (外部カラムの指定を参照)
`metric_family`	`String`	メトリクスファミリーの名前 (メトリクスのメタデータ用)
`type`	`String`	メトリクスの型 (例: "counter"、"gauge")
`unit`	`String`	メトリクスの単位
`help`	`String`	メトリクスの説明

例:

INSERT INTO my_table (metric_name, tags, time_series) VALUES
    ('cpu_usage', {'job': 'node_exporter', 'instance': 'host1:9100'},
     [(toDateTime64('2024-01-01 00:00:00', 3), 0.5), (toDateTime64('2024-01-01 00:01:00', 3), 0.7)])

metric_name は挿入時に空でもかまいません。つまり、メトリクス名は tags 内の __name__ に指定されます。たとえば次のとおりです:

INSERT INTO my_table (tags, time_series) VALUES
    ({'__name__': 'cpu_usage', 'job': 'test'},
     [(toDateTime64('2024-01-01 00:00:00', 3), 0.5)])

メトリクスのメタデータを挿入するには、metric_family、type、unit、help の各カラムに値を挿入します：

INSERT INTO my_table (metric_name, tags, time_series, metric_family, type, unit, help) VALUES
    ('http_requests_total', {'method': 'GET'}, [(now64(), 100.0)],
     'http_requests_total', 'counter', 'requests', 'Total HTTP requests')

外部カラムの指定

外部 time_series カラムは、デフォルトの Array(タプル(DateTime64(3), Float64)) 型をオーバーライドするために、CREATE TABLE ステートメントで明示的に指定できます。ClickHouse はそのタプルから timestamp 型と scalar 型を抽出し、それらを内部の Samples テーブルに反映します：

CREATE TABLE my_table (time_series Array(Tuple(UInt32, Float32))) ENGINE=TimeSeries

これは、samples の INNER COLUMNS 句で timestamp と値のカラム型を直接宣言するのと同じです:

CREATE TABLE my_table ENGINE=TimeSeries
SAMPLES INNER COLUMNS (timestamp UInt32 CODEC(DoubleDelta, ZSTD(1)), value Float32 CODEC(ZSTD(3)))

両方の形式を同じ CREATE TABLE ステートメント内で使用する場合、宣言する型は一致していなければなりません。

ターゲットテーブル

TimeSeries テーブル自体はデータを持たず、すべてのデータはそのターゲットテーブルに格納されます。これは materialized view の仕組みに似ていますが、 materialized view ではターゲットテーブルは 1 つであるのに対し、 TimeSeries テーブルには samples、tags、metrics という 3 つのターゲットテーブルがあります。

ターゲットテーブルは CREATE TABLE クエリで明示的に指定することもできますし、 TimeSeries テーブルエンジンが内部ターゲットテーブルを自動生成することもできます。

TimeSeries テーブルに挿入された行は変換され、ブロックに分割されたうえで、これら 3 つのターゲットテーブルに挿入されます。

ターゲットテーブルは次のとおりです:

samples テーブル

samples テーブルには、識別子に関連付けられた時系列が格納されます。

samples テーブルには、次のカラムが必要です。

Name	必須?	デフォルト型	使用可能な型	Description
`id`	[x]	`Tuple(UInt64, UUID)`	any	メトリクス名とタグの組み合わせを識別します
`timestamp`	[x]	`DateTime64(3)`	`DateTime64(X)`	時点
`value`	[x]	`Float64`	`Float32` or `Float64`	`timestamp` に対応する値

エンジンが自動作成するカラムには、時系列圧縮コーデックが設定されます。 timestamp CODEC(DoubleDelta, ZSTD(1)) および value CODEC(ZSTD(3))。ほぼ単調なタイムスタンプは汎用コーデックではほとんど圧縮されず、samples テーブルのディスク上のサイズの大部分を占める可能性があります。カラムの型の調整も参照してください。

Tags テーブル

tags テーブルには、メトリクス名とタグの各組み合わせに対して計算された識別子が格納されます。

tags テーブルには、次のカラムが必要です。

名前	必須?	デフォルト型	使用可能な型	説明
`id`	[x]	`Tuple(UInt64, UUID)`	任意 (samples テーブルの `id` の型と一致している必要があります)	`id` は、メトリクス名とタグの組み合わせを識別します。DEFAULT 式は、この識別子の計算方法を指定します
`metric_name`	[x]	`LowCardinality(String)`	`String` または `LowCardinality(String)`	メトリクス名
`<tag_value_column>`	[ ]	`String`	`String` または `LowCardinality(String)` または `LowCardinality(Nullable(String))`	特定のタグの値。タグ名と対応するカラム名は、tags_to_columns 設定で指定します
`tags`	[x]	`Map(LowCardinality(String), String)`	`Map(String, String)` または `Map(LowCardinality(String), String)` または `Map(LowCardinality(String), LowCardinality(String))`	メトリクス名を含むタグ `__name__` および tags_to_columns 設定で列挙された名前のタグを含む、すべてのタグのマップ。古いバージョンの ClickHouse で作成されたテーブルでは、このカラムには専用カラムを持たずメトリクス名も含まないタグのみが格納されていました。読み取り時にはどちらの場合も処理されます
`min_time`	[ ]	`Nullable(DateTime64(3))`	`DateTime64(X)` または `Nullable(DateTime64(X))`	その `id` を持つ時系列の最小タイムスタンプ。このカラムは store_min_time_and_max_time が `true` の場合に作成されます
`max_time`	[ ]	`Nullable(DateTime64(3))`	`DateTime64(X)` または `Nullable(DateTime64(X))`	その `id` を持つ時系列の最大タイムスタンプ。このカラムは store_min_time_and_max_time が `true` の場合に作成されます

Metrics テーブル

metrics テーブルには、収集されるメトリクスに関する情報、各メトリクスのタイプ、および説明が格納されます。

metrics テーブルには、次のカラムが必要です。

名前	必須?	デフォルト型	使用可能な型	説明
`metric_family_name`	[x]	`String`	`String` または `LowCardinality(String)`	メトリクスファミリーの名前
`type`	[x]	`LowCardinality(String)`	`String` または `LowCardinality(String)`	メトリクスファミリーのタイプ。"counter"、"gauge"、"summary"、"stateset"、"histogram"、"gaugehistogram" のいずれか
`unit`	[x]	`LowCardinality(String)`	`String` または `LowCardinality(String)`	メトリクスで使用される単位
`help`	[x]	`String`	`String` または `LowCardinality(String)`	メトリクスの説明

作成

TimeSeries テーブルエンジンを使ってテーブルを作成する方法はいくつかあります。最も簡単なステートメントは

CREATE TABLE my_table ENGINE=TimeSeries

実際には、次のテーブルが作成されます (SHOW CREATE TABLE my_table を実行すると確認できます) :

CREATE TABLE my_table
(
    `metric_name` String,
    `tags` Map(String, String),
    `time_series` Array(Tuple(DateTime64(3), Float64)),
    `metric_family` String,
    `type` String,
    `unit` String,
    `help` String
)
ENGINE = TimeSeries
SAMPLES INNER COLUMNS
(
    `id` Tuple(UInt64, UUID),
    `timestamp` DateTime64(3) CODEC(DoubleDelta, ZSTD(1)),
    `value` Float64 CODEC(ZSTD(3))
)
SAMPLES INNER ENGINE = MergeTree ORDER BY (id, timestamp) SETTINGS index_granularity = 32768
TAGS INNER COLUMNS
(
    `id` Tuple(UInt64, UUID) DEFAULT tuple(sipHash64(metric_name), reinterpretAsUUID(sipHash128(tags))),
    `metric_name` LowCardinality(String),
    `tags` Map(LowCardinality(String), String),
    `min_time` SimpleAggregateFunction(min, Nullable(DateTime64(3))),
    `max_time` SimpleAggregateFunction(max, Nullable(DateTime64(3)))
)
TAGS INNER ENGINE = AggregatingMergeTree PRIMARY KEY metric_name ORDER BY (metric_name, id) SETTINGS allow_dimensions_outside_sorting_key = 1, index_granularity = 8192
METRICS INNER COLUMNS
(
    `metric_family_name` String,
    `type` LowCardinality(String),
    `unit` LowCardinality(String),
    `help` String
)
METRICS INNER ENGINE = ReplacingMergeTree ORDER BY metric_family_name

したがって、カラムは自動的に生成されており、INNER COLUMNS 句にはそれぞれ独自のカラム定義を持つ 3 つの内部ターゲットテーブルも格納されています。

内部ターゲットテーブルの名前は .inner_id.samples.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx、 .inner_id.tags.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx、.inner_id.metrics.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx のようになっており、各ターゲットテーブルはそれぞれ独自のカラムセットを持っています:

CREATE TABLE default.`.inner_id.samples.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`
(
    `id` Tuple(UInt64, UUID),
    `timestamp` DateTime64(3) CODEC(DoubleDelta, ZSTD(1)),
    `value` Float64 CODEC(ZSTD(3))
)
ENGINE = MergeTree
ORDER BY (id, timestamp)
SETTINGS index_granularity = 32768

CREATE TABLE default.`.inner_id.tags.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`
(
    `id` Tuple(UInt64, UUID) DEFAULT tuple(sipHash64(metric_name), reinterpretAsUUID(sipHash128(tags))),
    `metric_name` LowCardinality(String),
    `tags` Map(LowCardinality(String), String),
    `min_time` SimpleAggregateFunction(min, Nullable(DateTime64(3))),
    `max_time` SimpleAggregateFunction(max, Nullable(DateTime64(3)))
)
ENGINE = AggregatingMergeTree
PRIMARY KEY metric_name
ORDER BY (metric_name, id)
SETTINGS allow_dimensions_outside_sorting_key = 1, index_granularity = 8192

CREATE TABLE default.`.inner_id.metrics.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`
(
    `metric_family_name` String,
    `type` LowCardinality(String),
    `unit` LowCardinality(String),
    `help` String
)
ENGINE = ReplacingMergeTree
ORDER BY metric_family_name
SETTINGS index_granularity = 8192

既存のテーブルを AS で指定してテーブルを作成する

ステートメント CREATE TABLE new_table AS existing_table は、existing_table から以下をコピーします。

SETTINGS
kind ごとの INNER COLUMNS
kind ごとの INNER ENGINE

existing_table に外部ターゲットがある場合、このステートメントは使用できません。外側のカラム一覧はコピーされず、再生成されます。

カラム型の調整

INNER COLUMNS 句を使用すると、内部ターゲットテーブルのカラム型を調整できます。たとえば、timestamp をマイクロ秒単位で保存し、値を Float32 として保存するには、次のようにします。

CREATE TABLE my_table ENGINE=TimeSeries
SAMPLES INNER COLUMNS (timestamp DateTime64(6) CODEC(DoubleDelta, ZSTD(1)), value Float32 CODEC(ZSTD(3)))

内部カラムをコーデックなしで指定すると、デフォルトのコーデックが使用されます。

CREATE TABLE my_table ENGINE=TimeSeries
SAMPLES INNER COLUMNS (timestamp DateTime64(6), value Float32)

`id` カラム

id カラムには識別子が格納されており、各識別子はメトリクス名とタグの組み合わせごとに計算されます。識別子の生成に使用される型と DEFAULT 式は、TAGS INNER COLUMNS 句でカスタマイズできます。

CREATE TABLE my_table ENGINE=TimeSeries
TAGS INNER COLUMNS (id UInt64 DEFAULT sipHash64(tags))

id カラムには任意の比較可能な非 Nullable 型を使用できます。samples および tags の内部テーブルで宣言される id の型は一致している必要があります。

id カラムに DEFAULT 式が指定されておらず、かつ id_generator 設定がされていない場合、id の型が UUID、UInt64、UInt128、FixedString(16)、またはこれらの型のうち2つからなるタプルである場合に限り、ClickHouse は id の型に基づいて DEFAULT 式を自動的に選択します。このようなタプルでは、自動的に選択される式により、最初の部分でメトリクス名のハッシュが、2番目の部分ですべてのタグのハッシュが計算されます。

id_generator 設定では、INNER COLUMNS 句を使用せずに同じカスタマイズを行えます。

CREATE TABLE my_table ENGINE=TimeSeries
SETTINGS id_generator = 'sipHash64(tags)'

この設定が有効な場合、カラムのDEFAULTに別の式が含まれていても、idの生成にはこの設定が使用されます。

`tags` カラム

tags カラムには、メトリクス名を持つ __name__ タグを含む、時系列のすべてのタグが格納されます。

tags_to_columns 設定を使うと、特定のタグを tags カラム内のマップに加えて、個別のカラムにも格納するよう指定できます。

CREATE TABLE my_table
ENGINE = TimeSeries
SETTINGS tags_to_columns = {'instance': 'instance', 'job': 'job'}

このステートメントにより、内部の tags ターゲットテーブルに instance と job のカラムが追加されます。 instance と job のタグの値は、これらのカラムと tags カラムの両方に格納されます。

内部ターゲットテーブルのテーブルエンジン

デフォルトでは、内部ターゲットテーブルでは次のテーブルエンジンを使用します。

samples テーブルでは MergeTree を使用します。
tags テーブルでは AggregatingMergeTree を使用します。これは、同じデータがこのテーブルに複数回挿入されることが多いため、重複を除去する手段が必要であり、また、カラム min_time と max_time の集約にも必要だからです。
metrics テーブルでは ReplacingMergeTree を使用します。これは、同じデータがこのテーブルに複数回挿入されることが多いため、重複を除去する手段が必要だからです。

指定すれば、内部ターゲットテーブルで他のテーブルエンジンを使用することもできます。

CREATE TABLE my_table ENGINE=TimeSeries
SAMPLES ENGINE=ReplicatedMergeTree
TAGS ENGINE=ReplicatedAggregatingMergeTree
METRICS ENGINE=ReplicatedReplacingMergeTree

tags テーブルでは、タグのカラム (および tags の Map) を sorting key の外に保持します。これは AggregatingMergeTree ではデフォルトで拒否されます (allow_dimensions_outside_sorting_key を参照) 。ここでこれが安全なのは、これらのカラムが sorting key の一部である id に関数従属しているためであり、そのためバックグラウンド merge でまとめて統合されるすべての行は同じ値を共有します。上記のように内部 tags テーブルが生成される場合、またはそのエンジンがインラインで指定される場合、TimeSeries は自動的にそのテーブルに allow_dimensions_outside_sorting_key = 1 を設定します。手動で作成した外部の集約 tags テーブルでは、自分でこれを設定する必要があります。

外部ターゲットテーブル

TimeSeries テーブルでは、手動で作成したテーブルを使用することもできます:

CREATE TABLE samples_for_my_table
(
    `id` UUID,
    `timestamp` DateTime64(3),
    `value` Float64
)
ENGINE = MergeTree
ORDER BY (id, timestamp);

CREATE TABLE tags_for_my_table ...

CREATE TABLE metrics_for_my_table ...

CREATE TABLE my_table ENGINE=TimeSeries SAMPLES samples_for_my_table TAGS tags_for_my_table METRICS metrics_for_my_table;

外部テーブルのカラム型 (id、timestamp、value、および tags_to_columns に記載された <tag_value_column>) は、TimeSeries テーブルが通常内部的に生成する型と一致している必要があります (型の制約については、Samples テーブル、Tags テーブル、および Metrics テーブルを参照してください) 。型の不一致は CREATE 時に報告されます。

外部タグターゲットの id 生成式は、INSERT 時に次の順序で決定されます。まず id_generator 設定 (設定されている場合) 、次に外部テーブルの id カラムで宣言された DEFAULT (存在する場合) 、最後に id 型から導出される正規のジェネレーターです。したがって、この設定は外部テーブルで宣言された DEFAULT より優先されます。詳細は The id column を参照してください。

設定の変更

CREATE 実行後に変更できる設定は、次の 2 つです。

id_generator
filter_by_min_time_and_max_time

ALTER TABLE my_table MODIFY SETTING id_generator = 'sipHash64(tags)';
ALTER TABLE my_table MODIFY SETTING filter_by_min_time_and_max_time = 0;

データがすでに Tags テーブルに存在する状態で id_generator を変更すると、同じ metric+tag の組み合わせに対して異なる ID が生成される可能性がある点に注意してください。古い行は従来の ID のまま残り、新しい行では新しいジェネレーターが使用されます。

他の設定は、CREATE 時に内部テーブルのスキーマに組み込まれるため、ALTER ... MODIFY SETTING では変更できません。

設定

以下は、TimeSeries テーブルの定義時に指定できる設定の一覧です。

Name	Type	Default	Description
`id_generator`	Expression	`id` 型に依存	タグから時系列の識別子 (フィンガープリント) を計算する式です。未設定の場合は、`id` カラムのデフォルト式が使用されます。`id` カラムのデフォルト式も未設定であれば、式は自動的に選択されます
`tags_to_columns`	Map		tags テーブルで、どのタグを個別のカラムに格納するかを指定する Map。構文: `{'tag1': 'column1', 'tag2' : column2, ...}`
`use_all_tags_column_to_generate_id`	Bool	false	廃止された設定であり、何も行いません
`store_min_time_and_max_time`	Bool	true	true に設定すると、テーブルは各時系列の `min_time` と `max_time` を保存します
`aggregate_min_time_and_max_time`	Bool	true	内部ターゲット `tags` テーブルの作成時に、このフラグを有効にすると、`min_time` カラムの型として単なる `Nullable(DateTime64(3))` ではなく `SimpleAggregateFunction(min, Nullable(DateTime64(3)))` を使用し、`max_time` カラムにも同様に適用されます
`filter_by_min_time_and_max_time`	Bool	true	true に設定すると、テーブルは時系列のフィルタリングに `min_time` カラムと `max_time` カラムを使用します
`samples_index_granularity`	UInt64	32768	内部 samples テーブルの `index_granularity` を設定します。明示的に設定した場合、エンジン宣言の `index_granularity` をオーバーライドします。外部 samples テーブルおよび MergeTree 以外のエンジンでは無視されます
`tags_index_granularity`	UInt64	8192	内部 tags テーブルの `index_granularity` を設定します。明示的に設定した場合、エンジン宣言の `index_granularity` をオーバーライドします。外部 tags テーブルおよび MergeTree 以外のエンジンでは無視されます
`recent_samples_ttl_seconds`	UInt64	345600	挿入されたすべてのサンプルも書き込まれる追加の `recent samples` ターゲットテーブルの保持期間。内部 recent samples テーブルには、この設定に基づいて常に `TTL toDateTime(timestamp) + toIntervalSecond(recent_samples_ttl_seconds)` が設定されます (エンジン宣言の TTL はオーバーライドされます) 。外部 recent samples テーブルでは、少なくともこの秒数分のデータを保持する必要があります。時間範囲が TTL ウィンドウ内に収まるクエリでは、メインの samples テーブルより recent samples テーブルが優先されます (クエリレベルの設定 `time_series_prefer_recent_samples_table` を参照) 。デフォルトは 4 日です。有効な値は CREATE 時にテーブル定義に固定されます。recent samples テーブルを無効にするには 0 に設定します
`recent_samples_partition_by`	Expression	`toStartOfInterval(toDateTime(timestamp), toIntervalHour(5))`	内部 `recent samples` テーブルのパーティションキー。例: `toStartOfHour(timestamp)`。`recent_samples_ttl_seconds` は 0 以外である必要があります
`recent_samples_index_granularity`	UInt64	8192	内部 `recent samples` テーブルの `index_granularity` を設定します。`recent_samples_ttl_seconds` は 0 以外である必要があります

関数

以下は、TimeSeries テーブルを引数としてサポートする関数の一覧です。