次の方法で共有

ai_forecast 関数

  • [アーティクル]

適用対象: Databricks SQL

重要

この機能はパブリック プレビュー段階です。 プレビューに参加する場合は、Databricks アカウント チームにお問い合わせください。

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

要件

Pro または Serverless SQL Warehouse

構文


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 は、予測手順のトレーニング データとして使われるテーブル値入力です。
    • この入力関係には、1 つの "時刻" 列と 1 つ以上の "値" 列が含まれている必要があります。 "グループ" 列と "パラメーター" 列は省略可能です。 入力関係に含まれるその他の列は無視されます。
  • 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 のオフセット エイリアスの文字列です。 指定しない場合、予測の細分性はグループごとに個別に自動的に推論されます。 頻度の値を指定した場合は、すべてのグループに等しく適用されます。
    • グループ内で推論される頻度は、最新の観測のモードです。 これは、ユーザーがチューニングできない便利な操作です。
    • たとえば、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 というパターンの 3 つの出力列があります。 入力値の型に関係なく、予測値の列の型は常に DOUBLE です。 出力テーブルには、観測されたデータの終了から horizon までの時間範囲にわたる将来の値のみが含まれます。

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 のままで構いません。

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

最後に、入力テーブルのさまざまなグループに異なる予測パラメーターが適用される例を示します。

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 トレース バック情報が含まれます。 トレース バックの末尾には、実際のエラー メッセージが含まれています。