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
- The
timeRange
to query over, - The
dimensions
to break down by, - The
rowLimit
for controling the number of rows to return, and - 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 thedimensions
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 theheaders
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:
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.
- GraphQL Query
- GraphQL Variables
- JSON Response
query LeaderboardExample1 (
$timeRange: RelativeTimeRange,
) {
sales: metricByName (uniqueName: "sales") {
leaderboard ({
timeRange: { relative: $timeRange }
dimensions: [{ columnName: "Salesperson" }]
rowLimit: 10
}) {
headers
rows
}
}
}
{
"timeRange": "THIS_YEAR"
}
{
"data": {
"sales": {
"leaderboard": {
"headers": ["Salesperson", "value"],
"rows": [
["Mike", "100"],
["John", "200"],
["Judy", "300"],
["Martha", "400"],
["Jean", "500"],
["Elsa", "600"]
]
}
}
}
}
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.
- GraphQL Query
- GraphQL Variables
- JSON Response
query LeaderboardExample2 (
$timeRange: RelativeTimeRange,
) {
sales: metricByName (uniqueName: "sales") {
leaderboard ({
timeRange: { relative: $timeRange }
dimensions: [{ columnName: "Product ID" }]
rowLimit: 10
}) {
headers
rows
}
}
}
{
"timeRange": "THIS_YEAR"
}
{
"data": {
"sales": {
"leaderboard": {
"headers": ["Product ID", "value"],
"rows": [
["Bacon", "100"],
["Towel", "200"],
["Stand", "300"],
["Bus", "400"],
["Lamp", "500"],
["Carpet", "600"]
]
}
}
}
}