motor de tabla TimeSeries

Un motor de tabla que almacena series temporales, es decir, un conjunto de valores asociados a marcas de tiempo y etiquetas (o labels).

Un motor de tabla que almacena series temporales, es decir, un conjunto de valores asociados a marcas de tiempo y etiquetas (o labels):

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

Esta es una funcionalidad experimental que puede cambiar de formas incompatibles con versiones anteriores en futuras versiones. Habilite el uso del motor de tabla TimeSeries con el ajuste allow_experimental_time_series_table. Ejecute el comando set allow_experimental_time_series_table = 1.

​

Sintaxis

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

La palabra clave SAMPLES tiene el alias DATA, que se mantiene por compatibilidad con versiones anteriores.

​

Uso

Es más fácil empezar con la configuración predeterminada (se puede crear una tabla TimeSeries sin especificar una lista de columnas):

CREATE TABLE my_table ENGINE=TimeSeries

A continuación, esta tabla puede utilizarse con los siguientes protocolos (debe asignarse un puerto en la configuración del servidor):

• prometheus remote-write
• prometheus remote-read

​

Columnas externas

Las columnas de una tabla TimeSeries se generan automáticamente. Son columnas externas: no almacenan datos, solo proporcionan la interfaz para SELECT/INSERT. Los datos reales se almacenan en las tablas de destino. Aquí está la lista de las columnas externas:

Nombre	Tipo	Descripción
metric_name	String	El nombre de la métrica
tags	Map(String, String)	Mapa de etiquetas (labels) de la serie temporal
time_series	Array(Tuple(DateTime64(3), Float64)) de forma predeterminada	Array de pares (timestamp, valor) de una serie temporal. Los tipos del timestamp y del elemento escalar de la tupla pueden derivarse de la declaración INNER COLUMNS de las sample (consulta Especificación de columnas externas)
metric_family	String	El nombre de la familia de métricas (para los metadatos de métricas)
type	String	El tipo de la métrica (p. ej., “counter”, “gauge”)
unit	String	La unidad de la métrica
help	String	La descripción de la métrica

Ejemplo:

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

Se permite que metric_name esté vacío durante la inserción, lo que significa que el nombre de la métrica se especifica en tags con __name__, por ejemplo:

INSERT INTO my_table (tags, time_series) VALUES
    ({'__name__': 'cpu_usage', 'job': 'test'},
     [(toDateTime64('2024-01-01 00:00:00', 3), 0.5)])

Para insertar metadatos de métricas, insértelos en las columnas metric_family, type, unit y 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')

​

Especificación de columnas externas

La columna externa time_series se puede incluir explícitamente en una sentencia CREATE TABLE para sobrescribir su tipo predeterminado Array(Tuple(DateTime64(3), Float64)). ClickHouse extrae de la tupla los tipos de marca temporal y escalares, y los propaga a la tabla interna de muestras:

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

Esto equivale a declarar directamente los tipos de las columnas timestamp y value en la cláusula INNER COLUMNS de sample:

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

Si ambas formas se usan en la misma sentencia CREATE TABLE, los tipos declarados deben coincidir.

​

Tablas de destino

Una tabla TimeSeries no tiene datos propios; todo se almacena en sus tablas de destino. Esto es similar al funcionamiento de una vista materializada, con la diferencia de que una vista materializada tiene una sola tabla de destino, mientras que una tabla TimeSeries tiene tres tablas de destino llamadas samples, etiqueta y metrics.

Las tablas de destino pueden especificarse explícitamente en la consulta CREATE TABLE o el motor de tabla TimeSeries puede generar automáticamente tablas de destino internas.

Las filas insertadas en una tabla TimeSeries se transforman, se dividen en bloques y se insertan en estas tres tablas de destino.

Las tablas de destino son las siguientes:

​

Tabla samples

La tabla samples contiene series temporales asociadas a algún identificador.

La tabla samples debe tener las siguientes columnas:

Nombre	¿Obligatorio?	Tipo predeterminado	Tipos posibles	Descripción
id	[x]	UUID	cualquiera	Identifica una combinación de nombres de métricas y etiquetas
timestamp	[x]	DateTime64(3)	DateTime64(X)	Un instante temporal
value	[x]	Float64	Float32 o Float64	Un valor asociado al timestamp

​

Tabla de tags

La tabla tags contiene identificadores calculados para cada combinación de un nombre de métrica y etiquetas.

La tabla tags debe tener las siguientes columnas:

Nombre	¿Obligatorio?	Tipo predeterminado	Tipos posibles	Descripción
id	[x]	UUID	cualquiera (debe coincidir con el tipo de id de la tabla samples)	Un id identifica una combinación de un nombre de métrica y etiquetas. La expresión DEFAULT especifica cómo calcular ese identificador
metric_name	[x]	LowCardinality(String)	String o LowCardinality(String)	El nombre de una métrica
<tag_value_column>	[ ]	String	String o LowCardinality(String) o LowCardinality(Nullable(String))	El valor de una etiqueta específica; el nombre de la etiqueta y el nombre de la columna correspondiente se especifican en la configuración tags_to_columns
tags	[x]	Map(LowCardinality(String), String)	Map(String, String) o Map(LowCardinality(String), String) o Map(LowCardinality(String), LowCardinality(String))	Mapa de etiquetas que excluye la etiqueta __name__, que contiene el nombre de una métrica, y las etiquetas cuyos nombres se enumeran en la configuración tags_to_columns
all_tags	[ ]	Map(String, String)	Map(String, String) o Map(LowCardinality(String), String) o Map(LowCardinality(String), LowCardinality(String))	Columna efímera; cada fila es un mapa de todas las etiquetas, excluyendo únicamente la etiqueta __name__, que contiene el nombre de una métrica. El único propósito de esta columna es usarse al calcular id
min_time	[ ]	Nullable(DateTime64(3))	DateTime64(X) o Nullable(DateTime64(X))	Marca temporal mínima de la serie temporal con ese id. La columna se crea si store_min_time_and_max_time es true
max_time	[ ]	Nullable(DateTime64(3))	DateTime64(X) o Nullable(DateTime64(X))	Marca temporal máxima de la serie temporal con ese id. La columna se crea si store_min_time_and_max_time es true

​

Tabla de métricas

La tabla metrics contiene información sobre las métricas recopiladas, sus tipos y sus descripciones.

La tabla metrics debe tener las siguientes columnas:

Nombre	¿Obligatorio?	Tipo predeterminado	Tipos posibles	Descripción
metric_family_name	[x]	String	String o LowCardinality(String)	El nombre de una familia de métricas
type	[x]	LowCardinality(String)	String o LowCardinality(String)	El tipo de una familia de métricas; uno de “counter”, “gauge”, “summary”, “stateset”, “histogram”, “gaugehistogram”
unit	[x]	LowCardinality(String)	String o LowCardinality(String)	La unidad utilizada en una métrica
help	[x]	String	String o LowCardinality(String)	La descripción de una métrica

​

Creación

Hay varias formas de crear una tabla con el motor de tabla TimeSeries. La sentencia más sencilla

CREATE TABLE my_table ENGINE=TimeSeries

