ai_forecast 関数

適用対象: Databricks SQL

重要

この関数のバージョン 1 は パブリック プレビュー であり、 HIPAA に準拠しています。 バージョン 2 (推奨) は ベータ版です。

ai_forecast() は、時系列データを時間単位で推定するテーブル値関数です。 この関数を構成するために利用可能な引数については、「引数」を参照してください。

この関数には 2 つのバージョンがあります。 研究に最適化された時系列基盤モデルは、すぐに使用できる精度を向上させるためにバージョン 2 を強化し、バージョン 2 では休日、外部共変量、および負でない予測のサポートが追加されます。 version引数を使用して、実行するバージョンを選択します。 詳細については 、「引数」 を参照してください。

Requirements

  • ProまたはサーバーレスSQLウェアハウス
  • 予測 AI Functions プレビューにワークスペースを登録します (推奨バージョン 2 では必須)。 Manage Azure Databricks プレビューを参照してください。

構文

Tip

Azure Databricksでは、バージョン 2 をai_forecastに推奨しています。 バージョン 2 では、バージョン 1 に対して次の機能強化が行われます。

  • すぐに使用する精度を向上させる、研究用に最適化された時系列基盤モデル
  • 組み込みの休日のサポート holiday_region
  • 外部共変量 (将来および過去のみの共変量を含む) covariate_col
  • 非負の予測 positive_only

バージョン 2 を使用するには、 version => '2'渡します。 予測 AI Functions プレビューが有効になっていることを確認します。 Manage Azure Databricks プレビューを参照してください。

ai_forecast(observed, horizon, time_col, value_col
  [, group_col] [, covariate_col] [, prediction_interval_width]
  [, frequency] [, holiday_region] [, positive_only] [, version])

バージョン 1

ai_forecast(observed, horizon, time_col, value_col
  [, group_col] [, prediction_interval_width] [, frequency]
  [, seed] [, parameters] [, version])

引数

ai_forecast() は、各グループ内にあるグループ (group_col を参照) の任意の数と、最大 100 メトリック (value_col を参照) を予測できます。 予測頻度は、グループ内のすべてのメトリックで同じですが、グループ間で異なる場合があります ( frequencyを参照)。

  • observed は、予測手順のトレーニング データとして使われるテーブル値入力です。
    • この入力リレーションシップには、1 つの "time" 列と 1 つ以上の "value" 列が含まれている必要があります。 "Group" 列と "共変量" 列は省略可能です。 入力関係に含まれるその他の列は無視されます。
  • horizon は、上限が排他的な予測結果の終了時刻を表す、タイムスタンプにキャスト可能な数量です。 グループ内で (group_col を参照)、予測結果は最後の観測から horizon までの時間に及びます。 horizon が最後の観測時刻より小さい場合、結果は生成されません。
  • time_col は、 observedの "時間列" を参照する文字列です。 time_colによって参照される列は、DATEまたはTIMESTAMPである必要があります。
  • value_col は、observed の値列を参照する文字列または文字列の配列です。 この引数によって参照される列は、 DOUBLEにキャスト可能である必要があります。
  • group_col (省略可能) は、observed のグループ列を表す文字列または文字列の配列です。 指定した場合、パーティション分割の基準としてグループ列が使われ、予測はグループごとに個別に生成されます。 指定しない場合、入力データのすべてが 1 つのグループとして扱われます。
  • covariate_col (省略可能) は、 observedの外部共変量列を参照する文字列または文字列の配列です。 共変量は、価格、マーケティング支出、天気など、予測に影響を与える追加の変数です。 次の 2 種類の共変量がサポートされています。
    • 将来の共変量: 値は、計画価格やスケジュールされたキャンペーンなどの予測期間で知られています。 この方法で共変量を使用するには、予測期間 (最後の観測の後の日付、最大observed) をカバーする行をhorizonに含め、共変量が設定され、value_col列がNULL残ります。 ai_forecast は、これらの NULLターゲット行を予測し、予測をその共変量値で条件します。
    • 過去のみの共変量: 値は、観測された気象やマクロ経済指標など、過去の期間でのみ認識されます。 履歴行のみに共変量を設定します。 予測期間に共変量値を指定しない場合、 ai_forecast は共変量を過去専用として使用します。これはエラーではありません。
  • prediction_interval_width (省略可能) は、予測の間隔の幅を表す 0 から 1 の値です。 予測値には、prediction_interval_widthと{v}_upperの間で低下する{v}_lower %確率があります。
  • frequency (省略可能) は、予測結果の時間粒度を指定する pandas オフセットエイリアス文字列 (たとえば、 'D'、 'W'、 'ME'、 'H') です。 指定しない場合、予測の細分性はグループごとに個別に自動的に推論されます。 指定する場合は、各グループ内の入力データの推定粒度と一致する必要があります。
    • グループ内で推論される頻度は、最新の観測のモードです。 この推論は、ユーザーがチューニングできない便利な操作です。
    • たとえば、"mondays" が 99 で "tuesday" が 1 の時系列では、"week" が推定頻度になります。
  • holiday_region (省略可能) は、 'US'など、そのリージョンの休日効果の自動モデリングを有効にするリージョン コードです。 指定しない場合、休日の効果はモデル化されません。
  • positive_only (省略可能) TRUEに設定すると、予測値が負でない値に制限されます。 この引数は、売上、カウント、在庫など、負の値にできないメトリックに使用します。 既定値は FALSE です。
  • version (省略可能): 移行をサポートするバージョン 切り替え (バージョン 1 の動作の場合は'1' 、バージョン 2 の動作では '2' )。 指定しない場合、既定値はバージョン 1 です。 バージョン 2 の引数 (covariate_col、 holiday_region、 positive_only) には、 version => '2'が必要です。

