Time Series

Use cases

Time Series visualization

Visualize time series data in your apps.

In-app sparklines

Create inline visualizations in your apps.

Features

All the common API features, plus:

Aggregate data by time granularities

Aggregate data by various time granularities.Available granularities:

MINUTE: Aggregates values by minute intervals
FIVE_MINUTES: Aggregates values by 5-minute intervals
TEN_MINUTES: Aggregates values by 10-minute intervals
FIFTEEN_MINUTES: Aggregates values by 15-minute intervals
HOUR: Aggregates values by hourly intervals
DAY: Aggregates values by daily intervals
WEEK: Aggregates values by weekly intervals
MONTH: Aggregates values by monthly intervals
YEAR: Aggregates values by yearly intervals

Group results by columns

Group results by specific columns.

Query

query TimeSeriesWithGroupByExample {
  timeSeries(input: {
    ...
    groupBy: ["restaurant_name"]
    ...
  }) {
    labels
    values
  }
}

Zero-fill missing data points

Automatically zero-fills missing data points to ensure consistent time series.

Timezone-aware time granularities

Calculates time series granules for the given time zone, allowing for accurate representation of data across different geographical locations.

Query

query TimeSeriesWithGroupByExample {
  timeSeries(input: {
    ...
    timeZone: "America/Los_Angeles"
    ...
  }) {
    labels
    values
  }
}

Example

Example 1: Simple time series query

Get the total taco sales for the last 3 days, filtered by the restaurant name.

query TimeSeriesExample1 {
  timeSeries(input: {
    metric: {
      sum: {
        dataPool: {
          name: "TacoSoft Demo Data"
        },
        measure: {
          columnName: "taco_total_price"
        }
      }
    },
    granularity: DAY,
    timeRange: {
      relative: LAST_N_DAYS,
      n: 3
    },
    filterSql: "restaurant_name = 'El Buen Sabor'"
  }) {
    labels
    values
  }
}

{
  "timeSeries": {
    "labels": [
      "2024-10-06T00:00:00Z",
      "2024-10-07T00:00:00Z",
      "2024-10-08T00:00:00Z"
    ],
    "values": [
      "382",
      "977.25",
      "0"
    ]
  }
}

Usage

Arguments

The fields for querying a Metric in time series format. A Metric’s time series query returns the values over a given time range aggregated by a given time granularity; day, month, or year, for example.

MetricInput

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

Show MetricInput

The ID of a pre-configured Metric.

String

The name of a pre-configured Metric.

CustomMetricQueryInput

An ad hoc Custom Metric.

Show CustomMetricQueryInput

DataPoolInput

required

The Data Pool to which this Metric belongs.

Show DataPoolInput

The ID of the Data Pool.

String

The name of the Data Pool.

String

required

Custom expression for defining the Metric.

CountMetricQueryInput

An ad hoc Count Metric.

Show CountMetricQueryInput

DataPoolInput

required

The Data Pool to which this Metric belongs.

Show DataPoolInput

The ID of the Data Pool.

String

The name of the Data Pool.

SumMetricQueryInput

An ad hoc Sum Metric.

Show SumMetricQueryInput

DataPoolInput

required

The Data Pool to which this Metric belongs.

Show DataPoolInput

The ID of the Data Pool.

String

The name of the Data Pool.

DimensionInput

required

The column to be summed.

Show DimensionInput

The fields for creating or modifying a Dimension.

String

required

The name of the column to create the Dimension from.

AverageMetricQueryInput

An ad hoc Average Metric.

Show AverageMetricQueryInput

DataPoolInput

required

The Data Pool to which this Metric belongs.

Show DataPoolInput

The ID of the Data Pool.

String

The name of the Data Pool.

DimensionInput

required

The column to be averaged.

Show DimensionInput

The fields for creating or modifying a Dimension.

String

required

The name of the column to create the Dimension from.

MinMetricQueryInput

An ad hoc Min Metric.

Show MinMetricQueryInput

DataPoolInput

required

The Data Pool to which this Metric belongs.

Show DataPoolInput

The ID of the Data Pool.

String

The name of the Data Pool.

