Funções para trabalhar com séries temporais

Documentação de funções para trabalhar com séries temporais

As funções abaixo foram projetadas para uso com funções de agregação timeSeries*(), como timeSeriesInstantRateToGrid, timeSeriesLastToGrid, entre outras.

​

seriesDecomposeSTL

Introduzido em: v24.1.0

Decompõe uma série de dados usando STL (Procedimento de Decomposição Sazonal-Tendência Baseado em Loess) em sazonalidade, tendência e um componente residual.

Sintaxe

seriesDecomposeSTL(series, period)

Argumentos

• series — Um array de valores numéricos Array((U)Int8/16/32/64) ou Array(Float*)
• period — Um inteiro positivo UInt8/16/32/64

Valor retornado

Retorna um array de quatro arrays, em que o primeiro contém os componentes sazonais, o segundo, a tendência, o terceiro, o componente residual, e o quarto, o componente de linha de base (sazonal + tendência). Array(Array(Float32), Array(Float32), Array(Float32), Array(Float32))

Exemplos

Decompor dados de série temporal usando STL

Query

SELECT seriesDecomposeSTL([10.1, 20.45, 40.34, 10.1, 20.45, 40.34, 10.1, 20.45, 40.34, 10.1, 20.45, 40.34, 10.1, 20.45, 40.34, 10.1, 20.45, 40.34, 10.1, 20.45, 40.34, 10.1, 20.45, 40.34], 3) AS print_0

Response

┌───────────print_0──────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ [[
        -13.529999, -3.1799996, 16.71,      -13.53,     -3.1799996, 16.71,      -13.53,     -3.1799996,
        16.71,      -13.530001, -3.18,      16.710001,  -13.530001, -3.1800003, 16.710001,  -13.530001,
        -3.1800003, 16.710001,  -13.530001, -3.1799994, 16.71,      -13.529999, -3.1799994, 16.709997
    ],
    [
        23.63,     23.63,     23.630003, 23.630001, 23.630001, 23.630001, 23.630001, 23.630001,
        23.630001, 23.630001, 23.630001, 23.63,     23.630001, 23.630001, 23.63,     23.630001,
        23.630001, 23.63,     23.630001, 23.630001, 23.630001, 23.630001, 23.630001, 23.630003
    ],
    [
        0, 0.0000019073486, -0.0000019073486, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, -0.0000019073486, 0,
        0
    ],
    [
        10.1, 20.449999, 40.340004, 10.100001, 20.45, 40.34, 10.100001, 20.45, 40.34, 10.1, 20.45, 40.34,
        10.1, 20.45, 40.34, 10.1, 20.45, 40.34, 10.1, 20.45, 40.34, 10.100002, 20.45, 40.34
    ]]                                                                                                                   │
└────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

​

seriesOutliersDetectTukey

Introduzido em: v24.2.0

Detecta valores atípicos em dados de séries temporais usando Tukey Fences.

Sintaxe

seriesOutliersDetectTukey(series[, min_percentile, max_percentile, K])

Argumentos

• series — Um array de valores numéricos. Array((UInt8/16/32/64)) ou Array(Float*)
• min_percentile — Opcional. O percentil mínimo a ser usado para calcular o intervalo interquartil (IQR). O valor deve estar no intervalo [0.02,0.98]. O padrão é 0.25. Float*
• max_percentile — Opcional. O percentil máximo a ser usado para calcular o intervalo interquartil (IQR). O valor deve estar no intervalo [0.02,0.98]. O padrão é 0.75. Float*
• K — Opcional. Valor constante não negativo para detectar outliers leves ou mais severos. O valor padrão é 1.5. Float*

Valor retornado

Retorna um array com o mesmo comprimento do array de entrada, em que cada valor representa a pontuação de uma possível anomalia do elemento correspondente na série. Uma pontuação diferente de zero indica uma possível anomalia. Array(Float32)

Exemplos

Detecção básica de outliers

Query

SELECT seriesOutliersDetectTukey([-3, 2, 15, 3, 5, 6, 4, 5, 12, 45, 12, 3, 3, 4, 5, 6]) AS print_0

Response

┌───────────print_0─────────────────┐
│[0,0,0,0,0,0,0,0,0,27,0,0,0,0,0,0] │
└───────────────────────────────────┘

Detecção de valores atípicos com parâmetros personalizados

Query

