Skip to main content

Metric Report

The Metric Report query allows you to build comprehensive reports by grouping one or more Metrics by common dimensions. These reports can be visualized as tables with sortable columns and built-in pagination.


When you need to display tabular data that includes multiple Metrics grouped by specific dimensions, the Metric Report is a suitable choice. It can be used in conjunction with Time Series to provide valuable insights within in-product analytics. Metric Reports are typically rendered as tables like so:

restaurant_nametaco_nameRevenueTaco Sales Count
El Buen SaborCarne Asada2754789
El Buen SaborAl Pastor2251681
El Buen SaborFish2105623
Sabor MexicanoShrimp2031598
Taco FiestaBarbacoa1987564
Sabor MexicanoChorizo1890530
Taco FiestaPollo1782482
El Buen SaborVeggie1542377
Sabor MexicanoBreakfast1523412
Taco FiestaCarnitas1345321

See below for an example of how data like this can be retrieved using Metric Report.


You will pass a MetricReportInput when querying. The most important arguments when querying a metric report are

  1. The timeRange to query over.
  2. The dimensions to break down by. Supports a maximum of 10 dimensions. You must supply at least one dimension.
  3. The metrics you wish to display. Supports a maximum of 10 Metrics. You must supply at least one Metric.
  4. orderByColumn - which column, specified by number starting at 1 inclusive of dimensions and metrics you wish to order by.
  5. first refers to the number of rows to return.

Read more about MetricReportInput.


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

  • The headers array is an array of header names for the report table: the first header names correspond to the dimensions you passed to the dimensions argument when querying the report; the final header name is always "value".
  • The rows array is an array of rows for the metric report 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 MetricReportConnection.


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


Note: this data has essentially the same format as the TacoSoft data we used in our Quickstart.

Before proceeding with the example query below, you will need to create two Sum Metrics:

  1. A Sum Metric for the "total price" column, which could be named "Revenue". This will represent the total revenue of all tacos sold.
  2. A Sum Metric for the "quantity" column, which could be named "Taco Sales Count". This will represent the total number of tacos sold.

What are the top performing restaurants and best selling tacos?

In this example, we aim to identify the top-performing restaurants and best-selling tacos by grouping sales data by the attributes restaurant_name and taco_name. The query below groups the "Revenue" Metric and the "Taco Sales Count" Metric by these two attributes. By specifying "orderByColumn": 1 in the input, the results are ordered by the first column, which corresponds to the restaurant name. Additionally, by setting "first": 10 in the input, the query retrieves only the first 10 rows.

query MetricReportExample($input: MetricReportInput!) {
metricReport(input: $input) {
pageInfo {

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

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