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

The Metric to Query. It can be a pre-created one or it can be inlined here.

timeRangeTimeRangeInputNo

The time range for calculating the time series.

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

granularityTimeSeriesGranularityYes

The time granularity (hour, day, month, etc.) to aggregate the Metric values by.

filters array of FilterInputNo

The Query Filters to apply before retrieving the time series data. If no Query Filters are provided, all data is included.

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.

FieldTypeNullableDescription
labels array of StringNo

The time series labels.

values array of StringNo

The time series values.

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 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:
query TimeSeriesExample1($input: TimeSeriesInput!) {
  timeSeries(input: $input) {
    labels
    values
  }
}

Variables:

{
  "input": {
    "metric": {
      "sum": {
        "dataPool": {
          "name": "TacoSoft Demo Data"
        },
        "measure": {
          "columnName": "taco_total_price"
        }
      }
    },
    "granularity": "DAY",
    "timeRange": {
      "start": "2023-08-03T07:00:00.000Z",
      "stop": "2023-08-09T07:00:00.000Z"
    },
    "filters": [
      "column": "restaurant_name",
      "operator": "EQUALS",
      "value": "El Buen Sabor"
    ]
  }
}

Variables:

{
  "data": {
    "timeSeries": {
      "labels": [
        "2023-08-03T00:00:00.000Z",
        "2023-08-04T00:00:00.000Z",
        "2023-08-05T00:00:00.000Z",
        "2023-08-06T00:00:00.000Z",
        "2023-08-07T00:00:00.000Z",
        "2023-08-08T00:00:00.000Z",
        "2023-08-09T00:00:00.000Z"
      ],
      "values": ["0", "1654.75", "4288.5", "3751", "3994", "4311", "1655.75"]
    }
  }
}

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.