uddsketch()

uddsketch(
    size INTEGER,
    max_error DOUBLE PRECISION,
    value DOUBLE PRECISION
) RETURNS UddSketch

This constructs and returns a new UddSketch with at most size buckets. The maximum relative error of the UddSketch is bounded by max_error unless it is impossible to do so while with the bucket bound.

If the sketch has to combine buckets, the new error can be found with the uddsketch_error command. Because the error is increased automatically (roughly doubling at each step) as the number of buckets is exceeded, start smaller unless you have a good understanding of exactly what your error should be.

Timescale's UddSketch implementation is provided as an aggregate function in PostgreSQL. The output is currently only suitable as input to the the percentile approximation functions. This can be directly as part of a one-off SQL query, or as transient data stored in a continuous aggregate that is queried later with these functions and using the UddSketch data as input.

Required arguments

NameTypeDescription
sizeINTEGERMaximum number of buckets in the sketch. Providing a larger value here makes it more likely that the aggregate is able to maintain the desired error, but potentially increases the memory usage.
max_errorDOUBLE PRECISIONThis is the starting maximum relative error of the sketch, as a multiple of the actual value. The true error may exceed this if too few buckets are provided for the data distribution.
valueDOUBLE PRECISIONColumn to aggregate

Returns

ColumnTypeDescription
uddsketchUddSketchA UddSketch object which can be passed to other UddSketch APIs

Sample usage

This example uses a table called samples with a column called data that holds DOUBLE PRECISION values. This query returns a Uddsketch over that column:

SELECT uddsketch(100, 0.01, data) FROM samples;

This example builds a view from the aggregate that you can pass to other Uddsketch functions:

CREATE VIEW sketch AS
    SELECT uddsketch(100, 0.01, data)
    FROM samples;

Found an issue on this page?

Report an issue!

Related Content