Função ai_forecast

Aplica-se a: Databricks SQL

ai_forecast() é uma função com valor de tabela que extrapola dados de série temporal no tempo. Consulte Argumentos para saber os argumentos disponíveis para configurar essa função.

A função tem duas versões. Um modelo de base de série temporal com otimização de pesquisa alimenta a versão 2 para melhorar a precisão pronta para uso, e a versão 2 adiciona suporte para feriados, covariados externos e previsões não negativas. Use o version argumento para selecionar qual versão é executada. Consulte argumentos para obter detalhes.

Requisitos

• SQL Warehouse Pro ou Sem Servidor
• Registre seu workspace na versão prévia do Predictive AI Functions (obrigatório para a versão 2 recomendada). Consulte Gerenciar visualizações do Azure Databricks.

Sintaxe

Versão 2 (recomendado)

ai_forecast(observed, horizon, time_col, value_col
  [, group_col] [, covariate_col] [, prediction_interval_width]
  [, frequency] [, holiday_region] [, positive_only] [, version])

Versão 1

ai_forecast(observed, horizon, time_col, value_col
  [, group_col] [, prediction_interval_width] [, frequency]
  [, seed] [, parameters] [, version])

Argumentos

ai_forecast() pode prever qualquer número de grupos (consulte group_col) e até 100 métricas (consulte value_col) dentro de cada grupo. A frequência de previsão é a mesma para todas as métricas em um grupo, mas pode ser diferente entre grupos (consulte frequency).

Versão 2 (recomendado)

• observed é a entrada com valor de tabela que é usada como dados de treinamento para o procedimento de previsão.
  • Essa relação de entrada deve conter uma coluna "time" e uma ou mais colunas de "valor". As colunas "Agrupar" e "covariar" são opcionais. Quaisquer colunas adicionais na relação de entrada são ignoradas.
• horizon é uma quantidade de carimbo de data/hora que representa a hora de término exclusiva à direita dos resultados da previsão. Dentro de um grupo (veja group_col), os resultados da previsão abrangem o tempo entre a última observação e o horizonte. Se o horizonte for menor que o último tempo de observação, nenhum resultado será gerado.
• time_col é uma cadeia de caracteres que faz referência à "coluna de tempo" em observed. A coluna referenciada por time_col deve ser um DATE ou um TIMESTAMP.
• value_col é uma cadeia de caracteres ou uma matriz de strings que faz referência a colunas de valor em observed. As colunas referenciadas por esse argumento devem ser castráveis para DOUBLE.
• group_col (opcional) é uma string ou uma matriz de strings que representa as colunas do grupo em observed. Se especificado, as colunas de grupo serão usadas como critérios de particionamento e as previsões serão geradas para cada grupo de forma independente. Se não for especificado, todos os dados de entrada serão tratados como um único grupo.
• covariate_col (opcional) é uma cadeia de caracteres ou uma matriz de cadeias de caracteres que fazem referência a colunas covariadas externas em observed. Covariados são variáveis adicionais que influenciam a previsão, como preço, gastos de marketing ou clima. Há suporte para dois tipos de covariados:
  • Covariados futuros: os valores são conhecidos pelo horizonte de previsão, como preços planejados ou campanhas agendadas. Para usar um covariado dessa forma, inclua linhas observed que abrangem o horizonte de previsão (datas após a última observação, até horizon) com o covariado preenchido e as value_col colunas esquerdas NULL. ai_forecast prevê essas NULLlinhas de destino e condiciona a previsão em seus valores covariados.
  • Covariados somente anteriores: os valores são conhecidos apenas pelo período histórico, como indicadores meteorológicos ou macroeconômicos observados. Preencha o covariado apenas em linhas históricas. Se você não fornecer valores covariados no horizonte de previsão, ai_forecast usará o covariado como somente anterior; isso não é um erro.
• prediction_interval_width (opcional) é um valor entre 0 e 1 que representa a largura do intervalo de predição. Os valores previstos têm uma prediction_interval_width probabilidade % de cair entre {v}_upper e {v}_lower.
• frequency (opcional) é uma cadeia de caracteres de alias de deslocamento pandas (por exemplo, 'D', 'W', 'ME', ) 'H'especificando a granularidade de tempo dos resultados da previsão. Se não for especificado, a granularidade da previsão será inferida automaticamente para cada grupo de forma independente. Se especificado, ele deve corresponder à granularidade inferida dos dados de entrada em cada grupo.
  • A frequência inferida em um grupo é determinada pela moda das observações mais recentes. Essa inferência é uma operação de conveniência que não é ajustável pelo usuário.
  • Por exemplo, uma série temporal com 99 "segundas- feiras" e 1 "terça-feira" resulta na "semana" sendo a frequência inferida.
