> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-fix-nav-issues.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

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

# 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`](/pt-BR/reference/functions/aggregate-functions/timeSeriesInstantRateToGrid),
[`timeSeriesLastToGrid`](/pt-BR/reference/functions/aggregate-functions/timeSeriesResampleToGridWithStaleness),
entre outras.

{/*AUTOGENERATED_START*/}

<div id="seriesDecomposeSTL">
  ## seriesDecomposeSTL
</div>

Introduzido em: v24.1.0

Decompõe uma série de dados usando STL [(Procedimento de Decomposição Sazonal-Tendência Baseado em Loess)](https://www.wessa.net/download/stl.pdf) em sazonalidade, tendência e um componente residual.

**Sintaxe**

```sql theme={null}
seriesDecomposeSTL(series, period)
```

**Argumentos**

* `series` — Um array de valores numéricos [`Array((U)Int8/16/32/64)`](/pt-BR/reference/data-types/array) ou [`Array(Float*)`](/pt-BR/reference/data-types/array)
* `period` — Um inteiro positivo [`UInt8/16/32/64`](/pt-BR/reference/data-types/int-uint)

**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))`](/pt-BR/reference/data-types/array)

**Exemplos**

**Decompor dados de série temporal usando STL**

```sql title=Query theme={null}
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 title=Response theme={null}
┌───────────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
    ]]                                                                                                                   │
└────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
```

<div id="seriesOutliersDetectTukey">
  ## seriesOutliersDetectTukey
</div>

Introduzido em: v24.2.0

Detecta valores atípicos em dados de séries temporais usando [Tukey Fences](https://en.wikipedia.org/wiki/Outlier#Tukey%27s_fences).

**Sintaxe**

```sql theme={null}
seriesOutliersDetectTukey(series[, min_percentile, max_percentile, K])
```

**Argumentos**

* `series` — Um array de valores numéricos. [`Array((UInt8/16/32/64))`](/pt-BR/reference/data-types/array) ou [`Array(Float*)`](/pt-BR/reference/data-types/array)
* `min_percentile` — Opcional. O percentil mínimo a ser usado para calcular o intervalo interquartil [(IQR)](https://en.wikipedia.org/wiki/Interquartile_range). O valor deve estar no intervalo \[0.02,0.98]. O padrão é 0.25. [`Float*`](/pt-BR/reference/data-types/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*`](/pt-BR/reference/data-types/float)
* `K` — Opcional. Valor constante não negativo para detectar outliers leves ou mais severos. O valor padrão é 1.5. [`Float*`](/pt-BR/reference/data-types/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)`](/pt-BR/reference/data-types/array)

**Exemplos**

**Detecção básica de outliers**

```sql title=Query theme={null}
SELECT seriesOutliersDetectTukey([-3, 2, 15, 3, 5, 6, 4, 5, 12, 45, 12, 3, 3, 4, 5, 6]) AS print_0
```

```response title=Response theme={null}
┌───────────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**

```sql title=Query theme={null}
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 title=Response theme={null}
┌─print_0──────────────────────────────┐
│ [0,0,0,0,0,0,0,0,0,19.5,0,0,0,0,0,0] │
└──────────────────────────────────────┘
```

<div id="seriesPeriodDetectFFT">
  ## seriesPeriodDetectFFT
</div>

Introduzido em: v23.12.0

