分享方式：

ai_forecast函式

  • 文章

適用於： 檢查標示為是 Databricks SQL

重要

這項功能處於 公開預覽狀態。 請連絡 Databricks 帳戶小組以參與預覽。

ai_forecast() 是一個數據表值函式，其設計目的是將時間序列數據推斷到未來。 如需設定此函式的可用自變數，請參閱自變數。

需求

語法


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

參數

ai_forecast()可以預測每個群組中任意數目的群組（請參閱group_col），以及最多 100 個計量（請參閱value_col）。 群組中所有計量的預測頻率都相同，但在不同的群組之間可能不同（請參閱 frequency）。

以下是此函式的可用自變數：

  • observed 是做為預測程式定型數據的數據表值輸入。
    • 此輸入關聯必須包含一個「時間」數據行和一或多個「值」數據行。 “Group” 和 “parameters” 數據行是選擇性的。 輸入關聯中的任何額外數據行會被忽略。
  • horizon 是時間戳可轉換的數量，代表預測結果的右獨佔結束時間。 在群組中（請參閱 group_col）預測結果會跨越最後一個觀察與地平線之間的時間。 如果地平線小於上次觀察時間，則不會產生任何結果。
  • time_col 是參考 中「時間數據行」的 observed字串。 參考 time_col 的資料行應該是 DATE 或 TIMESTAMP。
  • value_col 是參考 中 observed值數據行的字串或字串陣列。 這個自變數所參考的資料列應該可 DOUBLE轉換成 。
  • group_col （選擇性） 是字串或字串陣列，代表中的 observed群組數據行。 如果指定，則會使用群組數據行做為分割準則，而且會針對每個群組獨立產生預測。 如果未指定，則會將完整輸入數據視為單一群組。
  • prediction_interval_width （選擇性） 是介於 0 到 1 之間的值，代表預測間隔的寬度。 未來值在和 {v}_lower之間{v}_upper有 %prediction_interval_width的下降機率。
  • frequency （選擇性） 是時間單位或 pandas 位移別名字符串，指定預測結果的時間粒度。 如果未指定，則會個別推斷每個群組的預測粒度。 如果指定頻率值，則會同樣套用至所有群組。
    • 群組內推斷的頻率是最近觀察的模式。 這是用戶無法復原的便利作業。
    • 例如，具有99個「星期一」和1個「星期二」的時間序列會導致「周」成為推斷的頻率。
  • seed （選擇性） 是用來初始化預測程式中使用的任何虛擬隨機數位產生器的數位。
  • parameters （選擇性） 是字串編碼的 JSON 或資料行識別碼的名稱，代表預測程式的參數化。 任何參數組合都可以依任何順序指定，例如 {“weekly_order”: 10, “global_cap”: 1000}。 任何未指定的參數都會根據定型數據的屬性自動決定。 支援下列參數：
    • global_cap 和 global_floor 可以一起使用，或單獨用來定義計量值的可能定義域。 {“global_floor”: 0}例如，可用來限制成本等計量一律為正數。 這些會全域套用至定型數據和預測的數據，而且無法用來提供嚴格限制的預測值。
    • daily_order 並 weekly_order 設定每日和每周季節性元件的四分之一順序。

傳回

包含預測數據的新數據列集。 輸出架構會包含其類型不變的時間和群組數據行。 例如，如果輸入時間資料行的類型為 DATE，則輸出時間資料行類型也會是 DATE。 針對每個值資料列，有三個輸出資料列具有 模式 {v}_forecast、 {v}_upper和 {v}_lower。 不論輸入值類型為何，預測的值數據行一律為 類型 DOUBLE。 輸出數據表只包含未來的值，跨越觀察數據結尾到地平線之間的時間範圍。

請參閱下列AI_FORECAST所執行的架構推斷的一些範例：

輸入數據表 引數 輸出資料表
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

範例

下列範例會預測到指定的日期為止：


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

以下是更複雜的範例：


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

請注意，數據表通常不會具體化0或空白專案。 例如 0，如果可以推斷遺漏專案的值，則這些值應該在呼叫forecast函式之前合併。 如果值確實遺失或未知，則可以保留為 NULL。

對於非常疏鬆的數據，最佳做法是聯合遺漏值或明確提供頻率值，以避免從「自動」頻率推斷產生非預期的輸出。 例如，相隔 14 天之兩個專案的「自動」頻率推斷會推斷「14D」的頻率，即使「實際」頻率可能每周有 1 個遺漏值。 合併遺漏的專案會移除此模棱兩可。

最後，我們示範一個範例，其中不同的預測參數會套用至輸入數據表中的不同群組：

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

請注意，使用數據行標識碼做為 parameters 自變數。 這可讓使用者將先前決定的參數 JSON 儲存在數據表中，並在新的數據上重複使用它們。

限制

預覽期間適用下列限制：

  • 默認預測程式是類似先知的線性和季節性模型。 這是唯一支持的預測程式。
  • 錯誤訊息會透過 Python UDTF 引擎傳遞，並包含 Python 追蹤回溯資訊。 追蹤結尾包含實際的錯誤訊息。