ai_detect_anomalies-Funktion

Gilt für: Databricks SQL

ai_detect_anomalies() ist eine tabellenwertige Funktion, die anomale Werte in Zeitreihendaten identifiziert. Es verwendet die Historie vor jedem Wert, um den Erwartungswert und das Vorhersageintervall zu schätzen, und weist dann einen Anomaliewert zu.

Anforderungen

• Ein Pro- oder Serverless-SQL-Warehouse. Diese Funktion ist in einem klassischen SQL-Warehouse nicht verfügbar.
• Melden Sie Ihren Arbeitsbereich in der Vorschau der Predictive AI Functions an. Siehe Manage Azure Databricks Previews.

Syntax

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

Argumente

• observed ist die tabellenwertige Eingabe, die die Zeitreihendaten enthält.
• time_col ist eine STRING Benennung einer DATE oder Spalte TIMESTAMP in observed. Zeitstempel müssen innerhalb jeder Zeitreihe einzigartig sein.
• value_col ist eine STRING Benennung der numerischen Spalte, die analysiert werden soll. Du kannst pro Aufruf eine Wertspalte analysieren.
• group_col (optional) ist eine STRING oder eine Namensspalte ARRAY<STRING> , die separate Zeitreihen kennzeichnet. Jede Gruppe wird unabhängig analysiert. Wenn ausgelassen, wird der gesamte Eingang als eine Zeitreihe behandelt.
• anomaly_threshold (optional) ist ein DOUBLE Wert zwischen 0 und 1, der steuert, wann ein Wert als anomal markiert wird. Eine Reihe ist anomal, wenn sie anomaly_score größer als diese Schwelle ist. Der Standardwert lautet 0.95. Niedrigere Werte signalisieren mehr Anomalien, während höhere Werte weniger Anomalien anzeigen.
• covariate_col (optional) ist eine STRING oder eine ARRAY<STRING> Namens- oder Zeichenketten-Spalte, deren Werte helfen können, die Zeitreihe zu erklären, wie zum Beispiel Preis, Aktionen oder Wetter.
• holiday_region (optional) ist a STRING , der einen Ländercode enthält, wie zum Beispiel 'US'. Wenn angegeben, berücksichtigt die Funktion die Feiertagseffekte in den Erwartungswerten.
• only_last_n (optional) begrenzt die zurückgegebenen und bewerteten Reihen, während frühere Zeilen als historischer Kontext erhalten bleiben. Geben Sie eine ganze Zahl von 1 bis 8.192 an, um nur die aktuellste Anzahl von Zeilen in jeder Reihe zu analysieren, oder geben Sie ein oder TIMESTAMP Cutoff DATE an, um Zeilen bei oder nach diesem Wert zu analysieren. Die Begrenzung des Wertungsbereichs kann Anomaliewerte verändern, da die Funktion über verschiedene Prognosefenster weniger Vorhersagen treffen kann. Lassen Sie dieses Argument weg, um die gesamte Serie zu analysieren.
• smoothing (optional) steuert, ob kurze Lücken zwischen Anomalien in derselben anomalen Episode enthalten sind. Wenn TRUE, markiert die Funktion Lücken von bis zu drei Reihen zwischen markierten Anomalien als anomal. Dies kann fragmentierte Anomalie-Episoden reduzieren, aber auch Normalwerte innerhalb dieser Lücken markieren. Glättung ändert nur is_anomaly; sie ändert keine erwarteten Werte, Grenzen oder Anomaliewerte. Der Standardwert lautet TRUE.

Rückkehr

Die Funktion liefert die Spalten für Eingabezeit, Gruppe und Wert, gefolgt von diesen Spalten:

Die ersten acht Zeilen jeder Zeitreihe bieten historischen Kontext. Für diese Zeilen sind , , , und anomaly_score , NULLund is_anomaly ist FALSE. upper_boundlower_boundexpected

Beispiele

Das folgende Beispiel erzeugt eine Zeitreihe mit einem injizierten Spike und identifiziert deren Anomalien:

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

Das folgende Beispiel analysiert jedes Gerät einzeln, berücksichtigt Temperatur und Feiertage in den USA und gibt nur die aktuellsten 100 Zeilen jeder Geräteserie zurück:

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

Limitations

Während der Beta gelten folgende Einschränkungen:

• Jede Zeitreihe kann höchstens 8.192 Eingabezeilen enthalten. Eine Abfrage mit einer längeren Serie schlägt fehl.
• Jede Zeitreihe muss mindestens einen endlichen beobachteten Wert enthalten.
• Zeitstempel müssen innerhalb jeder Zeitreihe einzigartig sein.
• Du kannst pro Aufruf eine Wertspalte analysieren.
• Fehlermeldungen werden über die Python UDTF-Engine übermittelt und können Python-Rückverfolgungsinformationen enthalten. Das Ende der Rückverfolgung enthält die eigentliche Fehlermeldung.