timeSeriesTopKMasks | ClickHouse Docs

Introduced in: v26.8.0

Selects the time series with the k greatest values at each time step of a time grid.

Each input row is one time series: key identifies the series and values contains its values aligned to a common time grid, so the values arrays of all rows must have the same size. At each time step, the series with the k greatest non-NULL values at that step are selected (NaN is considered smaller than any other value). Value ties are broken by preferring the series with the smaller key.

This function implements the topk() aggregation operator of PromQL and keeps only one bounded heap of size k per time step, so its state size does not depend on the number of aggregated series.

Syntax

timeSeriesTopKMasks(k, key, values)

Arguments

k — How many series to select at each time step, either one value for all time steps or an array with one value per time step. Must be the same for all rows. UInt* or Array(UInt*)
key — Identifier of the time series. UInt64
values — Values of the time series aligned to the time grid, one element per time step. Array(Nullable(Float32)) or Array(Nullable(Float64)) or Array(Float32) or Array(Float64)

Returned value

Returns the selected series in the order of ascending key, each together with its per-step mask: steps_mask[t] = 1 if the series is selected at time step t. Series which are selected at no time step are not returned. Array(Tuple(key UInt64, steps_mask Array(UInt8)))

Examples

Selecting the 2 greatest series per time step

SET enable_time_series_aggregate_functions = 1;
WITH [(1, [10., 1., NULL]), (2, [20., 2., 2.]), (3, [30., NULL, 1.])]::Array(Tuple(UInt64, Array(Nullable(Float64)))) AS series
SELECT timeSeriesTopKMasks(2, s.1, s.2)
FROM (SELECT arrayJoin(series) AS s);

[(1,[0,1,0]),(2,[1,1,1]),(3,[1,0,1])]