en realidad creará la siguiente tabla (puedes comprobarlo ejecutando 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

Así que las columnas se generaron automáticamente y, además, hay tres tablas de destino internas con sus propias definiciones de columnas almacenadas en las cláusulas INNER COLUMNS.

Las tablas de destino internas tienen nombres como .inner_id.samples.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx, .inner_id.tags.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx, .inner_id.metrics.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx y cada tabla de destino tiene su propio conjunto de columnas:

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

​

Crear una tabla AS desde una tabla existente

La sentencia CREATE TABLE new_table AS existing_table copia de existing_table:

• SETTINGS
• INNER COLUMNS para cada tipo
• INNER ENGINE para cada tipo

La sentencia no está permitida si existing_table tiene destinos externos. La lista de columnas externa se vuelve a generar y no se copia.

​

Ajuste de los tipos de las columnas

Puede ajustar los tipos de las columnas en las tablas de destino internas mediante la cláusula INNER COLUMNS. Por ejemplo, para almacenar marcas de tiempo en microsegundos y valores como Float32:

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

La misma cláusula puede usarse para especificar códecs y otros atributos de la columna:

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

​

La columna id

La columna id contiene identificadores; cada uno se calcula a partir de una combinación de un nombre de métrica y etiquetas. El tipo y la expresión DEFAULT utilizados para generar los identificadores se pueden personalizar mediante la cláusula TAGS INNER COLUMNS:

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

El tipo de la columna id debe ser uno de estos: UUID, UInt64, UInt128 o FixedString(16). Si no se proporciona ninguna expresión DEFAULT, ClickHouse la elegirá automáticamente en función del tipo de id. Los tipos de id declarados en las tablas internas de samples y etiquetas deben coincidir.

La configuración id_generator permite la misma personalización sin usar la cláusula INNER COLUMNS:

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

Si el ajuste está definido, se usa para generar id incluso si el DEFAULT de la columna contiene otra expresión.

​

Las columnas tags y all_tags

Hay dos columnas que contienen mapas de etiquetas: tags y all_tags. En este ejemplo significan lo mismo; sin embargo, pueden ser diferentes si se usa la configuración tags_to_columns. Esta configuración permite especificar que una etiqueta concreta debe almacenarse en una columna independiente en lugar de almacenarse en un mapa dentro de la columna tags:

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

Esta sentencia añadirá las columnas instance y job a la tabla de destino interna etiquetas. En este caso, la columna tags no contendrá las etiquetas instance y job, pero la columna all_tags sí las contendrá. La columna all_tags es efímera y su único propósito es servir para la expresión DEFAULT de la columna id.

​

Motores de las tablas internas de destino

De forma predeterminada, las tablas internas de destino usan los siguientes motores de tabla:

• la tabla samples usa MergeTree;
• la tabla tags usa AggregatingMergeTree porque los mismos datos suelen insertarse varias veces en esta tabla, por lo que hace falta una forma de eliminar duplicados, y también porque es necesario realizar agregación para las columnas min_time y max_time;
• la tabla metrics usa ReplacingMergeTree porque los mismos datos suelen insertarse varias veces en esta tabla, por lo que hace falta una forma de eliminar duplicados.

También se pueden usar otros motores de tabla para las tablas internas de destino si así se especifica:

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

​

Tablas de destino externas

Es posible hacer que una tabla TimeSeries utilice una tabla creada manualmente:

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;

Los tipos de columna de las tablas externas (id, timestamp, value y las <tag_value_column> enumeradas en tags_to_columns) deben coincidir con los que la tabla TimeSeries generaría internamente en otras circunstancias (consulte tabla Samples, tabla Etiquetas y tabla Metrics para conocer las restricciones de tipo). Las discrepancias de tipo se notifican en el momento de CREATE.

La expresión del generador de id para un destino externo de etiquetas se resuelve en tiempo de INSERT en el siguiente orden: la configuración id_generator (si está establecida), luego el DEFAULT declarado en la columna id de la tabla externa (si existe) y, por último, el generador canónico derivado del tipo de id. Por lo tanto, la configuración sobrescribe cualquier DEFAULT declarado en la tabla externa; consulte La columna id para obtener más detalles.

​

Modificar los ajustes

Se pueden modificar dos ajustes después de CREATE:

• 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;

Ten en cuenta que cambiar id_generator cuando ya hay datos en la tabla de etiquetas puede generar IDs distintos para la misma combinación de métrica+tag: las filas antiguas conservan sus IDs anteriores y las nuevas usan el nuevo generador.

Los demás ajustes no se pueden cambiar con ALTER ... MODIFY SETTING porque quedan incorporados en el esquema de las tablas internas en el momento de CREATE.

​

Configuración

Aquí tienes una lista de configuraciones que se pueden especificar al definir una tabla TimeSeries:

Nombre	Tipo	Predeterminado	Descripción
id_generator	Expression	depende del tipo de id	Expresión que calcula el identificador (huella) de una serie temporal a partir de sus etiquetas. Si no se establece, se usa la expresión predeterminada para la columna id. Si la expresión predeterminada para la columna id tampoco está establecida, la expresión se elige automáticamente
tags_to_columns	Map	Map que especifica qué etiquetas deben colocarse en columnas independientes en la tabla tags. Sintaxis: {'tag1': 'column1', 'tag2' : column2, ...}
use_all_tags_column_to_generate_id	Bool	true	Al generar una expresión para calcular el identificador de una serie temporal, esta opción permite usar la columna all_tags en ese cálculo
store_min_time_and_max_time	Bool	true	Si se establece en true, la tabla almacenará min_time y max_time para cada serie temporal
aggregate_min_time_and_max_time	Bool	true	Al crear una tabla tags interna de destino, esta opción permite usar SimpleAggregateFunction(min, Nullable(DateTime64(3))) en lugar de solo Nullable(DateTime64(3)) como tipo de la columna min_time, y lo mismo para la columna max_time
filter_by_min_time_and_max_time	Bool	true	Si se establece en true, la tabla usará las columnas min_time y max_time para filtrar las series temporales

​

Funciones

Aquí tienes una lista de funciones que admiten una tabla TimeSeries como argumento:

• timeSeriesSamples
• timeSeriesTags
• timeSeriesMetrics