# How to Configure Time Series Features in Apache Superset: Time Grain, Comparison, and Forecasting

> Master Apache Superset time series features. Configure time grain, comparisons, and forecasting to visualize, analyze, and predict your data effectively.

- Repository: [The Apache Software Foundation/superset](https://github.com/apache/superset)
- Tags: how-to-guide
- Published: 2026-03-03

---

**Apache Superset provides three core time series controls—time grain selection, time comparison offsets, and predictive analytics forecasting—that allow users to temporalize, compare, and project data directly within the Explore interface.**

When you configure time series features in Apache Superset, you manipulate how temporal data is aggregated, compared across periods, and projected into the future. These capabilities are implemented as reusable control sections in the `superset-ui-chart-controls` package, consumed by chart plugins such as the ECharts Timeseries visualization.

## Core Time Series Components

Superset’s time series functionality revolves around three distinct control groups that appear in the Explore panel when a dataset contains temporal columns.

### Time Grain Selection

The **time grain** control determines the granularity of temporal aggregation. Users select from predefined intervals—such as `P1D` (day), `P1W` (week), or `P1M` (month)—to bucket timestamp data. This control is defined in [`shared-controls.tsx`](https://github.com/apache/superset/blob/main/shared-controls.tsx) and dynamically populates its options based on the datasource’s supported grains.

### Time Comparison

The **time comparison** feature enables overlaying current data against historical periods. Users can select predefined offsets (e.g., “1 week ago”) or define custom date ranges. The control supports multiple comparison periods and calculation types—actual values, difference, percentage change, or ratio. This logic is encapsulated in [`timeComparison.tsx`](https://github.com/apache/superset/blob/main/timeComparison.tsx) as a reusable section.

### Predictive Analytics and Forecasting

The **forecast** control adds statistical forecasting to time series charts using the Prophet library. When enabled, users configure the number of future periods to predict, confidence interval width (typically 0.8), and seasonality components (yearly, weekly, daily). This section is defined in [`forecastInterval.tsx`](https://github.com/apache/superset/blob/main/forecastInterval.tsx) and only appears when the datasource supports time-related controls.

## Source Code Architecture and Implementation

Understanding where these controls are defined allows developers to customize behavior or build new chart plugins that leverage temporal features.

### Shared Control Definitions

The foundational `time_grain_sqla` control resides in [`superset-frontend/packages/superset-ui-chart-controls/src/shared-controls/sharedControls.tsx`](https://github.com/apache/superset/blob/main/superset-frontend/packages/superset-ui-chart-controls/src/shared-controls/sharedControls.tsx) (lines 183–199). It implements the `SharedControlConfig` interface, mapping datasource properties to UI options:

```tsx
const time_grain_sqla: SharedControlConfig<'SelectControl'> = {
  type: 'SelectControl',
  label: TIME_FILTER_LABELS.time_grain_sqla,
  placeholder: t('None'),
  initialValue: (control, state) => {
    return state?.metadata || 'time_grain_sqla' in (state?.form_data ?? {})
      ? state?.form_data?.time_grain_sqla
      : 'P1D';
  },
  description: t('Select a time grain for the visualization.'),
  mapStateToProps: ({ datasource }) => ({
    choices: (datasource as Dataset)?.time_grain_sqla || [],
  }),
  visibility: displayTimeRelatedControls,
};

```

The `visibility` property uses `displayTimeRelatedControls` from [`utils.ts`](https://github.com/apache/superset/blob/main/utils.ts) to ensure the control only appears for time-capable datasources.

### Time Comparison Logic

The time comparison UI is constructed in [`superset-frontend/packages/superset-ui-chart-controls/src/sections/timeComparison.tsx`](https://github.com/apache/superset/blob/main/superset-frontend/packages/superset-ui-chart-controls/src/sections/timeComparison.tsx) (lines 71–98). This file exports `timeComparisonControls`, a factory function returning a `ControlPanelSectionConfig`:

```tsx
export const timeComparisonControls = ({
  multi = true,
  showCalculationType = true,
  showFullChoices = true,
}) => ({
  label: t('Time Comparison'),
  tabOverride: 'data',
  description: t('Compare results with other time periods.'),
  controlSetRows: [
    [
      {
        name: 'time_compare',
        config: {
          type: 'SelectControl',
          multi,
          freeForm: true,
          placeholder: t('Select or type a custom value...'),
          label: t('Time shift'),
          choices: showFullChoices ? fullChoices : reducedChoices,
          description: t('Overlay results from a relative time period.'),
        },
      },
    ],
    [
      {
        name: 'start_date_offset',
        config: {
          type: 'TimeOffsetControl',
          label: t('Shift start date'),
          visibility: ({ controls }) => controls?.time_compare.value === 'custom',
        },
      },
    ],
    [
      {
        name: 'comparison_type',
        config: {
          type: 'SelectControl',
          label: t('Calculation type'),
          default: 'values',
          choices: [
            [ComparisonType.Values, t('Actual values')],
            [ComparisonType.Difference, t('Difference')],
            [ComparisonType.Percentage, t('Percentage change')],
            [ComparisonType.Ratio, t('Ratio')],
          ],
        },
      },
    ],
  ],
});

```

This structure allows chart plugins to enable multi-select time shifts, toggle between full and reduced choice lists, and conditionally display custom offset controls.

### Forecast Configuration

Predictive analytics controls are defined in [`superset-frontend/packages/superset-ui-chart-controls/src/sections/forecastInterval.tsx`](https://github.com/apache/superset/blob/main/superset-frontend/packages/superset-ui-chart-controls/src/sections/forecastInterval.tsx) (lines 33–80):

```tsx
export const forecastIntervalControls = {
  label: t('Predictive Analytics'),
  expanded: false,
  visibility: displayTimeRelatedControls,
  controlSetRows: [
    [
      {
        name: 'forecastEnabled',
        config: {
          type: 'CheckboxControl',
          label: t('Enable forecast'),
          default: false,
          description: t('Enable forecasting'),
        },
      },
    ],
    [
      {
        name: 'forecastPeriods',
        config: {
          type: 'TextControl',
          label: t('Forecast periods'),
          validators: [legacyValidateInteger],
          default: 10,
          description: t('How many periods into the future do we want to predict'),
        },
      },
    ],
    [
      {
        name: 'forecastInterval',
        config: {
          type: 'TextControl',
          label: t('Confidence interval'),
          validators: [legacyValidateNumber],
          default: 0.8,
          description: t('Width of the confidence interval. Should be between 0 and 1'),
        },
      },
    ],
  ],
};

```

The `expanded: false` property ensures the section starts collapsed, reducing UI clutter until the user needs predictive features.

### Chart Plugin Integration

Chart plugins consume these sections by importing from `@superset-ui/chart-controls`. The ECharts Line chart demonstrates this pattern in [`superset-frontend/plugins/plugin-chart-echarts/src/Timeseries/Regular/Line/controlPanel.tsx`](https://github.com/apache/superset/blob/main/superset-frontend/plugins/plugin-chart-echarts/src/Timeseries/Regular/Line/controlPanel.tsx) (line 63):

```tsx
import { sections } from '../../../../../packages/superset-ui-chart-controls';

export default {
  controlSetRows: [
    // … other rows …
    sections.timeComparisonControls({ multi: true, showFullChoices: true }),
    sections.forecastIntervalControls,
  ],
};

```

This modular approach allows any visualization to adopt time series capabilities by including the appropriate section factories in its control panel configuration.

## How to Customize Time Series Controls in Custom Plugins

When building a custom chart plugin, you can import and configure these sections to match your visualization’s requirements:

```tsx
import { sections } from '@superset-ui/chart-controls';

export default {
  controlSetRows: [
    // Time grain selector (provided by sharedControls via the chart’s datasource)
    ['time_grain_sqla'],
    // Time comparison UI – multi-select enabled with reduced choices
    sections.timeComparisonControls({ multi: true, showFullChoices: false }),
    // Forecast UI – collapsible predictive analytics section
    sections.forecastIntervalControls,
  ],
};

```

To conditionally show controls based on datasource capabilities, use the `visibility` property with `displayTimeRelatedControls` from the chart-controls utilities.

## Summary

- **Time grain** configuration resides in [`sharedControls.tsx`](https://github.com/apache/superset/blob/main/sharedControls.tsx) as `time_grain_sqla`, dynamically populating options from the datasource and defaulting to `P1D` (daily) when unspecified.
- **Time comparison** functionality is packaged in [`timeComparison.tsx`](https://github.com/apache/superset/blob/main/timeComparison.tsx), offering multi-select period offsets, custom date ranges, and calculation types (difference, percentage, ratio).
- **Forecasting** capabilities are defined in [`forecastInterval.tsx`](https://github.com/apache/superset/blob/main/forecastInterval.tsx), providing Prophet-based predictive analytics with configurable periods, confidence intervals, and seasonality.
- Chart plugins integrate these features by importing `sections` from `@superset-ui/chart-controls` and adding them to `controlSetRows`, with visibility governed by `displayTimeRelatedControls`.

## Frequently Asked Questions

### What is time grain in Apache Superset?

**Time grain** refers to the temporal aggregation level applied to datetime columns in a visualization. In Superset, the `time_grain_sqla` control (defined in [`sharedControls.tsx`](https://github.com/apache/superset/blob/main/sharedControls.tsx)) allows users to select intervals such as hour, day, week, or month, which determines how data points are bucketed on the x-axis of time series charts.

### How does time comparison work in Superset charts?

Time comparison overlays current data with historical periods using the `timeComparisonControls` section from [`timeComparison.tsx`](https://github.com/apache/superset/blob/main/timeComparison.tsx). Users select predefined offsets (e.g., "1 week ago") or custom ranges, and choose calculation types including actual values, absolute difference, percentage change, or ratio. The backend then generates SQL queries that retrieve data for both the current and comparison periods.

### Can I enable forecasting on any chart type?

Forecasting is available only on chart plugins that explicitly import the `forecastIntervalControls` section from [`forecastInterval.tsx`](https://github.com/apache/superset/blob/main/forecastInterval.tsx) and operate on time-series datasources. The feature requires the `displayTimeRelatedControls` visibility check to pass, ensuring the datasource supports temporal operations. Currently, this is primarily implemented in ECharts-based time series visualizations within the Superset codebase.

### Where are time series controls defined in the source code?

The three primary time series control definitions reside in the `superset-frontend/packages/superset-ui-chart-controls/src/` directory: [`shared-controls/sharedControls.tsx`](https://github.com/apache/superset/blob/main/shared-controls/sharedControls.tsx) contains the time grain logic; [`sections/timeComparison.tsx`](https://github.com/apache/superset/blob/main/sections/timeComparison.tsx) defines the comparison UI; and [`sections/forecastInterval.tsx`](https://github.com/apache/superset/blob/main/sections/forecastInterval.tsx) manages predictive analytics. Chart plugins consume these through the `sections` export to build their control panels.