함수 - ClickHouse Documentation

시계열, 즉 타임스탬프와 태그(또는 레이블)에 연결된 값 집합을 저장하는 테이블 엔진입니다:

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

이 기능은 실험적 기능이며, 향후 릴리스에서 하위 호환되지 않는 방식으로 변경될 수 있습니다. allow_experimental_time_series_table 설정을 사용하여 TimeSeries 테이블 엔진 사용을 활성화하십시오. set allow_experimental_time_series_table = 1 명령을 입력하십시오.

구문

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)]

사용법

기본 설정을 그대로 사용해 시작하는 편이 더 쉽습니다 (TimeSeries 테이블은 컬럼 목록을 지정하지 않고도 생성할 수 있습니다):

CREATE TABLE my_table ENGINE=TimeSeries

그러면 이 테이블을 다음 프로토콜과 함께 사용할 수 있습니다(포트는 서버 구성에서 할당해야 합니다):

대상 테이블

TimeSeries 테이블은 자체 데이터를 갖지 않으며, 모든 데이터는 대상 테이블에 저장됩니다. 이는 materialized view의 동작 방식과 비슷하지만, materialized view는 대상 테이블이 하나인 반면 TimeSeries 테이블에는 data, 태그, 메트릭라는 세 개의 대상 테이블이 있습니다. 대상 테이블은 CREATE TABLE 쿼리에서 명시적으로 지정할 수도 있고 TimeSeries 테이블 엔진이 내부 대상 테이블을 자동으로 생성할 수도 있습니다. 대상 테이블은 다음과 같습니다:

데이터 테이블

data 테이블에는 특정 식별자에 연결된 시계열이 포함됩니다. data 테이블에는 다음 컬럼이 있어야 합니다:

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

Tags 테이블

tags 테이블에는 메트릭 이름과 태그의 각 조합별로 계산된 식별자가 포함됩니다. tags 테이블에는 다음 컬럼이 있어야 합니다:

Name	Mandatory?	Default type	Possible types	Description
`id`	[x]	`UUID`	any (must match the type of `id` in the data 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 설정에서 지정합니다
`tags`	[x]	`Map(LowCardinality(String), String)`	`Map(String, String)` or `Map(LowCardinality(String), String)` or `Map(LowCardinality(String), LowCardinality(String))`	메트릭 이름을 담는 태그 `__name__`와 tags_to_columns 설정에 나열된 이름의 태그를 제외한 태그 맵
`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가 `true`이면 이 컬럼이 생성됩니다
`max_time`	[ ]	`Nullable(DateTime64(3))`	`DateTime64(X)` or `Nullable(DateTime64(X))`	해당 `id`를 가진 시계열의 최대 타임스탬프입니다. store_min_time_and_max_time가 `true`이면 이 컬럼이 생성됩니다

Metrics 테이블

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, tags, metrics 테이블의 모든 컬럼이 포함됩니다.

생성

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

CREATE TABLE my_table ENGINE=TimeSeries

실제로는 다음과 같은 테이블이 생성됩니다(SHOW CREATE TABLE my_table을 실행하면 이를 확인할 수 있습니다):

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 을 설정하기 전까지는 표시되지 않습니다.) 내부 대상 테이블의 이름은 .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 테이블의 컬럼 중 일부에 해당하는 컬럼이 있습니다:

CREATE TABLE default.`.inner_id.data.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`
(
    `id` UUID,
    `timestamp` DateTime64(3),
    `value` Float64
)
ENGINE = MergeTree
ORDER BY (id, timestamp)

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)

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

컬럼 타입 조정

메인 테이블을 정의할 때 이를 명시적으로 지정하면 내부 대상 테이블의 거의 모든 컬럼 타입을 조정할 수 있습니다. 예를 들어,

CREATE TABLE my_table
(
    timestamp DateTime64(6)
) ENGINE=TimeSeries

그러면 내부 데이터 테이블은 timestamp를 밀리초 대신 마이크로초 단위로 저장합니다:

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

`id` 컬럼

id 컬럼에는 식별자가 저장되며, 각 식별자는 메트릭 이름과 태그 조합을 기준으로 계산됩니다. id 컬럼의 DEFAULT 표현식은 이러한 식별자를 계산하는 데 사용됩니다. id 컬럼의 유형과 이 표현식은 명시적으로 지정하여 조정할 수 있습니다:

CREATE TABLE my_table
(
  id UInt64 DEFAULT sipHash64(metric_name, all_tags)
)
ENGINE=TimeSeries

`tags` 및 `all_tags` 컬럼

태그 맵을 포함하는 컬럼은 tags와 all_tags 두 개입니다. 이 예시에서는 두 컬럼이 같은 의미이지만, tags_to_columns 설정을 사용하면 서로 다를 수 있습니다. 이 설정을 사용하면 특정 태그를 tags 컬럼 내부의 맵에 저장하는 대신 별도의 컬럼에 저장하도록 지정할 수 있습니다:

CREATE TABLE my_table
ENGINE = TimeSeries 
SETTINGS tags_to_columns = {'instance': 'instance', 'job': 'job'}

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

`instance` String,
`job` String

my_table과 그 내부 태그 대상 테이블의 정의 둘 다에 추가합니다. 이 경우 tags 컬럼에는 instance 및 job 태그가 포함되지 않지만, all_tags 컬럼에는 포함됩니다. all_tags 컬럼은 일시적(임시)이며, 오직 id 컬럼의 DEFAULT 표현식에서 사용하기 위한 것입니다. 컬럼의 타입은 명시적으로 지정하여 조정할 수 있습니다:

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

내부 대상 테이블의 테이블 엔진

기본적으로 내부 대상 테이블에는 다음 테이블 엔진이 사용됩니다.

data 테이블은 MergeTree를 사용합니다;
tags 테이블은 AggregatingMergeTree를 사용합니다. 이 테이블에는 동일한 데이터가 여러 번 삽입되는 경우가 많으므로 중복을 제거할 방법이 필요하고, min_time 및 max_time 컬럼에 대해 집계를 수행해야 하기 때문입니다;
metrics 테이블은 ReplacingMergeTree를 사용합니다. 이 테이블에도 동일한 데이터가 여러 번 삽입되는 경우가 많으므로 중복을 제거할 방법이 필요하기 때문입니다.

다음과 같이 지정하면 내부 대상 테이블에 다른 테이블 엔진을 사용할 수도 있습니다:

CREATE TABLE my_table ENGINE=TimeSeries
DATA ENGINE=ReplicatedMergeTree
TAGS ENGINE=ReplicatedAggregatingMergeTree
METRICS ENGINE=ReplicatedReplacingMergeTree

외부 대상 테이블

TimeSeries 테이블이 수동으로 생성한 테이블을 사용하도록 할 수 있습니다:

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;

설정

다음은 TimeSeries 테이블을 정의할 때 지정할 수 있는 설정 목록입니다.

이름	유형	기본값	설명
`tags_to_columns`	맵	태그 테이블에서 어떤 태그를 별도의 컬럼으로 저장할지 지정하는 맵입니다. 구문: `{'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 테이블을 인수로 지원하는 함수 목록입니다.

​구문

​사용법

​대상 테이블

​데이터 테이블

​Tags 테이블

​Metrics 테이블

​생성

​컬럼 타입 조정

​id 컬럼

​tags 및 all_tags 컬럼

​내부 대상 테이블의 테이블 엔진

​외부 대상 테이블

​설정

구문

사용법

대상 테이블

데이터 테이블

Tags 테이블

Metrics 테이블

생성

컬럼 타입 조정

`id` 컬럼

`tags` 및 `all_tags` 컬럼

내부 대상 테이블의 테이블 엔진

외부 대상 테이블

설정