Time series functions

```
┌─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**

- `id` — Identifier of a time series. [`UInt64`](/docs/sql-reference/data-types/int-uint) or [`UInt128`](/docs/sql-reference/data-types/int-uint) or [`UUID`](/docs/sql-reference/data-types/uuid) or [`FixedString(16)`](/docs/sql-reference/data-types/fixedstring)

**Returned value**

Returns a group of tags associated with the identifier `id` of a time series. [`UInt64`](/docs/sql-reference/data-types/int-uint)

**Examples**

**Example**

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

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

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

Introduced in: v25.8.0

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

**Syntax**

```
timeSeriesIdToTags(id)
```

**Arguments**

- `id` — Identifier of a time series. [`UInt64`](/docs/sql-reference/data-types/int-uint) or [`UInt128`](/docs/sql-reference/data-types/int-uint) or [`UUID`](/docs/sql-reference/data-types/uuid) or [`FixedString(16)`](/docs/sql-reference/data-types/fixedstring)

**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 8374283493092 AS id,
       timeSeriesStoreTags(id, [('region', 'eu'), ('env', 'dev')], '__name__', 'http_requests_count') AS same_id,
       throwIf(same_id != id),
       timeSeriesIdToTags(same_id)
```

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

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

Introduced in: v26.1.0

Joins the values of specified tags extracted from a group of tags.
The function inserts a separator between joined values and returns a new group of tags
with the tag `dest_tag` set to the joined value.
This function mimics the logic of the prometheus function
[label\_join()](https://prometheus.io/docs/prometheus/latest/querying/functions/#label_join).

**Syntax**

```
timeSeriesJoinTags(group, dest_tag, separator, src_tags)
```

**Arguments**

- `group` — A group of tags. [`UInt64`](/docs/sql-reference/data-types/int-uint)
- `dest_tag` — The name of a tag with the joined result which will be added to the `group`. [`String`](/docs/sql-reference/data-types/string)
- `separator` — A separator to insert between joined values. [`String`](/docs/sql-reference/data-types/string)
- `src_tags` — The names of source tags with values which will be joined. [`Array(String)`](/docs/sql-reference/data-types/array)

**Returned value**

Returns a new group of tags with the `dest_tag` tag set to the joined result. [`UInt64`](/docs/sql-reference/data-types/int-uint)

**Examples**

**Example**

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

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

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

Introduced in: v25.8.0

Generates a range of timestamps [start\_timestamp, start\_timestamp + step, start\_timestamp + 2 \* step, ..., end\_timestamp].

If `start_timestamp` is equal to `end_timestamp`, the function returns a 1-element array containing `[start_timestamp]`.

Function `timeSeriesRange()` is similar to function [range](/docs/sql-reference/functions/array-functions#range).

**Syntax**

```
timeSeriesRange(start_timestamp, end_timestamp, step)
```

**Arguments**

- `start_timestamp` — Start of the range. [`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 range. [`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 range in seconds [`UInt32/64`](/docs/sql-reference/data-types/int-uint) or [`Decimal32/64`](/docs/sql-reference/data-types/decimal)

**Returned value**

Returns a range of timestamps. [`Array(DateTime64)`](/docs/sql-reference/data-types/array)

**Examples**

**Usage example**

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

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

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

Introduced in: v26.1.0

Removes all tags except specified ones from a group of tags.
See also function [timeSeriesRemoveTag()](/docs/sql-reference/functions/time-series-functions#timeSeriesRemoveTag),
[timeSeriesRemoveTags()](/docs/sql-reference/functions/time-series-functions#timeSeriesRemoveTags).

**Syntax**

```
timeSeriesRemoveAllTagsExcept(group, tags_to_keep)
```

**Arguments**

- `group` — A group of tags. [`UInt64`](/docs/sql-reference/data-types/int-uint)
- `tags_to_keep` — The names of tags to keep in the group. [`Array(String)`](/docs/sql-reference/data-types/array)

**Returned value**

A new group of tags with only the specified tags kept. [`UInt64`](/docs/sql-reference/data-types/int-uint)

**Examples**

**Example**

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