Remarque
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de vous connecter ou de modifier des répertoires.
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de modifier des répertoires.
S’applique à :
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
-
observedest l’entrée à valeurs de table qui contient les données de la série temporelle. -
time_colest uneSTRINGcolonne qui nomme aDATEouTIMESTAMPdansobserved. Les horodatages doivent être uniques au sein de chaque série temporelle. -
value_colest unSTRINGnom de la colonne numérique à analyser. Vous pouvez analyser une colonne de valeur par invocation. -
group_col(optionnel) est uneSTRINGou uneARRAY<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 unDOUBLEentre 0 et 1 qui détermine quand une valeur est signalée comme anormale. Une ligne est anormale lorsqu’elleanomaly_scoreest supérieure à ce seuil. La valeur par défaut est0.95. Des valeurs plus basses signalent plus d’anomalies, tandis que des valeurs plus élevées signalent moins d’anomalies. -
covariate_col(optionnel) est unSTRINGou unARRAY<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 unSTRINGcontenant 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 unDATEouTIMESTAMPun 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. LorsqueTRUE, 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 queis_anomaly; il ne modifie pas les valeurs attendues, les bornes ou les scores d’anomalie. La valeur par défaut estTRUE.
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.