Funktion ai_forecast

Gäller för:markerad ja Databricks SQL

Viktigt!

Version 1 av den här funktionen är i offentlig förhandsversion och HIPAA-kompatibel. Version 2 (rekommenderas) är i Beta.

ai_forecast() är en tabellvärdesfunktion som extrapolerar tidsseriedata framåt i tiden. Se Argument för tillgängliga argument för att konfigurera den här funktionen.

Funktionen har två versioner. En forskningsoptimerad grundmodell för tidsserier driver version 2 för bättre noggrannhet, och version 2 ger stöd för helgdagar, externa samvariater och icke-negativa prognoser. version Använd argumentet för att välja vilken version som ska köras. Mer information finns i Argument .

Requirements

Syntax

Tip

Azure Databricks rekommenderar version 2 för ai_forecast. Version 2 innehåller följande förbättringar jämfört med version 1:

  • En forskningsoptimerad grundmodell för tidsserier för bättre noggrannhet
  • Inbyggt semesterstöd med holiday_region
  • Externa samvariat, inklusive framtida och endast tidigare samvariater, med covariate_col
  • Icke-negativa prognoser med positive_only

Om du vill använda version 2 skickar du version => '2'. Kontrollera att du har aktiverat förhandsversionen av Predictive AI Functions . Se Hantera förhandsversioner av Azure Databricks.

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

Version 1

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

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 åt mellan grupper (se frequency).

  • 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 "samvariera" ä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 måste 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 av det här argumentet måste vara gjutbara 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.
  • covariate_col (valfritt) är en sträng eller en matris med strängar som refererar till externa samvariatkolumner i observed. Covariates är ytterligare variabler som påverkar prognosen, till exempel pris, marknadsföringsutgifter eller väder. Två typer av samvariat stöds:
    • Framtida samvariat: värden är kända för prognoshorisonten, till exempel planerade priser eller schemalagda kampanjer. Om du vill använda ett samvariat på det här sättet tar du med rader i observed som täcker prognoshorisonten (datum efter den senaste observationen, upp till horizon) med covariatet fyllt och kolumnerna value_col till vänster NULL. ai_forecast prognostiserar dessa NULL-målrader och villkorar prognosen på deras samvariatvärden.
    • Endast tidigare samvariat: värden är endast kända för den historiska perioden, till exempel observerat väder eller makroekonomiska indikatorer. Fyll endast i samvariatet på historiska rader. Om du inte anger samvariatvärden över prognoshorisonten ai_forecast använder du covariatet som endast förr. Det här är inte ett fel.
  • prediction_interval_width (valfritt) är ett värde mellan 0 och 1 som representerar bredden på förutsägelseintervallet. Prognostiserade värden har en prediction_interval_width % sannolikhet att falla mellan {v}_upper och {v}_lower.
  • frequency (valfritt) är en pandas offsetaliassträng (till exempel 'D', 'W', 'ME', 'H') som anger tidskornigheten för prognosresultatet. Om ospecificerad härleds prognosens detaljeringsnivå automatiskt för varje grupp oberoende. Om den anges måste den matcha den härledda kornigheten för indata i varje grupp.
    • Den härledda frekvensen i en grupp är läget för de senaste observationerna. Den här slutsatsdragningen ä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.
  • holiday_region (valfritt) är en regionkod som möjliggör automatisk modellering av semestereffekter för den regionen, till exempel 'US'. När de är ospecificerade modelleras inga semestereffekter.
  • positive_only (valfritt) när det är inställt på TRUE, begränsar de prognostiserade värdena till icke-negativa. Använd det här argumentet för mått som inte kan vara negativa, till exempel försäljning, antal eller inventering. Standard är FALSE.
  • version (valfritt): Versionsväxel för att stödja migrering ('1' för version 1-beteende, '2' för version 2-beteende). Om det är ospecificerat är standardvärdet version 1. Version 2-argumenten (covariate_col, holiday_region, positive_only) kräver version => '2'.

