Skip to main content

Time Series

Every Metric can be visualized as a Time Series. Unlike Counters, which return a single value for a time range, a Time Series returns values for every time granule over the requested time range. For example, a Time Series could represent

  • Monthly sales for the quarter,
  • Daily signups for the week, or
  • Minute-by-minute error occurrences in the last hour.

Any time you need to visualize a change in Metric over time, consider using a Time Series. If one value will do, consider using a Counter; otherwise, if you need a Metric broken down by Dimension and sorted, consider using a Leaderboard.

Usage​

When building customer-facing analytics, Time Series are essential for understanding how a Metric changes over time. Most customer dashboards are centered around a time series, and any additional visualizations use a time range derived from the Time Series.

There are lots of libraries you can use to visualize Time Series. We've chosen to use Propel's open source UI Kit in the example above, but Propel is compatible with all charting libraries. If you're using React and want some inspiration, check out our blog post, Best React Charting Libraries for Data Visualization and Analytics.

Arguments​

You will pass a TimeSeriesInput when querying the Time Series. The most important arguments are

  1. The timeRange to query over,
  2. The time granularity to aggregate by, and
  3. The filters to use.

Read more about TimeSeriesInput.

Returns​

The query returns an array of labels and an array of values inside a TimeSeriesResponse. There is a label and value for every time granule of the requested time range.

Each label is a timestamp wrapped in a string, for example, "2023-02-01T00:00:00.000Z".

Each value 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 TimeSeriesResponse.

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 create a Sum Metric named "Revenue" which sums up the sales data. By including "taco_name" and "restaurant_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 demonstrate how to query the total revenue for a specific restaurant, "El Buen Sabor," over a set period of time from "2023-08-03T07:00:00.000Z" to "2023-08-09T07:00:00.000Z".

query TimeSeriesExample1($input: TimeSeriesInput!) {
  timeSeries(input: $input) {
    labels
    values
  }
}

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

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

2. How much revenue did a particular taco generate?​

In this example, we demonstrate how to query the revenue generated by a specific taco, "Shrimp," using a relative time range for the current month.

query TimeSeriesExample2($input: TimeSeriesInput!) {
  timeSeries(input: $input) {
    labels
    values
  }
}

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