Encontra o período dos dados de série temporal fornecidos usando FFT - [Transformada rápida de Fourier](https://en.wikipedia.org/wiki/Fast_Fourier_transform)

**Sintaxe**

```sql theme={null}
seriesPeriodDetectFFT(series)
```

**Argumentos**

* `series` — Um array de valores numéricos. [`Array((U)Int8/16/32/64)`](/pt-BR/reference/data-types/array) ou [`Array(Float*)`](/pt-BR/reference/data-types/array)

**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`](/pt-BR/reference/data-types/float)

**Exemplos**

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

```sql title=Query theme={null}
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 title=Response theme={null}
┌───────────print_0──────┐
│                      3 │
└────────────────────────┘
```

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

```sql title=Query theme={null}
SELECT seriesPeriodDetectFFT(arrayMap(x -> abs((x % 6) - 3), range(1000))) AS print_0
```

```response title=Response theme={null}
┌─print_0─┐
│       6 │
└─────────┘
```

<div id="timeSeriesCopyTag">
  ## timeSeriesCopyTag
</div>

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](https://prometheus.io/docs/prometheus/latest/querying/operators/#group-modifiers) do Prometheus.

**Sintaxe**

```sql theme={null}
timeSeriesCopyTag(dest_group, src_group, tag_to_copy)
```

**Argumentos**

* `dest_group` — O grupo de tags de destino. [`UInt64`](/pt-BR/reference/data-types/int-uint)
* `src_group` — O grupo de tags de origem. [`UInt64`](/pt-BR/reference/data-types/int-uint)
* `tag_to_copy` — O nome da tag a ser copiada. [`String`](/pt-BR/reference/data-types/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`](/pt-BR/reference/data-types/int-uint)

**Exemplos**

**Exemplo**

```sql title=Query theme={null}
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 title=Response theme={null}
┌─dest_group─┬─src_group─┬─result_group─┬─timeSeriesGroupToTags(result_group)────────────────────────┐
│          1 │         2 │            3 │ [('__name__','http_codes'),('code','404'),('region','eu')] │
└────────────┴───────────┴──────────────┴────────────────────────────────────────────────────────────┘
```

<div id="timeSeriesCopyTags">
  ## timeSeriesCopyTags
