Funzione ai_forecast

Si applica a: Databricks SQL

ai_forecast() è una funzione a valori tableprogettata per estrapolare i dati delle serie temporali nel futuro. Si veda Argomenti per gli argomenti disponibili per configurare questa funzione.

Requisito

Pro o Serverless SQL Warehouse

Sintassi

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

Argomenti

ai_forecast()può prevedere un numero qualsiasi di gruppi (si veda group_col) e fino a 100 metriche (si veda value_col) all'interno di ogni gruppo. La frequenza di previsione è la stessa per tutte le metriche in un gruppo, ma può essere diversa in gruppi diversi (si veda frequency).

Per questa funzione sono disponibili i seguenti argomenti:

• observed è l'input table-valued utilizzato come dati di addestramento per la procedura di previsione.
  • Questa relazione di input deve contenere un "time" column e uno o più "value" columns. "Gruppo" e "parameters" columns sono facoltativi. Eventuali columns aggiuntive nella relazione di input vengono ignorate.
• horizon è una quantità di timestamp castable che rappresenta l'ora di fine esclusiva corretta dei risultati della previsione. All'interno di un gruppo (vedere group_col) i risultati delle previsioni si estendono nel tempo tra l'ultima osservazione e l'orizzonte. Se l'orizzonte è minore dell'ora dell'ultima osservazione, non vengono generati risultati.
• time_col è una stringa che fa riferimento al “tempo column” in observed. Il column a cui fa riferimento time_col deve essere un DATE o un TIMESTAMP.
• value_col è una stringa o un array di stringhe che fanno riferimento al valore columns in observed. Il columns a cui fa riferimento questo argomento dovrebbe essere convertibile in DOUBLE.
• group_col (facoltativo) è una stringa o una matrice di stringhe che rappresentano il gruppo columns in observed. Se specificato, i gruppi columns vengono utilizzati come criteri di partizionamento e le previsioni vengono generate indipendentemente per ciascun gruppo. Se non specificato, i dati di input completi vengono considerati come un singolo gruppo.
• prediction_interval_width (facoltativo) è un valore compreso tra 0 e 1 che rappresenta la larghezza dell'intervallo di previsione. I futuri values hanno una probabilità prediction_interval_width % di ricadere tra {v}_upper e {v}_lower.
• frequency (facoltativo) è un'unità di tempo o una stringa di alias della libreria pandas offset che specifica la granularità temporale dei risultati della previsione. Se non specificato, la granularità della previsione viene dedotta automaticamente per ogni gruppo in modo indipendente. Se è specificato un valore di frequenza, viene applicato allo stesso modo a tutti i gruppi.
  • La frequenza inferita all'interno di un gruppo è la modalità delle osservazioni più recenti. Si tratta di un'operazione di praticità che non è ottimizzabile dall'utente.
  • Ad esempio, una serie temporale con 99 “lunedì” e 1 “martedì” determina come frequenza inferita la “settimana”.
• seed (facoltativo) è un numero utilizzato per inizializzare qualsiasi generatore di numeri pseudorandom utilizzato nella procedura di previsione.
• parameters (facoltativo) è un codice JSON con codifica stringa o il nome di un columnidentifier che rappresenta la parametrizzazione della procedura di previsione. Qualsiasi combinazione di parameters può essere specificata in qualsiasi ordine, ad esempio {“weekly_order”: 10, “global_cap”: 1000}. Qualsiasi parameters non specificato viene determinato automaticamente in base agli attributi dei dati di addestramento. Sono supportati i parameters seguenti:
  • global_cap e global_floor possono essere usati insieme o indipendentemente per definire il possibile dominio della metrica values. {“global_floor”: 0}, ad esempio, può essere usato per vincolare una metrica come il costo per essere sempre positiva. Si applicano a livello globale ai dati di training e ai dati previsti e non possono essere usati per fornire vincoli stretti solo ai dati values previsti.
  • daily_order e weekly_ordereset l'ordine di Fourier dei componenti di stagionalità giornaliera e settimanale.

Valori restituiti

Una nuova set di righe contenenti i dati previsti. L'output schema conterrà l'ora e il gruppo columns con i relativi tipi invariati. Ad esempio, se l'ora di input column ha tipo DATE, anche il tipo dell'ora di output column sarà DATE. Per ogni valore column ci sono tre uscite columns con il pattern {v}_forecast, {v}_uppere {v}_lower. Indipendentemente dai tipi di valore di input, il valore previsto columns è sempre di tipo DOUBLE. L'output table contiene solo values future, che copre l'intervallo di tempo che intercorre dalla fine dei dati osservati fino all'orizzonte temporale.

Vedere alcuni esempi dell'inferenza schema eseguita da AI_FORECAST di seguito:

Esempi

L'esempio seguente effettua previsioni fino a una data specificata:

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

Il seguente esempio è più complesso:

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

Per i dati molto sparsi, è consigliabile unire i values mancanti o fornire esplicitamente un valore di frequenza per evitare output imprevisti dall'inferenza della frequenza automatica. Ad esempio, l'inferenza di frequenza “automatica” su due voci distanti 14 giorni dedurrà una frequenza di “14g” anche se la frequenza “reale” potrebbe essere settimanale con un valore mancante. L'accorpamento delle voci mancanti elimina questa ambiguità.

Di seguito viene illustrato un esempio where di previsioni diverse parameters che vengono applicate a gruppi diversi nell'input table. Nell'esempio viene utilizzato l'argomento parameters come columnidentifier. In questo modo gli utenti possono archiviare i JSON dei parametri determinati in precedenza in un table e riutilizzarli sui nuovi dati.

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

Limiti

Durante l'anteprima, si applicano le seguenti limitazioni:

• La procedura di previsione predefinita è un modello di tipo profetico, lineare e stagionale. Questa è l'unica procedura di previsione supportata disponibile.
• I messaggi di errore vengono recapitati tramite il motore UDTF Python e contengono informazioni di tracciamento Python. La fine del tracciamento contiene il messaggio di errore vero e proprio.