ai_forecast-functie

Van toepassing op: Databricks SQL

Belangrijk

Versie 1 van deze functie is compatibel met openbare preview en HIPAA. Versie 2 (aanbevolen) bevindt zich in de bètaversie.

ai_forecast() is een tabelwaardefunctie die tijdreeksgegevens naar voren extrapoleert. Zie Argumenten voor beschikbare argumenten voor het configureren van deze functie.

De functie heeft twee versies. Een door onderzoek geoptimaliseerde basismodel voor tijdreeksen zorgt voor versie 2 voor verbeterde out-of-the-box nauwkeurigheid, en versie 2 voegt ondersteuning toe voor feestdagen, externe covariaten en niet-negatieve prognoses. Gebruik het version argument om te selecteren welke versie wordt uitgevoerd. Zie Argumenten voor meer informatie.

Requirements

• Pro of Serverless SQL Warehouse
• Registreer uw werkruimte in de preview-versie van Predictive AI Functions (verplicht voor de aanbevolen versie 2). Zie Azure Databricks previews beheren.

Syntaxis

Tip

Azure Databricks raadt versie 2 aan voor ai_forecast. Versie 2 biedt de volgende verbeteringen ten opzichte van versie 1:

• Een door onderzoek geoptimaliseerd basismodel voor tijdreeksen voor verbeterde out-of-the-box nauwkeurigheid
• Ingebouwde vakantieondersteuning met holiday_region
• Externe covariaten, inclusief toekomstige en alleen-eerdere covariaten, met covariate_col
• Niet-negatieve prognoses met positive_only

Als u versie 2 wilt gebruiken, geeft u door version => '2'. Zorg ervoor dat u de preview van voorspellende AI-functies hebt ingeschakeld. Zie Azure Databricks previews beheren.

Versie 2 (aanbevolen)

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

Versie 1

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

Argumenten

ai_forecast() kan een willekeurig aantal groepen voorspellen (zie group_col) en tot 100 kenmerken (zie value_col) binnen elke groep. De prognosefrequentie is hetzelfde voor alle metrische gegevens in een groep, maar kan verschillen tussen groepen (zie frequency).

Versie 2 (aanbevolen)

• observed is de invoer met tabelwaarde die wordt gebruikt als trainingsgegevens voor de prognoseprocedure.
  • Deze invoerrelatie moet één kolom 'tijd' en een of meer 'waardekolommen' bevatten. Kolommen 'Groeperen' en 'covariate' zijn optioneel. Eventuele extra kolommen in de invoerrelatie worden genegeerd.
• horizon is een hoeveelheid die kan worden omgezet naar een tijdstempel en die de rechtsuitsluitende eindtijd van de prognoseresultaten vertegenwoordigt. Binnen een groep (zie group_col) beslaan de prognoseresultaten de tijd tussen de laatste observatie en de horizon. Als horizon kleiner is dan de laatste observatietijd, worden er geen resultaten gegenereerd.
• time_col is een tekenreeks die verwijst naar de 'tijdkolom' in observed. De kolom waarnaar wordt time_col verwezen, moet een DATE of een TIMESTAMP.
• value_col is een tekenreeks of een matrix met tekenreeksen die verwijzen naar waardekolommen in observed. De kolommen waarnaar door dit argument wordt verwezen, moeten worden geconverteerd naar DOUBLE.
• group_col (optioneel) is een tekenreeks of een matrix met tekenreeksen die de groepskolommen in observedvertegenwoordigen. Indien opgegeven, worden groepskolommen gebruikt als partitioneringscriteria en worden prognoses voor elke groep onafhankelijk gegenereerd. Als dit niet is opgegeven, worden de volledige invoergegevens behandeld als één groep.
• covariate_col (optioneel) is een tekenreeks of een matrix met tekenreeksen die verwijzen naar externe covariatekolommen in observed. Covariaties zijn aanvullende variabelen die van invloed zijn op de prognose, zoals prijs, marketinguitgaven of weer. Er worden twee soorten covariaten ondersteund:
  • Toekomstige covariabelen: waarden zijn bekend voor de prognose horizon, zoals geplande prijzen of geplande campagnes. Als u een covariatie op deze manier wilt gebruiken, moet u rijen opnemen die observed betrekking hebben op de prognose horizon (datums na de laatste observatie, tot horizon) met het covariabele ingevuld en de value_col kolom(en) links NULL. ai_forecast voorspelt deze NULLdoelrijen en voorwaarden de prognose voor hun covariate waarden.
  • Eerdere covariabelen: waarden zijn alleen bekend voor de historische periode, zoals waargenomen weer of macro-economische indicatoren. Vul alleen de covariantie in op historische rijen. Als u geen covariatewaarden opgeeft voor de prognose horizon, ai_forecast gebruikt u de covariate als alleen-verleden. Dit is geen fout.