DimensionInput

required

The column to calculate the minimum from.

Show DimensionInput

The fields for creating or modifying a Dimension.

String

required

The name of the column to create the Dimension from.

MaxMetricQueryInput

An ad hoc Max Metric.

Show MaxMetricQueryInput

DataPoolInput

required

The Data Pool to which this Metric belongs.

Show DataPoolInput

The ID of the Data Pool.

String

The name of the Data Pool.

DimensionInput

required

The column to calculate the maximum from.

Show DimensionInput

The fields for creating or modifying a Dimension.

String

required

The name of the column to create the Dimension from.

CountDistinctMetricQueryInput

An ad hoc Count Distinct Metric.

Show CountDistinctMetricQueryInput

DataPoolInput

required

The Data Pool to which this Metric belongs.

Show DataPoolInput

The ID of the Data Pool.

String

The name of the Data Pool.

DimensionInput

required

The column to count distinct values from.

Show DimensionInput

The fields for creating or modifying a Dimension.

String

required

The name of the column to create the Dimension from.

TimeRangeInput

The time range for calculating the time series.

Show TimeRangeInput

The fields required to specify the time range for a time series, counter, or leaderboard Metric query.If no relative or absolute time ranges are provided, Propel defaults to an absolute time range beginning with the earliest record in the Metric’s Data Pool and ending with the latest record.If both relative and absolute time ranges are provided, the relative time range will take precedence.If a LAST_N relative time period is selected, an n ≥ 1 must be provided. If no n is provided or n < 1, a BAD_REQUEST error will be returned.

String

The timestamp field to use when querying. Defaults to the timestamp configured on the Data Pool or Metric, if any. Set this to filter on an alternative timestamp field.

RelativeTimeRange

The relative time period.

Show RelativeTimeRange

The Relative time ranges are based on the current date and time.THIS - The current unit of time. For example, if today is June 8, 2022, and THIS_MONTH is selected, then data for June 2022 would be returned.PREVIOUS - The previous unit of time. For example, if today is June 8, 2022, and PREVIOUS_MONTH is selected, then data for May 2022 would be returned. It excludes the current unit of time.NEXT - The next unit of time. For example, if today is June 8, 2022, and NEXT_MONTH is selected, then data for July 2022 would be returned. It excludes the current unit of time.LAST_N - The last n units of time, including the current one. For example, if today is June 8, 2022 and LAST_N_YEARS with n = 3 is selected, then data for 2020, 2021, and 2022 will be returned. It will include the current time period.

