uddsketch()

Toolkit

TimescaleDB Toolkit functions are available under Timescale Community Edition. They are automatically included with Timescale Cloud. Click to learn more.

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.

• For more information about percentile approximation functions, see the hyperfunctions documentation.
• For some more technical details and usage examples of this algorithm, see the developer documentation.

Required arguments

Returns

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;