• prediction_interval_width (optioneel) is een waarde tussen 0 en 1 die de breedte van het voorspellingsinterval vertegenwoordigt. Voorspelde waarden hebben een prediction_interval_width % waarschijnlijkheid tussen {v}_upper en {v}_lower.
• frequency(optioneel) is een pandas-offsetaliastekenreeks (bijvoorbeeld 'D', 'W''ME', 'H') waarmee de tijdgranulariteit van de prognoseresultaten wordt opgegeven. Indien niet opgegeven, wordt de prognosegranulariteit automatisch voor elke groep afzonderlijk afgeleid. Indien opgegeven, moet deze overeenkomen met de uitgestelde granulariteit van de invoergegevens binnen elke groep.
  • De afgeleide frequentie binnen een groep is de modus van de meest recente waarnemingen. Deze deductie is een handige bewerking die niet door de gebruiker kan worden uitgevoerd.
  • Een tijdreeks met 99 'maandagen' en 1 'dinsdag' resulteert bijvoorbeeld in de 'week' als de uitgestelde frequentie.
• holiday_region (optioneel) is een regiocode die automatische modellering van vakantie-effecten voor die regio mogelijk maakt, zoals 'US'. Wanneer u niets hebt opgegeven, worden er geen vakantie-effecten gemodelleerd.
• positive_only (optioneel) als deze optie is ingesteld TRUE, beperkt u de voorspelde waarden als niet-negatief. Gebruik dit argument voor metrische gegevens die niet negatief kunnen zijn, zoals verkoop, aantallen of voorraad. De standaardwaarde is FALSE.
• version (optioneel): Versieswitch voor ondersteuning van migratie ('1' voor gedrag van versie 1, '2' voor gedrag van versie 2). Als dit niet is opgegeven, wordt standaard versie 1 gebruikt. Voor de argumenten van versie 2 (covariate_col, holiday_region, positive_only) is vereist version => '2'.

Versie 1

• observed is de invoer met tabelwaarde die wordt gebruikt als trainingsgegevens voor de prognoseprocedure.
  • Deze invoerrelatie moet één kolom 'tijd' en een of meer 'waardekolommen' bevatten. Kolommen Groeperen en Parameters zijn optioneel. Eventuele extra kolommen in de invoerrelatie worden genegeerd.
• horizon is een hoeveelheid die kan worden omgezet naar een tijdstempel en die de rechtsuitsluitende eindtijd van de prognoseresultaten vertegenwoordigt. Binnen een groep (zie group_col) beslaan de prognoseresultaten de tijd tussen de laatste observatie en de horizon. Als horizon kleiner is dan de laatste observatietijd, worden er geen resultaten gegenereerd.
• time_col is een tekenreeks die verwijst naar de 'tijdkolom' in observed. De kolom waarnaar wordt time_col verwezen, moet een DATE of een TIMESTAMP.
• value_col is een tekenreeks of een matrix met tekenreeksen die verwijzen naar waardekolommen in observed. De kolommen waarnaar door dit argument wordt verwezen, moeten worden geconverteerd naar DOUBLE.
• group_col (optioneel) is een tekenreeks of een matrix met tekenreeksen die de groepskolommen in observedvertegenwoordigen. Indien opgegeven, worden groepskolommen gebruikt als partitioneringscriteria en worden prognoses voor elke groep onafhankelijk gegenereerd. Als dit niet is opgegeven, worden de volledige invoergegevens behandeld als één groep.
• prediction_interval_width (optioneel) is een waarde tussen 0 en 1 die de breedte van het voorspellingsinterval vertegenwoordigt. Voorspelde waarden hebben een prediction_interval_width % waarschijnlijkheid tussen {v}_upper en {v}_lower.
• frequency (optioneel) is een tijdseenheid of een pandas-offset aliasstring die de tijdsgranulariteit van de prognoseresultaten aangeeft. Indien niet opgegeven, wordt de prognosegranulariteit automatisch voor elke groep afzonderlijk afgeleid. Als een frequentiewaarde is opgegeven, wordt deze evenzeer toegepast op alle groepen.
  • De afgeleide frequentie binnen een groep is de modus van de meest recente waarnemingen. Deze deductie is een handige bewerking die niet door de gebruiker kan worden uitgevoerd.
  • Een tijdreeks met 99 'maandagen' en 1 'dinsdag' resulteert bijvoorbeeld in de 'week' als de uitgestelde frequentie.
