Funktion `ai_forecast`

2025-06-07

Gäller för: markerad ja Databricks SQL

Viktigt!

Den här funktionen finns i offentlig förhandsversion och HIPAA-kompatibel.

ai_forecast() är en tabellvärdesfunktion som är utformad för att extrapolera tidsseriedata i framtiden. Se Argument för tillgängliga argument för att konfigurera den här funktionen.

Krav

Pro- eller serverlös SQL-datalager

Syntax


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

Argument

ai_forecast()kan förutsäga valfritt antal grupper (se group_col) och upp till 100 mätvärden (se value_col) i varje grupp. Prognosfrekvensen är densamma för alla mått i en grupp men kan skilja sig mellan olika grupper (se frequency).

Följande är tillgängliga argument för den här funktionen:

observed är tabellvärdesindata som används som träningsdata för prognosproceduren.
- Den här indatarelationen måste innehålla en "tidskolumn" och en eller flera "värde"-kolumner. Kolumnerna "Gruppera" och "parametrar" är valfria. Eventuella ytterligare kolumner i indatarelationen ignoreras.
horizon är en kvantitet som kan omvandlas till en tidsstämpel och representerar den högra gränsen för sluttiden för prognosresultaten. I en grupp (se group_col) sträcker sig prognosresultatet över tiden mellan den senaste observationen och horisonten. Om horisonten är mindre än den senaste observationstiden genereras inga resultat.
time_col är en sträng som refererar till "tidskolumnen" i observed. Kolumnen som refereras av time_col ska vara en DATE eller en TIMESTAMP.
value_col är en sträng eller en matris med strängar som refererar till värdekolumner i observed. Kolumnerna som refereras till med det här argumentet ska kunna konverteras till DOUBLE.
group_col (valfritt) är en sträng eller en matris med strängar som representerar gruppkolumnerna i observed. Om det anges används gruppkolumner som partitioneringsvillkor och prognoser genereras för varje grupp oberoende av varandra. Om de är ospecificerade behandlas de fullständiga indata som en enda grupp.
prediction_interval_width (valfritt) är ett värde mellan 0 och 1 som representerar bredden på förutsägelseintervallet. Framtida värden har en prediction_interval_width % sannolikhet att falla mellan {v}_upper och {v}_lower.
frequency (valfritt) är en tidsenhet eller pandas offsetaliassträng som anger tidskornigheten för prognosresultatet. Om ospecificerad härleds prognosens detaljeringsnivå automatiskt för varje grupp oberoende. Om ett frekvensvärde anges tillämpas det lika på alla grupper.
- Den härledda frekvensen i en grupp är läget för de senaste observationerna. Det här är en bekvämlighetsåtgärd som inte kan ändras av användaren.
- Till exempel resulterar en tidsserie med 99 "måndagar" och 1 "tisdag" i "veckan" som den härledda frekvensen.
seed (valfritt) är ett tal som används för att initiera eventuella pseudorandomnummergeneratorer som används i prognosproceduren.
parameters (valfritt) är en strängkodad JSON eller namnet på en kolumnidentifierare som representerar parameteriseringen av prognosproceduren. Valfri kombination av parametrar kan anges i valfri ordning, till exempel {“weekly_order”: 10, “global_cap”: 1000}. Alla ospecificerade parametrar bestäms automatiskt baserat på attributen för träningsdata. Följande parametrar stöds:
- global_cap och global_floor kan användas tillsammans eller oberoende av varandra för att definiera måttvärdenas möjliga domän. {“global_floor”: 0}kan till exempel användas för att begränsa ett mått som kostnad till att alltid vara positivt. Dessa gäller globalt för träningsdata och prognostiserade data och kan inte användas för att endast ge snäva begränsningar för de prognostiserade värdena.
- daily_order och weekly_order anger Fourier-ordningen för de dagliga och veckovisa säsongskomponenterna.

Returer

En ny uppsättning rader som innehåller prognostiserade data. Utdataschemat innehåller tids- och gruppkolumnerna med sina typer oförändrade. Om kolumnen för indatatid till exempel har typen DATEblir kolumntypen för utdatatid också DATE. För varje värdekolumn finns det tre utdatakolumner med mönstret {v}_forecast, {v}_upperoch {v}_lower. Oavsett indatavärdetyperna är kolumnerna för prognostiserade värden alltid typ DOUBLE. Utdatatabellen innehåller endast framtida värden, som sträcker sig över tidsperioden mellan slutet av de observerade data till horisont.

Se några exempel på schemainferensen som utförs av AI_FORECAST nedan:

Indatatabell	Argument	Utdatatabell
`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`

Exempel

Följande exempelprognoser fram till ett angivet datum:


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

Följande är ett mer komplext exempel:


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

Anteckning

ai_forecast genererar inte nollor för saknade eller NULL-poster i tabellen. Om rätt värden för de saknade uppgifterna kan härledas bör de kombineras innan man anropar funktionen ai_forecast. Om värdena verkligen saknas eller är okända kan du lämna värdena som NULL eller ta bort dem.

För mycket glesa data är det bästa praxis att sammanställa saknade värden eller uttryckligen ange ett frekvensvärde för att undvika oväntade utdata från "automatisk" frekvensinferens. Till exempel kommer "automatisk" frekvensinferens på två poster med 14 dagars mellanrum att härleda en frekvens av "14D" även om den "verkliga" frekvensen kan vara veckovis med ett värde som saknas. Sammanslagning av de saknade posterna tar bort den här tvetydigheten.

Följande visar ett exempel där olika prognosparametrar tillämpas på olika grupper i indatatabellen. I exemplet används argumentet parameters som kolumnidentifierare. Detta gör det möjligt för användare att lagra tidigare fastställda parameter-JSON:er i en tabell och återanvända dem på nya data.

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

Begränsningar

Följande begränsningar gäller under förhandsversionen:

Standardprognosproceduren är en bitvis linjär modell med säsongskomponent. Det här är den enda tillgängliga prognosproceduren som stöds.
Felmeddelanden levereras via Python UDTF-motorn och innehåller Python-spårningsinformation. Slutet av felsökningskedjan innehåller det faktiska felmeddelandet.

Feedback

Var den här sidan till hjälp?