これはプライベートプレビュー機能であり、今後のリリースで後方互換性のない変更が行われる可能性があります。
enable_time_series_table 設定で
TimeSeries テーブルエンジン の使用を有効にします。
set enable_time_series_table = 1 コマンドを実行します。TimeSeries テーブルエンジンは ClickHouse Cloud でプライベートプレビュー機能として利用できます。
プライベートプレビューに参加しているサービスでは、すでに
enable_time_series_table 設定が構成されています。その他の ClickHouse Cloud サービス
ではこの構成は行われておらず、そのようなサービスでご自身でこのエンジンを有効にすることはできません。構文
キーワード
SAMPLES には DATA というエイリアスがあり、キーワード METRIC FAMILIES には METRICS というエイリアスがあります。いずれも後方互換性のために残されています。
バージョン 4 より前のバージョンのテーブル定義は METRICS を用いて書き込まれるため、古いサーバーでも読み取ることができます。使い方
まずは、すべてデフォルト設定のままで始めるのが簡単です (カラムの一覧を指定しなくてもTimeSeries テーブルを作成できます) :
外部カラム
TimeSeries テーブルのカラムは自動的に自動生成されます。これらは外部カラムであり、データ自体は保持せず、SELECT/INSERT のためのインターフェイスだけを提供します。実際のデータはターゲットテーブルに格納されます。外部カラムの一覧は次のとおりです。
例:
metric_name は挿入時に空でもかまいません。つまり、メトリクス名は tags 内の __name__ に指定されます。たとえば次のとおりです:
metric_family、type、unit、help の各カラムに値を挿入します：
外部カラムの指定
外部samples カラムは、デフォルトの Array(タプル(DateTime64(3), Float64)) 型をオーバーライドするために、CREATE TABLE ステートメントで明示的に指定できます (旧名称の time_series も使用できます) 。ClickHouse はその タプル から timestamp 型と scalar 型を抽出し、それらを内部の Samples テーブルに反映します：
INNER COLUMNS 句で timestamp と値のカラム型を直接宣言するのと同じです:
CREATE TABLE ステートメント内で使用する場合、宣言する型は一致していなければなりません。
ターゲットテーブル
TimeSeries テーブル自体はデータを持たず、すべてのデータはそのターゲットテーブルに格納されます。
これは materialized view の仕組みに似ていますが、
materialized view ではターゲットテーブルは 1 つであるのに対し、
TimeSeries テーブルには samples、tags、metric families という 3 つの必須のターゲットテーブルと、
デフォルトで有効になっている任意の recent samples ターゲットテーブルがあります
(recent_samples_ttl_seconds 設定を参照してください) 。
ターゲットテーブルは CREATE TABLE クエリで明示的に指定することもできますし、
TimeSeries テーブルエンジンが内部ターゲットテーブルを自動生成することもできます。
TimeSeries テーブルに挿入された行は変換され、ブロックに分割されたうえで、これらのターゲットテーブルに挿入されます。
ターゲットテーブルは次のとおりです:
samples テーブル
samples テーブルには、識別子に関連付けられた時系列が格納されます。 samples テーブルには、次のカラムが必要です。
エンジンが自動作成するカラムには、時系列圧縮コーデックが設定されます。
timestamp CODEC(Delta, T64, ZSTD(3)) および value CODEC(ALP, ZSTD(3))。ほぼ単調なタイムスタンプは汎用コーデックではほとんど
圧縮されず、samples テーブルのディスク上のサイズの大部分を占める可能性があります。
エンジンは、内部の samples テーブルおよび recent samples テーブルに対して、enable_alp_codec を設定しなくても ALP を有効にします。
カラムの型の調整も参照してください。
Recent samples テーブル
recent samples テーブルは任意であり、デフォルトで有効になっています (recent_samples_ttl_seconds 設定を参照してください。この値をゼロに設定するとテーブルは無効になります) 。このテーブルには、当該設定で定義された有効期限 (TTL) より新しいサンプルのコピーが格納され、samples テーブルと同じカラムを持つ必要があります。 生成されたtimestamp カラムには CODEC(Delta, T64, ZSTD(3)) が使用され、
生成された value カラムには CODEC(ALP, ZSTD(3)) が使用されます。
挿入されたサンプルはすべて、samples テーブルと recent samples テーブルの両方に書き込まれます。
時間範囲が TTL の期間内に収まるクエリは、メインの samples テーブルではなく recent samples テーブルから読み取ります。recent samples テーブルの方がはるかに小さいためです (この動作はクエリレベルの設定 time_series_prefer_recent_samples_table で無効化できます) 。
内部の recent samples テーブルの有効期限 (TTL) は、常に recent_samples_ttl_seconds 設定から導出されます。
Tags テーブル
tags テーブルには、メトリクス名とタグの各組み合わせに対して計算された識別子が格納されます。 tags テーブルには、次のカラムが必要です。
バージョン 5 以降で新しく作成され、
MergeTree ファミリーのエンジンを使用する内部 tags テーブルには、tags に対する転置テキスト索引が作成されます:
INDEX tags_idx tags TYPE text(tokenizer = 'keyValuePairs')。これは、キーと値をまとめて検索することで、PromQL における
{job="api"} のような完全一致のラベル照合を高速化します。空文字列との比較は欠落しているラベルにも
一致するため、この索引は使用されません。
TAGS INNER COLUMNS で明示的に宣言された索引は、デフォルトの索引を置き換えます。既存のテーブルおよび外部の
tags テーブルは、それぞれの索引をそのまま保持します。有効にするには、その tags ターゲットテーブルに索引を追加してマテリアライズしてください。
Metric families テーブル
metric families テーブルには、収集されるメトリクスファミリーに関する情報、それらのメトリクスファミリーのタイプ、および説明が格納されます。 メトリクスファミリーとは、同じ名前 (__name__ タグ) と同じタイプを持つメトリクスのグループであり、例えば histogram は複数のメトリクスから構成されるメトリクスファミリーです。
metric families テーブルには、次のカラムが必要です。
作成
TimeSeries テーブルエンジンを使用してテーブルを作成する方法は複数あります。
最もシンプルなステートメントは次のとおりです
SHOW CREATE TABLE my_table を実行すると確認できます) :
INNER COLUMNS 句に格納された独自のカラム定義を持つ4つの内部ターゲットテーブルも存在します。recent_samples_ttl_seconds 設定はデフォルト値のまま SETTINGS 句に書き込まれています。この設定は recent samples テーブルの TTL を定義するため、その実効値は作成時に固定されます。また、最新のスキーマバージョンが version 設定に固定されています (スキーマのバージョン管理 を参照) 。
内部ターゲットテーブルには .inner_id.samples.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx、
.inner_id.recentsamples.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx、.inner_id.tags.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx、
.inner_id.metricfamilies.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
のような名前が付けられており、各ターゲットテーブルはそれぞれ固有のカラム構成を持ちます:
既存テーブルを AS 指定してテーブルを作成する
ステートメントCREATE TABLE new_table AS existing_table は、existing_table と同じ構成の TimeSeries テーブルを作成します。
existing_table は TimeSeries テーブルである必要があります。existing_table の外部ターゲットはコピーされないため、ステートメントで
それらのターゲットを明示的に宣言する必要があります。
このステートメントは existing_table から次の内容をコピーします。
versionを除くSETTINGS句。新しいテーブルには常に最新バージョンが設定されます。ステートメント自体に記述された設定 は、名前に基づいてコピーされた設定とマージされるため、記述された設定がコピーされた設定より優先されます。また、name = DEFAULTはコピーされた設定をデフォルト値にリセットします。- 各内部テーブルの
INNER COLUMNS句およびINNER ENGINE句。カスタマイズされたカラム (例: 追加カラム、codec または DEFAULT 式を 持つカラム) とカスタマイズされたエンジン部分 (例: 引数を持つエンジン、カスタムソートキー またはエンジン設定) は保持されます。それ以外のカラムとエンジン部分は新しいテーブルの設定に合わせて調整されるため、 例えばステートメントに記述されたtags_to_columns、aggregate_min_time_and_max_time、tags_index_granularityが有効になります。
id、timestamp、値のカラムの型、および内部エンジンのレプリケーション種別 (MergeTree、
ReplicatedMergeTree、または SharedMergeTree) も、ステートメントで明示的に宣言しない限り existing_table から取得されます。
外部カラムリストは再生成され、コピーされません。
古いバージョンの ClickHouse で作成されたテーブルも existing_table として使用できます。新しいテーブルには現在の
構造、たとえば現在の id 型やデフォルトの識別子式が設定されます。
カラム型の調整
INNER COLUMNS 句を使用すると、内部ターゲットテーブルのカラム型を調整できます。たとえば、timestamp をマイクロ秒単位で保存し、値を Float32 として保存するには、次のようにします。
id カラム
id カラムには識別子が格納されており、各識別子はメトリクス名とタグの組み合わせごとに計算されます。
識別子の生成に使用される型と DEFAULT 式は、TAGS INNER COLUMNS 句でカスタマイズできます。
id カラムには任意の比較可能な非 Nullable 型を使用できます。samples および tags の内部テーブルで宣言される id の型は一致している必要があります。
id カラムに DEFAULT 式が指定されておらず、かつ id_generator SETTINGがされていない場合、id の型が UUID、UInt64、UInt128、FixedString(16)、これらと同じ型を LowCardinality でラップしたもの、またはこれらの型のうち2つからなるタプルである場合に限り、ClickHouse は id の型に基づいて DEFAULT 式を自動的に選択します。このようなタプルでは、自動的に選択される式により、最初の部分でメトリクス名のハッシュが、2番目の部分ですべてのタグのハッシュが計算されます。
Tuple(UInt64, LowCardinality(UUID)) のような LowCardinality の識別子型を使用すると、識別子は辞書エンコードされた状態で保持されます。Samples テーブルは、すべての行に完全な識別子を繰り返して格納する代わりに、ブロックごとの小さな辞書と辞書索引を格納するため、クエリが読み取るデータ量が削減されます。
id_generator SETTINGでは、INNER COLUMNS 句を使用せずに同じカスタマイズを行えます。
DEFAULTに別の式が含まれていても、idの生成にはこのSETTINGが使用されます。
id カラムの型は、INNER COLUMNS 句の代わりに id_type SETTINGで指定することもできます。
id_generator SETTINGが指定されている場合、id_type SETTINGは CREATE 時に自動的に記録されるため、その式が想定して記述された型が定義に保持されます。
tags カラム
tags カラムには、メトリクス名を持つ __name__ タグを含む、時系列のすべてのタグが格納されます。
tags_to_columns 設定を使うと、特定のタグを tags カラム内のマップに加えて、個別のカラムにも格納するよう指定できます。
instance と job のカラムが追加されます。
instance と job のタグの値は、これらのカラムと tags カラムの両方に格納されます。
古いバージョンの ClickHouse で作成されたテーブルでは、
tags カラムには専用のカラムを持たないタグのみが含まれ、メトリクス名は含まれません。また、all_tags カラムは一時的なカラムであり、INSERT 時にメトリクス名以外のすべてのタグで補完されます。内部ターゲットテーブルのテーブルエンジン
デフォルトでは、内部ターゲットテーブルでは次のテーブルエンジンを使用します。- samples テーブルでは MergeTree を使用します。
- recent samples テーブルでは、5 時間単位の bucket でパーティション化された (recent_samples_partition_by 設定を参照) MergeTree を使用します。この際、recent_samples_ttl_seconds 設定から導出された
TTLが設定され、ttl_only_drop_partsが有効になっているため、期限切れのパーツはまとめて drop されます。 - tags テーブルでは AggregatingMergeTree を使用します。これは、同じデータがこのテーブルに複数回挿入されることが多いため、重複を除去する手段が必要であり、
また、カラム
min_timeとmax_timeの集約にも必要だからです。 - metric families テーブルでは ReplacingMergeTree を使用します。これは、同じデータがこのテーブルに複数回挿入されることが多いため、重複を除去する手段が必要だからです。
default_table_engine に従います。
default_table_engine = ReplicatedMergeTree または SharedMergeTree の場合、内部テーブルは対応する
Replicated または Shared エンジンを使用します。default_table_engine = None (またはその他の値) の場合、内部テーブルのエンジンは
明示的に指定する必要があります。
すべての内部テーブルは同じレプリケーション種別でなければなりません。いずれか 1 つが replicated (または shared) である場合、他の内部
テーブルも replicated (または shared) でなければなりません。そうでなければ、レプリカ間でその内容が乖離してしまいます。たとえば、
SAMPLES INNER ENGINE = ReplicatedMergeTree(...) を宣言する場合、他の内部エンジンも replicated である必要があります。
明示的に宣言するか、default_table_engine = ReplicatedMergeTree で生成するかのいずれかです。
指定すれば、内部ターゲットテーブルで他のテーブルエンジンを使用することもできます。
tags の Map) を sorting key の外に保持します。
これは AggregatingMergeTree ではデフォルトで拒否されます (allow_dimensions_outside_sorting_key を参照) 。
ここでこれが安全なのは、これらのカラムが sorting key の一部である id に関数従属しているためであり、そのため
バックグラウンド merge でまとめて統合されるすべての行は同じ値を共有します。上記のように内部 tags テーブルが生成される場合、またはその
エンジンがインラインで指定される場合、TimeSeries は自動的にそのテーブルに allow_dimensions_outside_sorting_key = 1 を設定します。
手動で作成した外部の集約 tags テーブルでは、自分でこれを設定する必要があります。
外部ターゲットテーブル
TimeSeries テーブルでは、手動で作成したテーブルを使用することもできます:
RECENT SAMPLES my_recent_samples_table 句) としても使用できます。
そのようなテーブルは外部 samples テーブルと同じカラムを持つ必要があり、少なくとも
recent_samples_ttl_seconds 秒分のデータを保持しなければなりません。これはユーザーの責任です。
外部テーブルのカラム型 (id、timestamp、value、および tags_to_columns に記載された <tag_value_column>) は、TimeSeries テーブルが通常内部的に生成する型と一致している必要があります (型の制約については、Samples テーブル、Tags テーブル、および Metric families テーブル を参照してください) 。型の不一致は CREATE 時に報告されます。
外部 tags テーブルの id カラムの型と、識別子を生成する式は、CREATE 時に id_type および id_generator 設定に記録されます (バージョン 2 以降) 。そのため TimeSeries テーブルの定義がそれらを保持します。たとえば CREATE TABLE ... AS my_table では、外部ターゲットテーブルを読み取ることなく my_table の定義から id 型を読み取ります。id_generator 設定が指定されていない場合は、外部テーブルの id カラムで宣言された DEFAULT (存在する場合) が設定され、それがなければ id 型から導出される正規のジェネレーターが設定されます。記録された式は、後で外部テーブルの DEFAULT が変更された場合でも id の生成に使用されます。詳細は The id column を参照してください。
設定の変更
CREATE 実行後に変更できる設定は、次の 2 つです。
id_generatorfilter_by_min_time_and_max_time
id_generator を変更すると、同じメトリクス+タグ の組み合わせに対して異なる ID が生成される可能性がある点に注意してください。古い行は従来の ID のまま残り、新しい行では新しいジェネレーターが使用されます。
他の設定は、ALTER ... MODIFY SETTING では変更できません。大半は CREATE 時に内部テーブルのスキーマに組み込まれ、
version 設定は CREATE 時に自動的に固定され、スキーマ自体を識別します (スキーマのバージョニング を参照) 。
SETTING
以下は、TimeSeries テーブルの定義時に指定できるSETTINGの一覧です。
スキーマのバージョン管理
TimeSeries テーブルエンジンと PromQL 実行レイヤーは現在も活発に開発されています。
そのため、ターゲットテーブルのセットや構造は ClickHouse のバージョン間で変更される可能性があります。
このような変更を検出できるよう、各 TimeSeries テーブルでは version SETTINGにバージョンを保存します。
テーブル作成時には、バージョンが CREATE クエリに自動的に固定されます。その値はサーバーが認識している最新バージョン (現在は 5) であり、
テーブルのメタデータに永続化され、ALTER では変更できません。このSETTINGの導入前に作成されたテーブルは、バージョン 0 と見なされます。
通常、このSETTINGは CREATE TABLE クエリで省略します。省略した場合、テーブルには最新バージョンが設定されます。
サーバーがそのバージョンをサポートしている場合は、明示的な version も指定できます。その場合、テーブルはそのバージョンの定義方法に従って定義されます (バージョン履歴を参照)。
CREATE TABLE ... AS other_table は別のテーブルのバージョンをコピーしません。詳細は既存テーブルを AS 指定してテーブルを作成するを参照してください。
サーバーは一定範囲のバージョンをサポートしており、最小バージョンは、SELECT による読み取り、INSERT による書き込み、
Prometheus remote-write プロトコル、PromQL の評価 (prometheusQuery、
prometheusQueryRange、
timeSeriesSelector テーブル関数、
promql 方言、Prometheus HTTP クエリ API) によって異なる場合があります。
TimeSeriesテーブルのバージョンが PromQL には古すぎる場合、そのテーブルに対する PromQL クエリは拒否されます。例外メッセージではテーブルを再作成するよう案内されます。 新しいTimeSeriesテーブルを作成し、INSERT ... SELECTクエリでデータをコピーしてから、古いテーブルを新しいテーブルに置き換えます。- バージョンが書き込みには古すぎる場合、
INSERTクエリと Prometheus remote-write プロトコルは拒否されますが、SELECTクエリは引き続き機能します。 - バージョンがサーバーでまったくサポートされないほど古い場合、テーブルに対するすべてのクエリ (
SHOW CREATE TABLE、DETACH、DROPを除く) が拒否されます。
バージョン履歴
関数
以下は、TimeSeries テーブルを引数としてサポートする関数の一覧です。