• seed (optioneel) is een getal dat wordt gebruikt om pseudorandomnummergeneratoren te starten die in de prognoseprocedure worden gebruikt.
• parameters (optioneel) is een met tekenreeks gecodeerde JSON of de naam van een kolom-id die de parameterisatie van de prognoseprocedure vertegenwoordigt. Elke combinatie van parameters kan in elke volgorde worden opgegeven, bijvoorbeeld {"weekly_order": 10, "global_cap": 1000}. Eventuele niet-opgegeven parameters worden automatisch bepaald op basis van de kenmerken van de trainingsgegevens. De volgende parameters worden ondersteund:
  • global_cap en global_floor kunnen samen of onafhankelijk worden gebruikt om het mogelijke domein van de metrische waarden te definiëren. {"global_floor": 0}kan bijvoorbeeld worden gebruikt om een metrische waarde te beperken, zoals kosten, om altijd positief te zijn. Deze beperkingen zijn globaal van toepassing op de trainingsgegevens en de voorspelde gegevens en kunnen niet worden gebruikt om alleen strikte beperkingen voor de voorspelde waarden te bieden.
  • daily_order en weekly_order stellen de fouriervolgorde van de dagelijkse en wekelijkse seizoensgebonden onderdelen in.
• version (optioneel): Versieswitch voor ondersteuning van migratie ('1' voor gedrag van versie 1, '2' voor gedrag van versie 2). Als dit niet is opgegeven, wordt standaard versie 1 gebruikt. Voor de argumenten van versie 2 (covariate_col, holiday_region, positive_only) is vereist version => '2'.

Retouren

Versie 2 (aanbevolen)

Een nieuwe set rijen met de voorspelde gegevens. Het uitvoerschema bevat de tijd- en groepskolommen met hun typen ongewijzigd. Als de kolom invoertijd bijvoorbeeld type DATEheeft, is het kolomtype uitvoertijd ook DATE. Voor elke waardekolom zijn er drie uitvoerkolommen met het patroon {v}_forecast, {v}_upperen {v}_lower. Ongeacht de invoerwaardetypen zijn de kolommen met voorspelde waarden altijd type DOUBLE. De uitvoertabel bevat alleen voorspelde waarden, die het tijdsbereik tussen het einde van de waargenomen gegevens tot de horizon beslaat.

In de volgende tabel ziet u enkele voorbeelden van de schemadeductie die door AI_FORECAST wordt uitgevoerd:

Invoertabel	Argumenten	Uitvoertabel
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

Versie 1

Een nieuwe set rijen met de voorspelde gegevens. Het uitvoerschema bevat de tijd- en groepskolommen met hun typen ongewijzigd. Als de kolom invoertijd bijvoorbeeld type DATEheeft, is het kolomtype uitvoertijd ook DATE. Voor elke waardekolom zijn er drie uitvoerkolommen met het patroon {v}_forecast, {v}_upperen {v}_lower. Ongeacht de invoerwaardetypen zijn de kolommen met voorspelde waarden altijd type DOUBLE. De uitvoertabel bevat alleen voorspelde waarden, die het tijdsbereik tussen het einde van de waargenomen gegevens tot de horizon beslaat.

In de volgende tabel ziet u enkele voorbeelden van de schemadeductie die door AI_FORECAST wordt uitgevoerd:

Invoertabel	Argumenten	Uitvoertabel
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

Voorbeelden

Versie 2 (aanbevolen)

In het volgende voorbeeld wordt een opgegeven datum voorspeld met versie 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'
)

In het volgende voorbeeld worden vakantie-effecten voor de Verenigde Staten en wordt de prognose beperkt tot niet-negatieve waarden:

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

