Stay organized with collections
Save and categorize content based on your preferences.
The ML.ARIMA_EVALUATE function
This document describes the ML.ARIMA_EVALUATE function, which you can use
to evaluate the model metrics of ARIMA_PLUS or ARIMA_PLUS_XREG time series
models.
Syntax
ML.ARIMA_EVALUATE(
MODEL `PROJECT_ID.DATASET.MODEL_NAME`,
[, STRUCT(SHOW_ALL_CANDIDATE_MODELS AS show_all_candidate_models)])
Arguments
ML.ARIMA_EVALUATE takes the following arguments:
PROJECT_ID: Your project ID.
DATASET: The BigQuery dataset that contains
the model.
MODEL_NAME: The name of the model.
SHOW_ALL_CANDIDATE_MODELS: a BOOL value that
indicates whether to show evaluation metrics or an error message for either
all candidate models or for only the best model with the lowest
Akaike information criterion (AIC).
When the SHOW_ALL_CANDIDATE_MODELS argument value is FALSE, the
ML.ARIMA_EVALUATE function returns evaluation metrics for only the best
model. When the SHOW_ALL_CANDIDATE_MODELS argument value 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
the SHOW_ALL_CANDIDATE_MODELS argument, 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.
Output
ML.ARIMA_EVALUATE returns the following columns:
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: an INT64 value that contains the order of the
autoregressive part in a non-seasonal ARIMA model.
non_seasonal_d: an INT64 value that contains the degree of first
differencing involved in a non-seasonal ARIMA model.
non_seasonal_q: an INT64 value that contains the order of the moving
average part in a non-seasonal ARIMA model.
has_drift: a BOOL value that indicates whether the model has drift.
log_likelihood: a FLOAT64 value that contains the
log-likelihood
of the model.
AIC: the AIC of the model.
variance: a FLOAT64 value that contains the variance of the model.
seasonal_periods: an ARRAY<STRING> value that contains one or more of
the following values:
DAILY
WEEKLY
MONTHLY
QUARTERLY
YEARLY
NO_SEASONALITY
has_holiday_effect: a BOOL value that indicates whether the history data
has a holiday effect.
has_spikes_and_dips: a BOOL value that indicates whether the history data
has spikes and dips.
has_step_changes: a BOOL value that indicates whether the model has
step changes.
error_message: a STRING value that contains the error message raised if
any time series fail in the model.
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.
All of the columns are specific to the fitted ARIMA models except for the
following columns:
time_series_id_col
time_series_id_cols
seasonal_periods
has_holiday_effect
has_spikes_and_dips
has_step_changes
When the non_seasonal_d value is not 1, has_drift is set to FALSE by
default, because has_drift doesn't apply in those cases.
Example
The following example retrieves the evaluation metrics of the best model from
the model mydataset.mymodel in your default project:
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-08-25 UTC."],[[["\u003cp\u003e\u003ccode\u003eML.ARIMA_EVALUATE\u003c/code\u003e is a function used to evaluate metrics for \u003ccode\u003eARIMA_PLUS\u003c/code\u003e or \u003ccode\u003eARIMA_PLUS_XREG\u003c/code\u003e time series models without requiring input data.\u003c/p\u003e\n"],["\u003cp\u003eThe function's syntax includes specifying the model, project ID, and dataset, along with an optional boolean parameter \u003ccode\u003eshow_all_candidate_models\u003c/code\u003e to display evaluation metrics for all models or just the best one.\u003c/p\u003e\n"],["\u003cp\u003eOutput columns from \u003ccode\u003eML.ARIMA_EVALUATE\u003c/code\u003e include identifiers, non-seasonal parameters (p, d, q), drift status, log-likelihood, AIC, variance, seasonal periods, and indicators for holiday effects, spikes, dips, and step changes, plus error messages.\u003c/p\u003e\n"],["\u003cp\u003eThe \u003ccode\u003eshow_all_candidate_models\u003c/code\u003e parameter determines whether metrics are returned for all candidate models or just the best model, and its default value differs between single time series models and large-scale time series models.\u003c/p\u003e\n"],["\u003cp\u003eThe output metrics provided, are specific to the fitted \u003ccode\u003eARIMA\u003c/code\u003e models, with the exception of the identifier columns (\u003ccode\u003etime_series_id_col\u003c/code\u003e, \u003ccode\u003etime_series_id_cols\u003c/code\u003e) and a few others that relay information on the time series history.\u003c/p\u003e\n"]]],[],null,["# The ML.ARIMA_EVALUATE function\n==============================\n\nThis document describes the `ML.ARIMA_EVALUATE` function, which you can use\nto evaluate the model metrics of `ARIMA_PLUS` or `ARIMA_PLUS_XREG` time series\nmodels.\n\nSyntax\n------\n\n```sql\nML.ARIMA_EVALUATE(\n MODEL `PROJECT_ID.DATASET.MODEL_NAME`,\n [, STRUCT(SHOW_ALL_CANDIDATE_MODELS AS show_all_candidate_models)])\n```\n| **Note:** No input data is required.\n\n### Arguments\n\n`ML.ARIMA_EVALUATE` takes the following arguments:\n\n- \u003cvar translate=\"no\"\u003ePROJECT_ID\u003c/var\u003e: Your project ID.\n- \u003cvar translate=\"no\"\u003eDATASET\u003c/var\u003e: The BigQuery dataset that contains the model.\n- \u003cvar translate=\"no\"\u003eMODEL_NAME\u003c/var\u003e: The name of the model.\n- \u003cvar translate=\"no\"\u003eSHOW_ALL_CANDIDATE_MODELS\u003c/var\u003e: a `BOOL` value that\n indicates whether to show evaluation metrics or an error message for either\n all candidate models or for only the best model with the lowest\n [Akaike information criterion (AIC)](https://en.wikipedia.org/wiki/Akaike_information_criterion).\n\n When the `SHOW_ALL_CANDIDATE_MODELS` argument value is `FALSE`, the\n `ML.ARIMA_EVALUATE` function returns evaluation metrics for only the best\n model. When the `SHOW_ALL_CANDIDATE_MODELS` argument value is `TRUE`,\n metrics are returned for all candidate models, along with a possible fitting\n error on a setting of `non_seasonal_p`, `non_seasonal_d`, `non_seasonal_q`,\n and `drift`; this applies to both single time series training with\n `auto.ARIMA` and large-scale time series training cases.\n\n For large-scale time series forecasting training, regardless of the value of\n the `SHOW_ALL_CANDIDATE_MODELS` argument, a single row is returned for a\n time series for which there is no a valid model. The error message explains\n the reason, and the values of all other columns are `NULL`.\n\n For single time series `ARIMA_PLUS` or `ARIMA_PLUS_XREG` models, the default\n value is `TRUE`. For large-scale time series `ARIMA_PLUS` models, the\n default value is `FALSE`.\n\nOutput\n------\n\n`ML.ARIMA_EVALUATE` returns the following columns:\n\n- `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.\n- `non_seasonal_p`: an `INT64` value that contains the order of the autoregressive part in a non-seasonal ARIMA model.\n- `non_seasonal_d`: an `INT64` value that contains the degree of first differencing involved in a non-seasonal ARIMA model.\n- `non_seasonal_q`: an `INT64` value that contains the order of the moving average part in a non-seasonal ARIMA model.\n- `has_drift`: a `BOOL` value that indicates whether the model has drift.\n- `log_likelihood`: a `FLOAT64` value that contains the [log-likelihood](https://en.wikipedia.org/wiki/Likelihood_function#Log-likelihood) of the model.\n- `AIC`: the AIC of the model.\n- `variance`: a `FLOAT64` value that contains the variance of the model.\n- `seasonal_periods`: an `ARRAY\u003cSTRING\u003e` value that contains one or more of\n the following values:\n\n - `DAILY`\n - `WEEKLY`\n - `MONTHLY`\n - `QUARTERLY`\n - `YEARLY`\n - `NO_SEASONALITY`\n- `has_holiday_effect`: a `BOOL` value that indicates whether the history data\n has a holiday effect.\n\n- `has_spikes_and_dips`: a `BOOL` value that indicates whether the history data\n has spikes and dips.\n\n- `has_step_changes`: a `BOOL` value that indicates whether the model has\n step changes.\n\n- `error_message`: a `STRING` value that contains the error message raised if\n any time series fail in the model.\n\nThe `has_holiday_effect`, `has_spikes_and_dips`, and `has_step_changes` columns\nare only populated for `ARIMA_PLUS` models that have `decompose_time_series`\nenabled.\n\nAll of the columns are specific to the fitted `ARIMA` models except for the\nfollowing columns:\n\n- `time_series_id_col`\n- `time_series_id_cols`\n- `seasonal_periods`\n- `has_holiday_effect`\n- `has_spikes_and_dips`\n- `has_step_changes`\n\nWhen the `non_seasonal_d` value is not `1`, `has_drift` is set to `FALSE` by\ndefault, because `has_drift` doesn't apply in those cases.\n\nExample\n-------\n\nThe following example retrieves the evaluation metrics of the best model from\nthe model `mydataset.mymodel` in your default project: \n\n```sql\nSELECT\n *\nFROM\n ML.ARIMA_EVALUATE(MODEL `mydataset.mymodel`, STRUCT(FALSE AS show_all_candidate_models))\n```\n\nWhat's next\n-----------\n\n- For information about model evaluation, see [BigQuery ML model evaluation overview](/bigquery/docs/evaluate-overview).\n- For information about the supported SQL statements and functions for each model type, see [End-to-end user journey for each model](/bigquery/docs/e2e-journey)."]]