SELECT seriesOutliersDetectTukey([-3, 2, 15, 3, 5, 6, 4.50, 5, 12, 45, 12, 3.40, 3, 4, 5, 6], 0.2, 0.8, 1.5) AS print_0

Response

┌─print_0──────────────────────────────┐
│ [0,0,0,0,0,0,0,0,0,19.5,0,0,0,0,0,0] │
└──────────────────────────────────────┘

​

seriesPeriodDetectFFT

Introduzido em: v23.12.0

Encontra o período dos dados de série temporal fornecidos usando FFT - Transformada rápida de Fourier

Sintaxe

seriesPeriodDetectFFT(series)

Argumentos

• series — Um array de valores numéricos. Array((U)Int8/16/32/64) ou Array(Float*)

Valor retornado

Retorna um valor real igual ao período da série. NaN quando o número de pontos de dados é menor que quatro. Float64

Exemplos

Detecção de período com padrão simples

Query

SELECT seriesPeriodDetectFFT([1, 4, 6, 1, 4, 6, 1, 4, 6, 1, 4, 6, 1, 4, 6, 1, 4, 6, 1, 4, 6]) AS print_0

Response

┌───────────print_0──────┐
│                      3 │
└────────────────────────┘

Detecção de período usando padrão complexo

Query

SELECT seriesPeriodDetectFFT(arrayMap(x -> abs((x % 6) - 3), range(1000))) AS print_0

Response

┌─print_0─┐
│       6 │
└─────────┘

​

timeSeriesCopyTag

Introduzido em: v26.1.0

Copia uma tag específica de um grupo de tags (src_group) para outro (dest_group). A função substitui todos os valores anteriores da tag copiada em dest_group. Se a tag copiada não estiver presente em src_group, a função também a removerá de dest_group. A função imita a lógica de cópia dos modificadores group left/group right do Prometheus.

Sintaxe

timeSeriesCopyTag(dest_group, src_group, tag_to_copy)

Argumentos

• dest_group — O grupo de tags de destino. UInt64
• src_group — O grupo de tags de origem. UInt64
• tag_to_copy — O nome da tag a ser copiada. String

Valor retornado

Retorna um grupo de tags que contém as tags de dest_group, junto com as tags copiadas de src_group. UInt64

Exemplos

Exemplo

Query

SELECT timeSeriesTagsToGroup([('region', 'eu'), ('env', 'dev')], '__name__', 'http_requests_count') AS dest_group,
       timeSeriesTagsToGroup([('code', '404'), ('message', 'Page not found')], '__name__', 'http_codes') AS src_group,
       timeSeriesCopyTag(dest_group, src_group, '__name__') AS result_group,
       timeSeriesGroupToTags(result_group)

Response

┌─dest_group─┬─src_group─┬─result_group─┬─timeSeriesGroupToTags(result_group)────────────────────────┐
│          1 │         2 │            3 │ [('__name__','http_codes'),('code','404'),('region','eu')] │
└────────────┴───────────┴──────────────┴────────────────────────────────────────────────────────────┘

​

timeSeriesCopyTags

Introduzido em: v26.1.0

Copia as tags especificadas de um grupo de tags (src_group) para outro (dest_group). A função substitui quaisquer valores anteriores das tags copiadas em dest_group. Se algumas das tags copiadas não estiverem presentes em src_group, a função também as removerá de dest_group. A função reproduz a lógica de cópia dos modificadores group left/group right do Prometheus.

Sintaxe

timeSeriesCopyTags(dest_group, src_group, tags_to_copy)

Argumentos

• dest_group — O grupo de tags de destino. UInt64
• src_group — O grupo de tags de origem. UInt64
• tags_to_copy — Os nomes das tags a copiar. Array(String)

Valor retornado

Retorna um grupo de tags que contém as tags de dest_group junto com as tags copiadas de src_group. UInt64

Exemplos

Exemplo

Query

SELECT timeSeriesTagsToGroup([('region', 'eu'), ('env', 'dev')], '__name__', 'http_requests_count') AS dest_group,
       timeSeriesTagsToGroup([('code', '404'), ('message', 'Page not found')], '__name__', 'http_codes') AS src_group,
       timeSeriesCopyTags(dest_group, src_group, ['__name__', 'code', 'env']) AS result_group,
       timeSeriesGroupToTags(result_group)

Response

