ai_forecast
函式
適用於: Databricks SQL
重要
這項功能處於 公開預覽狀態。 請連絡 Databricks 帳戶小組以參與預覽。
ai_forecast()
是一個數據表值函式,其設計目的是將時間序列數據推斷到未來。 如需設定此函式的可用自變數,請參閱自變數。
需求
- 僅適用於執行 Databricks SQL 2024.35 版和更新版本的 Pro SQL 倉儲。
- 檢查 Databricks 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 之間的值,代表預測間隔的寬度。 未來值在和{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 追蹤回溯資訊。 追蹤結尾包含實際的錯誤訊息。