ai_detect_anomalies Função

Aplica-se a: Databricks SQL

ai_detect_anomalies() é uma função com valores de tabela que identifica valores anómalos em dados de séries temporais. Utiliza o histórico anterior a cada valor para estimar o valor esperado e o intervalo de previsão, atribuindo depois uma pontuação de anomalia.

Requisitos

• Um armazém SQL Pro ou Serverless. Esta função não está disponível num armazém SQL clássico.
• Inscreva o seu espaço de trabalho na pré-visualização de Funções Preditivas de IA . Ver Gerir as pré-visualizações 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 é a entrada com valores de tabela que contém os dados da série temporal.
• time_col é uma STRING coluna que nomeia a DATE ou TIMESTAMP em observed. Os carimbos temporais devem ser únicos dentro de cada série temporal.
• value_col é um STRING nome da coluna numérica a analisar. Podes analisar uma coluna de valor por invocação.
• group_col (opcional) é a STRING ou uma ARRAY<STRING> coluna de nomes que identifica séries temporais separadas. Cada grupo é analisado de forma independente. Se for omitido, a entrada completa é tratada como uma série temporal única.
• anomaly_threshold (opcional) é um DOUBLE entre 0 e 1 que controla quando um valor é assinalado como anómalo. Uma linha é anómala quando é anomaly_score superior a este limiar. A predefinição é 0.95. Valores mais baixos assinalam mais anomalias, enquanto valores mais altos sinalizam menos anomalias.
• covariate_col (opcional) é a STRING ou um ARRAY<STRING> nome de colunas numéricas ou de cadeia cujos valores podem ajudar a explicar a série temporal, como preço, promoções ou tempo.
• holiday_region (opcional) é um STRING que contém um código de país, como 'US'. Quando especificado, a função tem em conta os efeitos de feriado nos valores esperados.
• only_last_n (opcional) limita as linhas devolvidas e pontuadas, mantendo as linhas anteriores como contexto histórico. Especifique um inteiro de 1 a 8.192 para analisar apenas o número mais recente de linhas em cada série, ou especifique um DATE corte TIMESTAMP ou para analisar linhas iguais ou posteriores a esse valor. Limitar o intervalo de pontuação pode alterar as pontuações das anomalias porque a função pode fazer menos previsões em diferentes janelas de previsão. Omita este argumento para analisar a série completa.
• smoothing (opcional) controla se pequenos intervalos entre anomalias estão incluídos no mesmo episódio anómalo. Quando TRUE, a função marca lacunas de até três linhas entre anomalias sinalizadas como anómalas. Isto pode reduzir episódios de anomalias fragmentadas, mas também pode sinalizar valores normais dentro desses intervalos. A suavização apenas is_anomalyaltera ; não altera valores esperados, limites ou pontuações de anomalias. A predefinição é TRUE.

Devoluções

A função devolve as colunas de tempo, grupo e valor de entrada, seguidas por estas colunas:

As primeiras oito linhas de cada série temporal fornecem contexto histórico. Para estas linhas, , , , e anomaly_score são NULL, e is_anomaly é FALSE. upper_boundlower_boundexpected

Exemplos

O exemplo seguinte gera uma série temporal com um pico injetado e identifica as suas anomalias:

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

O exemplo seguinte analisa cada dispositivo de forma independente, tem em conta a temperatura e os feriados dos Estados Unidos, e apresenta apenas as 100 linhas mais recentes de cada série 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

As seguintes limitações aplicam-se durante a Beta:

• Cada série temporal pode conter no máximo 8.192 linhas de entrada. Uma consulta com uma série mais longa falha.
• Cada série temporal deve conter pelo menos um valor finito observado.
• Os carimbos temporais devem ser únicos dentro de cada série temporal.
• Podes analisar uma coluna de valor por invocação.
• As mensagens de erro são entregues através do motor Python UDTF e podem conter informação de rastreamento em Python. O final do rastreio contém a mensagem de erro real.