┌─dest_group─┬─src_group─┬─result_group─┬─timeSeriesGroupToTags(result_group)────────────────────────┐
│          1 │         2 │            3 │ [('__name__','http_codes'),('code','404'),('region','eu')] │
└────────────┴───────────┴──────────────┴────────────────────────────────────────────────────────────┘

​

timeSeriesExtractTag

Introduzida na versão: v26.1.0

Extrai o valor de uma tag específica do grupo. Retorna NULL se não for encontrada. Veja também a função timeSeriesGroupToTags().

Sintaxe

timeSeriesExtractTag(group)

Argumentos

• group — Um grupo de tags. UInt64
• tag_to_extract — O nome de uma tag a ser extraída do grupo String

Valor retornado

Retorna o valor da tag especificada. Nullable(String)

Exemplos

Exemplo

Query

SELECT timeSeriesTagsToGroup([('region', 'eu'), ('env', 'dev')], '__name__', 'http_requests_count') AS group,
       timeSeriesExtractTag(group, '__name__'),
       timeSeriesExtractTag(group, 'env'),
       timeSeriesExtractTag(group, 'instance')

Response

┌─group─┬─timeSeriesExtractTag(group, '__name__')─┬─timeSeriesExtractTag(group, 'env')─┬─timeSeriesExtractTag(group, 'instance')─┐
│     1 │ http_requests_count                     │ dev                                │ ᴺᵁᴸᴸ                                    │
└───────┴─────────────────────────────────────────┴────────────────────────────────────┴─────────────────────────────────────────┘

​

timeSeriesFromGrid

Introduzido em: v25.8.0

Converte um array de valores [x1, x2, x3, ...] em um array de tuplas [(start_timestamp, x1), (start_timestamp + step, x2), (start_timestamp + 2 * step, x3), ...].

O timestamp atual é incrementado em step até ficar maior que end_timestamp Se a quantidade de valores não corresponder à quantidade de timestamps, a função lança uma exceção.

Valores NULL em [x1, x2, x3, ...] são ignorados, mas o timestamp atual ainda é incrementado. Por exemplo, para [value1, NULL, x2], a função retorna [(start_timestamp, x1), (start_timestamp + 2 * step, x2)].

Sintaxe

timeSeriesFromGrid(start_timestamp, end_timestamp, step, values)

Argumentos

• start_timestamp — Início da grade temporal. DateTime64 ou DateTime ou UInt32
• end_timestamp — Fim da grade temporal. DateTime64 ou DateTime ou UInt32
• step — passo da grade temporal em segundos Decimal64 ou Decimal32 ou UInt32/64
• values — Array de valores Array(Float*) ou Array(Nullable(Float*))

Valor retornado

Retorna valores do array de origem combinados com timestamps em uma grade temporal regular descrita por start_timestamp e step. Array(Tuple(DateTime64, Float64))

Exemplos

Exemplo de uso

Query

SELECT timeSeriesFromGrid('2025-06-01 00:00:00'::DateTime64(3), '2025-06-01 00:01:30.000'::DateTime64(3), 30, [10, 20, NULL, 30]) AS result;

Response

┌─────────────────────────────────────────────result─────────────────────────────────────────────┐
│ [('2025-06-01 00:00:00.000',10),('2025-06-01 00:00:30.000',20),('2025-06-01 00:01:30.000',30)] │
└────────────────────────────────────────────────────────────────────────────────────────────────┘

​

timeSeriesGroupToSamplingKey

Introduzido em: v26.4.0

Retorna uma chave de amostragem UInt64 estável derivada das tags de um grupo especificado.

O valor é determinístico: tags de entrada idênticas sempre produzem a mesma chave. Ela foi projetada para ser usada como chave de ordenação para operadores de amostragem como limitk e limit_ratio.

Sintaxe

timeSeriesGroupToSamplingKey(group)

Argumentos

• group — Um grupo de tags. UInt64

Valor retornado

Um hash UInt64 estável derivado das tags associadas ao grupo. UInt64

Exemplos

Exemplo

Query

SELECT timeSeriesTagsToGroup([('region', 'eu'), ('env', 'dev')], '__name__', 'http_requests_count') AS group,
       timeSeriesGroupToSamplingKey(group) AS sampling_key

Response

┌─group─┬─────────sampling_key─┐
│     1 │ 12876543210987654321 │
└───────┴──────────────────────┘

​

timeSeriesGroupToTags

Introduzido em: v26.1.0

Retorna os nomes e valores das tags associadas a um grupo especificado. Veja também a função timeSeriesTagsToGroup().

