> ## Documentation Index > Fetch the complete documentation index at: https://private-7c7dfe99-parallel-read-in-order-multi-part.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. > 時系列、つまりタイムスタンプとタグ（またはラベル）に関連付けられた値の集合を格納するテーブルエンジン。 # TimeSeries テーブルエンジン export const PrivatePreviewBadge = () => { return
{'プライベートプレビュー'}
; }; 時系列、つまりタイムスタンプとタグ (またはラベル) に関連付けられた値の集合を格納するテーブルエンジン: ```sql theme={null} metric_name1[tag1=value1, tag2=value2, ...] = {timestamp1: value1, timestamp2: value2, ...} metric_name2[...] = ... ``` これはプライベートプレビュー機能であり、今後のリリースで後方互換性のない変更が行われる可能性があります。 `enable_time_series_table` 設定で TimeSeries テーブルエンジン の使用を有効にします。 `set enable_time_series_table = 1` コマンドを実行します。 `TimeSeries` テーブルエンジンは ClickHouse Cloud でプライベートプレビュー機能として利用できます。 プライベートプレビューに参加しているサービスでは、すでに `enable_time_series_table` 設定が構成されています。その他の ClickHouse Cloud サービス ではこの構成は行われておらず、そのようなサービスでご自身でこのエンジンを有効にすることはできません。 ## 構文 ```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)]] [RECENT SAMPLES db.recent_samples_table_name | [RECENT SAMPLES INNER COLUMNS (...)] [RECENT SAMPLES INNER ENGINE engine(arguments)]] [TAGS db.tags_table_name | [TAGS INNER COLUMNS (...)] [TAGS INNER ENGINE engine(arguments)]] [METRIC FAMILIES db.metric_families_table_name | [METRIC FAMILIES INNER COLUMNS (...)] [METRIC FAMILIES INNER ENGINE engine(arguments)]] ``` キーワード `SAMPLES` には `DATA` というエイリアスがあり、キーワード `METRIC FAMILIES` には `METRICS` というエイリアスがあります。いずれも後方互換性のために残されています。 バージョン 4 より前の[バージョン](#schema-versioning)のテーブル定義は `METRICS` を用いて書き込まれるため、古いサーバーでも読み取ることができます。 ## 使い方 まずは、すべてデフォルト設定のままで始めるのが簡単です (カラムの一覧を指定しなくても `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)` | 時系列のタグ (ラベル) のマップ | | `samples` | 既定では `Array(Tuple(DateTime64(3), Float64))` | 時系列の `(timestamp, value)` ペアの Array。タプルの timestamp と scalar 要素の型は、samples の `INNER COLUMNS` 宣言から導出できます ([外部カラムの指定](#specifying-outer-columns)を参照)。[バージョン](#schema-versioning) 2 以前のテーブルでは、このカラムの名前は `time_series` です | | `metric_family` | `String` | メトリクスファミリーの名前 (メトリクスのメタデータ用) | | `type` | `String` | メトリクスの型 (例: "counter"、"gauge") | | `unit` | `String` | メトリクスの単位 | | `help` | `String` | メトリクスの説明 | 例: ```sql theme={null} INSERT INTO my_table (metric_name, tags, samples) 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, samples) 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, samples, metric_family, type, unit, help) VALUES ('http_requests_total', {'method': 'GET'}, [(now64(), 100.0)], 'http_requests_total', 'counter', 'requests', 'Total HTTP requests') ``` ### 外部カラムの指定 外部 `samples` カラムは、デフォルトの `Array(タプル(DateTime64(3), Float64))` 型をオーバーライドするために、`CREATE TABLE` ステートメントで明示的に指定できます (旧名称の `time_series` も使用できます) 。ClickHouse はその タプル から timestamp 型と scalar 型を抽出し、それらを内部の Samples テーブルに反映します： ```sql theme={null} CREATE TABLE my_table (samples 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(Delta, T64, ZSTD(3)), value Float32 CODEC(ALP, ZSTD(3))) ``` 両方の形式を同じ `CREATE TABLE` ステートメント内で使用する場合、宣言する型は一致していなければなりません。 ## ターゲットテーブル `TimeSeries` テーブル自体はデータを持たず、すべてのデータはそのターゲットテーブルに格納されます。 これは [materialized view](/ja/reference/statements/create/view#materialized-view) の仕組みに似ていますが、 materialized view ではターゲットテーブルは 1 つであるのに対し、 `TimeSeries` テーブルには [samples](#samples-table)、[tags](#tags-table)、[metric families](#metric-families-table) という 3 つの必須のターゲットテーブルと、 デフォルトで有効になっている任意の [recent samples](#recent-samples-table) ターゲットテーブルがあります ([recent\_samples\_ttl\_seconds](#settings) 設定を参照してください) 。 ターゲットテーブルは `CREATE TABLE` クエリで明示的に指定することもできますし、 `TimeSeries` テーブルエンジンが内部ターゲットテーブルを自動生成することもできます。 `TimeSeries` テーブルに挿入された行は変換され、ブロックに分割されたうえで、これらのターゲットテーブルに挿入されます。 ターゲットテーブルは次のとおりです: ### samples テーブル *samples* テーブルには、識別子に関連付けられた時系列が格納されます。 *samples* テーブルには、次のカラムが必要です。 | Name | 必須? | デフォルト型 | 使用可能な型 | Description | | - | - | - | - | - | | `id` | \[x] | `Tuple(UInt64, LowCardinality(UUID))` | any | メトリクス名とタグの組み合わせを識別します | | `timestamp` | \[x] | `DateTime64(3)` | `DateTime64(X)` | 時点 | | `value` | \[x] | `Float64` | `Float32` or `Float64` | `timestamp` に対応する値 | エンジンが自動作成するカラムには、時系列圧縮コーデックが設定されます。 `timestamp CODEC(Delta, T64, ZSTD(3))` および `value CODEC(ALP, ZSTD(3))`。ほぼ単調なタイムスタンプは汎用コーデックではほとんど 圧縮されず、samples テーブルのディスク上のサイズの大部分を占める可能性があります。 エンジンは、内部の samples テーブルおよび recent samples テーブルに対して、`enable_alp_codec` を設定しなくても `ALP` を有効にします。 [カラムの型の調整](#adjusting-column-types)も参照してください。 ### Recent samples テーブル *recent samples* テーブルは任意であり、デフォルトで有効になっています ([recent\_samples\_ttl\_seconds](#settings) 設定を参照してください。この値をゼロに設定するとテーブルは無効になります) 。このテーブルには、当該設定で定義された有効期限 (TTL) より新しいサンプルのコピーが格納され、[samples](#samples-table) テーブルと同じカラムを持つ必要があります。 生成された `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](#settings) 設定から導出されます。 ### Tags テーブル *tags* テーブルには、メトリクス名とタグの各組み合わせに対して計算された識別子が格納されます。 *tags* テーブルには、次のカラムが必要です。 | 名前 | 必須? | デフォルト型 | 使用可能な型 | 説明 | | - | - | - | - | - | | `id` | \[x] | `Tuple(UInt64, LowCardinality(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` の場合に作成されます | [バージョン](#schema-versioning) 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* テーブルには、次のカラムが必要です。 | 名前 | 必須? | デフォルト型 | 使用可能な型 | 説明 | | - | - | - | - | - | | `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), `samples` Array(Tuple(DateTime64(3), Float64)), `metric_family` String, `type` String, `unit` String, `help` String ) ENGINE = TimeSeries SETTINGS version = 5, recent_samples_ttl_seconds = 345600 SAMPLES INNER COLUMNS ( `id` Tuple(UInt64, LowCardinality(UUID)), `timestamp` DateTime64(3) CODEC(Delta, T64, ZSTD(3)), `value` Float64 CODEC(ALP, ZSTD(3)) ) SAMPLES INNER ENGINE = MergeTree ORDER BY (id, timestamp) SETTINGS index_granularity = 32768 RECENT SAMPLES INNER COLUMNS ( `id` Tuple(UInt64, UUID), `timestamp` DateTime64(3) CODEC(Delta, T64, ZSTD(3)), `value` Float64 CODEC(ALP, ZSTD(3)) ) RECENT SAMPLES INNER ENGINE = MergeTree PARTITION BY toStartOfInterval(toDateTime(timestamp), toIntervalHour(5)) ORDER BY (id, timestamp) TTL toDateTime(timestamp) + toIntervalSecond(345600) SETTINGS index_granularity = 8192, ttl_only_drop_parts = 1 TAGS INNER COLUMNS ( `id` Tuple(UInt64, LowCardinality(UUID)) DEFAULT tuple(sipHash64(metric_name), toLowCardinality(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))), INDEX tags_idx tags TYPE text(tokenizer = 'keyValuePairs') GRANULARITY 100000000 ) TAGS INNER ENGINE = AggregatingMergeTree PRIMARY KEY metric_name ORDER BY (metric_name, id) SETTINGS allow_dimensions_outside_sorting_key = 1, index_granularity = 8192 METRIC FAMILIES INNER COLUMNS ( `metric_family_name` String, `type` LowCardinality(String), `unit` LowCardinality(String), `help` String ) METRIC FAMILIES INNER ENGINE = ReplacingMergeTree ORDER BY metric_family_name ``` このように、カラムは自動的に生成され、さらに `INNER COLUMNS` 句に格納された独自のカラム定義を持つ4つの内部ターゲットテーブルも存在します。`recent_samples_ttl_seconds` 設定はデフォルト値のまま `SETTINGS` 句に書き込まれています。この設定は recent samples テーブルの TTL を定義するため、その実効値は作成時に固定されます。また、最新のスキーマバージョンが `version` 設定に固定されています ([スキーマのバージョン管理](#schema-versioning) を参照) 。 内部ターゲットテーブルには `.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` のような名前が付けられており、各ターゲットテーブルはそれぞれ固有のカラム構成を持ちます: ```sql theme={null} CREATE TABLE default.`.inner_id.samples.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` ( `id` Tuple(UInt64, LowCardinality(UUID)), `timestamp` DateTime64(3) CODEC(Delta(8), T64, ZSTD(3)), `value` Float64 CODEC(ALP, ZSTD(3)) ) ENGINE = MergeTree ORDER BY (id, timestamp) SETTINGS index_granularity = 32768 ``` ```sql theme={null} CREATE TABLE default.`.inner_id.recentsamples.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` ( `id` Tuple(UInt64, UUID), `timestamp` DateTime64(3) CODEC(Delta(8), T64, ZSTD(3)), `value` Float64 CODEC(ALP, ZSTD(3)) ) ENGINE = MergeTree PARTITION BY toStartOfInterval(toDateTime(timestamp), toIntervalHour(5)) ORDER BY (id, timestamp) TTL toDateTime(timestamp) + toIntervalSecond(345600) SETTINGS index_granularity = 8192, ttl_only_drop_parts = 1 ``` ```sql theme={null} CREATE TABLE default.`.inner_id.tags.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` ( `id` Tuple(UInt64, LowCardinality(UUID)) DEFAULT tuple(sipHash64(metric_name), toLowCardinality(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))), INDEX tags_idx tags TYPE text(tokenizer = 'keyValuePairs') GRANULARITY 100000000 ) 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.metricfamilies.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` と同じ構成の `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` として保存するには、次のようにします。 ```sql theme={null} CREATE TABLE my_table ENGINE=TimeSeries SAMPLES INNER COLUMNS (timestamp DateTime64(6) CODEC(Delta, T64, ZSTD(3)), value Float32 CODEC(ALP, ZSTD(3))) ``` 内部カラムをコーデックなしで指定すると、デフォルトのコーデックが使用されます。 ```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` SETTINGがされていない場合、`id` の型が `UUID`、`UInt64`、`UInt128`、`FixedString(16)`、これらと同じ型を `LowCardinality` でラップしたもの、またはこれらの型のうち2つからなるタプルである場合に限り、ClickHouse は `id` の型に基づいて `DEFAULT` 式を自動的に選択します。このようなタプルでは、自動的に選択される式により、最初の部分でメトリクス名のハッシュが、2番目の部分ですべてのタグのハッシュが計算されます。 `Tuple(UInt64, LowCardinality(UUID))` のような `LowCardinality` の識別子型を使用すると、識別子は辞書エンコードされた状態で保持されます。Samples テーブルは、すべての行に完全な識別子を繰り返して格納する代わりに、ブロックごとの小さな辞書と辞書索引を格納するため、クエリが読み取るデータ量が削減されます。 `id_generator` SETTINGでは、`INNER COLUMNS` 句を使用せずに同じカスタマイズを行えます。 ```sql theme={null} CREATE TABLE my_table ENGINE=TimeSeries SETTINGS id_generator = 'sipHash64(tags)' ``` このSETTINGが有効な場合、カラムの`DEFAULT`に別の式が含まれていても、`id`の生成にはこのSETTINGが使用されます。 `id` カラムの型は、`INNER COLUMNS` 句の代わりに `id_type` SETTINGで指定することもできます。 ```sql theme={null} CREATE TABLE my_table ENGINE=TimeSeries SETTINGS id_type = 'UInt64', id_generator = 'sipHash64(tags)' ``` `id_generator` SETTINGが指定されている場合、`id_type` SETTINGは `CREATE` 時に自動的に記録されるため、その式が想定して記述された型が定義に保持されます。 ## `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) を使用します。 * [recent samples](#recent-samples-table) テーブルでは、5 時間単位の bucket でパーティション化された ([recent\_samples\_partition\_by](#settings) 設定を参照) [MergeTree](/ja/reference/engines/table-engines/mergetree-family/mergetree) を使用します。この際、[recent\_samples\_ttl\_seconds](#settings) 設定から導出された `TTL` が設定され、 `ttl_only_drop_parts` が有効になっているため、期限切れのパーツはまとめて drop されます。 * [tags](#tags-table) テーブルでは [AggregatingMergeTree](/ja/reference/engines/table-engines/mergetree-family/aggregatingmergetree) を使用します。これは、同じデータがこのテーブルに複数回挿入されることが多いため、重複を除去する手段が必要であり、 また、カラム `min_time` と `max_time` の集約にも必要だからです。 * [metric families](#metric-families-table) テーブルでは [ReplacingMergeTree](/ja/reference/engines/table-engines/mergetree-family/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` で生成するかのいずれかです。 指定すれば、内部ターゲットテーブルで他のテーブルエンジンを使用することもできます。 ```sql theme={null} CREATE TABLE my_table ENGINE=TimeSeries SAMPLES ENGINE=ReplicatedMergeTree RECENT SAMPLES ENGINE=ReplicatedMergeTree TAGS ENGINE=ReplicatedAggregatingMergeTree METRIC FAMILIES 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 metric_families_for_my_table ... CREATE TABLE my_table ENGINE=TimeSeries SAMPLES samples_for_my_table TAGS tags_for_my_table METRIC FAMILIES metric_families_for_my_table; ``` 外部テーブルは [recent samples](#recent-samples-table) のターゲット (`RECENT SAMPLES my_recent_samples_table` 句) としても使用できます。 そのようなテーブルは外部 samples テーブルと同じカラムを持つ必要があり、少なくとも [recent\_samples\_ttl\_seconds](#settings) 秒分のデータを保持しなければなりません。これはユーザーの責任です。 外部テーブルのカラム型 (`id`、`timestamp`、`value`、および [`tags_to_columns`](#settings) に記載された ``) は、`TimeSeries` テーブルが通常内部的に生成する型と一致している必要があります (型の制約については、[Samples テーブル](#samples-table)、[Tags テーブル](#tags-table)、および [Metric families テーブル](#metric-families-table) を参照してください) 。型の不一致は `CREATE` 時に報告されます。 外部 tags テーブルの `id` カラムの型と、識別子を生成する式は、`CREATE` 時に [`id_type`](#settings) および [`id_generator`](#settings) 設定に記録されます ([バージョン](#schema-versioning) 2 以降) 。そのため `TimeSeries` テーブルの定義がそれらを保持します。たとえば `CREATE TABLE ... AS my_table` では、外部ターゲットテーブルを読み取ることなく `my_table` の定義から `id` 型を読み取ります。`id_generator` 設定が指定されていない場合は、外部テーブルの `id` カラムで宣言された `DEFAULT` (存在する場合) が設定され、それがなければ `id` 型から導出される正規のジェネレーターが設定されます。記録された式は、後で外部テーブルの `DEFAULT` が変更された場合でも `id` の生成に使用されます。詳細は [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; ALTER TABLE my_table RESET SETTING filter_by_min_time_and_max_time; ``` データがすでに Tags テーブルに存在する状態で `id_generator` を変更すると、同じメトリクス+タグ の組み合わせに対して異なる ID が生成される可能性がある点に注意してください。古い行は従来の ID のまま残り、新しい行では新しいジェネレーターが使用されます。 他の設定は、`ALTER ... MODIFY SETTING` では変更できません。大半は `CREATE` 時に内部テーブルのスキーマに組み込まれ、 `version` 設定は `CREATE` 時に自動的に固定され、スキーマ自体を識別します ([スキーマのバージョニング](#schema-versioning) を参照) 。 ## SETTING 以下は、`TimeSeries` テーブルの定義時に指定できるSETTINGの一覧です。 | Name | Type | Default | Description | | - | - | - | - | | `id_type` | データ型 | `id` カラムに依存 | ターゲットテーブルの `id` カラムの型。通常、型は内部テーブルの `INNER COLUMNS` 句、または[外部](#external-target-tables) tags テーブルで宣言されます。型が定義内に保持されない場合、すなわち tags のターゲットが外部テーブルである場合、または `id_generator` 設定が設定されている場合には、この設定は `CREATE` 時に自動的に記録されます。この設定は `TAGS INNER COLUMNS (id )` の代わりに明示的に指定することもできます。`version` は 2 以上である必要があります | | `id_generator` | Expression | `id` 型に依存 | タグから時系列の識別子 (フィンガープリント) を計算する式です。未設定の場合は、`id` カラムのデフォルト式が使用されます。`id` カラムのデフォルト式も未設定であれば、式は自動的に選択されます。外部 tags テーブルの場合、`version` が 2 以上であれば、この設定は `CREATE` 時に自動的に記録されます ([外部ターゲットテーブル](#external-target-tables) を参照) | | `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 以外のエンジンでは無視されます | | `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)`。明示的に設定した場合、エンジン宣言のパーティションキーをオーバーライドします。いずれも設定されていない場合は、5 時間ごとに 1 パーティションが使用されます。外部 recent samples テーブルでは無視されます。`recent_samples_ttl_seconds` は 0 以外である必要があります | | `recent_samples_index_granularity` | UInt64 | 8192 | 内部 `recent samples` テーブルの `index_granularity` を設定します。明示的に設定した場合、エンジン宣言の `index_granularity` をオーバーライドします。外部 recent samples テーブルおよび MergeTree 以外のエンジンでは無視されます。`recent_samples_ttl_seconds` は 0 以外である必要があります | | `tags_index_granularity` | UInt64 | 8192 | 内部 [tags](#tags-table) テーブルの `index_granularity` を設定します。明示的に設定した場合、エンジン宣言の `index_granularity` をオーバーライドします。外部 tags テーブルおよび MergeTree 以外のエンジンでは無視されます | | `version` | UInt64 | 5 | テーブルのバージョン。ターゲットテーブルの集合とその構造を識別します。バージョンはテーブルの作成時に自動的に固定され、その後は変更できません。通常は `CREATE TABLE` クエリで省略すべきです ([スキーマのバージョニング](#schema-versioning) を参照) | ## スキーマのバージョン管理 `TimeSeries` テーブルエンジンと PromQL 実行レイヤーは現在も活発に開発されています。 そのため、ターゲットテーブルのセットや構造は ClickHouse のバージョン間で変更される可能性があります。 このような変更を検出できるよう、各 `TimeSeries` テーブルでは [version](#settings) SETTINGにバージョンを保存します。 テーブル作成時には、バージョンが `CREATE` クエリに自動的に固定されます。その値はサーバーが認識している最新バージョン (現在は 5) であり、 テーブルのメタデータに永続化され、`ALTER` では変更できません。このSETTINGの導入前に作成されたテーブルは、バージョン 0 と見なされます。 通常、このSETTINGは `CREATE TABLE` クエリで省略します。省略した場合、テーブルには最新バージョンが設定されます。 サーバーがそのバージョンをサポートしている場合は、明示的な `version` も指定できます。その場合、テーブルはそのバージョンの定義方法に従って定義されます ([バージョン履歴](#version-history)を参照)。 `CREATE TABLE ... AS other_table` は別のテーブルのバージョンをコピーしません。詳細は[既存テーブルを AS 指定してテーブルを作成する](#create-as)を参照してください。 サーバーは一定範囲のバージョンをサポートしており、最小バージョンは、`SELECT` による読み取り、`INSERT` による書き込み、 Prometheus remote-write プロトコル、PromQL の評価 ([prometheusQuery](/ja/reference/functions/table-functions/prometheusQuery)、 [prometheusQueryRange](/ja/reference/functions/table-functions/prometheusQueryRange)、 [timeSeriesSelector](/ja/reference/functions/table-functions/timeSeriesSelector) テーブル関数、 `promql` 方言、Prometheus HTTP クエリ API) によって異なる場合があります。 * `TimeSeries` テーブルのバージョンが PromQL には古すぎる場合、そのテーブルに対する PromQL クエリは拒否されます。例外メッセージではテーブルを再作成するよう案内されます。 新しい `TimeSeries` テーブルを作成し、`INSERT ... SELECT` クエリでデータをコピーしてから、古いテーブルを新しいテーブルに置き換えます。 * バージョンが書き込みには古すぎる場合、`INSERT` クエリと Prometheus remote-write プロトコルは拒否されますが、`SELECT` クエリは引き続き機能します。 * バージョンがサーバーでまったくサポートされないほど古い場合、テーブルに対するすべてのクエリ (`SHOW CREATE TABLE`、`DETACH`、`DROP` を除く) が拒否されます。 ### バージョン履歴 | バージョン | 変更内容 | | - | - | | 0 | `version` 設定が導入される前に作成されたテーブル。「プレアルファ」テーブル (ターゲットテーブルのカラムを[外部カラム](#outer-columns)として宣言していたもの) や、[recent samples](#recent-samples-table) テーブルを持たないテーブルが含まれる | | 1 | `version` 設定が導入された | | 2 | [`id_type`](#settings) 設定が導入された。外部の tags テーブルを持つテーブルは、`id` カラムの型を `id_type` に、識別子を生成する式を [`id_generator`](#settings) に記録するため、その定義が外部テーブルに依存しなくなる。`id_generator` が設定されている場合にも `id_type` が記録される ([`id` カラム](#id-column)を参照) | | 3 | 外部カラム `time_series` が `samples` にリネームされた ([外部カラム](#outer-columns)を参照) 。それ以前のバージョンのテーブルはカラムの旧名称をそのまま保持し、[prometheusQuery](/ja/reference/functions/table-functions/prometheusQuery) および [prometheusQueryRange](/ja/reference/functions/table-functions/prometheusQueryRange) テーブル関数は、そのテーブルで使用されている名前でカラムを返す。格納されるデータ自体に変更はない | | 4 | `metrics` ターゲットテーブルが `metric families` にリネームされた。内部テーブルの名前は `.inner_id.metrics.` ではなく `.inner_id.metricfamilies.` となり、定義には `METRICS` ではなく `METRIC FAMILIES` キーワードが使用される。格納されるデータ自体に変更はない | | 5 | `MergeTree` ファミリーのエンジンを使用する新しい内部 tags テーブルでは、デフォルトで `tags` map に `keyValuePairs` テキスト索引が作成される ([Tags テーブル](#tags-table)を参照) | # 関数 以下は、`TimeSeries` テーブルを引数としてサポートする関数の一覧です。 * [timeSeriesSamples](/ja/reference/functions/table-functions/timeSeriesSamples) * [timeSeriesTags](/ja/reference/functions/table-functions/timeSeriesTags) * [timeSeriesMetricFamilies](/ja/reference/functions/table-functions/timeSeriesMetricFamilies)