TopN is an open source PostgreSQL extension that returns the top values in a database according to some criteria. TopN takes elements in a data set, ranks them according to a given rule, and picks the top elements in that data set. When doing this, TopN applies an approximation algorithm to provide fast results using few compute and memory resources.
TopN extension becomes useful when you want to materialize top values, incrementally update these top values, and/or merge top values from different time intervals. If you're familiar with the PostgreSQL HLL extension, you can think of
TopN as its cousin.
When to use TopN
TopN becomes helpful when serving customer-facing dashboards or running analytical queries that need sub-second responses. Ranking events, users, or products in a given dimension becomes important for these workloads.
TopN is used by customers in production to serve real-time analytics queries over terabytes of data.
Why use TopN
Calculating TopN elements in a set by applying count, sort, and limit is simple. As data sizes increase however, this method becomes slow and resource intensive.
The open source
TopN extension enables you to serve instant and approximate results to TopN queries. To do this, you first materialize top values according to some criteria in a data type. You can then incrementally update these top values, or merge them on-demand across different time intervals.
TopN was originally created to help Citus Data customers, who needed to scale out their PostgreSQL databases across dozens of machines. These customers needed to compute top values over terabytes of data in less than a second. We realized that the broader Postgres community could benefit from
TopN, and decided to open source it for all users.
How does TopN work
The TopN approximation algorithm keeps a predefined number of frequent items and counters. If a new item already exists among these frequent items, the algorithm increases the item's frequency counter. Else, the algorithm inserts the new item into the counter list when there is enough space. If there isn't enough space, the algorithm evicts the bottom half of all counters. Since we typically keep counters for many more items (e.g. 100*N) than we are actually interested in, the actual top N items are unlikely to get evicted and will typically have accurate counts.
You can increase the algoritm's accuracy by increasing the predefined number of frequent items/counters.
Once you have PostgreSQL, you're ready to build TopN. For this, you will need to include the pg_config directory path in your make command. This path is typically the same as your PostgreSQL installation's bin/ directory path. For example:
PATH=/usr/local/pgsql/bin/:$PATH make sudo PATH=/usr/local/pgsql/bin/:$PATH make install
You can run the regression tests as the following.
sudo make installcheck
In this example, we take example customer reviews data from Amazon. We're then going to analyze the most reviewed products based on different criteria.
Let's start by downloading and decompressing source data files.
wget http://examples.citusdata.com/customer_reviews_2000.csv.gz gzip -d customer_reviews_2000.csv.gz
Next, we're going to connect to PostgreSQL and create the
CREATE EXTENSION topn;
Let's then create our example table and load data into it.
CREATE TABLE customer_reviews ( customer_id TEXT, review_date DATE, review_rating INTEGER, review_votes INTEGER, review_helpful_votes INTEGER, product_id CHAR(10), product_title TEXT, product_sales_rank BIGINT, product_group TEXT, product_category TEXT, product_subcategory TEXT, similar_product_ids CHAR(10) ); \COPY customer_reviews FROM 'customer_reviews_2000.csv' WITH CSV;
Now, we're going to create an aggregation table that captures the most popular products for each month. We're then going to materialize top products for each month.
-- Create a roll-up table to capture most popular products CREATE TABLE popular_products ( review_date date UNIQUE, agg_data jsonb ); -- Create different summaries by grouping top reviews for each date (day, month, year) INSERT INTO popular_products SELECT review_date, topn_add_agg(product_id) FROM customer_reviews GROUP BY review_date;
From this table, you can compute the most popular/reviewed product for each day, in the blink of an eye.
SELECT review_date, (topn(agg_data, 1)).* FROM popular_products ORDER BY review_date;
You can also instantly find the top 10 reviewed products across any time interval, in this case January.
SELECT (topn(topn_union_agg(agg_data), 10)).* FROM popular_products WHERE review_date >= '2000-01-01' AND review_date < '2000-02-01' ORDER BY 2 DESC;
Or, you can quickly find the most reviewed product for each month in 2000.
SELECT date_trunc('month', review_date) AS review_month, (topn(topn_union_agg(agg_data), 1)).* FROM popular_products WHERE review_date >= '2000-01-01' AND review_date < '2001-01-01' GROUP BY review_month ORDER BY review_month;
TopN provides the following user-defined functions and aggregates.
A PostgreSQL type to keep the frequent items and their frequencies.
This is the aggregate add function. It creates an empty
JSONB and inserts series of item from given column to create aggregate summary of these items. Note that the value must be
TEXT type or casted to
This is the aggregate for union operation. It merges the
JSONB counter lists and returns the final
JSONB which stores overall result.
Gives the most frequent
n elements and their frequencies as set of rows from the given
Adds the given text value as a new counter into the
JSONB and returns a new
JSONB if there is an enough space for one more counter. If not, the counter is added and then the counter list is pruned.
Takes the union of both
JSONBs and returns a new
Sets the number of counters to be tracked in a
JSONB. If at some point, the current number of counters exceed
topn.number_of_counters * 3, the list is pruned. The default value is 1000 for
topn.number_of_counters. When you increase this setting,
TopN uses more space and provides more accurate estimates.
TopN is compatible with the PostgreSQL 9.6, 10, 11, 12, and 13 releases.
TopN is also compatible with all supported Citus releases, including Citus 6.x, 7.x, 8.x, and 9.x. If you need to run
TopN on a different version of PostgreSQL or Citus, please open an issue. Opening a pull request (PR) is also highly appreciated.
TopN extension to Postgres was created by and is maintained by the Citus database team, now part of Microsoft. The Citus team also created Citus, an open source extension to Postgres that transforms Postgres into a distributed database.