Fonction ai_forecast

S’applique à : Databricks SQL

Important

La version 1 de cette fonction est conforme à la préversion publique et HIPAA. La version 2 (recommandée) est en version bêta.

ai_forecast() est une fonction table qui extrapole les données de série chronologique dans le temps. Consultez Arguments pour connaître les arguments disponibles pour configurer cette fonction.

La fonction a deux versions. Un modèle de base de série chronologique optimisé pour la recherche alimente la version 2 pour améliorer la précision prête à l’emploi, et la version 2 ajoute la prise en charge des jours fériés, des covariés externes et des prévisions non négatives. Utilisez l’argument version pour sélectionner la version qui s’exécute. Pour plus d’informations, consultez Les arguments .

Exigences

• Entrepôt SQL pro ou serverless
• Inscrivez votre espace de travail dans la préversion De l’IA Functions prédictive (obligatoire pour la version 2 recommandée). Consultez Gérer les préversions d’Azure Databricks.

Syntaxe

Tip

Azure Databricks recommande la version 2 pour ai_forecast. La version 2 fournit les améliorations suivantes sur la version 1 :

• Modèle de base de série chronologique optimisé pour la recherche pour améliorer la précision prête à l’emploi
• Prise en charge intégrée des vacances avec holiday_region
• Covariés externes, y compris les covariés futurs et passés uniquement, avec covariate_col
• Prévisions non négatives avec positive_only

Pour utiliser la version 2, passez version => '2'. Vérifiez que vous avez activé la préversion des fonctions IA prédictives . Consultez Gérer les préversions d’Azure Databricks.

Version 2 (recommandée)

ai_forecast(observed, horizon, time_col, value_col
  [, group_col] [, covariate_col] [, prediction_interval_width]
  [, frequency] [, holiday_region] [, positive_only] [, version])

Édition 1

ai_forecast(observed, horizon, time_col, value_col
  [, group_col] [, prediction_interval_width] [, frequency]
  [, seed] [, parameters] [, version])

Arguments

ai_forecast() peut prévoir n’importe quel nombre de groupes (voir group_col) et jusqu’à 100 métriques (voir value_col) au sein de chaque groupe. La fréquence de prévision est la même pour toutes les métriques d’un groupe, mais peut différer entre les groupes (voir frequency).

Version 2 (recommandée)

• observed est l’entrée table-valeur utilisée comme données d’apprentissage pour la procédure de prévisions.
  • Cette relation d’entrée doit contenir une colonne « time » et une ou plusieurs colonnes « value ». Les colonnes « Group » et « covariate » sont facultatives. Toutes les colonnes supplémentaires de la relation d’entrée sont ignorées.
• horizon est une quantité horodateur-castable représentant l’heure de fin exclusive des résultats de prévisions. Dans un groupe (consultez group_col), les résultats des prévisions étendent le temps entre la dernière observation et l’horizon. Si l’horizon est inférieur à la dernière heure d’observation, aucun résultat n’est généré.
• time_col est une chaîne référençant la « colonne d’heure » dans observed. La colonne référencée par time_col doit être un DATE ou un TIMESTAMP.
• value_col est une chaîne ou un tableau de chaînes référençant les colonnes de valeur dans observed. Les colonnes référencées par cet argument doivent être castables à DOUBLE.
• group_col (facultatif) est une chaîne ou un tableau de chaînes représentant les colonnes de groupe dans observed. Si elles sont spécifiées, les colonnes de groupe sont utilisées comme critères de partitionnement et des prévisions générées pour chaque groupe indépendamment. Si elles ne sont pas spécifiées, les données d’entrée complètes sont traitées en tant que groupe unique.
• covariate_col (facultatif) est une chaîne ou un tableau de chaînes référençant des colonnes covariées externes dans observed. Les covariés sont des variables supplémentaires qui influencent les prévisions, telles que les prix, les dépenses marketing ou les conditions météorologiques. Deux types de covariés sont pris en charge :
  • Covariats futurs : les valeurs sont connues pour l’horizon de prévision, telles que la tarification planifiée ou les campagnes planifiées. Pour utiliser une covariée de cette façon, incluez des lignes qui observed couvrent l’horizon de prévision (dates après la dernière observation, jusqu’à horizon) avec le ou les covariés renseignés et les value_col colonnes à gauche NULL. ai_forecast prévoit ces NULLlignes et conditions cibles, la prévision sur leurs valeurs covariées.
  • Covariateurs passés uniquement : les valeurs sont connues uniquement pour la période historique, comme les indicateurs météorologiques ou macroéconomiques observés. Remplissez la covariée sur les lignes historiques uniquement. Si vous ne fournissez pas de valeurs covariées sur l’horizon de prévision, ai_forecast utilisez la covariée comme étant passée uniquement ; ce n’est pas une erreur.