</div>

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](https://prometheus.io/docs/prometheus/latest/querying/operators/#group-modifiers) do Prometheus.

**Sintaxe**

```sql theme={null}
timeSeriesCopyTags(dest_group, src_group, tags_to_copy)
```

**Argumentos**

* `dest_group` — O grupo de tags de destino. [`UInt64`](/pt-BR/reference/data-types/int-uint)
* `src_group` — O grupo de tags de origem. [`UInt64`](/pt-BR/reference/data-types/int-uint)
* `tags_to_copy` — Os nomes das tags a copiar. [`Array(String)`](/pt-BR/reference/data-types/array)

**Valor retornado**

Retorna um grupo de tags que contém as tags de `dest_group` junto com as tags copiadas de `src_group`. [`UInt64`](/pt-BR/reference/data-types/int-uint)

**Exemplos**

**Exemplo**

```sql title=Query theme={null}
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 title=Response theme={null}
┌─dest_group─┬─src_group─┬─result_group─┬─timeSeriesGroupToTags(result_group)────────────────────────┐
│          1 │         2 │            3 │ [('__name__','http_codes'),('code','404'),('region','eu')] │
└────────────┴───────────┴──────────────┴────────────────────────────────────────────────────────────┘
```

<div id="timeSeriesExtractTag">
  ## timeSeriesExtractTag
</div>

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()](/pt-BR/reference/functions/regular-functions/time-series-functions#timeSeriesGroupToTags).

**Sintaxe**

```sql theme={null}
timeSeriesExtractTag(group)
```

**Argumentos**

* `group` — Um grupo de tags. [`UInt64`](/pt-BR/reference/data-types/int-uint)
* `tag_to_extract` — O nome de uma tag a ser extraída do grupo [`String`](/pt-BR/reference/data-types/string)

**Valor retornado**

Retorna o valor da tag especificada. [`Nullable(String)`](/pt-BR/reference/data-types/nullable)

**Exemplos**

**Exemplo**

```sql title=Query theme={null}
SELECT timeSeriesTagsToGroup([('region', 'eu'), ('env', 'dev')], '__name__', 'http_requests_count') AS group,
       timeSeriesExtractTag(group, '__name__'),
       timeSeriesExtractTag(group, 'env'),
       timeSeriesExtractTag(group, 'instance')
```

```response title=Response theme={null}
┌─group─┬─timeSeriesExtractTag(group, '__name__')─┬─timeSeriesExtractTag(group, 'env')─┬─timeSeriesExtractTag(group, 'instance')─┐
│     1 │ http_requests_count                     │ dev                                │ ᴺᵁᴸᴸ                                    │
└───────┴─────────────────────────────────────────┴────────────────────────────────────┴─────────────────────────────────────────┘
```

<div id="timeSeriesFromGrid">
  ## timeSeriesFromGrid
</div>

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**

```sql theme={null}
timeSeriesFromGrid(start_timestamp, end_timestamp, step, values)
```

**Argumentos**

* `start_timestamp` — Início da grade temporal. [`DateTime64`](/pt-BR/reference/data-types/datetime64) ou [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`UInt32`](/pt-BR/reference/data-types/int-uint)
* `end_timestamp` — Fim da grade temporal. [`DateTime64`](/pt-BR/reference/data-types/datetime64) ou [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`UInt32`](/pt-BR/reference/data-types/int-uint)
* `step` — passo da grade temporal em segundos [`Decimal64`](/pt-BR/reference/data-types/decimal) ou [`Decimal32`](/pt-BR/reference/data-types/decimal) ou [`UInt32/64`](/pt-BR/reference/data-types/int-uint)
* `values` — Array de valores [`Array(Float*)`](/pt-BR/reference/data-types/array) ou [`Array(Nullable(Float*))`](/pt-BR/reference/data-types/array)

**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))`](/pt-BR/reference/data-types/array)

**Exemplos**

**Exemplo de uso**

```sql title=Query theme={null}
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 title=Response theme={null}
┌─────────────────────────────────────────────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)] │
└────────────────────────────────────────────────────────────────────────────────────────────────┘
```

<div id="timeSeriesGroupToSamplingKey">
  ## timeSeriesGroupToSamplingKey
</div>

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**

```sql theme={null}
timeSeriesGroupToSamplingKey(group)
```

**Argumentos**

* `group` — Um grupo de tags. [`UInt64`](/pt-BR/reference/data-types/int-uint)

**Valor retornado**

Um hash `UInt64` estável derivado das tags associadas ao grupo. [`UInt64`](/pt-BR/reference/data-types/int-uint)

**Exemplos**

**Exemplo**

```sql title=Query theme={null}
SELECT timeSeriesTagsToGroup([('region', 'eu'), ('env', 'dev')], '__name__', 'http_requests_count') AS group,
       timeSeriesGroupToSamplingKey(group) AS sampling_key
```

```response title=Response theme={null}
┌─group─┬─────────sampling_key─┐
│     1 │ 12876543210987654321 │
└───────┴──────────────────────┘
```

<div id="timeSeriesGroupToTags">
  ## timeSeriesGroupToTags
</div>

Introduzido em: v26.1.0

Retorna os nomes e valores das tags associadas a um grupo especificado.
Veja também a função [timeSeriesTagsToGroup()](/pt-BR/reference/functions/regular-functions/time-series-functions#timeSeriesTagsToGroup).

**Sintaxe**

```sql theme={null}
timeSeriesGroupToTags(group)
```

**Nomes alternativos**: `timeSeriesTagsGroupToTags`

**Argumentos**

* `group` — Um grupo de tags. [`UInt64`](/pt-BR/reference/data-types/int-uint)

**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))`](/pt-BR/reference/data-types/array)

**Exemplos**

**Exemplo**

```sql title=Query theme={null}
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 title=Response theme={null}
┌─group─┬─sorted_tags────────────────────────────────────────────────────────┬─same_group─┬─throwIf(notE⋯up, group))─┐
│     1 │ [('__name__','http_requests_count'),('env','dev'),('region','eu')] │          1 │                        0 │
└───────┴────────────────────────────────────────────────────────────────────┴────────────┴──────────────────────────┘
```

<div id="timeSeriesIdToGroup">
  ## timeSeriesIdToGroup
