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.

Usage​

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.

Arguments​

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

The time range for calculating the Metric Report.

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 MetricReportDimensionInputYes

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

metrics array of MetricReportMetricInputYes

One or more Metrics to include in the Metric Report. These will be broken down by dimensions.

filterSqlStringNo

The Query Filters to apply when building the Metric Report, in the form of SQL. These can be used to filter out rows.

orderByColumnIntNo

The index of the column to order the Metric Report by. The index is 1-based and defaults to the first Metric column. In other words, by default, reports are ordered by the first Metric; however, you can order by the second Metric, third Metric, etc., by overriding the orderByColumn input. You can also order by dimensions this way.

firstIntNo

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

afterStringNo

The cursor to use when paging forward.

lastIntNo

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

beforeStringNo

The cursor to use when paging backward.

Returns​

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.

FieldTypeNullableDescription
pageInfoPageInfoNo

The report connection's page info.

edges array of MetricReportEdgeNo

The report connection's edges.

nodes array of MetricReportNodeNo

The report connection's nodes.

headers array of StringNo

An ordered array of display names for your dimensions and Metrics, as defined in the report input. Use this to display your table's header.

rows array of StringNo

An ordered array of rows. Each row contains dimension and Metric values, as defined in the report input. Use these to display the rows of your table.

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

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:
query MetricReportExample($input: MetricReportInput!) {
  metricReport(input: $input) {
    headers
    rows
    pageInfo {
      startCursor
      endCursor
      hasNextPage
      hasPreviousPage
    }
  }
}

Variables:

{
  "input": {
    "timeRange": {
      "relative": "LAST_N_DAYS",
      "n": 30
    },
    "dimensions": [
      {
        "columnName": "restaurant_name"
      },
      {
        "columnName": "taco_name"
      }
    ],
    "metrics": [
      {
        "metric": {
          "sum": {
            "dataPool": {
              "name": "TacoSoft Demo Data"
            },
            "measure": {
              "columnName": "taco_total_price"
            }
          }
        }
      },
      {
        "metric": {
          "countDistinct": {
            "dataPool": {
              "name": "TacoSoft Demo Data"
            },
            "dimension": {
              "columnName": "order_id"
            }
          }
        }
      }
    ],
    "orderByColumn": 1,
    "first": 10
  }
}

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.