> ## 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](/ko/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](/ko/concepts/features/interfaces/prometheus#remote-write)
* [prometheus remote-read](/ko/concepts/features/interfaces/prometheus#remote-read)

<div id="target-tables">
  ## 대상 테이블
</div>

`TimeSeries` 테이블은 자체 데이터를 갖지 않으며, 모든 데이터는 대상 테이블에 저장됩니다.
이는 [materialized view](/ko/reference/statements/create/view#materialized-view)의 동작 방식과 비슷하지만,
materialized view는 대상 테이블이 하나인 반면
`TimeSeries` 테이블에는 [data](#data-table), [태그](#tags-table), [메트릭](#metrics-table)라는 세 개의 대상 테이블이 있습니다.

대상 테이블은 `CREATE TABLE` 쿼리에서 명시적으로 지정할 수도 있고
`TimeSeries` 테이블 엔진이 내부 대상 테이블을 자동으로 생성할 수도 있습니다.

대상 테이블은 다음과 같습니다:

<div id="data-table">
  ### 데이터 테이블
</div>

*data* 테이블에는 특정 식별자에 연결된 시계열이 포함됩니다.

*data* 테이블에는 다음 컬럼이 있어야 합니다:

| 이름          | 필수?  | 기본 타입           | 가능한 타입                 | 설명                   |
| ----------- | ---- | --------------- | ---------------------- | -------------------- |
| `id`        | \[x] | `UUID`          | 모든 타입                  | 메트릭 이름과 태그 조합을 식별합니다 |
| `timestamp` | \[x] | `DateTime64(3)` | `DateTime64(X)`        | 시점                   |
| `value`     | \[x] | `Float64`       | `Float32` 또는 `Float64` | `timestamp`에 연결된 값   |

<div id="tags-table">
  ### Tags 테이블
</div>

*tags* 테이블에는 메트릭 이름과 태그의 각 조합별로 계산된 식별자가 포함됩니다.

*tags* 테이블에는 다음 컬럼이 있어야 합니다:

| Name                 | Mandatory? | Default type                          | Possible types                                                                                                          | Description                                                                                       |
| -------------------- | ---------- | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| `id`                 | \[x]       | `UUID`                                | any (must match the type of `id` in the [data](#data-table) table)                                                      | `id`는 메트릭 이름과 태그의 조합을 식별합니다. DEFAULT 표현식은 이러한 식별자를 계산하는 방법을 지정합니다                                 |
| `metric_name`        | \[x]       | `LowCardinality(String)`              | `String` or `LowCardinality(String)`                                                                                    | 메트릭 이름                                                                                            |
| `<tag_value_column>` | \[ ]       | `String`                              | `String` or `LowCardinality(String)` or `LowCardinality(Nullable(String))`                                              | 특정 태그의 값입니다. 태그 이름과 해당 컬럼 이름은 [tags\_to\_columns](#settings) 설정에서 지정합니다                           |
| `tags`               | \[x]       | `Map(LowCardinality(String), String)` | `Map(String, String)` or `Map(LowCardinality(String), String)` or `Map(LowCardinality(String), LowCardinality(String))` | 메트릭 이름을 담는 태그 `__name__`와 [tags\_to\_columns](#settings) 설정에 나열된 이름의 태그를 제외한 태그 맵                 |
| `all_tags`           | \[ ]       | `Map(String, String)`                 | `Map(String, String)` or `Map(LowCardinality(String), String)` or `Map(LowCardinality(String), LowCardinality(String))` | 임시 컬럼이며, 각 행은 메트릭 이름을 담는 태그 `__name__`만 제외한 모든 태그의 맵입니다. 이 컬럼은 `id`를 계산할 때만 사용됩니다                 |
| `min_time`           | \[ ]       | `Nullable(DateTime64(3))`             | `DateTime64(X)` or `Nullable(DateTime64(X))`                                                                            | 해당 `id`를 가진 시계열의 최소 타임스탬프입니다. [store\_min\_time\_and\_max\_time](#settings)가 `true`이면 이 컬럼이 생성됩니다 |
| `max_time`           | \[ ]       | `Nullable(DateTime64(3))`             | `DateTime64(X)` or `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` or `LowCardinality(String)` | 메트릭 패밀리의 이름                                                                                     |
| `type`               | \[x] | `String` | `String` or `LowCardinality(String)` | 메트릭 패밀리의 타입으로, "counter", "gauge", "summary", "stateset", "histogram", "gaugehistogram" 중 하나입니다 |
| `unit`               | \[x] | `String` | `String` or `LowCardinality(String)` | 메트릭에 사용되는 단위                                                                                    |
| `help`               | \[x] | `String` | `String` or `LowCardinality(String)` | 메트릭 설명                                                                                          |

`TimeSeries` 테이블에 삽입된 모든 행은 실제로 이 3개의 대상 테이블에 저장됩니다.
`TimeSeries` 테이블에는 [data](#data-table), [tags](#tags-table), [metrics](#metrics-table) 테이블의 모든 컬럼이 포함됩니다.

<div id="creation">
  ## 생성
</div>

`TimeSeries` 테이블 엔진으로 테이블을 생성하는 방법은 여러 가지가 있습니다.
가장 간단한 SQL 문은

```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'
```

따라서 컬럼은 자동으로 생성되었으며, 이 구문에는 내부 UUID도 3개 있습니다 -
생성된 각 내부 대상 테이블마다 하나씩 있습니다.
(내부 UUID는 일반적으로 설정
[show\_table\_uuid\_in\_table\_create\_query\_if\_not\_nil](/ko/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-table) 테이블은 timestamp를 밀리초 대신 마이크로초 단위로 저장합니다:

```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` 두 개입니다. 이 예시에서는 두 컬럼이 같은 의미이지만, `tags_to_columns` 설정을 사용하면
서로 다를 수 있습니다. 이 설정을 사용하면 특정 태그를 `tags` 컬럼 내부의 맵에 저장하는 대신 별도의 컬럼에 저장하도록 지정할 수
있습니다:

```sql theme={null}
CREATE TABLE my_table
ENGINE = TimeSeries 
SETTINGS tags_to_columns = {'instance': 'instance', 'job': 'job'}
```

이 SQL 문은 컬럼을 추가합니다:

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

`my_table`과 그 내부 [태그](#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](/ko/reference/engines/table-engines/mergetree-family/mergetree)를 사용합니다;
* [tags](#tags-table) 테이블은 [AggregatingMergeTree](/ko/reference/engines/table-engines/mergetree-family/aggregatingmergetree)를 사용합니다. 이 테이블에는 동일한 데이터가 여러 번 삽입되는 경우가 많으므로
  중복을 제거할 방법이 필요하고, `min_time` 및 `max_time` 컬럼에 대해 집계를 수행해야 하기 때문입니다;
* [metrics](#metrics-table) 테이블은 [ReplacingMergeTree](/ko/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` 테이블을 정의할 때 지정할 수 있는 설정 목록입니다.

| 이름                                   | 유형   | 기본값  | 설명                                                                                                                                                                             |
| ------------------------------------ | ---- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `tags_to_columns`                    | 맵    | {}   | [태그](#tags-table) 테이블에서 어떤 태그를 별도의 컬럼으로 저장할지 지정하는 맵입니다. 구문: `{'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](/ko/reference/functions/table-functions/timeSeriesData)
* [timeSeriesTags](/ko/reference/functions/table-functions/timeSeriesTags)
* [timeSeriesMetrics](/ko/reference/functions/table-functions/timeSeriesMetrics)