バージョン 1

  • observed は、予測手順のトレーニング データとして使われるテーブル値入力です。
    • この入力リレーションシップには、1 つの "time" 列と 1 つ以上の "value" 列が含まれている必要があります。 "Group" 列と "parameters" 列は省略可能です。 入力関係に含まれるその他の列は無視されます。
  • horizon は、上限が排他的な予測結果の終了時刻を表す、タイムスタンプにキャスト可能な数量です。 グループ内で (group_col を参照)、予測結果は最後の観測から horizon までの時間に及びます。 horizon が最後の観測時刻より小さい場合、結果は生成されません。
  • time_col は、 observedの "時間列" を参照する文字列です。 time_colによって参照される列は、DATEまたはTIMESTAMPである必要があります。
  • value_col は、observed の値列を参照する文字列または文字列の配列です。 この引数によって参照される列は、 DOUBLEにキャスト可能である必要があります。
  • group_col (省略可能) は、observed のグループ列を表す文字列または文字列の配列です。 指定した場合、パーティション分割の基準としてグループ列が使われ、予測はグループごとに個別に生成されます。 指定しない場合、入力データのすべてが 1 つのグループとして扱われます。
  • prediction_interval_width (省略可能) は、予測の間隔の幅を表す 0 から 1 の値です。 予測値には、prediction_interval_widthと{v}_upperの間で低下する{v}_lower %確率があります。
  • frequency (省略可能) は、予測結果の時間の細分性を指定する、時間単位または pandas のオフセット エイリアスの文字列です。 指定しない場合、予測の細分性はグループごとに個別に自動的に推論されます。 頻度の値を指定した場合は、すべてのグループに等しく適用されます。
    • グループ内で推論される頻度は、最新の観測のモードです。 この推論は、ユーザーがチューニングできない便利な操作です。
    • たとえば、"mondays" が 99 で "tuesday" が 1 の時系列では、"week" が推定頻度になります。
  • seed (省略可能) は、予測手順で使用される擬似乱数ジェネレーターを開始するために使用される数値です。
  • parameters (省略可能) は、予測手順のパラメーター化を表す、文字列にエンコードされた JSON または列識別子の名前です。 {"weekly_order": 10, "global_cap": 1000} のように、任意のパラメーターを任意の順序で組み合わせて指定できます。 指定されていないパラメーターは、トレーニング データの属性に基づいて自動的に決定されます。 次のパラメーターがサポートされています。
    • global_cap と global_floor を使ってメトリック値の範囲を定義できます。これらは組み合わせて使うことも、個別に使うこともできます。 たとえば、{"global_floor": 0} を使うと、コストなどのメトリックが常に正になるように制限できます。 これらの制約は、トレーニング データと予測データにグローバルに適用され、予測値のみに厳密な制約を提供するために使用することはできません。
    • daily_order と weekly_order により、日単位と週単位の季節性コンポーネントのフーリエ次数を設定できます。
  • version (省略可能): 移行をサポートするバージョン 切り替え (バージョン 1 の動作の場合は'1' 、バージョン 2 の動作では '2' )。 指定しない場合、既定値はバージョン 1 です。 バージョン 2 の引数 (covariate_col、 holiday_region、 positive_only) には、 version => '2'が必要です。

戻り値

