Skip to main content

Leaderboard

Every Metric that has at least one Dimension can be visualized as a Leaderboard. This is useful for making rankings or 'top N' lists in different categories. For example, a Leaderboard could represent

  • Top salespeople for the quarter,
  • Signups by region for the week, or
  • Most frequent error codes in the last hour.

Any time you need to visualize a Metric broken down by Dimension and sorted, consider using a Leaderboard.

Usage​

Along with Time Series, Leaderboards can provide significant insight when included in in-product analytics. Although every Leaderboard can be rendered as a simple table, they can also be displayed as horizontal bar charts.

We've chosen to use Propel's open source UI Kit in the example above, but Propel is compatible with all charting libraries. If you're using React and want some inspiration, check out our blog post, Best React Charting Libraries for Data Visualization and Analytics.

Arguments​

You will pass a LeaderboardInput when querying the Leaderboard. The most important arguments when querying a Leaderboard are

  1. The timeRange to query over,
  2. The dimensions to break down by,
  3. The rowLimit for controling the number of rows to return, and
  4. The filters to use.

Read more about LeaderboardInput.

Returns​

The query returns an array of headers and an array of rows inside a LeaderboardResponse:

  • The headers array is an array of header names for the Leaderboard table: the first header names correspond to the Dimensions you passed to the dimensions argument when querying the Leaderboard; the final header name is always "value".
  • The rows array is an array of rows for the Leaderboard table. Each row is itself an array of columns. The column order matches the headers order.

The final column of each row is a number wrapped in a string. Using a string ensures we can support values greater than 32-bits in the GraphQL API.

Read more about LeaderboardResponse.

Example​

Suppose we have a Data Pool syncing from a table of restaurant sales data. The data might look like the following:

timestamp
restaurant_name
taco_name
taco_total_price
taco_unit_price
quantity

We can create a Sum Metric named "Revenue" that sums up the taco sales. By including "restaurant_name" and "taco_name" as Dimensions, we can answer questions with our Metric. Follow along for worked examples.

1. Which restaurants generated the most revenue?​

In order to determine the top-performing restaurants by revenue, we query our Sum Metric named "Revenue" and group by the "restaurant_name" Dimension. In the GraphQL query below, we specify the metric name, sort it in descending order, and limit the rows to the top 10, grouping by "restaurant_name" using the dimensions argument.

query LeaderboardExample1($input: LeaderboardInput!) {
  leaderboard(input: $input) {
    headers
    rows
  }
}

You can replicate this query on GraphQL Explorer by logging in here.

You can learn more about how to structure a Leaderboard query here.

2. Which products sold the most?​

In order to answer the question, "Which tacos sold the most?", we need to query our Sum Metric named "Revenue" and group by the "taco_name" Dimension. In the GraphQL query below, we specify the metric name, sort it in descending order, and limit the rows to the top 10, grouping by "taco_name" using the dimensions argument.

query LeaderboardExample2($input: LeaderboardInput!) {
  leaderboard(input: $input) {
    headers
    rows
  }
}

Replicate this query in the GraphQL Explorer. More on Leaderboard queries here.