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.
FieldTypeRequiredDescription
metricMetricInputNo

The Metric to query. You can query a pre-configured Metric by ID or name, or you can query an ad hoc Metric that you define inline.

timeRangeTimeRangeInputNo

The time range for calculating the leaderboard.

timeZoneStringNo

The time zone to use. Dates and times are always returned in UTC, but setting the time zone influences relative time ranges and granularities.

You can set this to "America/Los_Angeles", "Europe/Berlin", or any other value in the IANA time zone database. Defaults to "UTC".

dimensions array of DimensionInputYes

One or many Dimensions to group the Metric values by. Typically, Dimensions in a leaderboard are what you want to compare and rank.

sortSortNo

The sort order of the rows. It can be ascending (ASC) or descending (DESC) order. Defaults to descending (DESC) order when not provided.

rowLimitIntYes

The number of rows to be returned. It can be a number between 1 and 1,000.

filters array of FilterInputNo

The list of filters to apply before retrieving the leaderboard data. If no Query Filters are provided, all data is included.

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.

FieldTypeNullableDescription
headers array of StringNo

The table headers. It contains the Dimension and Metric names.

rows array of StringNo

An ordered array of rows. Each row contains the Dimension values and the corresponding Metric value. A Dimension value can be empty. A Metric value will never be empty.

queryQueryInfoNo

The Query statistics and metadata.

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:
query LeaderboardExample1($input: LeaderboardInput!) {
leaderboard(input: $input) {
headers
rows
}
}

Variables:

{
"input": {
"metric": {
"sum": {
"dataPool": {
"name": "TacoSoft Demo Data"
},
"measure": {
"columnName": "taco_total_price"
}
}
},
"sort": "DESC",
"timeRange": {
"relative": "THIS_YEAR",
"n": null
},
"rowLimit": 10,
"dimensions": [
{
"columnName": "restaurant_name"
}
],
"filters": []
}
}

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.