• holiday_region (opcional) é um código de região que permite a modelagem automática de efeitos de feriados para essa região, como 'US'. Quando não for especificado, nenhum efeito de feriado será modelado.
• positive_only (opcional) quando definido como TRUE, restringe os valores previstos como não negativos. Use esse argumento para métricas que não podem ser negativas, como vendas, contagens ou inventário. O padrão é FALSE.
• version (opcional): opção de versão para dar suporte à migração ('1' para o comportamento da versão 1, '2' para o comportamento da versão 2). Se não for especificado, o padrão será a versão 1. Os argumentos da versão 2 (covariate_col, holiday_region, positive_only) exigem version => '2'.

Versão 1

• observed é a entrada com valor de tabela que é usada como dados de treinamento para o procedimento de previsão.
  • Essa relação de entrada deve conter uma coluna "time" e uma ou mais colunas de "valor". As colunas "Agrupar" e "parâmetros" são opcionais. Quaisquer colunas adicionais na relação de entrada são ignoradas.
• horizon é uma quantidade de carimbo de data/hora que representa a hora de término exclusiva à direita dos resultados da previsão. Dentro de um grupo (veja group_col), os resultados da previsão abrangem o tempo entre a última observação e o horizonte. Se o horizonte for menor que o último tempo de observação, nenhum resultado será gerado.
• time_col é uma cadeia de caracteres que faz referência à "coluna de tempo" em observed. A coluna referenciada por time_col deve ser um DATE ou um TIMESTAMP.
• value_col é uma cadeia de caracteres ou uma matriz de strings que faz referência a colunas de valor em observed. As colunas referenciadas por esse argumento devem ser castráveis para DOUBLE.
• group_col (opcional) é uma string ou uma matriz de strings que representa as colunas do grupo em observed. Se especificado, as colunas de grupo serão usadas como critérios de particionamento e as previsões serão geradas para cada grupo de forma independente. Se não for especificado, todos os dados de entrada serão tratados como um único grupo.
• prediction_interval_width (opcional) é um valor entre 0 e 1 que representa a largura do intervalo de predição. Os valores previstos têm uma prediction_interval_width probabilidade % de cair entre {v}_upper e {v}_lower.
• frequency (opcional) é uma unidade de tempo ou cadeia de caracteres de alias de deslocamento pandas que especifica a granularidade da previsão. Se não for especificado, a granularidade da previsão será inferida automaticamente para cada grupo de forma independente. Se um valor de frequência for especificado, ele será aplicado igualmente a todos os grupos.
  • A frequência inferida em um grupo é determinada pela moda das observações mais recentes. Essa inferência é uma operação de conveniência que não é ajustável pelo usuário.
  • Por exemplo, uma série temporal com 99 "segundas- feiras" e 1 "terça-feira" resulta na "semana" sendo a frequência inferida.
• seed (opcional) é um número usado para iniciar os geradores de número de pseudorandom usados no procedimento de previsão.
• parameters (opcional) é um JSON codificado em cadeia de caracteres ou o nome de um identificador de coluna que representa a parametrização do procedimento de previsão. Qualquer combinação de parâmetros pode ser especificada em qualquer ordem, por exemplo, {"weekly_order": 10, "global_cap": 1000}. Quaisquer parâmetros não especificados são determinados automaticamente com base nos atributos dos dados de treinamento. Os seguintes parâmetros são compatíveis:
  • global_cap e global_floor podem ser usados ​​em conjunto ou independentemente para definir o domínio possível dos valores métricos. {"global_floor": 0}, por exemplo, pode ser usado para restringir uma métrica como o custo a ser sempre positiva. Essas restrições se aplicam globalmente aos dados de treinamento e aos dados previstos e não podem ser usadas para fornecer restrições rígidas apenas aos valores previstos.
  • daily_order e weekly_order definem a ordem de Fourier dos componentes de sazonalidade diária e semanal.
