`ai_forecast` 函式

發行項
12/27/2024

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

重要

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

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

需求

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 是用作預測程序的訓練數據的 table值輸入。
- 這個輸入關聯必須包含一個「時間」column 和一或多個「值」columns。「群組」和「parameters」columns 是選擇性的。在輸入的關係中任何額外的 columns 將會被忽略。
horizon 是一個可轉換為時間戳記的數量，表示預測結果的唯一正確結束時間。在一個群組 (請參閱 group_col) 中，預測結果的時間範圍是從上次觀測到邊際。如果邊際小於上次觀測時間，則不會產生任何結果。
time_col 是參考 observed中「時間 column」的字串。 time_col 所參考的 column 應該是 DATE 或 TIMESTAMP。
value_col 是字串或字串陣列，參考 observed中的值 columns。這個參數所參考的 columns 應該可轉換為 DOUBLE。
group_col （選擇性）是字串或字串陣列，代表 observed中的群組 columns。如果有指定，則會將群組 columns 作為分割標準，並為每個群組獨立產生預測。如果未指定，則完整輸入資料將視為單一群組。
prediction_interval_width (選用) 是一個介於 0 和 1 之間的值，表示預測間隔的寬度。未來的 values 有 prediction_interval_width % 落在 {v}_upper 和 {v}_lower之間的機率。
frequency （選擇性）是一個時間單位或 pandas offset 的化名字符串，用於指定預測結果的時間粒度。如果未指定，則會自動為每個群組單獨推斷預測細微性。如果已指定頻率值，則會同樣套用至所有群組。
- 群組內推斷的頻率是最近觀測的模式。這是一種便利作業，使用者無法調整。
- 例如，在包含 99 個「星期一」和 1 個「星期二」的時間序列中，「週」會成為推斷的頻率。
seed (選用) 是用於初始化預測程序中使用的任何偽亂數產生器的數字。
parameters （選擇性）是字串編碼的 JSON 或代表預測程式參數化之 columnidentifier 的名稱。 parameters 的任何組合都可以依任何順序指定，例如，{“weekly_order”: 10, “global_cap”: 1000}。任何未指定的 parameters 都會根據訓練數據的屬性自動決定。支援下列 parameters：
- global_cap 和 global_floor 可以一起使用或獨立使用，以定義計量 values的可能網域。例如，{“global_floor”: 0} 可用於限制成本等計量一律為正數。這些會全域套用至訓練數據和預測數據，而且無法用來僅提供預測 values 嚴格的限制約束。
- daily_order 和 weekly_orderset 每日和每周季節性元件的傅立葉階數。

傳回

包含預測數據的新資料列 set。輸出 schema 會包含時間與群組 columns，且其類型不變。例如，如果輸入時間 column 的類型 DATE，則輸出時間 column 類型也會 DATE。對於每個值 column，存在三個輸出 columns，其模式為 {v}_forecast、{v}_upper和 {v}_lower。不論輸入值類型為何，預測值 columns 一律是類型 DOUBLE。輸出 table 僅包含未來的 values，涵蓋從觀察數據結束到預測時間點之間的時間區間。

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

輸入 table	引數	輸出 table
`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}'
)

請注意，tables 無法產生 0 或空白條目是很常見的。如果可以推斷遺漏項目的 values，例如 0，則在呼叫 forecast 函數之前，應該先整合這些 values。如果 values 確實遺失或未知，則可以保留為 NULL。

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

最後，我們示範一個範例，where 不同的預測 parameters 會套用至輸入 table中的不同群組：

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

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

限制

預覽期間有下列限制：

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

共用方式為

`ai_forecast` 函式

需求

語法

引數

傳回

範例

限制

意見反應

其他資源

共用方式為

ai_forecast 函式

需求

語法

引數

傳回

範例

限制

意見反應

其他資源

`ai_forecast` 函式