The ML.FORECAST function

ML.FORECAST function

The ML.FORECAST function forecasts a time series based on a trained time series model.

ML.FORECAST returns the following columns:

  • time_series_id: the identifier of a time series. Only present when forecasting multiple time series at once. The column name and type are inherited from the TIME_SERIES_ID_COL option as specified in the model creation query.
  • forecast_timestamp (TIMESTAMP)
  • forecast_value (FLOAT64)
  • standard_error (FLOAT64)
  • confidence_level (FLOAT64)
  • prediction_interval_lower_bound (FLOAT64)
  • prediction_interval_upper_bound (FLOAT64)
  • confidence_interval_lower_bound (FLOAT64) (will be deprecated soon)
  • confidence_interval_upper_bound (FLOAT64) (will be deprecated soon)

ML.FORECAST syntax

ML.FORECAST(MODEL model_name,
           [, STRUCT<horizon INT64, confidence_level FLOAT64> settings])

model_name

model_name is the name of the model that you're using for forecasting. If you do not have a default project configured, prepend the project ID to the model name in following format: `[PROJECT_ID].[DATASET].[MODEL]` (including the backticks); for example, `myproject.mydataset.mymodel`.

horizon

(Optional) Horizon is the number of time points to forecast. The horizon value is type INT64 and is part of the settings STRUCT. The default value is 3, and the maximum value is the horizon value specified in the CREATE MODEL statement for time series models, or 1,000 if not specified. When forecasting multiple time series at the same time, this parameter applies to each time series.

confidence_level

(Optional) The percentage of the future values that fall in the prediction interval. The confidence_level value is type FLOAT64 and is part of the settings STRUCT. The default value is 0.95. The valid input range is [0, 1).

ML.FORECAST output

ML.FORECAST outputs the following columns for all cases: forecast_timestamp, forecast_valuestandard_errorconfidence_level, prediction_interval_lower_bound prediction_interval_upper_bound confidence_interval_lower_bound,and confidence_interval_upper_bound. When forecasting multiple time series at the same time, there is an additional output column: time_series_id.

The output of ML.FORECAST has the following properties:

  • For each time series, the output rows are sorted in the chronological order of forecast_timestamp.
  • forecast_timestamp always has a type of TIMESTAMP, regardless of the type of the input time_series_timestamp_col
  • forecast_value is the average of prediction_interval_lower_bound and prediction_interval_upper_bound.
  • confidence_level is the user-specified value, or the default value if unspecified. It is the same across all rows.

ML.FORECAST example

The following query uses ML.FORECAST to forecast 30 time points with a confidence level of 0.8.

SELECT
  *
FROM
  ML.FORECAST(MODEL `mydataset.mymodel`,
              STRUCT(30 AS horizon, 0.8 AS confidence_level))