Fonction ai_forecast

S’applique à : Databricks SQL

ai_forecast() est une fonction table conçue pour extrapoler les données de série chronologique dans le futur. Consultez Arguments pour connaître les arguments disponibles pour configurer cette fonction.

Exigence

Entrepôt SQL pro ou serverless

Syntaxe

ai_forecast(
  observed TABLE,
  horizon DATE | TIMESTAMP | STRING,
  time_col STRING,
  value_col STRING | ARRAY<STRING>,
  group_col STRING | ARRAY<STRING> | NULL DEFAULT NULL,
  prediction_interval_width DOUBLE DEFAULT 0.95,
  frequency STRING DEFAULT 'auto',
  seed INTEGER | NULL DEFAULT NULL,
  parameters STRING DEFAULT '{}'
)

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 être différente entre différents groupes (voir frequency).

Les arguments disponibles pour cette fonction sont les suivants :

• 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 « heure », ainsi qu’une ou plusieurs colonnes « valeur ». 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 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 vers 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 futures ont une probabilité de prediction_interval_width % 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. Il s’agit d’une opération pratique et non paramétrable par l’utilisateur.
  • Par exemple, une série chronologique avec 99 « lundis » et 1 « mardi » entraîne une fréquence déduite pour la « semaine ».
• seed (facultatif) est un nombre utilisé pour initialiser tous les générateurs pseudo-facultatifs de nombre utilisés dans la procédure de prévisions.
• 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. Celles-ci s’appliquent de manière globale aux données d’apprentissage et aux données prévues, mais 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.

Retours

Nouvel ensemble de lignes contenant les données prévues. Le schéma de sortie contient les colonnes temps et groupe avec leurs types inchangés. Par exemple, si la colonne heure d’entrée a le type DATE, le type de colonne heure 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 les valeurs futures, couvrant la plage de temps entre la fin des données observées et l’horizon.

Consultez quelques exemples d’inférence de schéma effectuée par AI_FORECAST ci-dessous :

Exemples

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}'
)

Remarquez qu’il est très courant que les tables ne matérialisent pas les entrées de valeur 0 ou vides. Si les valeurs des entrées manquantes peuvent être déduites (par exemple 0), ces valeurs doivent être fusionnées avant d’appeler la fonction de prévisions. Si les valeurs sont vraiment manquantes ou inconnues, elles peuvent être laissées en tant que NULL.

Pour les données très é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 d’intervalle 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é.

Enfin, nous montrons un exemple dans lequel différents paramètres de prévision sont appliqués à différents groupes dans la table d’entrée :

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'
)

Remarquez l’utilisation d’un identificateur de colonne comme argument parameters. Cela permet aux utilisateurs de stocker les fichiers JSON du paramètre précédemment déterminés dans une table et de les réutiliser sur de nouvelles données.

Limites

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

• La procédure de prévision par défaut est un modèle saisonnier, mais également linéaire et parcellaire de type prophétique. Il s’agit de la seule procédure de prévision disponible prise en charge.
• 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.