Sintaxe

timeSeriesGroupToTags(group)

Nomes alternativos: timeSeriesTagsGroupToTags

Argumentos

• group — Um grupo de tags. UInt64

Valor retornado

Retorna um array de pares (tag_name, tag_value). O array retornado é sempre ordenado por tag_name e nunca contém o mesmo tag_name mais de uma vez. Array(Tuple(String, String))

Exemplos

Exemplo

Query

SELECT timeSeriesTagsToGroup([('region', 'eu'), ('env', 'dev')], '__name__', 'http_requests_count') AS group,
       timeSeriesGroupToTags(group) AS sorted_tags,
       timeSeriesTagsToGroup(sorted_tags) AS same_group,
       throwIf(same_group != group)

Response

┌─group─┬─sorted_tags────────────────────────────────────────────────────────┬─same_group─┬─throwIf(notE⋯up, group))─┐
│     1 │ [('__name__','http_requests_count'),('env','dev'),('region','eu')] │          1 │                        0 │
└───────┴────────────────────────────────────────────────────────────────────┴────────────┴──────────────────────────┘

​

timeSeriesIdToGroup

Introduzido em: v26.1.0

Retorna os nomes e os valores das tags associadas ao identificador especificado de uma série temporal. Consulte também a função timeSeriesStoreTags().

Sintaxe

timeSeriesIdToGroup(id)

Aliases: timeSeriesIdToTagsGroup

Argumentos

• id — Identificador de uma série temporal. UInt64 ou UInt128 ou UUID ou FixedString(16)

Valor retornado

Retorna um grupo de tags associado ao identificador id de uma série temporal. UInt64

Exemplos

Exemplo

Query

SELECT 8374283493092 AS id,
       timeSeriesStoreTags(id, [('region', 'eu'), ('env', 'dev')], '__name__', 'http_requests_count') AS same_id,
       throwIf(same_id != id),
       timeSeriesIdToGroup(same_id) AS group,
       timeSeriesGroupToTags(group)

Response

┌────────────id─┬───────same_id─┬─throwIf(notE⋯me_id, id))─┬─group─┬─timeSeriesGroupToTags(group)───────────────────────────────────────┐
│ 8374283493092 │ 8374283493092 │                        0 │     1 │ [('__name__','http_requests_count'),('env','dev'),('region','eu')] │
└───────────────┴───────────────┴──────────────────────────┴───────┴────────────────────────────────────────────────────────────────────┘

​

timeSeriesIdToTags

Introduzido em: v25.8.0

Retorna as tags associadas a um identificador específico de uma série temporal. Veja também a função timeSeriesStoreTags().

Sintaxe

timeSeriesIdToTags(id)

Argumentos

• id — Identificador de uma série temporal. UInt64 ou UInt128 ou UUID ou FixedString(16)

Valor retornado

Retorna um array de pares (tag_name, tag_value). O array retornado é sempre ordenado por tag_name e nunca contém o mesmo tag_name mais de uma vez. Array(Tuple(String, String))

Exemplos

Exemplo

Query

SELECT 8374283493092 AS id,
       timeSeriesStoreTags(id, [('region', 'eu'), ('env', 'dev')], '__name__', 'http_requests_count') AS same_id,
       throwIf(same_id != id),
       timeSeriesIdToTags(same_id)

Response

┌────────────id─┬───────same_id─┬─throwIf(notE⋯me_id, id))─┬─timeSeriesIdToTags(same_id)────────────────────────────────────────┐
│ 8374283493092 │ 8374283493092 │                        0 │ [('__name__','http_requests_count'),('env','dev'),('region','eu')] │
└───────────────┴───────────────┴──────────────────────────┴────────────────────────────────────────────────────────────────────┘

​

timeSeriesJoinTags

Introduzido em: v26.1.0

Une os valores das tags especificadas extraídas de um grupo de tags. A função insere um separador entre os valores concatenados e retorna um novo grupo de tags com a tag dest_tag definida como o valor concatenado. Esta função reproduz a lógica da função do Prometheus label_join().

Sintaxe

timeSeriesJoinTags(group, dest_tag, separator, src_tags)

Argumentos

• group — Um grupo de tags. UInt64
• dest_tag — O nome de uma tag com o resultado concatenado que será adicionada ao group. String
• separator — Um separador a ser inserido entre os valores concatenados. String
• src_tags — Os nomes das tags de origem com valores que serão concatenados. Array(String)

