> ## Documentation Index > Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-fbfa8bee.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. > Un motor de tabla que almacena series temporales, es decir, un conjunto de valores asociados a marcas de tiempo y etiquetas (o labels). # motor de tabla TimeSeries export const CloudNotSupportedBadge = () => { return
No es compatible con ClickHouse Cloud
; }; export const ExperimentalBadge = () => { return
Funcionalidad experimental. Más información.
; }; Un motor de tabla que almacena series temporales, es decir, un conjunto de valores asociados a marcas de tiempo y etiquetas (o labels): ```sql theme={null} 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](/es/reference/settings/session-settings#allow_experimental_time_series_table). Ejecute el comando `set allow_experimental_time_series_table = 1`.
## Sintaxis
```sql theme={null} 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): ```sql theme={null} 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](/es/concepts/features/interfaces/prometheus#remote-write) * [prometheus remote-read](/es/concepts/features/interfaces/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](#target-tables). 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](#specifying-outer-columns)) | | `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: ```sql theme={null} 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: ```sql theme={null} 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`: ```sql theme={null} 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: ```sql theme={null} 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: ```sql theme={null} 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](/es/reference/statements/create/view#materialized-view), 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](#samples-table), [etiqueta](#tags-table) y [metrics](#metrics-table). 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](#samples-table)) | 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 | | `` | \[ ] | `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](#settings) | | `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](#settings) | | `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](#settings) 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](#settings) 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 ```sql theme={null} CREATE TABLE my_table ENGINE=TimeSeries ``` en realidad creará la siguiente tabla (puedes comprobarlo ejecutando `SHOW CREATE TABLE my_table`): ```sql theme={null} 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: ```sql theme={null} CREATE TABLE default.`.inner_id.samples.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` 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`: ```sql theme={null} 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: ```sql theme={null} 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`: ```sql theme={null} 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`: ```sql theme={null} 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`: ```sql theme={null} 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](#tags-table). 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](#samples-table) usa [MergeTree](/es/reference/engines/table-engines/mergetree-family/mergetree); * la tabla [tags](#tags-table) usa [AggregatingMergeTree](/es/reference/engines/table-engines/mergetree-family/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](#metrics-table) usa [ReplacingMergeTree](/es/reference/engines/table-engines/mergetree-family/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: ```sql theme={null} 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: ```sql theme={null} 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 `` enumeradas en [`tags_to_columns`](#settings)) deben coincidir con los que la tabla `TimeSeries` generaría internamente en otras circunstancias (consulte [tabla Samples](#samples-table), [tabla Etiquetas](#tags-table) y [tabla Metrics](#metrics-table) 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`](#settings) (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`](#id-column) 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` ```sql theme={null} 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](#tags-table). 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](/es/reference/functions/table-functions/timeSeriesSamples) * [timeSeriesTags](/es/reference/functions/table-functions/timeSeriesTags) * [timeSeriesMetrics](/es/reference/functions/table-functions/timeSeriesMetrics)