• prediction_interval_width (facultatif) est une valeur (comprise entre 0 et 1) représentant la largeur de l’intervalle de prédiction. Les valeurs prévues ont une prediction_interval_width probabilité % de chute entre {v}_upper et {v}_lower.
• frequency (facultatif) est une chaîne d’alias de décalage pandas (par exemple, 'D', 'W', 'ME', 'H') spécifiant la granularité temporelle des résultats de prévision. Si elle n’est pas spécifiée, la granularité de la prévision est déduite automatiquement et indépendamment pour chaque groupe. S’il est spécifié, il doit correspondre à la granularité déduite des données d’entrée au sein de chaque groupe.
  • La fréquence déduite au sein d’un groupe est le mode des observations les plus récentes. Cette inférence est une opération pratique qui n’est pas paramétrable par l’utilisateur.
  • Par exemple, une série chronologique avec 99 « lundis » et 1 « mardi » entraîne la fréquence déduite de la « semaine ».
• holiday_region (facultatif) est un code de région qui permet la modélisation automatique des effets des vacances pour cette région, par 'US'exemple . Lorsqu’il n’est pas spécifié, aucun effet de congé n’est modélisé.
• positive_only (facultatif) lorsqu’il est défini TRUEsur , limite les valeurs prévues à être non négatives. Utilisez cet argument pour les métriques qui ne peuvent pas être négatives, telles que les ventes, les nombres ou l’inventaire. La valeur par défaut est FALSE.
• version (facultatif) : changement de version pour prendre en charge la migration (pour le'1' comportement de version 1, '2' pour le comportement de la version 2). S’il n’est pas spécifié, la valeur par défaut est la version 1. Les arguments de version 2 (covariate_col, holiday_region, positive_only) nécessitent version => '2'.

Édition 1

• observed est l’entrée table-valeur utilisée comme données d’apprentissage pour la procédure de prévisions.
  • Cette relation d’entrée doit contenir une colonne « time » et une ou plusieurs colonnes « value ». Les colonnes « Groupe » et « paramètres » sont facultatives. Toutes les colonnes supplémentaires de la relation d’entrée sont ignorées.
• horizon est une quantité horodateur-castable représentant l’heure de fin exclusive des résultats de prévisions. Dans un groupe (consultez group_col), les résultats des prévisions étendent le temps entre la dernière observation et l’horizon. Si l’horizon est inférieur à la dernière heure d’observation, aucun résultat n’est généré.
• time_col est une chaîne référençant la « colonne d’heure » dans observed. La colonne référencée par time_col doit être un DATE ou un TIMESTAMP.
• value_col est une chaîne ou un tableau de chaînes référençant les colonnes de valeur dans observed. Les colonnes référencées par cet argument doivent être castables à DOUBLE.
• group_col (facultatif) est une chaîne ou un tableau de chaînes représentant les colonnes de groupe dans observed. Si elles sont spécifiées, les colonnes de groupe sont utilisées comme critères de partitionnement et des prévisions générées pour chaque groupe indépendamment. Si elles ne sont pas spécifiées, les données d’entrée complètes sont traitées en tant que groupe unique.
• prediction_interval_width (facultatif) est une valeur (comprise entre 0 et 1) représentant la largeur de l’intervalle de prédiction. Les valeurs prévues ont une prediction_interval_width probabilité % de chute entre {v}_upper et {v}_lower.
• frequency (facultatif) est une unité de temps ou une chaîne d’alias de décalage pandas spécifiant la granularité temporelle des résultats de prévisions. Si elle n’est pas spécifiée, la granularité de la prévision est déduite automatiquement et indépendamment pour chaque groupe. Si une valeur de la fréquence est spécifiée, elle est appliquée de façon égale à tous les groupes.
  • La fréquence déduite au sein d’un groupe est le mode des observations les plus récentes. Cette inférence est une opération pratique qui n’est pas paramétrable par l’utilisateur.
  • Par exemple, une série chronologique avec 99 « lundis » et 1 « mardi » entraîne la fréquence déduite de la « semaine ».
