ai_detect_anomalies Fonction

S’applique à :case cochée oui Databricks SQL

Important

Cette fonctionnalité est en version bêta. Pour l’utiliser, un administrateur d’espace de travail doit activer les fonctions d’IA prédictives depuis la page des aperçus . Consultez Gérer les préversions d’Azure Databricks.

ai_detect_anomalies() est une fonction à valeurs de table qui identifie des valeurs anormales dans les données de séries temporelles. Il utilise l’historique précédant chaque valeur pour estimer la valeur attendue et l’intervalle de prédiction, puis attribue un score d’anomalie.

Exigences

  • Un entrepôt SQL Pro ou Serverless. Cette fonction n’est pas disponible sur un entrepôt SQL classique.
  • Inscrivez votre espace de travail dans l’aperçu des fonctions d’IA prédictives . Consultez Gérer les préversions d’Azure Databricks.

Syntax

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

Arguments

  • observed est l’entrée à valeurs de table qui contient les données de la série temporelle.
  • time_col est une STRING colonne qui nomme a DATE ou TIMESTAMP dans observed. Les horodatages doivent être uniques au sein de chaque série temporelle.
  • value_col est un STRING nom de la colonne numérique à analyser. Vous pouvez analyser une colonne de valeur par invocation.
  • group_col (optionnel) est une STRING ou une ARRAY<STRING> colonne de nommage qui identifie des séries temporelles distinctes. Chaque groupe est analysé indépendamment. Si elle est omise, l’entrée complète est considérée comme une série temporelle unique.
  • anomaly_threshold (optionnel) est un DOUBLE entre 0 et 1 qui détermine quand une valeur est signalée comme anormale. Une ligne est anormale lorsqu’elle anomaly_score est supérieure à ce seuil. La valeur par défaut est 0.95. Des valeurs plus basses signalent plus d’anomalies, tandis que des valeurs plus élevées signalent moins d’anomalies.
  • covariate_col (optionnel) est un STRING ou un ARRAY<STRING> nom de colonnes numériques ou de chaîne dont les valeurs peuvent aider à expliquer la série temporelle, telles que le prix, les promotions ou la météo.
  • holiday_region (optionnel) est un STRING contenant un code de pays, tel que 'US'. Une fois spécifiée, la fonction prend en compte les effets des fêtes dans les valeurs attendues.
  • only_last_n (optionnel) limite les lignes retournées et notées tout en conservant les lignes antérieures comme contexte historique. Spécifiez un entier de 1 à 8 192 pour analyser uniquement le nombre le plus récent de lignes dans chaque série, ou spécifiez un DATE ou TIMESTAMP un seuil pour analyser les lignes à cette valeur ou après cette valeur. Limiter la plage de points peut modifier les scores d’anomalie car la fonction permet de faire moins de prédictions sur différentes fenêtres de prévision. Omet cet argument pour analyser toute la série.
  • smoothing (optionnel) détermine si de courts intervalles entre les anomalies sont inclus dans le même épisode anormal. Lorsque TRUE, la fonction marque des espaces allant jusqu’à trois lignes entre les anomalies signalées comme anormales. Cela peut réduire les épisodes d’anomalies fragmentées mais peut aussi signaler des valeurs normales à l’intérieur de ces intervalles. Le lissage ne change que is_anomaly; il ne modifie pas les valeurs attendues, les bornes ou les scores d’anomalie. La valeur par défaut est TRUE.

Returns

La fonction renvoie les colonnes d’entrée, temps, groupe et valeur, suivies de ces colonnes :

Column Type Description
expected DOUBLE La valeur attendue basée sur l’historique précédent.
lower_bound DOUBLE La borne inférieure de l’intervalle de prédiction.
upper_bound DOUBLE La borne supérieure de l’intervalle de prédiction.
anomaly_score DOUBLE Un score de 0 à 1 indiquant à quel point la valeur observée diffère fortement de la prédiction.
is_anomaly BOOLEAN Si la ligne est anormale basée sur anomaly_threshold et smoothing.

Les huit premières rangées de chaque série temporelle fournissent un contexte historique. Pour ces lignes, , , , et anomaly_score sont NULL, et is_anomaly est FALSE. upper_boundlower_boundexpected

Exemples

L’exemple suivant génère une série temporelle avec un pic injecté et identifie ses anomalies :

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

L’exemple suivant analyse chaque appareil indépendamment, prend en compte la température et les États-Unis jours fériés, et ne restitue que les 100 lignes les plus récentes de chaque série d’appareils :

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

Les limitations suivantes s’appliquent pendant la bêta :

  • Chaque série temporelle peut contenir au maximum 8 192 lignes d’entrée. Une requête avec une série plus longue échoue.
  • Chaque série temporelle doit contenir au moins une valeur observée finie.
  • Les horodatages doivent être uniques au sein de chaque série temporelle.
  • Vous pouvez analyser une colonne de valeur par invocation.
  • Les messages d’erreur sont transmis via le moteur Python UDTF et peuvent contenir des informations de traçabilité Python. La fin du traçage contient le message d’erreur réel.