予測データを含む行の新しいセットです。 出力スキーマには、型が変更されていない時刻列とグループ列が含まれています。 たとえば、入力時刻列の型が DATEの場合、出力時刻列の型も DATE。 値列ごとに、{v}_forecast、{v}_upper、{v}_lower というパターンの 3 つの出力列があります。 入力値の型に関係なく、予測値の列の型は常に 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

バージョン 1

予測データを含む行の新しいセットです。 出力スキーマには、型が変更されていない時刻列とグループ列が含まれています。 たとえば、入力時刻列の型が DATEの場合、出力時刻列の型も DATE。 値列ごとに、{v}_forecast、{v}_upper、{v}_lower というパターンの 3 つの出力列があります。 入力値の型に関係なく、予測値の列の型は常に 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

例

次の例では、バージョン 2 を使用して指定した日付まで予測します。


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',
  version => '2'
)

次の例では、米国の休日の影響をモデル化し、予測を負以外の値に制限します。


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',
  holiday_region => 'US',
  positive_only => true,
  version => '2'
)

次の例では、外部共変量を使用します。 observed テーブル (daily_sales) には、履歴期間と予測期間の両方に設定されたpromotion列が含まれており、予測期間の行にrevenue左NULLがあるため、promotionは将来の共変量として使用されます。


SELECT * FROM AI_FORECAST(
  TABLE(daily_sales),
  horizon => '2016-03-31',
  time_col => 'ds',
  value_col => 'revenue',
  covariate_col => 'promotion',
  version => '2'
)

バージョン 1

次の例では、指定した日付まで予測します。


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

手記

ai_forecast はテーブル内の欠損したエントリやNULLに対して0を補完しません。 不足しているエントリの適切な値を推論できる場合は、 ai_forecast 関数を呼び出す前に結合する必要があります。 値が本当に不足しているか不明な場合は、値を NULL のままにするか、削除できます。

スパース データの場合は、欠損値を結合するか、頻度値を明示的に指定して、"自動" 周波数推論からの予期しない出力を回避することをお勧めします。 たとえば、14 日離れた 2 つのエントリに対する "自動" 頻度推論では、"実際の" 頻度が週に 1 つの欠損値を持つ場合でも、"14D" の頻度が推論されます。 欠損しているエントリを結合することで、このあいまいさを解消できます。

次の例は、入力テーブルのさまざまなグループにさまざまな予測パラメーターを適用する方法を示しています。 この例では、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'
)

制限事項

ベータ期間中は、次の制限が適用されます。

  • バージョン 2 は ベータ版 であり、既定値ではありません。 バージョン 2 を使用するには、 version => '2'を設定してオプトインします。 パブリック プレビュー段階のバージョン 1 は既定値のままです。
  • 既定の予測手順は、時系列の基礎モデルです。 このモデルは、サポートされている唯一の予測手順です。
  • エラー メッセージは Python UDTF エンジンを介して配信され、Python トレース バック情報が含まれます。 トレース バックの末尾には、実際のエラー メッセージが含まれています。
  • ai_forecastの各呼び出しでは、独立した推論が実行されます。 異なるai_forecast値でprediction_interval_widthを複数回呼び出して、入れ子になった予測間隔を生成する場合、結果の間隔が正しく入れ子になることは保証されません。 予測間隔を比較するには、1 つのai_forecast値を持つ 1 つのprediction_interval_width呼び出しを使用します。

バージョン 1

パブリック プレビューでは、次の制限が適用されます。

  • バージョン 1 はパブリック プレビュー段階であり、既定のバージョンです。 ベータ版のバージョン 2 は、version => '2'を設定することで利用できます。
  • バージョン 1 は非推奨パスにあります。 今後のリリースでは、既定のバージョンがバージョン 2 に変更され、バージョン 1 は非推奨になります。 既定の変更後もバージョン 1 の動作を使用し続けるためには、 version => '1'設定してピン留めします。
  • 既定の予測手順は、prophet のような区分的に線形な季節性モデルです。 このモデルは、サポートされている唯一の予測手順です。
  • エラー メッセージは Python UDTF エンジンを介して配信され、Python トレース バック情報が含まれます。 トレース バックの末尾には、実際のエラー メッセージが含まれています。
  • ai_forecastの各呼び出しでは、独立した分位点回帰が実行されます。 異なるai_forecast値でprediction_interval_widthを複数回呼び出して入れ子になった予測間隔を生成する場合、結果の間隔は正しく入れ子になることは保証されません。これは、分位点が呼び出し間で独立して計算されるためです。正しい順序を確認する制約はありません。 予測間隔を比較するには、1 つのai_forecast値を持つ 1 つのprediction_interval_width呼び出しを使用します。
  • Last updated on