• seed (facultatif) est un nombre utilisé pour démarrer les générateurs de nombre pseudo-random utilisés dans la procédure de prévision.
• parameters (facultatif) est un JSON encodé en chaîne ou le nom d’un identificateur de colonne qui représente le paramétrage de la procédure de prévisions. Toute combinaison de paramètres peut être spécifiée dans n’importe quel ordre, par exemple {"weekly_order": 10, "global_cap": 1000}. Tous les paramètres non spécifiés sont automatiquement déterminés en fonction des attributs des données de formation. Les paramètres suivants sont pris en charge :
  • global_cap et global_floor peuvent être utilisés conjointement ou indépendamment pour définir le domaine possible des valeurs de métriques. Par exemple, {"global_floor": 0} peut être utilisé pour restreindre une métrique telle que le coût à une valeur positive. Ces contraintes s’appliquent globalement aux données d’apprentissage et aux données prévues, et ne peuvent pas être utilisées pour fournir des contraintes strictes sur les valeurs prévues uniquement.
  • daily_order et weekly_order définissent l’ordre fourier des composants de saisonnalité quotidienne et hebdomadaire.
• version (facultatif) : changement de version pour prendre en charge la migration (pour le'1' comportement de version 1, '2' pour le comportement de la version 2). S’il n’est pas spécifié, la valeur par défaut est la version 1. Les arguments de version 2 (covariate_col, holiday_region, positive_only) nécessitent version => '2'.

Retours

Version 2 (recommandée)

Nouvel ensemble de lignes contenant les données prévues. Le schéma de sortie contient les colonnes de temps et de groupe avec leurs types inchangés. Par exemple, si la colonne d’heure d’entrée a le type DATE, le type de colonne de temps de sortie est également DATE. Pour chaque colonne de valeur, il existe trois colonnes de sortie avec le modèle {v}_forecast, {v}_upper et {v}_lower. Quels que soient les types de valeur d’entrée, les colonnes de valeur prévues sont toujours du type DOUBLE. La table de sortie contient uniquement des valeurs prévues, couvrant la plage de temps entre la fin des données observées jusqu’à l’horizon.

Le tableau suivant présente quelques exemples d’inférence de schéma effectuée par AI_FORECAST :

Table d’entrée	Les arguments	Table de sortie
ts: TIMESTAMP val: DOUBLE	time_col => 'ts' value_col => 'val'	ts: TIMESTAMP val_forecast: DOUBLE val_upper: DOUBLE val_lower: DOUBLE
ds: DATE val BIGINT	time_col => 'ds' value_col => 'val'	ds: DATE val_forecast: DOUBLE val_upper: DOUBLE val_lower: DOUBLE
ts: TIMESTAMP dim1: STRING dollars: DECIMAL(10, 2)	time_col => 'ts' value_col => 'dollars' group_col => 'dim1'	ts: TIMESTAMP dim1: STRING dollars_forecast: DOUBLE dollars_upper: DOUBLE dollars_lower: DOUBLE
ts: TIMESTAMP dim1: STRING dim2: BIGINT dollars: DECIMAL(10, 2) users: BIGINT	time_col => 'ts' value_col => ARRAY('dollars', 'users') group_col => ARRAY('dim1', 'dim2')	ts: TIMESTAMP dim1: STRING dim2: BIGINT dollars_forecast: DOUBLE dollars_upper: DOUBLE dollars_lower: DOUBLE users_forecast: DOUBLE users_upper: DOUBLE users_lower: DOUBLE

Édition 1

Nouvel ensemble de lignes contenant les données prévues. Le schéma de sortie contient les colonnes de temps et de groupe avec leurs types inchangés. Par exemple, si la colonne d’heure d’entrée a le type DATE, le type de colonne de temps de sortie est également DATE. Pour chaque colonne de valeur, il existe trois colonnes de sortie avec le modèle {v}_forecast, {v}_upper et {v}_lower. Quels que soient les types de valeur d’entrée, les colonnes de valeur prévues sont toujours du type DOUBLE. La table de sortie contient uniquement des valeurs prévues, couvrant la plage de temps entre la fin des données observées jusqu’à l’horizon.

Le tableau suivant présente quelques exemples d’inférence de schéma effectuée par AI_FORECAST :