• version (opcional): opção de versão para dar suporte à migração ('1' para o comportamento da versão 1, '2' para o comportamento da versão 2). Se não for especificado, o padrão será a versão 1. Os argumentos da versão 2 (covariate_col, holiday_region, positive_only) exigem version => '2'.

Devoluções

Versão 2 (recomendado)

Um novo conjunto de linhas contendo os dados previstos. O esquema de saída contém as colunas de tempo e grupo com seus tipos inalterados. Por exemplo, se a coluna de tempo de entrada tiver tipo DATE, o tipo de coluna de tempo de saída também DATEserá . Para cada coluna de valor existem três colunas de saída com o padrão {v}_forecast, {v}_upper, e {v}_lower. Independentemente dos tipos de valores de entrada, as colunas de valores previstos são sempre do tipo DOUBLE. A tabela de saída contém apenas valores previstos, abrangendo o intervalo de tempo entre o final dos dados observados até o horizonte.

A tabela a seguir mostra alguns exemplos da inferência de esquema executada pelo AI_FORECAST:

Versão 1

Um novo conjunto de linhas contendo os dados previstos. O esquema de saída contém as colunas de tempo e grupo com seus tipos inalterados. Por exemplo, se a coluna de tempo de entrada tiver tipo DATE, o tipo de coluna de tempo de saída também DATEserá . Para cada coluna de valor existem três colunas de saída com o padrão {v}_forecast, {v}_upper, e {v}_lower. Independentemente dos tipos de valores de entrada, as colunas de valores previstos são sempre do tipo DOUBLE. A tabela de saída contém apenas valores previstos, abrangendo o intervalo de tempo entre o final dos dados observados até o horizonte.

A tabela a seguir mostra alguns exemplos da inferência de esquema executada pelo AI_FORECAST:

Exemplos

Versão 2 (recomendado)

O exemplo a seguir prevê até uma data especificada usando a versão 2:

WITH
aggregated AS (
  SELECT
    DATE(tpep_pickup_datetime) AS ds,
    SUM(fare_amount) AS revenue
  FROM
    samples.nyctaxi.trips
  GROUP BY
    1
)
SELECT * FROM AI_FORECAST(
  TABLE(aggregated),
  horizon => '2016-03-31',
  time_col => 'ds',
  value_col => 'revenue',
  version => '2'
)

O exemplo a seguir modela efeitos de feriado para o Estados Unidos e restringe a previsão a valores não negativos:

WITH
aggregated AS (
  SELECT
    DATE(tpep_pickup_datetime) AS ds,
    SUM(fare_amount) AS revenue
  FROM
    samples.nyctaxi.trips
  GROUP BY
    1
)
SELECT * FROM AI_FORECAST(
  TABLE(aggregated),
  horizon => '2016-03-31',
  time_col => 'ds',
  value_col => 'revenue',
  holiday_region => 'US',
  positive_only => true,
  version => '2'
)

O exemplo a seguir usa um covariado externo. A observed tabela (daily_sales) inclui uma promotion coluna preenchida para o período histórico e o horizonte de previsão, com revenue esquerda NULL nas linhas do horizonte de previsão, portanto promotion , é usada como um futuro covariado:

SELECT * FROM AI_FORECAST(
  TABLE(daily_sales),
  horizon => '2016-03-31',
  time_col => 'ds',
  value_col => 'revenue',
  covariate_col => 'promotion',
  version => '2'
)

Versão 1

O exemplo a seguir prevê até uma data especificada:

WITH
aggregated AS (
  SELECT
    DATE(tpep_pickup_datetime) AS ds,
    SUM(fare_amount) AS revenue
  FROM
    samples.nyctaxi.trips
  GROUP BY
    1
)
SELECT * FROM AI_FORECAST(
  TABLE(aggregated),
  horizon => '2016-03-31',
  time_col => 'ds',
  value_col => 'revenue'
)

O seguinte é um exemplo mais complexo:

