共用方式為

ai_forecast 函式

  • 發行項

適用於：核取記號為「是」 Databricks SQL

重要

這項功能為公開預覽階段。 請連絡 Databricks 客戶團隊以參與預覽版。

ai_forecast() 是一個資料表值函式，旨在推斷未來的時間序列資料。 如需設定此函式的可用引數，請參閱引數。

需求

Pro 或無伺服器 SQL 倉儲

語法


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 是用作預測程序的訓練資料的資料表值輸入。
    • 此輸入關聯必須包含一個「時間」資料行和一或多個「值」資料行。 「群組」和「參數」資料行是選用的。 輸入關聯中的任何額外資料行將忽略。
  • horizon 是一個可轉換為時間戳記的數量，表示預測結果的唯一正確結束時間。 在一個群組 (請參閱 group_col) 中，預測結果的時間範圍是從上次觀測到邊際。 如果邊際小於上次觀測時間，則不會產生任何結果。
  • time_col 是參考 observed 中「時間資料行」的字串。 time_col 參考的資料行應是 DATE 或 TIMESTAMP。
  • value_col 是參考 observed 中值資料行的字串或字串陣列。 此引數參考的資料行應可轉換為 DOUBLE。
  • group_col (選用) 是字串或字串陣列，表示 observed 中的群組資料行。 如果已指定，群組資料行將用作分割準則，並且會單獨為每個群組產生預測。 如果未指定，則完整輸入資料將視為單一群組。
  • prediction_interval_width (選用) 是一個介於 0 和 1 之間的值，表示預測間隔的寬度。 終值具有 prediction_interval_width 和 {v}_upper 之間的 {v}_lower% 的概率。
  • 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)，則應在呼叫預測函式之前合併這些值。 如果值確實遺失或未知，則可以將其保留為 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 儲存在資料表中，並在新資料上重複使用。

限制

預覽期間有下列限制：

  • 預設預測程序是一個類似 prophet 的分段線性和季節性模型。 這是唯一可用的受支援的預測程序。
  • 錯誤訊息透過 Python UDTF 引擎傳遞，並包含 Python 回溯資訊。 回溯結尾包含實際的錯誤訊息。