In het volgende voorbeeld wordt een externe covariatie gebruikt. De observed tabel (daily_sales) bevat een promotion kolom die is gevuld voor zowel de historische periode als de prognosehorizon, met revenue links NULL op de rijen voor de prognose-horizon, dus promotion wordt gebruikt als een toekomstige covariatie:

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

Versie 1

De volgende voorbeeldprognoses tot een opgegeven 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'
)

Hier volgt een complexer voorbeeld:

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

Notitie

ai_forecast materialiseert geen 0's voor ontbrekende of NULL vermeldingen in de tabel. Als de juiste waarden van de ontbrekende vermeldingen kunnen worden afgeleid, moeten ze worden gegroepeerd voordat de ai_forecast functie wordt aangeroepen. Als de waarden echt ontbreken of onbekend zijn, kunt u de waarden laten staan als NULL of verwijderen.

Voor sparse-gegevens kunt u het beste ontbrekende waarden combineren of expliciet een frequentiewaarde opgeven om onverwachte uitvoer van de frequentiedeductie 'automatisch' te voorkomen. Met 'automatische' frequentiedeductie voor twee vermeldingen van 14 dagen na elkaar wordt bijvoorbeeld een frequentie van '14D' afgeleid, zelfs als de "reële" frequentie wekelijks met 1 ontbrekende waarde kan zijn. Als u de ontbrekende vermeldingen samenwerkt, wordt deze dubbelzinnigheid verwijderd.

In het volgende voorbeeld ziet u hoe verschillende prognoseparameters worden toegepast op verschillende groepen in de invoertabel. In het voorbeeld wordt het argument parameters gebruikt als kolom-id. Met deze methode kunnen gebruikers eerder vastgestelde parameter-JSON's opslaan in een tabel en deze opnieuw gebruiken op nieuwe gegevens.

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

Beperkingen

Versie 2 (aanbevolen)

De volgende beperkingen zijn van toepassing tijdens de bètaversie:

• Versie 2 is bèta en is niet de standaardinstelling. Als u versie 2 wilt gebruiken, meldt u zich aan door de instelling in te stellen version => '2'. Versie 1, die zich in openbare preview bevindt, blijft de standaardwaarde.
• De standaardprognoseprocedure is een basismodel voor tijdreeksen. Dit model is de enige ondersteunde prognoseprocedure die beschikbaar is.
• Foutberichten worden bezorgd via de Python UDTF-engine en bevatten python-traceringsgegevens. Het einde van het terugtraceerproces bevat het werkelijke foutbericht.
• Elke aanroep van ai_forecast voert een onafhankelijke deductie uit. Als u meerdere keren met verschillende prediction_interval_width waarden aanroept ai_forecast om geneste voorspellingsintervallen te produceren, zijn de resulterende intervallen niet gegarandeerd correct genest. Als u voorspellingsintervallen wilt vergelijken, gebruikt u één ai_forecast aanroep met één prediction_interval_width waarde.

Versie 1

De volgende beperkingen zijn van toepassing tijdens de openbare preview:

• Versie 1 bevindt zich in openbare preview en is de standaardversie. Versie 2, die zich in bèta bevindt, is beschikbaar door de instelling in te stellen version => '2'.
• Versie 1 bevindt zich op een afschaffingspad. In een toekomstige release wordt de standaardversie gewijzigd in versie 2 en versie 1 is afgeschaft. Als u het gedrag van versie 1 na de standaardwijzigingen wilt blijven gebruiken, maakt u deze vast door deze in te stellen version => '1'.
• De standaard prognoseprocedure is een stukgewijs liniar en seizoensgebonden model vergelijkbaar met Prophet. Dit model is de enige ondersteunde prognoseprocedure die beschikbaar is.
• Foutberichten worden bezorgd via de Python UDTF-engine en bevatten python-traceringsgegevens. Het einde van het terugtraceerproces bevat het werkelijke foutbericht.
• Elke aanroep van ai_forecast voert een onafhankelijke kwantielregressie uit. Als u meerdere keren met verschillende prediction_interval_width waarden aanroept ai_forecast om geneste voorspellingsintervallen te produceren, worden de resulterende intervallen niet gegarandeerd correct genest omdat de kwantielen onafhankelijk worden berekend over aanroepen, zonder beperking om de juiste volgorde te controleren. Als u voorspellingsintervallen wilt vergelijken, gebruikt u één ai_forecast aanroep met één prediction_interval_width waarde.