Table d’entrée	Les arguments	Table de sortie
ts: TIMESTAMP val: DOUBLE	time_col => 'ts' value_col => 'val'	ts: TIMESTAMP val_forecast: DOUBLE val_upper: DOUBLE val_lower: DOUBLE
ds: DATE val BIGINT	time_col => 'ds' value_col => 'val'	ds: DATE val_forecast: DOUBLE val_upper: DOUBLE val_lower: DOUBLE
ts: TIMESTAMP dim1: STRING dollars: DECIMAL(10, 2)	time_col => 'ts' value_col => 'dollars' group_col => 'dim1'	ts: TIMESTAMP dim1: STRING dollars_forecast: DOUBLE dollars_upper: DOUBLE dollars_lower: DOUBLE
ts: TIMESTAMP dim1: STRING dim2: BIGINT dollars: DECIMAL(10, 2) users: BIGINT	time_col => 'ts' value_col => ARRAY('dollars', 'users') group_col => ARRAY('dim1', 'dim2')	ts: TIMESTAMP dim1: STRING dim2: BIGINT dollars_forecast: DOUBLE dollars_upper: DOUBLE dollars_lower: DOUBLE users_forecast: DOUBLE users_upper: DOUBLE users_lower: DOUBLE

Exemples

Version 2 (recommandée)

L’exemple suivant prévoit jusqu’à une date spécifiée à l’aide de la version 2 :

WITH
aggregated AS (
  SELECT
    DATE(tpep_pickup_datetime) AS ds,
    SUM(fare_amount) AS revenue
  FROM
    samples.nyctaxi.trips
  GROUP BY
    1
)
SELECT * FROM AI_FORECAST(
  TABLE(aggregated),
  horizon => '2016-03-31',
  time_col => 'ds',
  value_col => 'revenue',
  version => '2'
)

L’exemple suivant modélise les effets des congés pour le États-Unis et limite la prévision à des valeurs non négatives :

WITH
aggregated AS (
  SELECT
    DATE(tpep_pickup_datetime) AS ds,
    SUM(fare_amount) AS revenue
  FROM
    samples.nyctaxi.trips
  GROUP BY
    1
)
SELECT * FROM AI_FORECAST(
  TABLE(aggregated),
  horizon => '2016-03-31',
  time_col => 'ds',
  value_col => 'revenue',
  holiday_region => 'US',
  positive_only => true,
  version => '2'
)

L’exemple suivant utilise une covariée externe. La observed table (daily_sales) inclut une promotion colonne renseignée à la fois pour la période historique et l’horizon de prévision, avec revenue la gauche NULL sur les lignes de prévision-horizon. Elle est donc promotion utilisée comme covariée future :

SELECT * FROM AI_FORECAST(
  TABLE(daily_sales),
  horizon => '2016-03-31',
  time_col => 'ds',
  value_col => 'revenue',
  covariate_col => 'promotion',
  version => '2'
)

Édition 1

L’exemple suivant effectue des prévisions jusqu’à une date spécifiée :

WITH
aggregated AS (
  SELECT
    DATE(tpep_pickup_datetime) AS ds,
    SUM(fare_amount) AS revenue
  FROM
    samples.nyctaxi.trips
  GROUP BY
    1
)
SELECT * FROM AI_FORECAST(
  TABLE(aggregated),
  horizon => '2016-03-31',
  time_col => 'ds',
  value_col => 'revenue'
)

Voici un exemple plus complexe :

WITH
aggregated AS (
  SELECT
    DATE(tpep_pickup_datetime) AS ds,
    dropoff_zip,
    SUM(fare_amount) AS revenue,
    COUNT(*) AS n_trips
  FROM
    samples.nyctaxi.trips
  GROUP BY
    1, 2
),
spine AS (
  SELECT all_dates.ds, all_zipcodes.dropoff_zip
  FROM (SELECT DISTINCT ds FROM aggregated) all_dates
  CROSS JOIN (SELECT DISTINCT dropoff_zip FROM aggregated) all_zipcodes
)
SELECT * FROM AI_FORECAST(
  TABLE(
    SELECT
      spine.*,
      COALESCE(aggregated.revenue, 0) AS revenue,
      COALESCE(aggregated.n_trips, 0) AS n_trips
    FROM spine LEFT JOIN aggregated USING (ds, dropoff_zip)
  ),
  horizon => '2016-03-31',
  time_col => 'ds',
  value_col => ARRAY('revenue', 'n_trips'),
  group_col => 'dropoff_zip',
  prediction_interval_width => 0.9,
  parameters => '{"global_floor": 0}'
)