Valor retornado

Retorna um novo grupo de tags com a tag dest_tag definida como o resultado concatenado. UInt64

Exemplos

Exemplo

Query

SELECT timeSeriesTagsToGroup([('__name__', 'up'), ('job', 'api-server'), ('src1', 'a'), ('src2', 'b'), ('src3', 'c')]) AS group,
       timeSeriesJoinTags(group, 'foo', ',', ['src1', 'src2', 'src3']) AS result_group,
       timeSeriesGroupToTags(result_group)

Response

┌─group─┬─result_group─┬─timeSeriesGroupToTags(result_group)─────────────────────────────────────────────────────────────┐
│     1 │            2 │ [('__name__','up'),('foo','a,b,c'),('job','api-server'),('src1','a'),('src2','b'),('src3','c')] │
└───────┴──────────────┴─────────────────────────────────────────────────────────────────────────────────────────────────┘

​

timeSeriesRange

Introduzido em: v25.8.0

Gera uma sequência de timestamps [start_timestamp, start_timestamp + step, start_timestamp + 2 * step, …, end_timestamp].

Se start_timestamp for igual a end_timestamp, a função retorna um array de 1 elemento contendo [start_timestamp].

A função timeSeriesRange() é semelhante à função range.

Sintaxe

timeSeriesRange(start_timestamp, end_timestamp, step)

Argumentos

• start_timestamp — Início do intervalo. DateTime64 ou DateTime ou UInt32
• end_timestamp — Fim do intervalo. DateTime64 ou DateTime ou UInt32
• step — Passo do intervalo, em segundos. UInt32/64 ou Decimal32/64

Valor retornado

Retorna um intervalo de timestamps. Array(DateTime64)

Exemplos

Exemplo de uso

Query

SELECT timeSeriesRange('2025-06-01 00:00:00'::DateTime64(3), '2025-06-01 00:01:00'::DateTime64(3), 30)

Response

┌────────────────────────────────────result─────────────────────────────────────────┐
│ ['2025-06-01 00:00:00.000', '2025-06-01 00:00:30.000', '2025-06-01 00:01:00.000'] │
└───────────────────────────────────────────────────────────────────────────────────┘

​

timeSeriesRemoveAllTagsExcept

Introduzido em: v26.1.0

Remove todas as tags, exceto as especificadas, de um grupo de tags. Veja também a função timeSeriesRemoveTag(), timeSeriesRemoveTags().

Sintaxe

timeSeriesRemoveAllTagsExcept(group, tags_to_keep)

Argumentos

• group — Um grupo de tags. UInt64
• tags_to_keep — Os nomes das tags a serem mantidas no grupo. Array(String)

Valor retornado

Um novo grupo de tags contendo apenas as tags especificadas. UInt64

Exemplos

Exemplo

Query

SELECT timeSeriesTagsToGroup([('region', 'eu'), ('env', 'dev')], '__name__', 'http_requests_count') AS group,
       timeSeriesRemoveAllTagsExcept(group, ['env']) AS result_group,
       timeSeriesGroupToTags(result_group)

Response

┌─group─┬─result_group─┬─timeSeriesGroupToTags(result_group)─┐
│     1 │            2 │ [('env','dev')]                     │
└───────┴──────────────┴─────────────────────────────────────┘

​

timeSeriesRemoveTag

Introduzido em: v26.1.0

Remove uma tag específica de um grupo de tags. Se essa tag não existir no grupo, ele será retornado sem alterações. Veja também as funções timeSeriesRemoveTags(), timeSeriesRemoveAllTagsExcept().

Sintaxe

timeSeriesRemoveTag(group, tag_to_remove)

Argumentos

• group — Um grupo de tags. UInt64
• tag_to_remove — O nome de uma tag a ser removida do grupo. String

Valor retornado

Um novo grupo de tags sem a tag especificada. UInt64

Exemplos

Exemplo

Query

SELECT timeSeriesTagsToGroup([('region', 'eu'), ('env', 'dev')], '__name__', 'http_requests_count') AS group_of_3,
       timeSeriesRemoveTag(group_of_3, '__name__') AS group_of_2,
       timeSeriesGroupToTags(group_of_2),
       timeSeriesRemoveTag(group_of_2, 'env') AS group_of_1,
       timeSeriesGroupToTags(group_of_1),
       timeSeriesRemoveTag(group_of_1, 'region') AS empty_group,
       timeSeriesGroupToTags(empty_group)