THIS_HOUR: Starts at the zeroth minute of the current hour and continues for 60 minutes.
TODAY: Starts at 12:00:00 AM of the current day and continues for 24 hours.
THIS_WEEK: Starts on Monday, 12:00:00 AM of the current week and continues for seven days.
THIS_MONTH: Starts at 12:00:00 AM on the first day of the current month and continues for the duration of the month.
THIS_QUARTER: Starts at 12:00:00 AM on the first day of the current calendar quarter and continues for the duration of the quarter.
THIS_YEAR: Starts on January 1st, 12:00:00 AM of the current year and continues for the duration of the year.
PREVIOUS_HOUR: Starts at the zeroth minute of the previous hour and continues for 60 minutes.
YESTERDAY: Starts at 12:00:00 AM on the day before the today and continues for 24 hours.
PREVIOUS_WEEK: Starts on Monday, 12:00:00 AM, a week before the current week, and continues for seven days.
PREVIOUS_MONTH: Starts at 12:00:00 AM on the first day of the month before the current month and continues for the duration of the month.
PREVIOUS_QUARTER: Starts at 12:00:00 AM on the first day of the calendar quarter before the current quarter and continues for the duration of the quarter.
PREVIOUS_YEAR: Starts on January 1st, 12:00:00 AM, the year before the current year, and continues for the duration of the year.
NEXT_HOUR: Starts at the zeroth minute of the next hour and continues for 60 minutes.
TOMORROW: ” Starts at 12:00:00 AM, the day after the current day, and continues for 24 hours.
NEXT_WEEK: Starts on Monday, 12:00:00 AM, the week after the current week, and continues for the duration of the week.
NEXT_MONTH: Starts at 12:00:00 AM on the first day of the next month and continues for the duration of the month.
NEXT_QUARTER: Starts at 12:00:00 AM on the first day of the next calendar quarter and continues for the duration of the quarter.
NEXT_YEAR: Starts on January 1st, 12:00:00 AM of the next year and continues for the duration of the year.
LAST_N_MINUTES: Starts at the zeroth second n - 1 minute(s) before the current minute and continues through the current minute. It includes this minute.
LAST_N_HOURS: Starts at the zeroth minute of the n - 1 hour(s) before the current hour, and continues through the current hour. It includes this hour.
LAST_N_DAYS: Starts at 12:00:00 AM, n - 1 day(s) before the current day, and continues through the current day. It includes today.
LAST_N_WEEKS: Starts on Monday, 12:00:00 AM, n - 1 week(s) before the current week, and continues through the current week. It includes this week.
LAST_N_MONTHS: Starts at 12:00:00 AM on the first day of the month, n - 1 month(s) before the current month, and continues through the current month. It includes this month.
LAST_N_QUARTERS: Starts at 12:00:00 AM on the first day of the calendar quarter n - 1 quarter(s) before the current quarter and continues through the current quarter. It includes this quarter.
LAST_N_YEARS: Starts on January 1st, 12:00:00 AM of the year n - 1 year(s) before the current year and continues through the current year. It includes this year.
LAST_15_MINUTES
LAST_30_MINUTES
LAST_HOUR
LAST_4_HOURS
LAST_12_HOURS
LAST_24_HOURS
LAST_7_DAYS
LAST_30_DAYS
LAST_90_DAYS
LAST_3_MONTHS
LAST_6_MONTHS
LAST_YEAR
LAST_2_YEARS
LAST_5_YEARS

Int

The number of time units for the LAST_N relative periods.

DateTime

The optional start timestamp (inclusive). Defaults to the timestamp of the earliest record in the Data Pool.

DateTime

The optional end timestamp (exclusive). Defaults to the timestamp of the latest record in the Data Pool.

String

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

TimeSeriesGranularity

required

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

Show TimeSeriesGranularity

The available time series granularities. Granularities define the unit of time to aggregate the Metric data for a time series query.For example, if the granularity is set to DAY, then the the time series query will return a label and a value for each day.If there are no records for a given time series granularity, Propel will return the label and a value of “0” so that the time series can be properly visualized.

MINUTE: Aggregates values by minute intervals.
FIVE_MINUTES: Aggregates values by 5-minute intervals.
TEN_MINUTES: Aggregates values by 10-minute intervals.
FIFTEEN_MINUTES: Aggregates values by 15-minute intervals.
HOUR: Aggregates values by hourly intervals.
DAY: Aggregates values by daily intervals.
WEEK: Aggregates values by weekly intervals.
MONTH: Aggregates values by monthly intervals.
YEAR: Aggregates values by yearly intervals.

String

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

[String!]

Columns to group by.

Show Deprecated Fields

deprecated

The ID of the Metric to query.Required if metricName is not specified.deprecated: Use metric

String

deprecated

The name of the Metric to query.Required if metricId is not specified.deprecated: Use metric

[FilterInput!]

deprecated

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

Show FilterInput

The fields of a filter.You can construct more complex filters using and and or. For example, to construct a filter equivalent to

(value > 0 AND value <= 100) OR status = "confirmed"

you could write

{
  "column": "value",
  "operator": "GREATER_THAN",
  "value": "0",
  "and": [{
    "column": "value",
    "operator": "LESS_THAN_OR_EQUAL_TO",
    "value": "0"
  }],
  "or": [{
    "column": "status",
    "operator": "EQUALS",
    "value": "confirmed"
  }]
}

Note that and takes precedence over or.

String

required

The name of the column to filter on.

FilterOperator

required

The operation to perform when comparing the column and filter values.

Show FilterOperator

The available Filter operators.