Version 1

  • 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 måste 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 av det här argumentet måste vara gjutbara 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. Prognostiserade 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. Den här slutsatsdragningen ä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 starta pseudorandomnummergeneratorer som används i prognosförfarandet.
  • 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 begränsningar 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.
  • version (valfritt): Versionsväxel för att stödja migrering ('1' för version 1-beteende, '2' för version 2-beteende). Om det är ospecificerat är standardvärdet version 1. Version 2-argumenten (covariate_col, holiday_region, positive_only) kräver version => '2'.

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 DATEär 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 prognostiserade värden som sträcker sig över tidsintervallet mellan slutet av de observerade data till horisont.

I följande tabell visas några exempel på schemainferensen som utförs av AI_FORECAST:

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

Version 1

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 DATEär 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 prognostiserade värden som sträcker sig över tidsintervallet mellan slutet av de observerade data till horisont.

I följande tabell visas några exempel på schemainferensen som utförs av AI_FORECAST:

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 exempel prognoser fram till ett angivet datum med 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'
)

I följande exempel modellerar semestereffekter för United States och begränsar prognosen till icke-negativa värden:


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

I följande exempel används en extern samvariat. Tabellen observed (daily_sales) innehåller en promotion kolumn som fyllts i för både den historiska perioden och prognoshorisonten, med revenue vänster NULL på raderna för prognoshorisonten, så promotion används som en framtida samvariat:


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

Version 1

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 posterna kan härledas måste de sammanslutas innan funktionen ai_forecast anropas. Om värdena verkligen saknas eller är okända kan du lämna värdena som NULL eller ta bort dem.

För glesa data är det bästa praxis att slå samman saknade värden eller ange ett frekvensvärde explicit för att undvika oväntade utdata från "auto"-frekvensinferensen. Till exempel innebär "automatisk" frekvensinferens för två poster med 14 dagars mellanrum en frekvens på "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.

I följande exempel visas hur olika prognosparametrar tillämpas på olika grupper i indatatabellen. I exemplet används argumentet parameters som kolumnidentifierare. Med den här metoden kan användare lagra tidigare fastställda JSON-parametrar 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 betaversionen:

  • Version 2 är i Beta och är inte standard. Om du vill använda version 2 väljer du genom att ange version => '2'. Version 1, som finns i offentlig förhandsversion, förblir standard.
  • Standardprognosproceduren är en grundmodell för tidsserier. Den här modellen ä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.
  • Varje anrop av ai_forecast utför en oberoende slutsatsdragning. Om du anropar ai_forecast flera gånger med olika prediction_interval_width värden för att skapa kapslade förutsägelseintervall är de resulterande intervallen inte garanterade att vara korrekt kapslade. Om du vill jämföra förutsägelseintervall använder du ett enda ai_forecast anrop med ett prediction_interval_width värde.

Version 1

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

  • Version 1 finns i offentlig förhandsversion och är standardversionen. Version 2, som finns i Beta, är tillgänglig genom att ange version => '2'.
  • Version 1 finns på en utfasningssökväg. I en kommande version ändras standardversionen till version 2 och version 1 är inaktuell. Om du vill fortsätta använda version 1-beteendet efter standardändringarna fäster du det genom att ange version => '1'.
  • Standardprognosproceduren är en bitvis linjär modell med säsongskomponent. Den här modellen ä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.
  • Varje anrop av ai_forecast utför en oberoende kvantilregression. Om du anropar ai_forecast flera gånger med olika prediction_interval_width värden för att skapa kapslade förutsägelseintervall är de resulterande intervallen inte garanterade att vara korrekt kapslade eftersom kvantantiles beräknas oberoende över anrop, utan begränsning för att verifiera korrekt ordning. Om du vill jämföra förutsägelseintervall använder du ett enda ai_forecast anrop med ett prediction_interval_width värde.
  • Last updated on