WITH
aggregated AS (
  SELECT
    DATE(tpep_pickup_datetime) AS ds,
    dropoff_zip,
    SUM(fare_amount) AS revenue,
    COUNT(*) AS n_trips
  FROM
    samples.nyctaxi.trips
  GROUP BY
    1, 2
),
spine AS (
  SELECT all_dates.ds, all_zipcodes.dropoff_zip
  FROM (SELECT DISTINCT ds FROM aggregated) all_dates
  CROSS JOIN (SELECT DISTINCT dropoff_zip FROM aggregated) all_zipcodes
)
SELECT * FROM AI_FORECAST(
  TABLE(
    SELECT
      spine.*,
      COALESCE(aggregated.revenue, 0) AS revenue,
      COALESCE(aggregated.n_trips, 0) AS n_trips
    FROM spine LEFT JOIN aggregated USING (ds, dropoff_zip)
  ),
  horizon => '2016-03-31',
  time_col => 'ds',
  value_col => ARRAY('revenue', 'n_trips'),
  group_col => 'dropoff_zip',
  prediction_interval_width => 0.9,
  parameters => '{"global_floor": 0}'
)

Para dados esparsos, é uma prática recomendada unir valores ausentes ou fornecer um valor de frequência explicitamente para evitar uma saída inesperada da inferência de frequência "automática". Por exemplo, a inferência de frequência "automática" em duas entradas com 14 dias de diferença infere uma frequência de "14D", mesmo que a frequência "real" possa ser semanal com um valor ausente. A união das entradas ausentes elimina essa ambigüidade.

O exemplo a seguir mostra como diferentes parâmetros de previsão são aplicados a diferentes grupos na tabela de entrada. O exemplo usa o argumento parameters como um identificador de coluna. Essa abordagem permite que os usuários armazenem JSONs de parâmetro determinados anteriormente em uma tabela e os reutilizem em novos dados.

WITH past AS (
  SELECT
    CASE
      WHEN fare_amount < 30 THEN 'Under $30'
      ELSE '$30 or more'
    END AS revenue_bucket,
    CASE
      WHEN fare_amount < 30 THEN '{"daily_order": 0}'
      ELSE '{"daily_order": "auto"}'
    END AS parameters,
    DATE(tpep_pickup_datetime) AS ds,
    SUM(fare_amount) AS revenue
  FROM samples.nyctaxi.trips
  GROUP BY ALL
)
SELECT * FROM AI_FORECAST(
  TABLE(past),
  horizon => (SELECT MAX(ds) + INTERVAL 30 DAYS FROM past),
  time_col => 'ds',
  value_col => 'revenue',
  group_col => ARRAY('revenue_bucket'),
  parameters => 'parameters'
)

Limitações

Versão 2 (recomendado)

As seguintes limitações se aplicam durante o Beta:

• A versão 2 está em Beta e não é o padrão. Para usar a versão 2, opte por definir version => '2'. A versão 1, que está em Versão Prévia Pública, continua sendo o padrão.
• O procedimento de previsão padrão é um modelo de base de série temporal. Esse modelo é o único procedimento de previsão com suporte disponível.
• As mensagens de erro são entregues pelo mecanismo UDTF do Python e contêm informações de rastreamento do Python. O final do rastreamento contém a mensagem de erro real.
• Cada invocação de ai_forecast executa uma inferência independente. Se você chamar ai_forecast várias vezes com valores diferentes prediction_interval_width para produzir intervalos de previsão aninhados, os intervalos resultantes não deverão ser aninhados corretamente. Para comparar intervalos de previsão, use uma única ai_forecast chamada com um prediction_interval_width valor.

Versão 1

As seguintes limitações se aplicam durante a Visualização Pública:

• A versão 1 está em Versão Prévia Pública e é a versão padrão. A versão 2, que está em Beta, está disponível por meio da configuração version => '2'.
• A versão 1 está em um caminho de substituição. Em uma versão futura, a versão padrão muda para a versão 2 e a versão 1 é preterida. Para continuar usando o comportamento da versão 1 após as alterações padrão, fixe-o definindo version => '1'.
• O procedimento de previsão padrão é um modelo linear por partes e sazonal, semelhante ao modelo Prophet. Esse modelo é o único procedimento de previsão com suporte disponível.
• As mensagens de erro são entregues pelo mecanismo UDTF do Python e contêm informações de rastreamento do Python. O final do rastreamento contém a mensagem de erro real.
• Cada invocação de ai_forecast executa uma regressão de quantile independente. Se você chamar ai_forecast várias vezes com valores diferentes prediction_interval_width para produzir intervalos de previsão aninhados, os intervalos resultantes não deverão ser aninhados corretamente porque os quantiles são computados independentemente entre chamadas, sem nenhuma restrição para verificar a ordenação adequada. Para comparar intervalos de previsão, use uma única ai_forecast chamada com um prediction_interval_width valor.