Time series functions
The functions below are designed to be used with timeSeries*() aggregate functions like
timeSeriesInstantRateToGrid,
timeSeriesLastToGrid,
and so on.
seriesDecomposeSTL
Introduced in: v24.1
Decomposes a series data using STL (Seasonal-Trend Decomposition Procedure Based on Loess) into a season, a trend and a residual component.
Syntax
Arguments
series— An array of numeric valuesArray((U)Int8/16/32/64)orArray(Float*)period— A positive integerUInt8/16/32/64
Returned value
Returns an array of four arrays where the first array includes seasonal components, the second array - trend, the third array - residue component, and the fourth array - baseline(seasonal + trend) component. Array(Array(Float32), Array(Float32), Array(Float32), Array(Float32))
Examples
Decompose series data using STL
seriesOutliersDetectTukey
Introduced in: v24.2
Detects outliers in series data using Tukey Fences.
Syntax
Arguments
series— An array of numeric values.Array((UInt8/16/32/64))orArray(Float*)min_percentile— Optional. The minimum percentile to be used to calculate inter-quantile range (IQR). The value must be in range [0.02,0.98]. The default is 0.25.Float*max_percentile— Optional. The maximum percentile to be used to calculate inter-quantile range (IQR). The value must be in range [0.02,0.98]. The default is 0.75.Float*K— Optional. Non-negative constant value to detect mild or stronger outliers. The default value is 1.5.Float*
Returned value
Returns an array of the same length as the input array where each value represents score of possible anomaly of corresponding element in the series. A non-zero score indicates a possible anomaly. Array(Float32)
Examples
Basic outlier detection
Custom parameters outlier detection
seriesPeriodDetectFFT
Introduced in: v23.12
Finds the period of the given series data using FFT - Fast Fourier transform
Syntax
Arguments
series— An array of numeric values.Array((U)Int8/16/32/64)orArray(Float*)
Returned value
Returns a real value equal to the period of series data. NaN when number of data points are less than four. Float64
Examples
Period detection with simple pattern
Period detection with complex pattern
timeSeriesCopyTag
Introduced in: v26.1
Copies a specified tag from one group of tags (src_group) to another (dest_group).
The function replaces any previous values of the copied tag in dest_group.
If the copied tag is not present in src_group, then the function will remove it from dest_group as well.
The function mimics the copying logic of the prometheus
group left/group right modifiers.
Syntax
Arguments
dest_group— The destination group of tags.UInt64src_group— The source group of tags.UInt64tag_to_copy— The name of a tag to copy.String
Returned value
Returns a group of tags containing the tags from dest_group along with the copied tags from src_group. UInt64
Examples
Example
timeSeriesCopyTags
Introduced in: v26.1
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 modifiers.
Syntax
Arguments
dest_group— The destination group of tags.UInt64src_group— The source group of tags.UInt64tags_to_copy— The names of tags to copy.Array(String)
Returned value
Returns a group of tags containing the tags from dest_group along with the copied tags from src_group. UInt64
Examples
Example
timeSeriesExtractTag
Introduced in: v26.1
Extracts the value of a specified tag from the group. Returns NULL if not found. See also function timeSeriesGroupToTags().
Syntax
Arguments
Returned value
Returns the value of a specified tag. Nullable(String)
Examples
Example
timeSeriesFromGrid
Introduced in: v25.8
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
Arguments
start_timestamp— Start of the grid.DateTime64orDateTimeorUInt32end_timestamp— End of the grid.DateTime64orDateTimeorUInt32step— Step of the grid in secondsDecimal64orDecimal32orUInt32/64values— Array of valuesArray(Float*)orArray(Nullable(Float*))
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))
Examples
Usage example
timeSeriesGroupToTags
Introduced in: v26.1
Returns the names and values of the tags associated with a specified group. See also function timeSeriesTagsToGroup().
Syntax
Aliases: timeSeriesTagsGroupToTags
Arguments
group— A group of tags.UInt64
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))
Examples
Example
timeSeriesIdToGroup
Introduced in: v26.1
Returns the names and values of the tags associated with a specified identifier of a time series. See also function timeSeriesStoreTags().
Syntax
Aliases: timeSeriesIdToTagsGroup
Arguments
id— Identifier of a time series.UInt64orUInt128orUUIDorFixedString(16)
Returned value
Returns a group of tags associated with the identifier id of a time series. UInt64
Examples
Example
timeSeriesIdToTags
Introduced in: v25.8
Returns tags associated with a specified identifier of a time series. See also function timeSeriesStoreTags().
Syntax
Arguments
id— Identifier of a time series.UInt64orUInt128orUUIDorFixedString(16)
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))
Examples
Example
timeSeriesJoinTags
Introduced in: v26.1
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().
Syntax
Arguments
group— A group of tags.UInt64dest_tag— The name of a tag with the joined result which will be added to thegroup.Stringseparator— A separator to insert between joined values.Stringsrc_tags— The names of source tags with values which will be joined.Array(String)
Returned value
Returns a new group of tags with the dest_tag tag set to the joined result. UInt64
Examples
Example
timeSeriesRange
Introduced in: v25.8
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.
Syntax
Arguments
start_timestamp— Start of the range.DateTime64orDateTimeorUInt32end_timestamp— End of the range.DateTime64orDateTimeorUInt32step— Step of the range in secondsUInt32/64orDecimal32/64
Returned value
Returns a range of timestamps. Array(DateTime64)
Examples
Usage example
timeSeriesRemoveAllTagsExcept
Introduced in: v26.1
Removes all tags except specified ones from a group of tags. See also function timeSeriesRemoveTag(), timeSeriesRemoveTags().
Syntax
Arguments
group— A group of tags.UInt64tags_to_keep— The names of tags to keep in the group.Array(String)
Returned value
A new group of tags with only the specified tags kept. UInt64
Examples
Example
timeSeriesRemoveTag
Introduced in: v26.1
Removes a specified tag from a group of tags. If there is no such tag in the group then the group is returned unchanged. See also function timeSeriesRemoveTags(), timeSeriesRemoveAllTagsExcept().
Syntax
Arguments
Returned value
A new group of tags without the specified tag. UInt64
Examples
Example
timeSeriesRemoveTags
Introduced in: v26.1
Removes specified tags from a group of tags. If some of the specified tags are not in the group of tags the function ignores them. See also function timeSeriesRemoveTag(), timeSeriesRemoveAllTagsExcept().
Syntax
Arguments
group— A group of tags.UInt64tags_to_remove— The names of tags to remove from the group.Array(String)
Returned value
A new group of tags without the specified tags. UInt64
Examples
Example
timeSeriesReplaceTag
Introduced in: v26.1
Matches the regular expression regex against the value of the tag src_tag.
If it matches, the value of the tag dest_tag in the returned group will be the expansion of replacement,
together with the original tags in the input.
This function mimics the logic of the prometheus function
label_replace().
Syntax
Arguments
group— A group of tags.UInt64dest_tag— The name of a destination tag to get the result group.Stringreplacement— A replacement pattern, can contain 2 or $name to refer capturing groups in the regular expression 'regex'.Stringsrc_tag— The name of a tag which value is used to match the regular expression 'regex'.Stringregex— A regular expression.String
Returned value
A new group of tags with maybe dest_tag added. UInt64
Examples
Example
timeSeriesStoreTags
Introduced in: v25.8
Stores in the query context a mapping between a specified identifier of a time series and a set of tags. Functions timeSeriesIdToTags() and timeSeriesIdToGroup() can be used to access this mapping later during the query execution.
Syntax
Arguments
id— Identifier of a time series.UInt64orUInt128orUUIDorFixedString(16)tags_array— Array of pairs (tag_name, tag_value).Array(Tuple(String, String))orNULLseparate_tag_name_i— The name of a tag.StringorFixedStringseparate_tag_value_i— The value of a tag.StringorFixedStringorNullable(String)
Returned value
Returns the identifier of a time series (i.e. just the first argument).
Examples
Example
timeSeriesTagsToGroup
Introduced in: v26.1
Returns a group of tags associated with specified tags. If the same group of tags is found multiple times during the query execution, the function returns the same group. For an empty set of tags the function always returns 0. See also function timeSeriesGroupToTags().
Syntax
Arguments
tags_array— Array of pairs (tag_name, tag_value).Array(Tuple(String, String))orNULLtag_name_i— The name of a tag.StringorFixedStringtag_value_i— The value of a tag.StringorFixedStringorNullable(String)
Returned value
Returns a group of tags associated with the specified tags. UInt64
Examples
Example