The ML.ARIMA_EVALUATE function

ML.ARIMA_EVALUATE function

Use the ML.ARIMA_EVALUATE function to evaluate model metrics of ARIMA_PLUS or ARIMA_PLUS_XREG time-series models.

For information about model evaluation in BigQuery ML, see Model evaluation overview. For information about supported model types of each SQL statement and function, and all supported SQL statements and functions for each model type, read End-to-end user journey for each model.

ML.ARIMA_EVALUATE syntax

ML.ARIMA_EVALUATE(MODEL model_name,
                 [, STRUCT<show_all_candidate_models BOOL> settings])

Note: No input data is required.

model_name

model_name is the name of the ARIMA_PLUS or ARIMA_PLUS_XREG model that you're evaluating. If you do not have a default project configured, then prepend the project ID to the model name in following format: `[project_id].[dataset].[model]` (including the backticks); for example, `myproject.mydataset.mymodel`.

show_all_candidate_models

Optional: You can use show_all_candidate_models to show evaluation metrics or an error message for either all candidate models or for only the best model with the lowest AIC. The value is type BOOL and is part of the settings STRUCT.

When show_all_candidate_models is false, the ML.ARIMA_EVALUATE function returns evaluation metrics for only the best model. When show_all_candidate_models is true, metrics are returned for all candidate models, along with a possible fitting error on a setting of non_seasonal_p, non_seasonal_d, non_seasonal_q, and drift; this applies to both single time-series training with auto.ARIMA and large-scale time-series training cases.

For large-scale time-series forecasting training, regardless of the value of show_all_candidate_models, a single row is returned for a time series for which there is no a valid model. The error message explains the reason, and the values of all other columns are NULL.

For single time-series ARIMA_PLUS or ARIMA_PLUS_XREG models, the default value is TRUE. For large-scale time-series ARIMA_PLUS models, the default value is FALSE.

ML.ARIMA_EVALUATE output

ML.ARIMA_EVALUATE returns the following columns for ARIMA_PLUS and ARIMA_PLUS_XREG time-series models:

• time_series_id_col or time_series_id_cols: the identifiers of a time series. Only present when forecasting multiple time series at once. The column names and types are inherited from the TIME_SERIES_ID_COL option as specified in the model creation query.
• non_seasonal_p (INT64)
• non_seasonal_d (INT64)
• non_seasonal_q (INT64)
• has_drift (BOOL)
• log_likelihood (FLOAT64)
• AIC (FLOAT64)
• variance (FLOAT64)
• seasonal_periods (ARRAY<STRING>)
• has_holiday_effect (BOOL)
• has_spikes_and_dips (BOOL)
• has_step_changes (BOOL)
• error_message (STRING)

Notes:

• The has_holiday_effect, has_spikes_and_dips, and has_step_changes columns are only populated for ARIMA_PLUS models that have decompose_time_series enabled.
• Other than time_series_id_col, time_series_id_cols, seasonal_periods, has_holiday_effect, has_spikes_and_dips, and has_step_changes, all the columns are specific to the fitted ARIMA models.
• The seasonal_periods column has the following valid values: DAILY, WEEKLY, MONTHLY, QUARTERLY, YEARLY, and NO_SEASONALITY. It can be a combination of these values, as a time series can have multiple seasonal periods.
• When non_seasonal_d is not 1, has_drift is set to FALSE by default, as has_drift doesn't apply in those cases.

ML.ARIMA_EVALUATE examples

The following example retrieves the evaluation metrics of the best model from mymodel in mydataset. The dataset is in your default project.

SELECT
  *
FROM
  ML.ARIMA_EVALUATE(MODEL `mydataset.mymodel`, STRUCT(FALSE AS show_all_candidate_models))