Time Series Forecasting

Build production forecasting systems with ARIMA, Prophet, N-BEATS, and transformer-based temporal fusion models.

Time series forecasting is the process of predicting future values based on historical observations of a sequence of data points collected over time. It matters when systems need to anticipate resource usage, detect anomalies, or plan operations based on temporal patterns.

## Getting Started with Forecasting Models

To begin forecasting, you must first prepare data in a structured format and define a model configuration. Time series data should be stored as rows with timestamps and numeric values. The simplest approach uses a SQL table:

CREATE TABLE time_series_data (
    timestamp TIMESTAMP,
    value NUMERIC,
    metric_name TEXT
);

You can load sample data with:

INSERT INTO time_series_data (timestamp, value, metric_name)
VALUES ('2023-01-01 00:00:00', 100.0, 'cpu_usage'),
       ('2023-01-01 01:00:00', 105.2, 'cpu_usage'),
       ('2023-01-01 02:00:00', 98.7, 'cpu_usage');

Models are configured through JSON or YAML files that define the model type, features, and hyperparameters. For example, a configuration file for an ARIMA model might look like:

model:
  type: arima
  order: [1, 1, 1]
  seasonal_order: [0, 1, 1, 24]
  exogenous_vars: []

## Training a Forecasting Model

Training requires specifying the historical data source and the forecast horizon. You pass training data to a model trainer using standard HTTP APIs:

curl -X POST http://forecasting-api/train \
  -H "Content-Type: application/json" \
  -d '{
    "data_source": "time_series_data",
    "target_column": "value",
    "timestamp_column": "timestamp",
    "horizon": 24,
    "model_config": {
      "type": "arima",
      "order": [1, 1, 1]
    }
  }'

The API returns a model ID for later use:

{
  "model_id": "model_abc123",
  "status": "training"
}

Training fails silently if timestamps are not strictly increasing or if there are missing values in the series. The system does not validate data integrity before training begins.

## Making Predictions

To generate forecasts, you call the prediction endpoint with a model ID and a time range:

curl -X POST http://forecasting-api/predict \
  -H "Content-Type: application/json" \
  -d '{
    "model_id": "model_abc123",
    "start_time": "2023-01-02 00:00:00",
    "end_time": "2023-01-02 23:00:00"
  }'

The response contains predicted values:

{
  "predictions": [
    {"timestamp": "2023-01-02 00:00:00", "value": 102.1},
    {"timestamp": "2023-01-02 01:00:00", "value": 103.5}
  ]
}

Predictions fail when the model was trained on data with irregular intervals, even if the prediction interval is regular. The system assumes consistent sampling frequency during training.

## Handling Missing Data

Missing values in training data are handled by interpolation. You can configure interpolation methods:

preprocessing:
  missing_data_handling:
    method: linear_interpolation
    max_gap: 24

If gaps exceed the configured max_gap, the system skips those periods entirely, which can cause a misalignment in predictions.

## Setting Forecast Horizon

The forecast horizon defines how far into the future you want to predict. It is specified during training:

curl -X POST http://forecasting-api/train \
  -H "Content-Type: application/json" \
  -d '{
    "data_source": "time_series_data",
    "horizon": 72,
    "model_config": {
      "type": "prophet"
    }
  }'

Horizon values larger than 1000 may trigger warnings about computational complexity, but they do not fail the training process.

## Configuring Model Parameters

Each model type accepts specific parameters. For Prophet models, you specify:

model:
  type: prophet
  changepoint_prior_scale: 0.05
  seasonality_mode: multiplicative
  weekly_seasonality: true

Parameters like changepoint_prior_scale control how quickly the model adapts to changes in trend. Values outside the recommended range (e.g., below 0.01 or above 0.5) can cause overfitting or underfitting without clear error messages.

## Monitoring Model Performance

Model performance is evaluated using metrics such as MAE, RMSE, and MAPE. You can retrieve these after training:

curl http://forecasting-api/model/model_abc123/performance

Response includes:

{
  "mae": 2.3,
  "rmse": 3.1,
  "mape": 0.05
}

Performance metrics are calculated only on the last 10% of data points used for validation, not on all historical data.

## Managing Multiple Time Series

For multiple series, you must define a unique identifier per series:

CREATE TABLE multi_series_data (
    timestamp TIMESTAMP,
    value NUMERIC,
    series_id TEXT
);

Training is done per series ID:

curl -X POST http://forecasting-api/train \
  -H "Content-Type: application/json" \
  -d '{
    "data_source": "multi_series_data",
    "series_column": "series_id",
    "target_column": "value",
    "horizon": 24
  }'

Predictions for a specific series are made by specifying the series ID:

curl -X POST http://forecasting-api/predict \
  -H "Content-Type: application/json" \
  -d '{
    "model_id": "model_abc123",
    "series_id": "cpu_usage"
  }'

## Error Handling and Failure Modes

Training fails with a generic error message when data points are not ordered chronologically. The system does not return a detailed list of invalid rows but instead logs the first error encountered.

If a model is trained with insufficient historical data (e.g., less than 50 data points), it will still complete successfully, but predictions may be unreliable without explicit warnings.

Predictions fail when attempting to forecast beyond the last known timestamp in training data. The system does not extrapolate beyond the available window, even if the model supports it.

## Scaling Predictions

To scale prediction workloads, you can run multiple concurrent prediction requests:

parallel -j 4 curl -X POST http://forecasting-api/predict \
  -H "Content-Type: application/json" \
  -d '{
    "model_id": "model_abc123",
    "start_time": "2023-01-02 00:00:00",
    "end_time": "2023-01-02 01:00:00"
  }' ::: {0..3}

This approach works well for small horizons but may cause resource contention on larger predictions.

## Retraining Models

Models can be retrained with new data. You must provide a complete dataset including historical points:

curl -X POST http://forecasting-api/retrain \
  -H "Content-Type: application/json" \
  -d '{
    "model_id": "model_abc123",
    "new_data_source": "time_series_data",
    "horizon": 24
  }'

Retraining replaces the entire model rather than incrementally updating it. If new data has gaps, they are interpolated using the same method as during initial training.

## Versioning and Rollback

Models are versioned by ID, but no automatic rollback mechanism exists. If a retrained model performs poorly, you must manually switch back to an earlier version:

curl -X POST http://forecasting-api/rollback \
  -H "Content-Type: application/json" \
  -d '{
    "model_id": "model_abc123",
    "version": "v1.2"
  }'

The system does not maintain a history of model configurations or parameters, so rollback requires manual tracking of previous settings.

## Configuration Best Practices

Always ensure that your time series data is regularly updated and has consistent intervals. Avoid training models with data that includes gaps larger than expected for your domain.

Use a dedicated table for each forecasting task to simplify querying and prevent cross-contamination of data.

Configure appropriate horizons based on your use case. For example, if you're forecasting CPU usage for next 24 hours, set horizon to 24; if you're predicting seasonal trends, set it to at least 168 (a week).

Monitor for consistent timestamps in training and prediction phases. Inconsistent intervals will lead to misaligned predictions without clear error messages.

## Common Gotchas

The system does not validate that the forecasted period aligns with the model's expected sampling frequency. A model trained on hourly data may produce results when asked to predict minute-by-minute values, but those predictions will be unreliable.

Model parameters like seasonality_mode can silently default to additive if not explicitly set, leading to incorrect seasonal adjustments in some cases.

If a training job times out, it may leave the model in an inconsistent state. The system does not automatically retry failed jobs or provide recovery mechanisms.

Predictions made during model retraining are not atomic. If you request a prediction while retraining is in progress, you may receive results from either the old or new model depending on timing.

No automatic data quality checks occur during training. You must implement your own validation to ensure that data points are not outliers or corrupted before passing them to the forecasting engine.

This page was rewritten on 15 October 2026. It replaced a templated version that was not specific to its own title. How these pages are written and checked. If anything here is wrong, tell us at [email protected] and we will correct it.