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

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

これは実験的な機能であり、今後のリリースで後方互換性のない変更が行われる可能性があります。 allow_experimental_time_series_table 設定で TimeSeries テーブルエンジンの使用を有効にします。 set allow_experimental_time_series_table = 1 コマンドを実行します。

構文

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)]]

キーワード SAMPLES には、後方互換性のために DATA というエイリアスが残されています。

使い方

まずは、すべてデフォルト設定のままで始めるのが簡単です (カラムの一覧を指定しなくても 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(Tuple(DateTime64(3), Float64)) 型をオーバーライドするために、CREATE TABLE ステートメントで明示的に指定できます。ClickHouse はその Tuple から 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, value Float32)

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

ターゲットテーブル

TimeSeries テーブル自体はデータを持たず、すべてのデータはそのターゲットテーブルに格納されます。これは materialized view の仕組みに似ていますが、 materialized view ではターゲットテーブルは 1 つであるのに対し、 TimeSeries テーブルには samples、tags、metrics という 3 つのターゲットテーブルがあります。ターゲットテーブルは CREATE TABLE クエリで明示的に指定することもできますし、 TimeSeries テーブルエンジンが内部ターゲットテーブルを自動生成することもできます。 TimeSeries テーブルに挿入された行は変換され、ブロックに分割されたうえで、これら 3 つのターゲットテーブルに挿入されます。ターゲットテーブルは次のとおりです:

samples テーブル

samples テーブルには、識別子に関連付けられた時系列が格納されます。 samples テーブルには、次のカラムが必要です。

Name	Mandatory?	Default type	Possible types	Description
`id`	[x]	`UUID`	any	メトリクス名とタグの組み合わせを識別します
`timestamp`	[x]	`DateTime64(3)`	`DateTime64(X)`	時点
`value`	[x]	`Float64`	`Float32` or `Float64`	`timestamp` に対応する値

Tags テーブル

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

名前	必須?	デフォルト型	使用可能な型	説明
`id`	[x]	`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 設定で列挙された名前のタグを除外したタグのマップ
`all_tags`	[ ]	`Map(String, String)`	`Map(String, String)` または `Map(LowCardinality(String), String)` または `Map(LowCardinality(String), LowCardinality(String))`	一時的なカラムで、各行にはメトリクス名を含むタグ `__name__` のみを除外したすべてのタグのマップが入ります。このカラムの唯一の用途は、`id` の計算時に使用することです
`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` UUID,
    `timestamp` DateTime64(3),
    `value` Float64
)
SAMPLES INNER ENGINE = MergeTree ORDER BY (id, timestamp)
TAGS INNER COLUMNS
(
    `id` UUID DEFAULT reinterpretAsUUID(sipHash128(metric_name, all_tags)),
    `metric_name` LowCardinality(String),
    `tags` Map(LowCardinality(String), String),
    `all_tags` Map(String, String) EPHEMERAL,
    `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)
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` UUID,
    `timestamp` DateTime64(3),
    `value` Float64
)
ENGINE = MergeTree
ORDER BY (id, timestamp)

CREATE TABLE default.`.inner_id.tags.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`
(
    `id` UUID DEFAULT reinterpretAsUUID(sipHash128(metric_name, all_tags)),
    `metric_name` LowCardinality(String),
    `tags` Map(LowCardinality(String), String),
    `all_tags` Map(String, String) EPHEMERAL,
    `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)

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

既存のテーブルを 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), value Float32)

同じ句を使って、コーデックやその他のカラム属性を指定できます。

CREATE TABLE my_table ENGINE=TimeSeries
SAMPLES INNER COLUMNS (timestamp DateTime64(3) CODEC(DoubleDelta))

`id` カラム

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

CREATE TABLE my_table ENGINE=TimeSeries
TAGS INNER COLUMNS (id UInt64 DEFAULT sipHash64(metric_name, all_tags))

id カラムの型は、UUID、UInt64、UInt128、または FixedString(16) のいずれかである必要があります。DEFAULT 式が指定されていない場合、ClickHouse は id の型に基づいて自動的に選択します。samples および tags の内部テーブルで宣言される id の型は一致している必要があります。 id_generator 設定では、INNER COLUMNS 句を使用せずに同じカスタマイズを行えます。

CREATE TABLE my_table ENGINE=TimeSeries
SETTINGS id_generator = 'sipHash64(metric_name, all_tags)'

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

`tags` と `all_tags` カラム

タグのマップを含むカラムは tags と all_tags の 2 つあります。この例では両者は同じ意味ですが、tags_to_columns 設定を使用している場合は異なることがあります。この設定を使うと、特定のタグを tags カラム内のマップに格納する代わりに、個別のカラムに格納するよう指定できます。

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

このステートメントにより、内部の tags ターゲットテーブルに instance と job のカラムが追加されます。この場合、tags カラムには instance と job のタグは含まれませんが、 all_tags カラムにはそれらが含まれます。all_tags カラムは一時的なもので、唯一の目的は id カラムの DEFAULT 式で使用することです。

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

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

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

外部ターゲットテーブル

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(metric_name, all_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	true	時系列の識別子を計算する式を生成する際、このフラグを有効にすると、その計算に `all_tags` カラムを使用します
`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` カラムを使用します

関数

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

​構文

​使い方

​外部カラム

​外部カラムの指定

​ターゲットテーブル

​samples テーブル

​Tags テーブル

​Metrics テーブル

​作成

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

​カラム型の調整

​id カラム

​tags と all_tags カラム

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

​外部ターゲットテーブル

​設定の変更

​設定

​関数

構文

使い方

外部カラム

外部カラムの指定

ターゲットテーブル

samples テーブル

Tags テーブル

Metrics テーブル

作成

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

カラム型の調整

`id` カラム

`tags` と `all_tags` カラム

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

外部ターゲットテーブル

設定の変更

設定

関数