Response

┌─group_of_3─┬─group_of_2─┬─timeSeriesGroupToTags(group_of_2)─┬─group_of_1─┬─timeSeriesGroupToTags(group_of_1)─┬─empty_group─┬─timeSeriesGroupToTags(empty_group)─┐
│          1 │          2 │ [('env','dev'),('region','eu')]   │          3 │ [('region','eu')]                 │           0 │ []                                 │
└────────────┴────────────┴───────────────────────────────────┴────────────┴───────────────────────────────────┴─────────────┴────────────────────────────────────┘

​

timeSeriesRemoveTags

Introduzido em: v26.1.0

Remove as tags especificadas de um grupo de tags. Se algumas das tags especificadas não estiverem no grupo, a função as ignorará. Consulte também a função timeSeriesRemoveTag(), timeSeriesRemoveAllTagsExcept().

Sintaxe

timeSeriesRemoveTags(group, tags_to_remove)

Argumentos

• group — Um grupo de tags. UInt64
• tags_to_remove — Os nomes das tags a serem removidas do grupo. Array(String)

Valor retornado

Um novo grupo de tags sem as tags especificadas. UInt64

Exemplos

Exemplo

Query

SELECT timeSeriesTagsToGroup([('region', 'eu'), ('env', 'dev')], '__name__', 'http_requests_count') AS group_of_3,
       timeSeriesRemoveTags(group_of_3, ['env', 'region']) AS group_of_1,
       timeSeriesGroupToTags(group_of_1),
       timeSeriesRemoveTags(group_of_1, ['__name__', 'nonexistent']) AS empty_group,
       timeSeriesGroupToTags(empty_group)

Response

┌─group_of_3─┬─group_of_1─┬─timeSeriesGroupToTags(group_of_1)────┬─empty_group─┬─timeSeriesGroupToTags(empty_group)─┐
│          1 │          2 │ [('__name__','http_requests_count')] │           0 │ []                                 │
└────────────┴────────────┴──────────────────────────────────────┴─────────────┴────────────────────────────────────┘

​

timeSeriesReplaceTag

Introduzido em: v26.1.0

Compara a expressão regular regex com o valor da tag src_tag. Se houver correspondência, o valor da tag dest_tag no grupo retornado será a expansão de replacement, junto com as tags originais da entrada. Esta função reproduz a lógica da função do Prometheus label_replace().

Sintaxe

timeSeriesReplaceTag(group, dest_tag, replacement, src_tag, regex)

Argumentos

• group — Um grupo de tags. UInt64
• dest_tag — O nome de uma tag de destino para receber o grupo resultante. String
• replacement — Um padrão de substituição; pode conter $1,$2 ou $name para se referir a grupos de captura na expressão regular ‘regex’. String
• src_tag — O nome de uma tag cujo valor é usado para fazer a correspondência com a expressão regular ‘regex’. String
• regex — Uma expressão regular. String

Valor retornado

Um novo grupo de tags, possivelmente com dest_tag adicionada. UInt64

Exemplos

Exemplo

Query

SELECT timeSeriesTagsToGroup([('__name__', 'up'), ('job', 'api-server'), ('service', 'a:c')]) AS group,
       timeSeriesReplaceTag(group, 'foo', '$1', 'service', '(.*):.*') AS result_group,
       timeSeriesGroupToTags(result_group)

Response

┌─group─┬─result_group─┬─timeSeriesGroupToTags(result_group)────────────────────────────────────┐
│     1 │            2 │ [('__name__','up'),('foo','a'),('job','api-server'),('service','a:c')] │
└───────┴──────────────┴────────────────────────────────────────────────────────────────────────┘

​

timeSeriesStoreTags

Introduzido em: v25.8.0

Armazena, no contexto da consulta, um mapeamento entre um identificador especificado de série temporal e um conjunto de tags. As funções timeSeriesIdToTags() e timeSeriesIdToGroup() podem ser usadas para acessar esse mapeamento posteriormente durante a execução da consulta.

Sintaxe

timeSeriesStoreTags(id, tags_array, separate_tag_name_1, separate_tag_value_1, ...)

Argumentos

• id — Identificador de uma série temporal. UInt64 ou UInt128 ou UUID ou FixedString(16)
• tags_array — Array de pares (tag_name, tag_value). Array(Tuple(String, String)) ou NULL
• separate_tag_name_i — O nome de uma tag. String ou FixedString
• separate_tag_value_i — O valor de uma tag. String ou FixedString ou Nullable(String)

