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

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 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 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 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 (lines 183–199). It implements the SharedControlConfig interface, mapping datasource properties to UI options:

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 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 (lines 71–98). This file exports timeComparisonControls, a factory function returning a ControlPanelSectionConfig:

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 (lines 33–80):

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 (line 63):

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:

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 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, offering multi-select period offsets, custom date ranges, and calculation types (difference, percentage, ratio).
• Forecasting capabilities are defined in 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) 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. 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 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 contains the time grain logic; sections/timeComparison.tsx defines the comparison UI; and sections/forecastInterval.tsx manages predictive analytics. Chart plugins consume these through the sections export to build their control panels.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}