> ## Documentation Index > Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-fbfa8bee.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_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, value Float32) ``` 両方の形式を同じ `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] | `UUID` | any | メトリクス名とタグの組み合わせを識別します | | `timestamp` | \[x] | `DateTime64(3)` | `DateTime64(X)` | 時点 | | `value` | \[x] | `Float64` | `Float32` or `Float64` | `timestamp` に対応する値 |
### Tags テーブル
*tags* テーブルには、メトリクス名とタグの各組み合わせに対して計算された識別子が格納されます。 *tags* テーブルには、次のカラムが必要です。 | 名前 | 必須? | デフォルト型 | 使用可能な型 | 説明 | | -------------------- | ---- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | | `id` | \[x] | `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) 設定で列挙された名前のタグを除外したタグのマップ | | `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](#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` 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` のようになっており、各ターゲットテーブルはそれぞれ独自のカラムセットを持っています: ```sql theme={null} CREATE TABLE default.`.inner_id.samples.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` ( `id` UUID, `timestamp` DateTime64(3), `value` Float64 ) ENGINE = MergeTree ORDER BY (id, timestamp) ``` ```sql theme={null} 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) ``` ```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 ```
## 既存のテーブルを 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), value Float32) ``` 同じ句を使って、コーデックやその他のカラム属性を指定できます。 ```sql theme={null} CREATE TABLE my_table ENGINE=TimeSeries SAMPLES INNER COLUMNS (timestamp DateTime64(3) CODEC(DoubleDelta)) ```
## `id` カラム
`id` カラムには識別子が格納されており、各識別子はメトリクス名とタグの組み合わせごとに計算されます。 識別子の生成に使用される型と `DEFAULT` 式は、`TAGS INNER COLUMNS` 句でカスタマイズできます。 ```sql theme={null} 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` 句を使用せずに同じカスタマイズを行えます。 ```sql theme={null} 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` カラム内のマップに格納する代わりに、個別のカラムに格納するよう指定できます。 ```sql theme={null} CREATE TABLE my_table ENGINE = TimeSeries SETTINGS tags_to_columns = {'instance': 'instance', 'job': 'job'} ``` このステートメントにより、内部の [tags](#tags-table) ターゲットテーブルに `instance` と `job` のカラムが追加されます。 この場合、`tags` カラムには `instance` と `job` のタグは含まれませんが、 `all_tags` カラムにはそれらが含まれます。`all_tags` カラムは一時的なもので、唯一の目的は `id` カラムの DEFAULT 式で 使用することです。
## 内部ターゲットテーブルのテーブルエンジン
デフォルトでは、内部ターゲットテーブルでは次のテーブルエンジンを使用します。 * [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 ```
## 外部ターゲットテーブル
`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(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](#tags-table) テーブルで、どのタグを個別のカラムに格納するかを指定する 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` テーブルを引数としてサポートする関数の一覧です。 * [timeSeriesSamples](/ja/reference/functions/table-functions/timeSeriesSamples) * [timeSeriesTags](/ja/reference/functions/table-functions/timeSeriesTags) * [timeSeriesMetrics](/ja/reference/functions/table-functions/timeSeriesMetrics)