</div>

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()](/pt-BR/reference/functions/regular-functions/time-series-functions#timeSeriesStoreTags).

**Sintaxe**

```sql theme={null}
timeSeriesIdToGroup(id)
```

**Aliases**: `timeSeriesIdToTagsGroup`

**Argumentos**

* `id` — Identificador de uma série temporal. [`UInt64`](/pt-BR/reference/data-types/int-uint) ou [`UInt128`](/pt-BR/reference/data-types/int-uint) ou [`UUID`](/pt-BR/reference/data-types/uuid) ou [`FixedString(16)`](/pt-BR/reference/data-types/fixedstring)

**Valor retornado**

Retorna um grupo de tags associado ao identificador `id` de uma série temporal. [`UInt64`](/pt-BR/reference/data-types/int-uint)

**Exemplos**

**Exemplo**

```sql title=Query theme={null}
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 title=Response theme={null}
┌────────────id─┬───────same_id─┬─throwIf(notE⋯me_id, id))─┬─group─┬─timeSeriesGroupToTags(group)───────────────────────────────────────┐
│ 8374283493092 │ 8374283493092 │                        0 │     1 │ [('__name__','http_requests_count'),('env','dev'),('region','eu')] │
└───────────────┴───────────────┴──────────────────────────┴───────┴────────────────────────────────────────────────────────────────────┘
```

<div id="timeSeriesIdToTags">
  ## timeSeriesIdToTags
</div>

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()](/pt-BR/reference/functions/regular-functions/time-series-functions#timeSeriesStoreTags).

**Sintaxe**

```sql theme={null}
timeSeriesIdToTags(id)
```

**Argumentos**

* `id` — Identificador de uma série temporal. [`UInt64`](/pt-BR/reference/data-types/int-uint) ou [`UInt128`](/pt-BR/reference/data-types/int-uint) ou [`UUID`](/pt-BR/reference/data-types/uuid) ou [`FixedString(16)`](/pt-BR/reference/data-types/fixedstring)

**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))`](/pt-BR/reference/data-types/array)

**Exemplos**

**Exemplo**

```sql title=Query theme={null}
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 title=Response theme={null}
┌────────────id─┬───────same_id─┬─throwIf(notE⋯me_id, id))─┬─timeSeriesIdToTags(same_id)────────────────────────────────────────┐
│ 8374283493092 │ 8374283493092 │                        0 │ [('__name__','http_requests_count'),('env','dev'),('region','eu')] │
└───────────────┴───────────────┴──────────────────────────┴────────────────────────────────────────────────────────────────────┘
```

<div id="timeSeriesJoinTags">
  ## timeSeriesJoinTags
</div>

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()](https://prometheus.io/docs/prometheus/latest/querying/functions/#label_join).

**Sintaxe**

```sql theme={null}
timeSeriesJoinTags(group, dest_tag, separator, src_tags)
```

**Argumentos**

* `group` — Um grupo de tags. [`UInt64`](/pt-BR/reference/data-types/int-uint)
* `dest_tag` — O nome de uma tag com o resultado concatenado que será adicionada ao `group`. [`String`](/pt-BR/reference/data-types/string)
* `separator` — Um separador a ser inserido entre os valores concatenados. [`String`](/pt-BR/reference/data-types/string)
* `src_tags` — Os nomes das tags de origem com valores que serão concatenados. [`Array(String)`](/pt-BR/reference/data-types/array)

**Valor retornado**

Retorna um novo grupo de tags com a tag `dest_tag` definida como o resultado concatenado. [`UInt64`](/pt-BR/reference/data-types/int-uint)

**Exemplos**

**Exemplo**

```sql title=Query theme={null}
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 title=Response theme={null}
┌─group─┬─result_group─┬─timeSeriesGroupToTags(result_group)─────────────────────────────────────────────────────────────┐
│     1 │            2 │ [('__name__','up'),('foo','a,b,c'),('job','api-server'),('src1','a'),('src2','b'),('src3','c')] │
└───────┴──────────────┴─────────────────────────────────────────────────────────────────────────────────────────────────┘
```

<div id="timeSeriesRange">
  ## timeSeriesRange
</div>

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](/pt-BR/reference/functions/regular-functions/array-functions#range).

**Sintaxe**

```sql theme={null}
timeSeriesRange(start_timestamp, end_timestamp, step)
```

**Argumentos**

* `start_timestamp` — Início do intervalo. [`DateTime64`](/pt-BR/reference/data-types/datetime64) ou [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`UInt32`](/pt-BR/reference/data-types/int-uint)
* `end_timestamp` — Fim do intervalo. [`DateTime64`](/pt-BR/reference/data-types/datetime64) ou [`DateTime`](/pt-BR/reference/data-types/datetime) ou [`UInt32`](/pt-BR/reference/data-types/int-uint)
* `step` — Passo do intervalo, em segundos. [`UInt32/64`](/pt-BR/reference/data-types/int-uint) ou [`Decimal32/64`](/pt-BR/reference/data-types/decimal)

**Valor retornado**

Retorna um intervalo de timestamps. [`Array(DateTime64)`](/pt-BR/reference/data-types/array)

**Exemplos**

**Exemplo de uso**

```sql title=Query theme={null}
SELECT timeSeriesRange('2025-06-01 00:00:00'::DateTime64(3), '2025-06-01 00:01:00'::DateTime64(3), 30)
```

```response title=Response theme={null}
┌────────────────────────────────────result─────────────────────────────────────────┐
│ ['2025-06-01 00:00:00.000', '2025-06-01 00:00:30.000', '2025-06-01 00:01:00.000'] │
└───────────────────────────────────────────────────────────────────────────────────┘
```

<div id="timeSeriesRemoveAllTagsExcept">
  ## timeSeriesRemoveAllTagsExcept
</div>

Introduzido em: v26.1.0

Remove todas as tags, exceto as especificadas, de um grupo de tags.
Veja também a função [timeSeriesRemoveTag()](/pt-BR/reference/functions/regular-functions/time-series-functions#timeSeriesRemoveTag),
[timeSeriesRemoveTags()](/pt-BR/reference/functions/regular-functions/time-series-functions#timeSeriesRemoveTags).

**Sintaxe**

```sql theme={null}
timeSeriesRemoveAllTagsExcept(group, tags_to_keep)
```

**Argumentos**

* `group` — Um grupo de tags. [`UInt64`](/pt-BR/reference/data-types/int-uint)
* `tags_to_keep` — Os nomes das tags a serem mantidas no grupo. [`Array(String)`](/pt-BR/reference/data-types/array)

**Valor retornado**

Um novo grupo de tags contendo apenas as tags especificadas. [`UInt64`](/pt-BR/reference/data-types/int-uint)

**Exemplos**

**Exemplo**

```sql title=Query theme={null}
SELECT timeSeriesTagsToGroup([('region', 'eu'), ('env', 'dev')], '__name__', 'http_requests_count') AS group,
       timeSeriesRemoveAllTagsExcept(group, ['env']) AS result_group,
       timeSeriesGroupToTags(result_group)
