Skip to content

Frequency aggregation overview

Functions for finding the most common values using the SpaceSaving algorithm

Get the most common elements of a set and their relative frequency. The estimation uses the SpaceSaving algorithm.

This group of functions contains two aggregate functions, which let you set the cutoff for the values that topn() returns in different ways. freq_agg allows you to specify a minimum frequency, and mcv_agg allows you to specify the target number of values to return.

To estimate the absolute number of times a value appears, use count_min_sketch.

This group of functions uses the two-step aggregation pattern.

Rather than calculating the final result in one step, you first create an intermediate aggregate by using the aggregate function.

Then, use any of the accessors on the intermediate aggregate to calculate a final result. You can also roll up multiple intermediate aggregates with the rollup functions.

The two-step aggregation pattern has several advantages:

  1. More efficient because multiple accessors can reuse the same aggregate
  2. Easier to reason about performance, because aggregation is separate from final computation
  3. Easier to understand when calculations can be rolled up into larger intervals, especially in window functions and continuous aggregates
  4. Perform retrospective analysis even when underlying data is dropped, because the intermediate aggregate stores extra information not available in the final result

To learn more, see the blog post on two-step aggregates.

This test uses a table of randomly generated data. The values used are the integer square roots of a random number in the range 0 to 400.

CREATE TABLE value_test(value INTEGER);
INSERT INTO value_test SELECT floor(sqrt(random() * 400)) FROM generate_series(1,100000);

This returns the 5 most common values seen in the table:

SELECT topn(
toolkit_experimental.freq_agg(0.05, value),
5)
FROM value_test;

The output for this query:

topn
------
19
18
17
16
15

Generate a table with frequencies of the most commonly seen values

Section titled “Generate a table with frequencies of the most commonly seen values”

Return the stored values with the bounds of their estimated frequency:

SELECT value, min_freq, max_freq
FROM into_values(
(SELECT toolkit_experimental.freq_agg(0.05, value) FROM value_test));

The output for this query looks like this, with some variation due to randomness:

value | min_freq | max_freq
-------+----------+----------
19 | 0.09746 | 0.09746
18 | 0.09262 | 0.09262
17 | 0.08653 | 0.08653
16 | 0.08157 | 0.08157
15 | 0.07803 | 0.07803
14 | 0.07466 | 0.07466
13 | 0.06819 | 0.06819
12 | 0.06084 | 0.06084
11 | 0.05803 | 0.05803
10 | 0.05176 | 0.05176
9 | 0.04771 | 0.04771
8 | 0.04185 | 0.04185
7 | 0.03719 | 0.03719
6 | 0.03413 | 0.03413
5 | 0.02691 | 0.02691
4 | 0.02273 | 0.02273
3 | 0.01755 | 0.01755
2 | 0.01252 | 0.01252
1 | 0.00727 | 0.00727
0 | 0.00245 | 0.00245

You can adjust the following advanced options to suit your data distribution:

mcv_agg assumes that the data is skewed. In other words, some values are more frequent than others. The degree of skew is defined by the s parameter of a zeta distribution.

The default value of 1.1 works on data with this distribution or a more extreme one:

NMinimum percentage of all values represented by the top N (approximate)
520%
1025%
2030%
5036%
10040%
  • freq_agg(): aggregate data into a space-saving aggregate with a minimum frequency cutoff
  • mcv_agg(): aggregate data into a space-saving aggregate with a target number of values
  • into_values(): return the values and their estimated frequencies from a frequency aggregate
  • max_frequency(): get the maximum frequency of a value from a frequency aggregate
  • min_frequency(): get the minimum frequency of a value from a frequency aggregate
  • topn(): get the N most common values from a frequency aggregate
  • rollup(): combine multiple frequency aggregates