Counter

Every Metric can be visualized as a counter. This is the simplest way to query a Metric, returning a single value summarizing the Metric over the requested time range. For example, a counter could represent

• The sum of sales for the quarter,
• A count of signups for the week, or
• Error occurrences in the last hour.

Any time a single number will do, consider using a counter. For more complex visualizations that return multiple values, check out Time Series and Leaderboard.

Usage

When building customer-facing analytics, you could place a counter inline next to some text, as an icon at the start of a <button>, or you could make it extra-large in a dashboard, to grab the customer's attention:

659

An example of an extra-large counter you might present in a dashboard.

Arguments

You will pass a CounterInput when querying the counter. The most important arguments are

1. The timeRange to query over, and
2. The filters to use.

Field	Type	Required	Description
metric	MetricInput	No	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.
timeRange	TimeRangeInput	No	The time range for calculating the counter.
timeZone	String	No	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".
filterSql	String	No	The Query Filters to apply before retrieving the counter data, in the form of SQL. If no Query Filters are provided, all data is included.

Returns

The query returns a single value inside a CounterResponse. The value is a number wrapped in a string. Using a string ensures we can support values greater than 32-bits in the GraphQL API.

Field	Type	Nullable	Description
value	String	Yes	The value of the counter.
query	QueryInfo	No	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.

We can first create a Sum Metric named "Revenue" which sums up the price column. By including restaurant_name and taco_name as Dimensions, we can answer questions with our Metric. Follow along for worked examples.

1. How much revenue did a particular restaurant generate?

In this example, we seek to find out the total revenue generated by a specific restaurant over the last year. This is accomplished by querying our Revenue Metric and applying filters for the restaurant_name dimension. We pass in an input variable containing our specific conditions: a timeRange specifying the last year and a filter set to equal "La Taqueria". The query returns the total revenue wrapped in a string.

GraphQL query

Query:

query CounterExample1($input: CounterInput!) {
  counter(input: $input) {
    value
  }
}

Variables:

{
  "input": {
    "metric": {
      "sum": {
        "dataPool": {
          "name": "TacoSoft Demo Data"
        },
        "measure": {
          "columnName": "taco_total_price"
        }
      }
    },
    "timeRange": {
      "relative": "LAST_N_YEARS",
      "n": 1
    },
    "filters": [
      {
        "column": "restaurant_name",
        "operator": "EQUALS",
        "value": "La Taqueria"
      }
    ]
  }
}

JSON Response

{
  "data": {
    "counter": {
      "value": "2940"
    }
  }
}

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

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

2. How much revenue did a particular taco generate?

Building on the previous example, we can also determine the revenue generated by a specific taco. While the query structure remains the same, we'll modify the filter condition to target the taco_name Dimension instead of the restaurant_name Dimension.

GraphQL Query

query CounterExample2($input: CounterInput!) {
  counter(input: $input) {
    value
  }
}

GraphQL Variables

{
  "input": {
    "metricName": "Revenue",
    "timeRange": {
      "relative": "LAST_N_YEARS",
      "n": 1
    },
    "filters": [
      {
        "column": "taco_name",
        "operator": "EQUALS",
        "value": "Breakfast"
      }
    ]
  }
}

JSON Response

{
  "data": {
    "counter": {
      "value": "2979"
    }
  }
}

Replicate this query in the GraphQL Explorer. More on Counter queries here.