Skip to main content

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:

103

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

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.

timeRangeTimeRangeInputNo

The time range for calculating the counter.

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".

filters array of FilterInputNo

The Query Filters to apply before retrieving the counter data. 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.

FieldTypeNullableDescription
valueStringYes

The value of the counter.

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.

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.


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"
}
]
}
}

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.

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

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