> ## Documentation Index > Fetch the complete documentation index at: https://private-7c7dfe99-revert-104359-revert-104251-parquet-single.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. > 時系列、つまりタイムスタンプとタグ（またはラベル）に関連付けられた値の集合を格納するテーブルエンジン。 # TimeSeries テーブルエンジン export const CloudNotSupportedBadge = () => { return
ClickHouse Cloud ではサポートされていません ; }; export const ExperimentalBadge = () => { return
実験的な機能 ; }; 時系列、つまりタイムスタンプとタグ (またはラベル) に関連付けられた値の集合を格納するテーブルエンジン: ```sql theme={null} metric_name1[tag1=value1, tag2=value2, ...] = {timestamp1: value1, timestamp2: value2, ...} metric_name2[...] = ... ``` これは実験的な機能であり、今後のリリースで後方互換性のない変更が行われる可能性があります。 [allow\_experimental\_time\_series\_table](/ja/reference/settings/session-settings/allow-experimental#allow_experimental_time_series_table) 設定で TimeSeries テーブルエンジン の使用を有効にします。 `set allow_experimental_time_series_table = 1` コマンドを実行します。
## 構文
```sql theme={null} 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` テーブルを作成できます) : ```sql theme={null} CREATE TABLE my_table ENGINE=TimeSeries ``` このテーブルは、以下のプロトコルで使用できます (サーバー設定でポートを割り当てる必要があります) : * [prometheus remote-write](/ja/concepts/features/interfaces/prometheus#remote-write) * [prometheus remote-read](/ja/concepts/features/interfaces/prometheus#remote-read)
### 外部カラム
TimeSeries テーブルのカラムは自動的に自動生成されます。これらは外部カラムであり、データ自体は保持せず、`SELECT`/`INSERT` のためのインターフェイスだけを提供します。実際のデータは[ターゲットテーブル](#target-tables)に格納されます。外部カラムの一覧は次のとおりです。 | 名前 | 型 | 説明 | | --------------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | `metric_name` | `String` | メトリクスの名前 | | `tags` | `Map(String, String)` | 時系列のタグ (ラベル) のマップ | | `time_series` | 既定では `Array(Tuple(DateTime64(3), Float64))` | 時系列の `(timestamp, value)` ペアの Array。タプルの timestamp と scalar 要素の型は、samples の `INNER COLUMNS` 宣言から導出できます ([外部カラムの指定](#specifying-outer-columns)を参照) | | `metric_family` | `String` | メトリクスファミリーの名前 (メトリクスのメタデータ用) | | `type` | `String` | メトリクスの型 (例: "counter"、"gauge") | | `unit` | `String` | メトリクスの単位 | | `help` | `String` | メトリクスの説明 | 例: ```sql theme={null} 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__` に指定されます。たとえば次のとおりです: ```sql theme={null} 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` の各カラムに値を挿入します： ```sql theme={null} 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 テーブルに反映します： ```sql theme={null} CREATE TABLE my_table (time_series Array(Tuple(UInt32, Float32))) ENGINE=TimeSeries ``` これは、samples の `INNER COLUMNS` 句で timestamp と値のカラム型を直接宣言するのと同じです: ```sql theme={null} CREATE TABLE my_table ENGINE=TimeSeries SAMPLES INNER COLUMNS (timestamp UInt32 CODEC(DoubleDelta, ZSTD(1)), value Float32 CODEC(Gorilla, ZSTD(1))) ``` 両方の形式を同じ `CREATE TABLE` ステートメント内で使用する場合、宣言する型は一致していなければなりません。
## ターゲットテーブル
`TimeSeries` テーブル自体はデータを持たず、すべてのデータはそのターゲットテーブルに格納されます。 これは [materialized view](/ja/reference/statements/create/view#materialized-view) の仕組みに似ていますが、 materialized view ではターゲットテーブルは 1 つであるのに対し、 `TimeSeries` テーブルには [samples](#samples-table)、[tags](#tags-table)、[metrics](#metrics-table) という 3 つのターゲットテーブルがあります。 ターゲットテーブルは `CREATE TABLE` クエリで明示的に指定することもできますし、 `TimeSeries` テーブルエンジンが内部ターゲットテーブルを自動生成することもできます。 `TimeSeries` テーブルに挿入された行は変換され、ブロックに分割されたうえで、これら 3 つのターゲットテーブルに挿入されます。 ターゲットテーブルは次のとおりです:
### samples テーブル
*samples* テーブルには、識別子に関連付けられた時系列が格納されます。 *samples* テーブルには、次のカラムが必要です。 | Name | Mandatory? | Default type | Possible types | 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(Gorilla, ZSTD(1))`。ほぼ単調なタイムスタンプは汎用コーデックではほとんど 圧縮されず、samples テーブルのディスク上のサイズの大部分を占める可能性があります。 [カラムの型の調整](#adjusting-column-types)も参照してください。
### Tags テーブル
*tags* テーブルには、メトリクス名とタグの各組み合わせに対して計算された識別子が格納されます。 *tags* テーブルには、次のカラムが必要です。 | 名前 | 必須? | デフォルト型 | 使用可能な型 | 説明 | | -------------------- | ---- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | \[x] | `Tuple(UInt64, UUID)` | 任意 ([samples](#samples-table) テーブルの `id` の型と一致している必要があります) | `id` は、メトリクス名とタグの組み合わせを識別します。DEFAULT 式は、この識別子の計算方法を指定します | | `metric_name` | \[x] | `LowCardinality(String)` | `String` または `LowCardinality(String)` | メトリクス名 | | `` | \[ ] | `String` | `String` または `LowCardinality(String)` または `LowCardinality(Nullable(String))` | 特定のタグの値。タグ名と対応するカラム名は、[tags\_to\_columns](#settings) 設定で指定します | | `tags` | \[x] | `Map(LowCardinality(String), String)` | `Map(String, String)` または `Map(LowCardinality(String), String)` または `Map(LowCardinality(String), LowCardinality(String))` | メトリクス名を含むタグ `__name__` および [tags\_to\_columns](#settings) 設定で列挙された名前のタグを含む、すべてのタグのマップ。古いバージョンの ClickHouse で作成されたテーブルでは、このカラムには専用カラムを持たずメトリクス名も含まないタグのみが格納されていました。読み取り時にはどちらの場合も処理されます | | `min_time` | \[ ] | `Nullable(DateTime64(3))` | `DateTime64(X)` または `Nullable(DateTime64(X))` | その `id` を持つ時系列の最小タイムスタンプ。このカラムは [store\_min\_time\_and\_max\_time](#settings) が `true` の場合に作成されます | | `max_time` | \[ ] | `Nullable(DateTime64(3))` | `DateTime64(X)` または `Nullable(DateTime64(X))` | その `id` を持つ時系列の最大タイムスタンプ。このカラムは [store\_min\_time\_and\_max\_time](#settings) が `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` テーブルエンジンを使ってテーブルを作成する方法はいくつかあります。 最も簡単なステートメントは ```sql theme={null} CREATE TABLE my_table ENGINE=TimeSeries ``` 実際には、次のテーブルが作成されます (`SHOW CREATE TABLE my_table` を実行すると確認できます) : ```sql theme={null} 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(Gorilla, ZSTD(1)) ) 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` のようになっており、各ターゲットテーブルはそれぞれ独自のカラムセットを持っています: ```sql theme={null} 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(Gorilla(8), ZSTD(1)) ) ENGINE = MergeTree ORDER BY (id, timestamp) SETTINGS index_granularity = 32768 ``` ```sql theme={null} 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 ``` ```sql theme={null} 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` として保存するには、次のようにします。 ```sql theme={null} CREATE TABLE my_table ENGINE=TimeSeries SAMPLES INNER COLUMNS (timestamp DateTime64(6) CODEC(DoubleDelta, ZSTD(1)), value Float32 CODEC(Gorilla, ZSTD(1))) ``` 内部カラムをコーデックなしで指定すると、デフォルトのコーデックが使用されます。 ```sql theme={null} CREATE TABLE my_table ENGINE=TimeSeries SAMPLES INNER COLUMNS (timestamp DateTime64(6), value Float32) ```
## `id` カラム
`id` カラムには識別子が格納されており、各識別子はメトリクス名とタグの組み合わせごとに計算されます。 識別子の生成に使用される型と `DEFAULT` 式は、`TAGS INNER COLUMNS` 句でカスタマイズできます。 ```sql theme={null} 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` 句を使用せずに同じカスタマイズを行えます。 ```sql theme={null} CREATE TABLE my_table ENGINE=TimeSeries SETTINGS id_generator = 'sipHash64(tags)' ``` この設定が有効な場合、カラムの`DEFAULT`に別の式が含まれていても、`id`の生成にはこの設定が使用されます。
## `tags` カラム
`tags` カラムには、メトリクス名を持つ `__name__` タグを含む、時系列のすべてのタグが格納されます。 `tags_to_columns` 設定を使うと、特定のタグを `tags` カラム内のマップに加えて、個別のカラムにも格納するよう指定できます。 ```sql theme={null} CREATE TABLE my_table ENGINE = TimeSeries SETTINGS tags_to_columns = {'instance': 'instance', 'job': 'job'} ``` このステートメントにより、内部の [tags](#tags-table) ターゲットテーブルに `instance` と `job` のカラムが追加されます。 `instance` と `job` のタグの値は、これらのカラムと `tags` カラムの両方に格納されます。 古いバージョンの ClickHouse で作成されたテーブルでは、`tags` カラムには専用のカラムを持たないタグのみが含まれ、メトリクス名は含まれません。また、`all_tags` カラムは一時的なカラムであり、INSERT 時にメトリクス名以外のすべてのタグで補完されます。
## 内部ターゲットテーブルのテーブルエンジン
デフォルトでは、内部ターゲットテーブルでは次のテーブルエンジンを使用します。 * [samples](#samples-table) テーブルでは [MergeTree](/ja/reference/engines/table-engines/mergetree-family/mergetree) を使用します。 * [tags](#tags-table) テーブルでは [AggregatingMergeTree](/ja/reference/engines/table-engines/mergetree-family/aggregatingmergetree) を使用します。これは、同じデータがこのテーブルに複数回挿入されることが多いため、重複を除去する手段が必要であり、 また、カラム `min_time` と `max_time` の集約にも必要だからです。 * [metrics](#metrics-table) テーブルでは [ReplacingMergeTree](/ja/reference/engines/table-engines/mergetree-family/replacingmergetree) を使用します。これは、同じデータがこのテーブルに複数回挿入されることが多いため、重複を除去する手段が必要だからです。 指定すれば、内部ターゲットテーブルで他のテーブルエンジンを使用することもできます。 ```sql theme={null} CREATE TABLE my_table ENGINE=TimeSeries SAMPLES ENGINE=ReplicatedMergeTree TAGS ENGINE=ReplicatedAggregatingMergeTree METRICS ENGINE=ReplicatedReplacingMergeTree ``` [tags](#tags-table) テーブルでは、タグのカラム (および `tags` の Map) を sorting key の外に保持します。 これは `AggregatingMergeTree` ではデフォルトで拒否されます ([`allow_dimensions_outside_sorting_key`](/ja/reference/engines/table-engines/mergetree-family/aggregatingmergetree) を参照) 。 ここでこれが安全なのは、これらのカラムが sorting key の一部である `id` に関数従属しているためであり、そのため バックグラウンド merge でまとめて統合されるすべての行は同じ値を共有します。上記のように内部 tags テーブルが生成される場合、またはその エンジンがインラインで指定される場合、`TimeSeries` は自動的にそのテーブルに `allow_dimensions_outside_sorting_key = 1` を設定します。 手動で作成した[外部](#external-target-tables)の集約 tags テーブルでは、自分でこれを設定する必要があります。
## 外部ターゲットテーブル
`TimeSeries` テーブルでは、手動で作成したテーブルを使用することもできます: ```sql theme={null} 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`](#settings) に記載された ``) は、`TimeSeries` テーブルが通常内部的に生成する型と一致している必要があります (型の制約については、[Samples テーブル](#samples-table)、[Tags テーブル](#tags-table)、および [Metrics テーブル](#metrics-table) を参照してください) 。型の不一致は `CREATE` 時に報告されます。 外部タグターゲットの id 生成式は、INSERT 時に次の順序で決定されます。まず [`id_generator`](#settings) 設定 (設定されている場合) 、次に外部テーブルの `id` カラムで宣言された `DEFAULT` (存在する場合) 、最後に `id` 型から導出される正規のジェネレーターです。したがって、この設定は外部テーブルで宣言された `DEFAULT` より優先されます。詳細は [The `id` column](#id-column) を参照してください。
## 設定の変更
`CREATE` 実行後に変更できる設定は、次の 2 つです。 * `id_generator` * `filter_by_min_time_and_max_time` ```sql theme={null} 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](#tags-table) テーブルで、どのタグを個別のカラムに格納するかを指定する 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](#samples-table) テーブルの `index_granularity` を設定します。明示的に設定した場合、エンジン宣言の `index_granularity` をオーバーライドします。外部 samples テーブルおよび MergeTree 以外のエンジンでは無視されます | | `tags_index_granularity` | UInt64 | 8192 | 内部 [tags](#tags-table) テーブルの `index_granularity` を設定します。明示的に設定した場合、エンジン宣言の `index_granularity` をオーバーライドします。外部 tags テーブルおよび MergeTree 以外のエンジンでは無視されます |
# 関数
以下は、`TimeSeries` テーブルを引数としてサポートする関数の一覧です。 * [timeSeriesSamples](/ja/reference/functions/table-functions/timeSeriesSamples) * [timeSeriesTags](/ja/reference/functions/table-functions/timeSeriesTags) * [timeSeriesMetrics](/ja/reference/functions/table-functions/timeSeriesMetrics)