```

```response title=Response theme={null}
┌─group─┬─result_group─┬─timeSeriesGroupToTags(result_group)─┐
│     1 │            2 │ [('env','dev')]                     │
└───────┴──────────────┴─────────────────────────────────────┘
```

<div id="timeSeriesRemoveTag">
  ## timeSeriesRemoveTag
</div>

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()](/pt-BR/reference/functions/regular-functions/time-series-functions#timeSeriesRemoveTags),
[timeSeriesRemoveAllTagsExcept()](/pt-BR/reference/functions/regular-functions/time-series-functions#timeSeriesRemoveAllTagsExcept).

**Sintaxe**

```sql theme={null}
timeSeriesRemoveTag(group, tag_to_remove)
```

**Argumentos**

* `group` — Um grupo de tags. [`UInt64`](/pt-BR/reference/data-types/int-uint)
* `tag_to_remove` — O nome de uma tag a ser removida do grupo. [`String`](/pt-BR/reference/data-types/string)

**Valor retornado**

Um novo grupo de tags sem a tag especificada. [`UInt64`](/pt-BR/reference/data-types/int-uint)

**Exemplos**

**Exemplo**

```sql title=Query theme={null}
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 title=Response theme={null}
┌─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 │ []                                 │
└────────────┴────────────┴───────────────────────────────────┴────────────┴───────────────────────────────────┴─────────────┴────────────────────────────────────┘
```

<div id="timeSeriesRemoveTags">
  ## timeSeriesRemoveTags
</div>

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()](/pt-BR/reference/functions/regular-functions/time-series-functions#timeSeriesRemoveTag),
[timeSeriesRemoveAllTagsExcept()](/pt-BR/reference/functions/regular-functions/time-series-functions#timeSeriesRemoveAllTagsExcept).

**Sintaxe**

```sql theme={null}
timeSeriesRemoveTags(group, tags_to_remove)
```

**Argumentos**

* `group` — Um grupo de tags. [`UInt64`](/pt-BR/reference/data-types/int-uint)
* `tags_to_remove` — Os nomes das tags a serem removidas do grupo. [`Array(String)`](/pt-BR/reference/data-types/array)

**Valor retornado**

Um novo grupo de tags sem as tags especificadas. [`UInt64`](/pt-BR/reference/data-types/int-uint)

**Exemplos**

**Exemplo**

```sql title=Query theme={null}
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 title=Response theme={null}
┌─group_of_3─┬─group_of_1─┬─timeSeriesGroupToTags(group_of_1)────┬─empty_group─┬─timeSeriesGroupToTags(empty_group)─┐
│          1 │          2 │ [('__name__','http_requests_count')] │           0 │ []                                 │
└────────────┴────────────┴──────────────────────────────────────┴─────────────┴────────────────────────────────────┘
```

<div id="timeSeriesReplaceTag">
  ## timeSeriesReplaceTag
</div>

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()](https://prometheus.io/docs/prometheus/latest/querying/functions/#label_replace).

**Sintaxe**

```sql theme={null}
timeSeriesReplaceTag(group, dest_tag, replacement, src_tag, regex)
```

**Argumentos**

* `group` — Um grupo de tags. [`UInt64`](/pt-BR/reference/data-types/int-uint)
* `dest_tag` — O nome de uma tag de destino para receber o grupo resultante. [`String`](/pt-BR/reference/data-types/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`](/pt-BR/reference/data-types/string)
* `src_tag` — O nome de uma tag cujo valor é usado para fazer a correspondência com a expressão regular 'regex'. [`String`](/pt-BR/reference/data-types/string)
* `regex` — Uma expressão regular. [`String`](/pt-BR/reference/data-types/string)