Valor retornado

Retorna o identificador de uma série temporal (isto é, apenas o primeiro argumento).

Exemplos

Exemplo

Query

SELECT 8374283493092 AS id,
       timeSeriesStoreTags(id, [('region', 'eu'), ('env', 'dev')], '__name__', 'http_requests_count') AS same_id,
       throwIf(same_id != id),
       timeSeriesIdToTags(same_id),
       timeSeriesGroupToTags(timeSeriesIdToGroup(same_id))

Response

┌────────────id─┬───────same_id─┬─throwIf(notEquals(same_id, id))─┬─timeSeriesIdToTags(same_id)────────────────────────────────────────┬─timeSeriesGroupToTags(timeSeriesIdToGroup(same_id))────────────────┐
│ 8374283493092 │ 8374283493092 │                               0 │ [('__name__','http_requests_count'),('env','dev'),('region','eu')] │ [('__name__','http_requests_count'),('env','dev'),('region','eu')] │
└───────────────┴───────────────┴─────────────────────────────────┴────────────────────────────────────────────────────────────────────┴────────────────────────────────────────────────────────────────────┘

​

timeSeriesTagsToGroup

Introduzido em: v26.1.0

Retorna um grupo de tags associado às tags especificadas. Se o mesmo grupo de tags for encontrado várias vezes durante a execução da consulta, a função retornará o mesmo grupo. Para um conjunto vazio de tags, a função sempre retorna 0. Veja também a função timeSeriesGroupToTags().

Sintaxe

timeSeriesTagsToGroup(tags_array, tag_name_1, tag_value_1, tag_name2, tag_value2, ...)

Argumentos

• tags_array — Array de pares (tag_name, tag_value). Array(Tuple(String, String)) ou NULL
• tag_name_i — O nome de uma tag. String ou FixedString
• tag_value_i — O valor de uma tag. String ou FixedString ou Nullable(String)

Valor retornado

Retorna um grupo de tags associado às tags especificadas. UInt64

Exemplos

Exemplo

Query

SELECT timeSeriesTagsToGroup([('region', 'eu'), ('env', 'dev')], '__name__', 'http_requests_count') AS group1,
       timeSeriesTagsToGroup([], '__name__', 'http_failures') AS group2,
       timeSeriesTagsToGroup([]) AS empty_group,
       timeSeriesTagsToGroup([], '__name__', 'http_failures') AS same_group2,
       throwIf(same_group2 != group2),
       timeSeriesGroupToTags(group2)

Response

┌─group1─┬─group2─┬─empty_group─┬─same_group2─┬─throwIf(notEquals(same_group2, group2))─┬─timeSeriesGroupToTags(group2)──┐
│      1 │      2 │           0 │           2 │                                       0 │ [('__name__','http_failures')] │
└────────┴────────┴─────────────┴─────────────┴─────────────────────────────────────────┴────────────────────────────────┘

​

timeSeriesThrowDuplicateSeriesIf

Introduzido em: v26.2.0

Verifica a condition e, se ela for verdadeira, lança uma exceção com a seguinte mensagem: Multiple series have the same tags <tags>, duplicate series in the same result set are not allowed. Se a condition for falsa, a função retorna 0. Esta função é semelhante a throwIf(), mas usa um código de erro diferente e formata a mensagem de erro de outra maneira.

Sintaxe

timeSeriesThrowDuplicateSeriesIf(condition, group)

Argumentos

• condition — Condição a ser verificada, geralmente contém a função count() UInt8
• group — Grupo de tags. UInt64

Valor retornado

Retorna 0. UInt8

Exemplos

Exemplo

Query

CREATE TABLE test(tags Array(Tuple(String, String))) engine=Memory;

INSERT INTO test VALUES ([('__name__', 'up')]);

SELECT timeSeriesTagsToGroup(tags) AS group
FROM test
GROUP BY group
HAVING timeSeriesThrowDuplicateSeriesIf(count() > 1, group) = 0;  -- OK

INSERT INTO test VALUES ([('__name__', 'up')]);

SELECT timeSeriesTagsToGroup(tags) AS group
FROM test
GROUP BY group
HAVING timeSeriesThrowDuplicateSeriesIf(count() > 1, group) = 0;  -- Lança exceção "Multiple series have the same tags {'__name__': 'up'}"

Response