> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-fix-nav-issues.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

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

# 関数

export const CloudNotSupportedBadge = () => {
  return <div className="cloudNotSupportedBadge">
            <div className="cloudNotSupportedIcon">
            <svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
                <path strokeWidth="1.5" d="M6.33366 12.6666L12.3739 12.6667C13.6593 12.6667 14.7073 11.6187 14.7073 10.3334C14.7073 9.04804 13.6593 8.00003 12.3739 8.00003C12.3739 8.00003 12.3337 7.66659 12.0003 7.33325M10.667 5.33322C8.00033 2.33325 4.45395 4.78537 4.14195 6.68203C2.55728 6.7627 1.29395 8.06203 1.29395 9.6667C1.29395 11.3234 2.66699 12.6666 4.00033 12.6666" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
                <path strokeWidth="1.5" d="M2.66699 14L12.0003 4.66663" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
            </svg>

        </div>
            Not supported in ClickHouse Cloud
        </div>;
};

export const ExperimentalBadge = () => {
  return <div className="experimentalBadge">
            <div className="experimentalIcon">
            <svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
                <path strokeWidth="1.25" d="M5.5 2H10.5" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
                <path strokeWidth="1.25" d="M9.50015 2V6.19625L13.4283 12.7425C13.4738 12.8183 13.4985 12.9049 13.4996 12.9934C13.5008 13.0818 13.4785 13.169 13.435 13.246C13.3914 13.323 13.3283 13.3871 13.2519 13.4317C13.1755 13.4764 13.0886 13.4999 13.0002 13.5H3.00015C2.91164 13.5 2.8247 13.4766 2.74822 13.432C2.67174 13.3874 2.60847 13.3233 2.56487 13.2463C2.52126 13.1693 2.49889 13.082 2.50004 12.9935C2.50119 12.905 2.52582 12.8184 2.5714 12.7425L6.50015 6.19625V2" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
                <path strokeWidth="1.25" d="M4.47656 9.56754C5.30344 9.41254 6.47656 9.47942 7.99969 10.25C10.0153 11.2707 11.4216 11.0569 12.2184 10.7282" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
            </svg>
        </div>
            Experimental feature. <u><a href="/docs/beta-and-experimental-features#experimental-features">Learn more.</a></u>
        </div>;
};

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

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