**Valor retornado**

Um novo grupo de tags, possivelmente com `dest_tag` adicionada. [`UInt64`](/pt-BR/reference/data-types/int-uint)

**Exemplos**

**Exemplo**

```sql title=Query theme={null}
SELECT timeSeriesTagsToGroup([('__name__', 'up'), ('job', 'api-server'), ('service', 'a:c')]) AS group,
       timeSeriesReplaceTag(group, 'foo', '$1', 'service', '(.*):.*') AS result_group,
       timeSeriesGroupToTags(result_group)
```

```response title=Response theme={null}
┌─group─┬─result_group─┬─timeSeriesGroupToTags(result_group)────────────────────────────────────┐
│     1 │            2 │ [('__name__','up'),('foo','a'),('job','api-server'),('service','a:c')] │
└───────┴──────────────┴────────────────────────────────────────────────────────────────────────┘
```

<div id="timeSeriesStoreTags">
  ## timeSeriesStoreTags
</div>

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()](/pt-BR/reference/functions/regular-functions/time-series-functions#timeSeriesIdToTags)
e [timeSeriesIdToGroup()](/pt-BR/reference/functions/regular-functions/time-series-functions#timeSeriesIdToGroup)
podem ser usadas para acessar esse mapeamento posteriormente durante a execução da consulta.

**Sintaxe**

```sql theme={null}
timeSeriesStoreTags(id, tags_array, separate_tag_name_1, separate_tag_value_1, ...)
```

**Argumentos**

* `id` — Identificador de uma série temporal. [`UInt64`](/pt-BR/reference/data-types/int-uint) ou [`UInt128`](/pt-BR/reference/data-types/int-uint) ou [`UUID`](/pt-BR/reference/data-types/uuid) ou [`FixedString(16)`](/pt-BR/reference/data-types/fixedstring)
* `tags_array` — Array de pares (tag\_name, tag\_value). [`Array(Tuple(String, String))`](/pt-BR/reference/data-types/array) ou [`NULL`](/pt-BR/reference/syntax#null)
* `separate_tag_name_i` — O nome de uma tag. [`String`](/pt-BR/reference/data-types/string) ou [`FixedString`](/pt-BR/reference/data-types/fixedstring)
* `separate_tag_value_i` — O valor de uma tag. [`String`](/pt-BR/reference/data-types/string) ou [`FixedString`](/pt-BR/reference/data-types/fixedstring) ou [`Nullable(String)`](/pt-BR/reference/data-types/nullable)

**Valor retornado**

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

**Exemplos**

**Exemplo**

```sql title=Query theme={null}
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 title=Response theme={null}
┌────────────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')] │
└───────────────┴───────────────┴─────────────────────────────────┴────────────────────────────────────────────────────────────────────┴────────────────────────────────────────────────────────────────────┘
```

<div id="timeSeriesTagsToGroup">
  ## timeSeriesTagsToGroup
</div>

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()](/pt-BR/reference/functions/regular-functions/time-series-functions#timeSeriesGroupToTags).

**Sintaxe**

```sql theme={null}
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))`](/pt-BR/reference/data-types/array) ou [`NULL`](/pt-BR/reference/syntax#null)
* `tag_name_i` — O nome de uma tag. [`String`](/pt-BR/reference/data-types/string) ou [`FixedString`](/pt-BR/reference/data-types/fixedstring)
* `tag_value_i` — O valor de uma tag. [`String`](/pt-BR/reference/data-types/string) ou [`FixedString`](/pt-BR/reference/data-types/fixedstring) ou [`Nullable(String)`](/pt-BR/reference/data-types/nullable)

**Valor retornado**

Retorna um grupo de tags associado às tags especificadas. [`UInt64`](/pt-BR/reference/data-types/int-uint)

**Exemplos**

**Exemplo**

```sql title=Query theme={null}
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 title=Response theme={null}
┌─group1─┬─group2─┬─empty_group─┬─same_group2─┬─throwIf(notEquals(same_group2, group2))─┬─timeSeriesGroupToTags(group2)──┐
│      1 │      2 │           0 │           2 │                                       0 │ [('__name__','http_failures')] │
└────────┴────────┴─────────────┴─────────────┴─────────────────────────────────────────┴────────────────────────────────┘
```

<div id="timeSeriesThrowDuplicateSeriesIf">
  ## timeSeriesThrowDuplicateSeriesIf
</div>

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()](/pt-BR/reference/functions/regular-functions/other-functions#throwIf),
mas usa um código de erro diferente e formata a mensagem de erro de outra maneira.

**Sintaxe**

```sql theme={null}
timeSeriesThrowDuplicateSeriesIf(condition, group)
```

**Argumentos**

* `condition` — Condição a ser verificada, geralmente contém a função [count()](/pt-BR/reference/functions/aggregate-functions/count#count) [`UInt8`](/pt-BR/reference/data-types/int-uint)
* `group` — Grupo de tags. [`UInt64`](/pt-BR/reference/data-types/int-uint)

**Valor retornado**

Retorna `0`. [`UInt8`](/pt-BR/reference/data-types/int-uint)

**Exemplos**

**Exemplo**

```sql title=Query theme={null}
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 title=Response theme={null}
```