ai_forecast 函式

適用於： Databricks SQL

重要

這項功能目前處於公開預覽版，並符合 HIPAA 規範。 請連絡 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 是做為預測程式定型數據的數據表值輸入。
  • 此輸入關聯必須包含一個「時間」數據行和一或多個「值」數據行。 “Group” 和 “parameters” 欄位是可選的。 輸入關聯中的任何額外數據行會被忽略。
• 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，則在呼叫 ai_forecast 函式之前先合併這些值。 如果值確實遺失或未知，則可以保留為 NULL。

對於非常疏鬆的數據，最佳做法是聯合遺漏值或明確提供頻率值，以避免從「自動」頻率推斷產生非預期的輸出。 例如，對相隔 14 天的兩個項目進行「自動」頻率推斷將推斷出頻率為 “14D”，即使「實際」頻率可能是每週一次且有 1 個遺失值。 合併遺失的項目會消除這種歧義。

下列範例顯示將不同的預測參數套用至輸入數據表中的不同群組。 此範例使用 parameters 自變數作為數據行標識符。 這可讓使用者將先前決定的參數 JSON 儲存在數據表中，並在新的數據上重複使用它們。

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

限制

預覽期間有下列限制：

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