<Info>
  これは実験的な機能であり、今後のリリースで後方互換性のない変更が行われる可能性があります。
  [allow\_experimental\_time\_series\_table](/ja/reference/settings/session-settings#allow_experimental_time_series_table) 設定で
  TimeSeries テーブルエンジン の使用を有効にします。
  `set allow_experimental_time_series_table = 1` コマンドを実行します。
</Info>

<div id="syntax">
  ## 構文
</div>

```sql theme={null}
CREATE TABLE name [(columns)] ENGINE=TimeSeries
[SETTINGS var1=value1, ...]
[DATA db.data_table_name | DATA ENGINE data_table_engine(arguments)]
[TAGS db.tags_table_name | TAGS ENGINE tags_table_engine(arguments)]
[METRICS db.metrics_table_name | METRICS ENGINE metrics_table_engine(arguments)]
```

<div id="usage">
  ## 使い方
</div>

まずは、すべてデフォルト設定のままで始めるのが簡単です (カラムの一覧を指定しなくても `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)

<div id="target-tables">
  ## ターゲットテーブル
</div>

`TimeSeries` テーブル自体はデータを持たず、すべてのデータはそのターゲットテーブルに格納されます。
これは [materialized view](/ja/reference/statements/create/view#materialized-view) の仕組みに似ていますが、
materialized view ではターゲットテーブルは 1 つであるのに対し、
`TimeSeries` テーブルには [data](#data-table)、[tags](#tags-table)、[metrics](#metrics-table) という 3 つのターゲットテーブルがあります。

ターゲットテーブルは `CREATE TABLE` クエリで明示的に指定することもできますし、
`TimeSeries` テーブルエンジンが内部ターゲットテーブルを自動生成することもできます。

ターゲットテーブルは次のとおりです:

<div id="data-table">
  ### data テーブル
</div>

*data* テーブルには、識別子に関連付けられた時系列が格納されます。

*data* テーブルには、次のカラムが必要です。

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

<div id="tags-table">
  ### Tags テーブル
</div>

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

*tags* テーブルには、次のカラムが必要です。

| 名前                   | 必須?  | デフォルト型                                | 使用可能な型                                                                                                                    | 説明                                                                                                |
| -------------------- | ---- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| `id`                 | \[x] | `UUID`                                | 任意 ([data](#data-table) テーブルの `id` の型と一致している必要があります)                                                                      | `id` は、メトリクス名とタグの組み合わせを識別します。DEFAULT 式は、この識別子の計算方法を指定します                                          |
| `metric_name`        | \[x] | `LowCardinality(String)`              | `String` または `LowCardinality(String)`                                                                                     | メトリクス名                                                                                            |
| `<tag_value_column>` | \[ ] | `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` の場合に作成されます |

<div id="metrics-table">
  ### Metrics テーブル
</div>

*metrics* テーブルには、収集されるメトリクスに関する情報、各メトリクスのタイプ、および説明が格納されます。

*metrics* テーブルには、次のカラムが必要です。

| 名前                   | 必須?  | デフォルト型   | 使用可能な型                                | 説明                                                                                       |
| -------------------- | ---- | -------- | ------------------------------------- | ---------------------------------------------------------------------------------------- |
| `metric_family_name` | \[x] | `String` | `String` または `LowCardinality(String)` | メトリクスファミリーの名前                                                                            |
| `type`               | \[x] | `String` | `String` または `LowCardinality(String)` | メトリクスファミリーのタイプ。"counter"、"gauge"、"summary"、"stateset"、"histogram"、"gaugehistogram" のいずれか |
| `unit`               | \[x] | `String` | `String` または `LowCardinality(String)` | メトリクスで使用される単位                                                                            |
| `help`               | \[x] | `String` | `String` または `LowCardinality(String)` | メトリクスの説明                                                                                 |

`TimeSeries` テーブルに挿入された任意の行は、実際にはこれら 3 つのターゲットテーブルに格納されます。
`TimeSeries` テーブルには、[データ](#data-table)、[タグ](#tags-table)、[メトリクス](#metrics-table) テーブルのすべてのカラムが含まれます。

<div id="creation">
  ## 作成
</div>

`TimeSeries` テーブルエンジンを使ってテーブルを作成する方法はいくつかあります。
最も簡単なステートメントは

```sql theme={null}
CREATE TABLE my_table ENGINE=TimeSeries
```

実際には、次のテーブルが作成されます (`SHOW CREATE TABLE my_table` を実行すると確認できます) :

```sql theme={null}
CREATE TABLE my_table
(
    `id` UUID DEFAULT reinterpretAsUUID(sipHash128(metric_name, all_tags)),
    `timestamp` DateTime64(3),
    `value` Float64,
    `metric_name` LowCardinality(String),
    `tags` Map(LowCardinality(String), String),
    `all_tags` Map(String, String),
    `min_time` Nullable(DateTime64(3)),
    `max_time` Nullable(DateTime64(3)),
    `metric_family_name` String,
    `type` String,
    `unit` String,
    `help` String
)
ENGINE = TimeSeries
DATA ENGINE = MergeTree ORDER BY (id, timestamp)
DATA INNER UUID '01234567-89ab-cdef-0123-456789abcdef'
TAGS ENGINE = AggregatingMergeTree PRIMARY KEY metric_name ORDER BY (metric_name, id)
TAGS INNER UUID '01234567-89ab-cdef-0123-456789abcdef'
METRICS ENGINE = ReplacingMergeTree ORDER BY metric_family_name
METRICS INNER UUID '01234567-89ab-cdef-0123-456789abcdef'
```

したがって、カラムは自動的に生成されており、このステートメントには 3 つの内部 UUID も含まれています -
作成された各内部ターゲットテーブルに 1 つずつ対応しています。
(内部 UUID は通常は表示されず、
[show\_table\_uuid\_in\_table\_create\_query\_if\_not\_nil](/ja/reference/settings/session-settings#show_table_uuid_in_table_create_query_if_not_nil)
を設定した場合にのみ表示されます。)

内部ターゲットテーブルの名前は `.inner_id.data.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`、
`.inner_id.tags.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`、`.inner_id.metrics.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`
のようになっており、各ターゲットテーブルにはメインの `TimeSeries` テーブルのカラムの一部が含まれています:

```sql theme={null}
CREATE TABLE default.`.inner_id.data.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` String,
    `unit` String,
    `help` String
)
ENGINE = ReplacingMergeTree
ORDER BY metric_family_name
```

<div id="adjusting-column-types">
  ## カラムの型を調整する
</div>

メインテーブルの定義時に型を明示的に指定することで、内部ターゲットテーブルのほぼすべてのカラムの型を調整できます。例えば、

```sql theme={null}
CREATE TABLE my_table
(
    timestamp DateTime64(6)
) ENGINE=TimeSeries
```

これにより、内部の[data](#data-table)テーブルには、タイムスタンプがミリ秒ではなくマイクロ秒で保存されます:

```sql theme={null}
CREATE TABLE default.`.inner_id.data.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`
(
    `id` UUID,
    `timestamp` DateTime64(6),
    `value` Float64
)
ENGINE = MergeTree
ORDER BY (id, timestamp)
```

<div id="id-column">
  ## `id` カラム
</div>

`id` カラムには識別子が格納されており、各識別子はメトリクス名とタグの組み合わせごとに計算されます。
`id` カラムの DEFAULT 式は、そのような識別子を計算するために使用される式です。
`id` カラムの型とその式は、どちらも明示的に指定することで調整できます。

```sql theme={null}
CREATE TABLE my_table
(
  id UInt64 DEFAULT sipHash64(metric_name, all_tags)
)
ENGINE=TimeSeries
```

<div id="tags-and-all-tags">
  ## `tags` と `all_tags` カラム
</div>

タグのマップを含むカラムは `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'}
```

このステートメントにより、次のカラムが追加されます:

```sql theme={null}
`instance` String,
`job` String
```

`my_table` と、その内部の [tags](#tags-table) ターゲットテーブルの両方の定義に対してです。この場合、`tags` カラムには `instance` と `job` のタグは含まれませんが、
`all_tags` カラムにはそれらが含まれます。`all_tags` カラムは一時的なもので、唯一の目的は `id` カラムの DEFAULT 式で
使用することです。

カラムの型は、明示的に指定することで調整できます:

```sql theme={null}
CREATE TABLE my_table (
  instance LowCardinality(String),
  job LowCardinality(Nullable(String))
)
ENGINE=TimeSeries
SETTINGS tags_to_columns = {'instance': 'instance', 'job': 'job'}
```

<div id="inner-table-engines">
  ## 内部ターゲットテーブルのテーブルエンジン
</div>

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

* [data](#data-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
DATA ENGINE=ReplicatedMergeTree
TAGS ENGINE=ReplicatedAggregatingMergeTree
METRICS ENGINE=ReplicatedReplacingMergeTree
```

<div id="external-target-tables">
  ## 外部ターゲットテーブル
</div>

`TimeSeries` テーブルで、手動で作成したテーブルを使用できます。

```sql theme={null}
CREATE TABLE data_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 DATA data_for_my_table TAGS tags_for_my_table METRICS metrics_for_my_table;
```

<div id="settings">
  ## 設定
</div>

以下は、`TimeSeries` テーブルの定義時に指定できる設定の一覧です。

| Name                                 | Type | Default | Description                                                                                                                                                                        |
| ------------------------------------ | ---- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `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` テーブルを引数としてサポートする関数の一覧です。

* [timeSeriesData](/ja/reference/functions/table-functions/timeSeriesData)
* [timeSeriesTags](/ja/reference/functions/table-functions/timeSeriesTags)
* [timeSeriesMetrics](/ja/reference/functions/table-functions/timeSeriesMetrics)