Remarque

ai_forecast ne matérialise pas les 0 pour les entrées manquantes ou NULL dans la table. Si les valeurs appropriées des entrées manquantes peuvent être déduites, elles doivent être coalescées avant d’appeler la ai_forecast fonction. Si les valeurs sont vraiment manquantes ou inconnues, vous pouvez laisser les valeurs NULL ou les supprimer.

Pour les données éparses, il est recommandé de fusionner les valeurs manquantes ou de fournir explicitement une valeur de fréquence pour éviter une sortie inattendue de l’inférence de fréquence « auto ». Par exemple, l’inférence de fréquence « auto » sur deux entrées 14 jours à part déduit une fréquence de « 14D », même si la fréquence « réelle » peut être hebdomadaire avec 1 valeur manquante. La fusion des entrées manquantes supprime cette ambiguïté.

L’exemple suivant montre comment différents paramètres de prévision sont appliqués à différents groupes dans la table d’entrée. L’exemple utilise l’argument parameters comme identificateur de colonne. Cette approche permet aux utilisateurs de stocker les JSON de paramètre précédemment déterminés dans une table et de les réutiliser sur de nouvelles données.

WITH past AS (
  SELECT
    CASE
      WHEN fare_amount < 30 THEN 'Under $30'
      ELSE '$30 or more'
    END AS revenue_bucket,
    CASE
      WHEN fare_amount < 30 THEN '{"daily_order": 0}'
      ELSE '{"daily_order": "auto"}'
    END AS parameters,
    DATE(tpep_pickup_datetime) AS ds,
    SUM(fare_amount) AS revenue
  FROM samples.nyctaxi.trips
  GROUP BY ALL
)
SELECT * FROM AI_FORECAST(
  TABLE(past),
  horizon => (SELECT MAX(ds) + INTERVAL 30 DAYS FROM past),
  time_col => 'ds',
  value_col => 'revenue',
  group_col => ARRAY('revenue_bucket'),
  parameters => 'parameters'
)

Limites

Version 2 (recommandée)

Les limitations suivantes s’appliquent pendant la version bêta :

• La version 2 est en version bêta et n’est pas la valeur par défaut. Pour utiliser la version 2, optez en définissant version => '2'. La version 1, qui est en préversion publique, reste la valeur par défaut.
• La procédure de prévision par défaut est un modèle de base de série chronologique. Ce modèle est la seule procédure de prévision prise en charge disponible.
• Les messages d’erreur sont remis au travers du moteur UDTF Python et contiennent des informations du retour de trace Python. La fin du retour de trace contient le message d’erreur réel.
• Chaque appel d’exécution ai_forecast d’une inférence indépendante. Si vous appelez ai_forecast plusieurs fois avec des valeurs différentes prediction_interval_width pour produire des intervalles de prédiction imbriqués, les intervalles résultants ne sont pas garantis pour être correctement imbriqués. Pour comparer les intervalles de prédiction, utilisez un seul ai_forecast appel avec une prediction_interval_width seule valeur.

Édition 1

Les limitations suivantes s’appliquent pendant la préversion publique :

• La version 1 est disponible en préversion publique et est la version par défaut. La version 2, qui est en version bêta, est disponible en définissant version => '2'.
• La version 1 se trouve sur un chemin d’accès déconseillé. Dans une prochaine version, la version par défaut passe à la version 2 et la version 1 est déconseillée. Pour continuer à utiliser le comportement de la version 1 après les modifications par défaut, épinglez-le en définissant version => '1'.
• La procédure de prévision par défaut est un modèle saisonnier, mais également linéaire et parcellaire de type prophétique. Ce modèle est la seule procédure de prévision prise en charge disponible.
• Les messages d’erreur sont remis au travers du moteur UDTF Python et contiennent des informations du retour de trace Python. La fin du retour de trace contient le message d’erreur réel.
• Chaque appel d’effectuer ai_forecast une régression quantile indépendante. Si vous appelez ai_forecast plusieurs fois avec des valeurs différentes prediction_interval_width pour produire des intervalles de prédiction imbriqués, les intervalles résultants ne sont pas garantis pour être correctement imbriqués, car les quantiles sont calculés indépendamment entre les appels, sans contrainte pour vérifier l’ordre approprié. Pour comparer les intervalles de prédiction, utilisez un seul ai_forecast appel avec une prediction_interval_width seule valeur.