Funzione ai_detect_anomalies

Si applica a: Databricks SQL

ai_detect_anomalies() è una funzione a valori di tabella che identifica valori anomali nei dati delle serie temporali. Utilizza la storia precedente a ciascun valore per stimare il valore atteso e l'intervallo di previsione, quindi assegna un punteggio di anomalia.

Requisiti

• Un magazzino SQL Pro o serverless. Questa funzione non è disponibile su un Classic SQL warehouse.
• Iscrivi il tuo spazio di lavoro nell'anteprima delle Funzioni AI Predittive . Vedere Gestire le anteprime di Azure Databricks.

Syntax

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

Argomenti

• observed è l'input con valori di tabella che contiene i dati della serie temporale.
• time_col è una STRING colonna che nomina una DATE o TIMESTAMP in observed. I timestamp devono essere unici all'interno di ogni serie temporale.
• value_col è un STRING nome della colonna numerica da analizzare. Puoi analizzare una colonna di valore per ogni invocazione.
• group_col (opzionale) è una STRING o una ARRAY<STRING> colonna di denominazione che identifica serie temporali separate. Ogni gruppo viene analizzato indipendentemente. Se omesso, l'input completo viene trattato come una serie temporale unica.
• anomaly_threshold (opzionale) è un DOUBLE valore tra 0 e 1 che controlla quando un valore viene segnalato come anomalo. Una riga è anomala quando è anomaly_score superiore a questa soglia. Il valore predefinito è 0.95. Valori più bassi segnalano più anomalie, mentre valori più alti segnalano meno anomalie.
• covariate_col (opzionale) è un STRING o un ARRAY<STRING> numero di colonne o colonne a stringa di nomi i cui valori possono aiutare a spiegare la serie temporale, come prezzo, promozioni o meteo.
• holiday_region (opzionale) è un STRING contenente un codice paese, come 'US'. Quando specificato, la funzione tiene conto degli effetti delle festività nei valori attesi.
• only_last_n (opzionale) limita le righe restituite e segnate mantenendo le righe precedenti come contesto storico. Specificare un intero da 1 a 8.192 per analizzare solo il numero più recente di righe in ciascuna serie, oppure specificare un DATE o TIMESTAMP cutoff per analizzare le righe a quel valore o successivamente. Limitare l'intervallo di punteggio può modificare i punteggi anomali perché la funzione può fare meno previsioni su diverse finestre di previsione. Ometti questo argomento per analizzare l'intera serie.
• smoothing (opzionale) controlla se brevi intervalli tra anomalie sono inclusi nello stesso episodio anomalo. Quando TRUE, la funzione segna come anomalie le lacune fino a tre righe tra anomalie segnalate. Questo può ridurre gli episodi di anomalie frammentate, ma può anche segnalare valori normali all'interno di quei vuoti. Lo smoothing cambia solo is_anomaly; non cambia valori attesi, limiti o punteggi anomali. Il valore predefinito è TRUE.

Returns

La funzione restituisce le colonne di input, tempo, gruppo e valore, seguite da queste colonne:

Le prime otto file di ogni serie temporale forniscono un contesto storico. Per queste righe, , , , e anomaly_score sono NULL, e is_anomaly è FALSE. upper_boundlower_boundexpected

Examples

Il seguente esempio genera una serie temporale con uno spike iniettato e ne identifica le anomalie:

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

Il seguente esempio analizza ogni dispositivo in modo indipendente, tiene conto della temperatura e delle festività negli Stati Uniti, e restituisce solo le ultime 100 righe di ciascuna serie di dispositivi:

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

Durante la Beta si applicano le seguenti limitazioni:

• Ogni serie temporale può contenere al massimo 8.192 righe di input. Una query con una serie più lunga fallisce.
• Ogni serie temporale deve contenere almeno un valore osservato finito.
• I timestamp devono essere unici all'interno di ogni serie temporale.
• Puoi analizzare una colonna di valore per ogni invocazione.
• I messaggi di errore vengono inviati tramite il motore Python UDTF e possono contenere informazioni di tracciamento Python. La fine del tracciamento contiene il vero messaggio di errore.