Skip to main content

Leaderboard

Every Metric that has at least one Dimension can be visualized as a leaderboard. This visualization is useful for building rankings or "top N" visualizations over one or more dimensions. 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 be also be displayed as horizontal bar charts.

We've chosen to use echarts-for-react 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​

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

Timestamp
Salesperson
Product ID
Quantity

We can create a Sum Metric named "sales" which sums up the sales data. By including "Salesperson" and "Product ID" as Dimensions, we can answer questions with our Metric. Follow along for worked examples.

1. Who were our top performing sales people?​

In order to answer the question, "Who were our top performing sales people?", we need to query our Sum Metric and group by the "Salesperson" Dimension. In the GraphQL query below, we use metricByName to get the "sales" Metric, and then we group by "Salesperson" using the dimensions argument.

query LeaderboardExample1 (
  $timeRange: RelativeTimeRange,
) {
  sales: metricByName (uniqueName: "sales") {
    leaderboard ({
      timeRange: { relative: $timeRange }
      dimensions: [{ columnName: "Salesperson" }]
      rowLimit: 10
    }) {
      headers
      rows
    }
  }
}

2. Which products sold the most?​

In order to answer the question, "Which products sold the most?", we need to query our Sum Metric and group by the "Product ID" Dimension. In the GraphQL query below, we use metricByName to get the "sales" Metric, and then we group by "Product ID" using the dimensions argument.

query LeaderboardExample2 (
  $timeRange: RelativeTimeRange,
) {
  sales: metricByName (uniqueName: "sales") {
    leaderboard ({
      timeRange: { relative: $timeRange }
      dimensions: [{ columnName: "Product ID" }]
      rowLimit: 10
    }) {
      headers
      rows
    }
  }
}