EQUALS: Selects values that are equal to the specified value.
NOT_EQUALS: Selects values that are not equal to the specified value.
GREATER_THAN: Selects values that are greater than the specified value.
GREATER_THAN_OR_EQUAL_TO: Selects values that are greater or equal to the specified value.
LESS_THAN: Selects values that are less than the specified value.
LESS_THAN_OR_EQUAL_TO: Selects values that are less or equal to the specified value.
IS_NULL: Selects values that are null. This operator does not accept a value.
IS_NOT_NULL: Selects values that are not null. This operator does not accept a value.
LIKE: Selects values that match the specified pattern.
NOT_LIKE: “Selects values that do not match the specified pattern.

String

The value to compare the column to.

[FilterInput!]

Additional filters to AND with this one. AND takes precedence over OR.

[FilterInput!]

Additional filters to OR with this one. AND takes precedence over OR.

Response

The time series response object. It contains an array of time series labels and an array of Metric values for the given time range and Query Filters.

[String!]

required

The time series labels.

[String]

required

The time series values.

[TimeSeriesResponseGroup!]

The time series values for each group in groupBy, if specified.

Show TimeSeriesResponseGroup

The time series response object for a group specified in groupBy. It contains an array of time series labels and an array of Metric values for a particular group.

[String]

required

The time series group’s columns.

[String!]

required

The time series group’s labels.

[String]

required

The time series group’s values.

QueryInfo

required

The Query statistics and metadata.

Show QueryInfo

The Query Info object. It contains metadata and statistics about a Query performed.

required

The Query’s unique identifier.

DateTime

required

The date and time in UTC when the Query was created.

String

required

The unique identifier of the actor that performed the Query.

DateTime

required

The date and time in UTC when the Query was last modified.

String

required

The unique identifier of the actor that modified the Query.

String

required

The bytes processed by the Query.

Int

required

The duration of the Query in milliseconds.

String

required

The number of records processed by the Query.

Int

required

The bytes returned by the Query.

Int

required

The number of records returned by the Query.

Propeller

The Propeller used for this query.

Show Propeller

A Propeller determines your Application’s query processing power. The larger the Propeller, the faster the queries and the higher the cost. Every Propel Application (and therefore every set of API credentials) has a Propeller that determines the speed and cost of queries.

P1_X_SMALL: Max records per second: 5,000,000 records per second
P1_SMALL: Max records per second: 25,000,000 records per second
P1_MEDIUM: Max records per second: 100,000,000 records per second
P1_LARGE: Max records per second: 250,000,000 records per second
P1_X_LARGE: Max records per second: 500,000,000 records per second

QueryStatus

required

The Query status.

Show QueryStatus

The Query status.

COMPLETED: The Query was completed succesfully.
ERROR: The Query experienced an error.
TIMED_OUT: The Query timed out.

QueryType

required

The Query type.

Show QueryType

The Query type.

METRIC: Indicates a Metric Query.
STATS: Indicates a Dimension Stats Query.
REPORT: Indicates a Report Query.
RECORDS: Indicates a Record Table Query.
RECORDS_BY_UNIQUE_ID: Indicates records queried by unique ID.
SQL: Indicates a SQL Query.
TOP_VALUES: Indicates a Top Values Query.

QuerySubtype

The Query subtype.

Show QuerySubtype

The Query subtype.

COUNTER: Indicates a Metric counter Query.
TIME_SERIES: Indicates a Metric time series Query.
LEADERBOARD: Indicates a Metric leaderboard Query.

String

required

The SQL the query executed.

Embeddable UI components

Time series component

A React component for rendering ready-to-chart time series data.

useTimeSeries

A React Hook for ready-to-chart time series data from the Time Series API.

Get Started

APIs

Metrics

Guides

Use cases

Time Series visualization

In-app sparklines

Features

Example

Example 1: Simple time series query

Usage

Arguments

Response

Embeddable UI components

Time series component

useTimeSeries

​Use cases

Time Series visualization

In-app sparklines

​Features

​Example

​Example 1: Simple time series query

​Usage

​Arguments

​Response

​Embeddable UI components

Time series component

useTimeSeries

Use cases

Features

Example

Example 1: Simple time series query

Usage

Arguments

Response

Embeddable UI components