Time series functions

**Examples**

**Example**

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

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

## timeSeriesCopyTags[​](#timeSeriesCopyTags "Direct link to timeSeriesCopyTags")

Introduced in: v26.1.0

Copies specified tags from one group of tags (`src_group`) to another (`dest_group`).
The function replaces any previous values of the copied tags in `dest_group`.
If some of the copied tags don't present in `src_group` then the function will remove them in `dest_group` as well.
The function mimics the copying logic of the prometheus
[group left/group right](https://prometheus.io/docs/prometheus/latest/querying/operators/#group-modifiers) modifiers.

**Syntax**

```
timeSeriesCopyTags(dest_group, src_group, tags_to_copy)
```

**Arguments**

- `dest_group` — The destination group of tags. [`UInt64`](/docs/sql-reference/data-types/int-uint)
- `src_group` — The source group of tags. [`UInt64`](/docs/sql-reference/data-types/int-uint)
- `tags_to_copy` — The names of tags to copy. [`Array(String)`](/docs/sql-reference/data-types/array)

**Returned value**

Returns a group of tags containing the tags from `dest_group` along with the copied tags from `src_group`. [`UInt64`](/docs/sql-reference/data-types/int-uint)

**Examples**

**Example**

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

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

## timeSeriesExtractTag[​](#timeSeriesExtractTag "Direct link to timeSeriesExtractTag")

Introduced in: v26.1.0

Extracts the value of a specified tag from the group. Returns NULL if not found.
See also function [timeSeriesGroupToTags()](/docs/sql-reference/functions/time-series-functions#timeSeriesGroupToTags).

**Syntax**

```
timeSeriesExtractTag(group)
```

**Arguments**

- `group` — A group of tags. [`UInt64`](/docs/sql-reference/data-types/int-uint)
- `tag_to_extract` — The name of a tag to extract from the group [`String`](/docs/sql-reference/data-types/string)

**Returned value**

Returns the value of a specified tag. [`Nullable(String)`](/docs/sql-reference/data-types/nullable)

**Examples**

**Example**

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

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

## timeSeriesFromGrid[​](#timeSeriesFromGrid "Direct link to timeSeriesFromGrid")

Introduced in: v25.8.0

Converts an array of values `[x1, x2, x3, ...]` to an array of tuples
`[(start_timestamp, x1), (start_timestamp + step, x2), (start_timestamp + 2 * step, x3), ...]`.

The current timestamp is increased by `step` until it becomes greater than `end_timestamp`
If the number of the values doesn't match the number of the timestamps, the function throws an exception.

NULL values in `[x1, x2, x3, ...]` are skipped but the current timestamp is still incremented.
For example, for `[value1, NULL, x2]` the function returns `[(start_timestamp, x1), (start_timestamp + 2 * step, x2)]`.

**Syntax**

```
timeSeriesFromGrid(start_timestamp, end_timestamp, step, values)
```

**Arguments**

- `start_timestamp` — Start of the grid. [`DateTime64`](/docs/sql-reference/data-types/datetime64) or [`DateTime`](/docs/sql-reference/data-types/datetime) or [`UInt32`](/docs/sql-reference/data-types/int-uint)
- `end_timestamp` — End of the grid. [`DateTime64`](/docs/sql-reference/data-types/datetime64) or [`DateTime`](/docs/sql-reference/data-types/datetime) or [`UInt32`](/docs/sql-reference/data-types/int-uint)
- `step` — Step of the grid in seconds [`Decimal64`](/docs/sql-reference/data-types/decimal) or [`Decimal32`](/docs/sql-reference/data-types/decimal) or [`UInt32/64`](/docs/sql-reference/data-types/int-uint)
- `values` — Array of values [`Array(Float*)`](/docs/sql-reference/data-types/array) or [`Array(Nullable(Float*))`](/docs/sql-reference/data-types/array)

**Returned value**

Returns values from the source array of values combined with timestamps on a regular time grid described by `start_timestamp` and `step`. [`Array(Tuple(DateTime64, Float64))`](/docs/sql-reference/data-types/array)

**Examples**

**Usage example**

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

```
┌─────────────────────────────────────────────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)] │
└────────────────────────────────────────────────────────────────────────────────────────────────┘
```

## timeSeriesGroupToTags[​](#timeSeriesGroupToTags "Direct link to timeSeriesGroupToTags")

Introduced in: v26.1.0

Returns the names and values of the tags associated with a specified group.
See also function [timeSeriesTagsToGroup()](/docs/sql-reference/functions/time-series-functions#timeSeriesTagsToGroup).

**Syntax**

```
timeSeriesGroupToTags(group)
```

**Aliases**: `timeSeriesTagsGroupToTags`

**Arguments**

- `group` — A group of tags. [`UInt64`](/docs/sql-reference/data-types/int-uint)

**Returned value**

Returns an array of pairs `(tag_name, tag_value)`.
The returned array is always sorted by `tag_name` and never contains the same `tag_name` more than once.
[`Array(Tuple(String, String))`](/docs/sql-reference/data-types/array)

**Examples**

**Example**

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

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

## timeSeriesIdToGroup[​](#timeSeriesIdToGroup "Direct link to timeSeriesIdToGroup")

Introduced in: v26.1.0

Returns the names and values of the tags associated with a specified identifier of a time series.
See also function [timeSeriesStoreTags()](/docs/sql-reference/functions/time-series-functions#timeSeriesStoreTags).

**Syntax**

```
timeSeriesIdToGroup(id)
```

**Aliases**: `timeSeriesIdToTagsGroup`

**Arguments**