Skip to main content

Metric Report

The Metric Report query gives you an easy way to build reports based on one or many Metrics grouped by a common dimension. For example, a report that shows the revenue and volume for the top products. The revenue and volume would be the Metrics, and the product name would be the dimension.

Metric Reports can be visualized as tables. They have sortable columns and built-in pagination that make their implementation quick and simple.

Prerequisites:​

At least one Metric with at least one dimension is required in order to return a Metric Report.

Usage​

Any time you need to show tabular data with multiple Metrics broken down by dimension and sorted, consider using Metric Report. Along with time series, Metric Reports can provide significant insight when included in in-product analytics. Metric Reports are typically rendered as tables.

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.
  3. The metrics you wish to display.
  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.

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.

Read more about MetricReportConnection.

Example​

In the below query, we are grouping by Channel and then Product Name and then returning Sales and Sales Volume metrics for each row. We have a filter on the Sales Volume metric ensuring we are only seeing "DIRECT" channel results. OrderByColumn:3 means we are ordering by the Sales metric, and first means we are retrieving the first 5 rows.

query {
  metricReport(
    input: {
      timeRange: { start: "2022-01-01T00:00:00Z", stop: "2023-02-01T00:00:00Z" }
      dimensions: [
        { columnName: "CHANNEL", displayName: "Channel" }
        { columnName: "PRODUCT_NAME", displayName: "Product Name" }
      ]
      metrics: [
        { id: "METxxx", displayName: "Sales", sort: ASC }
        {
          id: "METxxx"
          displayName: "Sales Volume"
          filters: [{ column: "CHANNEL", operator: EQUALS, value: "DIRECT" }]
        }
      ]
      orderByColumn: 3
      first: 5
    }
  ) {
    headers
    rows
    query {
      durationInMilliseconds
      recordsProcessed
      bytesProcessed
    }
    pageInfo {
      startCursor
      endCursor
      hasNextPage
      hasPreviousPage
    }
  }
}