ai_detect_anomalies 関数

適用対象: チェック マークあり Databricks SQL

Important

この機能は ベータ版です。 使用するには、ワークスペース管理者がプレビューページから予測AI機能をオンにする必要があります。 Manage Azure Databricks プレビューを参照してください。

ai_detect_anomalies() は時系列データにおける異常値を識別するテーブル値関数です。 各値の前の履歴を使って期待値と予測区間を推定し、その後異常スコアを割り当てます。

必要条件

  • ProまたはServerless SQLウェアハウス。 この機能はクラシックSQLウェアハウスでは利用できません。
  • Predictive AI Functionsプレビューでワークスペースを登録してください。 Manage Azure Databricks プレビューを参照してください。

Syntax

ai_detect_anomalies(
  observed,
  time_col,
  value_col
  [, group_col]
  [, anomaly_threshold]
  [, covariate_col]
  [, holiday_region]
  [, only_last_n]
  [, smoothing]
)

引数

  • observed は時系列データを含むテーブル値入力です。
  • time_col observedの列に記載されたDATEまたはTIMESTAMP列を命名するSTRINGです。 タイムスタンプは各時系列内で一意でなければなりません。
  • value_col は解析する数値列の名前を付ける STRING です。 呼び出しごとに1つの値列を分析できます。
  • group_col (オプション)は、別々の時系列を示す命名列 STRING または ARRAY<STRING> の列です。 各グループは独立して分析されます。 省略すると、入力全体は1つの時間系列として扱われます。
  • anomaly_threshold (オプション)は0から1の間の DOUBLE で、値が異常としてフラグを立てられるタイミングを制御します。 行の異常は、その anomaly_score がこの閾値より大きい場合です。 既定値は 0.95 です。 値が低いほど異常が増え、値が高いほど異常が少ないのが示されます。
  • covariate_col (オプション)は、価格、プロモーション、天候などの時系列を説明するのに役立つ数値や文字列の列名を付ける、番号や文字列の列名を付ける STRING または ARRAY<STRING> です。
  • holiday_region (オプション)は国コードを含む国コードを含む STRING'US'。 指定された場合、この関数は期待値にホリデーの影響を考慮します。
  • only_last_n (任意)は、返却された行と得点された行を制限しつつ、過去の行は歴史的文脈として保持します。 1から8,192までの整数を指定して各系列の最新の行数のみを解析するか、 DATE または TIMESTAMP のカットオフを指定してその値以降の行を解析します。 スコア範囲を制限することで、関数が異なる予報ウィンドウで予測を減らせるため、異常スコアが変わる可能性があります。 この議論は省略してシリーズ全体を分析してください。
  • smoothing (任意)は、異常間の短い間隔が同じ異常エピソードに含まれるかどうかを制御します。 TRUEすると、フラグ付けされた異常の間に最大3行の隙間が異常として表示されます。 これにより断片的な異常エピソードを減らすことができますが、隙間内の正常値をフラグ付けすることもあります。 平滑化は is_anomalyだけを変えますが、期待値、境界、異常スコアは変わりません。 既定値は TRUE です。

返品

この関数は入力時間、グループ、値の各列を返し、その後に以下の列を返します。

Column タイプ Description
expected DOUBLE 前の履歴に基づく期待値。
lower_bound DOUBLE 予測区間の下限です。
upper_bound DOUBLE 予測区間の上限。
anomaly_score DOUBLE 観測値が予測値とどれだけ大きく異なるかを示す0から1までのスコアです。
is_anomaly BOOLEAN anomaly_thresholdやsmoothingに基づく、その騒動が異常かどうか。

各時系列の最初の8行は歴史的背景を提供します。 これらの行では、 expected、 lower_bound、 upper_bound、 anomaly_score が NULL、 is_anomaly が FALSEです。

例示

以下の例は、注入されたスパイクを持つ時系列を生成し、その異常を特定します。

WITH observed AS (
  SELECT
    date_add(DATE '2026-01-01', CAST(id AS INT)) AS ds,
    CASE
      WHEN id = 45 THEN 200.0
      ELSE 100.0 + 5.0 * sin(id / 3.0)
    END AS metric
  FROM range(60)
)
SELECT *
FROM ai_detect_anomalies(
  TABLE(observed),
  time_col => 'ds',
  value_col => 'metric'
)
ORDER BY ds

以下の例は各デバイスを独立して分析し、温度と米国の祝日を考慮し、各デバイスシリーズから最新の100行のみを返します。

SELECT *
FROM ai_detect_anomalies(
  TABLE(device_metrics),
  time_col => 'event_time',
  value_col => 'metric',
  group_col => 'device_id',
  anomaly_threshold => 0.98,
  covariate_col => 'temperature',
  holiday_region => 'US',
  only_last_n => 100,
  smoothing => FALSE
)
ORDER BY device_id, event_time

制限事項

ベータ期間中に適用される制限は以下の通りです:

  • 各時系列は最大8,192行の入力行を含めます。 より長い系列のクエリは失敗します。
  • 各時系列は少なくとも1つの有限の観測値を含む必要があります。
  • タイムスタンプは各時系列内で一意でなければなりません。
  • 呼び出しごとに1つの値列を分析できます。
  • エラーメッセージはPython UDTFエンジンを通じて配信され、Pythonのトレースバック情報を含むことができます。 トレースバックの末尾には実際のエラーメッセージが含まれています。
  • 最終更新: