TimeSeries 테이블 엔진

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

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

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, ...]
[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 테이블은 컬럼 목록을 지정하지 않고도 생성할 수 있습니다):

CREATE TABLE my_table ENGINE=TimeSeries

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

• prometheus remote-write
• prometheus remote-read

​

외부 컬럼

TimeSeries 테이블의 컬럼은 자동으로 생성됩니다. 이러한 컬럼을 외부 컬럼이라고 하며, 데이터는 저장하지 않고 SELECT/INSERT를 위한 인터페이스만 제공합니다. 실제 데이터는 대상 테이블에 저장됩니다. 다음은 외부 컬럼 목록입니다:

Name	Type	Description
metric_name	String	메트릭 이름
tags	Map(String, String)	시계열의 tags(labels) 맵
time_series	Array(Tuple(DateTime64(3), Float64))가 기본값	시계열에 대한 (timestamp, value) 쌍의 배열입니다. 튜플의 timestamp 및 스칼라 요소 타입은 샘플 INNER COLUMNS 선언에서 유추할 수 있습니다(외부 컬럼 지정 참고).
metric_family	String	메트릭 패밀리 이름(메트릭 메타데이터용)
type	String	메트릭 유형(예: “counter”, “gauge”)
unit	String	메트릭 단위
help	String	메트릭 설명

예시:

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__에 지정된다는 의미입니다. 예시는 다음과 같습니다:

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 컬럼에 값을 삽입합니다:

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 컬럼은 CREATE TABLE 문에서 명시적으로 나열해 기본 Array(Tuple(DateTime64(3), Float64)) 타입을 재정의할 수 있습니다. ClickHouse는 튜플에서 타임스탬프와 스칼라 타입을 추출해 내부 samples table에 반영합니다:

CREATE TABLE my_table (time_series Array(Tuple(UInt32, Float32))) ENGINE=TimeSeries

이는 samples INNER COLUMNS 절에서 timestamp 및 value 컬럼의 타입을 직접 선언하는 것과 동일합니다:

CREATE TABLE my_table ENGINE=TimeSeries
SAMPLES INNER COLUMNS (timestamp UInt32, value Float32)

두 형식을 모두 같은 CREATE TABLE 문에서 사용하는 경우, 선언된 타입이 일치해야 합니다.

​

대상 테이블

TimeSeries 테이블은 자체 데이터를 갖지 않으며, 모든 데이터는 대상 테이블에 저장됩니다. 이는 materialized view의 동작 방식과 비슷하지만, materialized view는 대상 테이블이 하나인 반면 TimeSeries 테이블에는 samples, tags, 메트릭라는 세 개의 대상 테이블이 있습니다.

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

TimeSeries 테이블에 삽입된 행은 변환되고 블록으로 분할된 후, 이 3개의 대상 테이블에 삽입됩니다.

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

​

Samples table

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

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

이름	필수?	기본 타입	가능한 타입	설명
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 samples 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 테이블에는 다음 컬럼이 있어야 합니다:

Name	Mandatory?	Default type	Possible types	Description
metric_family_name	[x]	String	String or LowCardinality(String)	메트릭 패밀리의 이름
type	[x]	LowCardinality(String)	String or LowCardinality(String)	메트릭 패밀리의 타입으로, “counter”, “gauge”, “summary”, “stateset”, “histogram”, “gaugehistogram” 중 하나입니다
unit	[x]	LowCardinality(String)	String or LowCardinality(String)	메트릭에 사용되는 단위
help	[x]	String	String or LowCardinality(String)	메트릭 설명

​

생성

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

CREATE TABLE my_table ENGINE=TimeSeries

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

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 와 같으며, 각 대상 테이블에는 고유한 컬럼 집합이 있습니다:

CREATE TABLE default.`.inner_id.samples.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` 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로 저장하려면 다음과 같습니다:

CREATE TABLE my_table ENGINE=TimeSeries
SAMPLES INNER COLUMNS (timestamp DateTime64(6), value Float32)

같은 절을 사용하여 코덱과 기타 컬럼 속성을 지정할 수 있습니다:

CREATE TABLE my_table ENGINE=TimeSeries
SAMPLES INNER COLUMNS (timestamp DateTime64(3) CODEC(DoubleDelta))

​

id 컬럼

id 컬럼에는 식별자가 들어 있으며, 각 식별자는 메트릭 이름과 태그의 조합을 기준으로 계산됩니다. 식별자를 생성하는 데 사용되는 유형과 DEFAULT 표현식은 TAGS INNER COLUMNS 절을 통해 사용자 지정할 수 있습니다:

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 절을 사용하지 않고도 동일하게 사용자 지정할 수 있습니다:

CREATE TABLE my_table ENGINE=TimeSeries
SETTINGS id_generator = 'sipHash64(metric_name, all_tags)'

이 설정이 지정되면, 컬럼의 DEFAULT에 다른 표현식이 있더라도 id를 생성하는 데 이 설정이 사용됩니다.

​

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 문은 내부 tags 대상 테이블에 instance 및 job 컬럼을 추가합니다. 이 경우 tags 컬럼에는 instance 및 job 태그가 포함되지 않지만, all_tags 컬럼에는 포함됩니다. all_tags 컬럼은 일시적(임시)이며, 오직 id 컬럼의 DEFAULT 표현식에서 사용하기 위한 것입니다.

​

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

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

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

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

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

​

외부 대상 테이블

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

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에 나열된 <tag_value_column>들)은 TimeSeries 테이블이 내부적으로 생성하는 타입과 일치해야 합니다(타입 제약 조건은 Samples table, Tags 테이블, Metrics 테이블을 참조하십시오). 타입 불일치는 CREATE 시점에 보고됩니다.

외부 Tags 대상의 id 생성기 표현식은 INSERT 시점에 다음 순서대로 결정됩니다: 먼저 id_generator 설정(설정된 경우), 다음으로 외부 테이블의 id 컬럼에 선언된 DEFAULT(있는 경우), 마지막으로 id 타입에서 파생된 표준 생성기입니다. 따라서 이 설정은 외부 테이블에 선언된 DEFAULT를 재정의합니다 — 자세한 내용은 The id column을 참조하십시오.

​

설정 변경

CREATE 이후에는 다음 2개의 설정을 변경할 수 있습니다:

• id_generator
• filter_by_min_time_and_max_time

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;

id_generator는 데이터가 이미 Tags 테이블에 있는 상태에서 변경하면 동일한 메트릭+태그 조합에 대해 서로 다른 ID가 생성될 수 있습니다. 기존 행은 이전 ID를 유지하고, 새 행은 새 생성기를 사용합니다.

다른 설정은 CREATE 시점에 내부 테이블의 스키마에 반영되므로 ALTER ... MODIFY SETTING으로는 변경할 수 없습니다.

​

설정

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

이름	유형	기본값	설명
id_generator	표현식	id 유형에 따라 다름	태그로부터 시계열의 식별자(지문)를 계산하는 표현식입니다. 설정하지 않으면 id 컬럼의 기본 표현식이 사용됩니다. id 컬럼의 기본 표현식도 설정되지 않은 경우 표현식이 자동으로 선택됩니다
tags_to_columns	맵	tags 테이블에서 어떤 태그를 별도의 컬럼으로 저장할지 지정하는 맵입니다. 구문: {'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
• timeSeriesTags
• timeSeriesMetrics