ai_detect_anomalies Función

Se aplica a: Databricks SQL

ai_detect_anomalies() es una función con valores de tabla que identifica valores anómalos en los datos de series temporales. Utiliza el historial previo a cada valor para estimar el valor esperado y el intervalo de predicción, y luego asigna una puntuación de anomalía.

Requisitos

• Un almacén SQL Pro o Serverless. Esta función no está disponible en un almacén SQL clásico.
• Inscribe tu espacio de trabajo en la vista previa de Funciones de IA Predictiva . Consulte Administrar versiones preliminares de Azure Databricks.

Syntax

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

Argumentos

• observed es la entrada con valores de tabla que contiene los datos de la serie temporal.
• time_col es una STRING columna que nombra a DATE o TIMESTAMP en observed. Las marcas temporales deben ser únicas dentro de cada serie temporal.
• value_col es nombrar STRING la columna numérica a analizar. Puedes analizar una columna de valor por invocación.
• group_col (opcional) es una STRING o una ARRAY<STRING> columna de nombres que identifica series temporales separadas. Cada grupo se analiza de forma independiente. Si se omite, la entrada completa se considera una serie temporal.
• anomaly_threshold (opcional) es un DOUBLE valor entre 0 y 1 que controla cuándo un valor se marca como anómalo. Una fila es anómala cuando es anomaly_score mayor que este umbral. El valor predeterminado es 0.95. Valores más bajos marcan más anomalías, mientras que valores más altos señalan menos anomalías.
• covariate_col (opcional) es una STRING o una ARRAY<STRING> columna numérica o de cadena cuyos valores pueden ayudar a explicar la serie temporal, como precio, promociones o clima.
• holiday_region (opcional) es un STRING que contiene un código de país, como 'US'. Cuando se especifica, la función tiene en cuenta los efectos festivos en los valores esperados.
• only_last_n (opcional) limita las filas devueltas y puntuadas, manteniendo las filas anteriores como contexto histórico. Especifique un entero del 1 al 8.192 para analizar solo el número más reciente de filas en cada serie, o especifique un DATE corte TIMESTAMP o para analizar filas en o después de ese valor. Limitar el rango de puntuación puede cambiar las puntuaciones de anomalías porque la función puede hacer menos predicciones en diferentes ventanas de pronóstico. Omite este argumento para analizar toda la serie.
• smoothing (opcional) controla si los breves intervalos entre anomalías se incluyen en el mismo episodio anómalo. Cuando TRUE, la función marca huecos de hasta tres filas entre anomalías marcadas como anómalas. Esto puede reducir episodios fragmentados de anomalías, pero también puede marcar valores normales dentro de esos huecos. El suavizado solo is_anomalycambia; no cambia los valores esperados, los límites ni las puntuaciones de anomalía. El valor predeterminado es TRUE.

Devoluciones

La función devuelve las columnas de tiempo, grupo y valor de entrada, seguidas de estas columnas:

Las primeras ocho filas de cada serie temporal proporcionan contexto histórico. Para estas filas, , , , y anomaly_score son NULL, y is_anomaly es FALSE. upper_boundlower_boundexpected

Examples

El siguiente ejemplo genera una serie temporal con un pico inyectado e identifica sus anomalías:

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

El siguiente ejemplo analiza cada dispositivo de forma independiente, tiene en cuenta la temperatura y los días festivos en Estados Unidos, y devuelve solo las 100 filas más recientes de cada serie de dispositivos:

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

Las siguientes limitaciones se aplican durante la Beta:

• Cada serie temporal puede contener como máximo 8.192 filas de entrada. Una consulta con una serie más larga falla.
• Cada serie temporal debe contener al menos un valor finito observado.
• Las marcas temporales deben ser únicas dentro de cada serie temporal.
• Puedes analizar una columna de valor por invocación.
• Los mensajes de error se entregan a través del motor Python UDTF y pueden contener información de rastreo en Python. El final del rastreo contiene el mensaje de error real.