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. Ele usa o histórico que precede cada valor para estimar o valor esperado e o intervalo de previsão, depois atribui uma pontuação de anomalia.

Requisitos

• Um armazém SQL Pro ou Serverless. Essa função não está disponível em um warehouse SQL clássico.
• Inscreva seu espaço de trabalho na prévia de Funções de IA Preditiva . Consulte Gerenciar visualizações do Azure Databricks.

Sintaxe

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

Argumentos

• observed é a entrada de 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 de data devem ser únicos dentro de cada série temporal.
• value_col é um STRING nome da coluna numérica a ser analisada. Você pode analisar uma coluna de valor por invocação.
• group_col (opcional) é uma STRING ou uma ARRAY<STRING> coluna de nomes que identificam séries temporais separadas. Cada grupo é analisado de forma independente. Se omitido, a entrada completa é tratada como uma série temporal.
• anomaly_threshold (opcional) é um DOUBLE entre 0 e 1 que controla quando um valor é sinalizado como anômalo. Uma linha é anômala quando é anomaly_score maior que esse limiar. O padrão é 0.95. Valores mais baixos sinalizam 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 clima.
• holiday_region (opcional) é um STRING que contém um código de país, como 'US'. Quando especificado, a função leva em conta os efeitos de feriado nos valores esperados.
• only_last_n (opcional) limita as linhas retornadas 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 ou TIMESTAMP cutoff para analisar linhas iguais ou posteriores a esse valor. Limitar o intervalo de pontuação pode alterar as pontuações de anomalia porque a função pode fazer menos previsões em diferentes janelas de previsão. Omita esse 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. Isso pode reduzir episódios de anomalias fragmentadas, mas também pode sinalizar valores normais dentro desses intervalos. A suavização muda apenas is_anomaly; ela não altera valores esperados, limites ou pontuações de anomalia. O padrão é TRUE.

Returns

A função retorna 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 essas linhas, , , , e anomaly_score são NULL, e is_anomaly é FALSE. upper_boundlower_boundexpected

Exemplos

O exemplo a seguir gera uma série temporal com um pico injetado e identifica 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 a seguir analisa cada dispositivo de forma independente, leva em conta temperatura e feriados dos Estados Unidos, e retorna 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

Limitações

As seguintes limitações se aplicam durante a versão 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 de data devem ser únicos dentro de cada série temporal.
• Você pode analisar uma coluna de valor por invocação.
• Mensagens de erro são entregues pelo motor Python UDTF e podem conter informações de rastreamento em Python. O final do rastreamento contém a mensagem de erro real.