Função ai_forecast

Aplica-se a: Databricks SQL

ai_forecast() é uma função com valores de tabela que extrapola os dados de séries temporais para a frente no tempo. Consulte Argumentos para obter argumentos disponíveis para configurar esta função.

A função tem duas versões. Um modelo de fundação de séries temporais otimizado para investigação alimenta a Versão 2 para melhorar a precisão pronta a usar, e a Versão 2 adiciona suporte para feriados, covariáveis externas e previsões não negativas. Use o version argumento para selecionar qual a versão que corre. Consulte Argumentos para mais detalhes.

Requisitos

• Armazém SQL Pro ou sem servidor
• Inscreva o seu espaço de trabalho na pré-visualização das Funções Preditivas de IA (obrigatório para a versão 2 recomendada). Ver Gerir as pré-visualizações de Azure Databricks.

Sintaxe

Versão 2 (recomendada)

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 (ver group_col) e até 100 métricas (ver value_col) em cada grupo. A frequência de previsão é a mesma para todas as métricas de um grupo, mas pode variar entre grupos (ver frequency).

Versão 2 (recomendada)

• observed é a entrada em formato de tabela que é usada como dados de treino para o procedimento de previsão.
  • Esta relação de entrada deve conter uma coluna de "tempo" e uma ou mais colunas de "valor". As colunas "Group" e "covariate" são opcionais. Todas as colunas adicionais na relação de entrada são ignoradas.
• horizon é uma quantidade associada ao tempo que representa o término do intervalo de tempo exclusivo à direita dos resultados da previsão. Dentro de um grupo (ver group_col) os resultados da previsão abrangem o tempo entre a última observação e o horizonte. Se o horizonte for menor do que o último tempo de observação, então nenhum resultado é gerado.
• time_col é uma cadeia que faz referência à "coluna de tempo" em observed. A coluna referenciada por time_col deve ser a DATE ou a TIMESTAMP.
• value_col é uma cadeia de caracteres ou uma matriz de cadeias de caracteres que fazem referência a colunas de valor em observed. As colunas referenciadas por este argumento devem ser lançadas para DOUBLE.
• group_col (opcional) é uma cadeia de caracteres ou uma matriz de cadeias de caracteres que representam as colunas do grupo em observed. Se especificado, as colunas de grupo são usadas como critérios de particionamento e as previsões são geradas para cada grupo de forma independente. Se não forem especificados, os dados de entrada completos são tratados como um único grupo.
• covariate_col (opcional) é uma cadeia ou um array de cadeias que referenciam colunas externas de covariadas em observed. As covariáveis são variáveis adicionais que influenciam a previsão, como o preço, o gasto em marketing ou o tempo. São suportados dois tipos de covariáveis:
  • Covariáveis futuras: os valores são conhecidos para o horizonte de previsão, como preços planeados ou campanhas agendadas. Para usar uma covariável desta forma, inclua-se linhas em observed que cobrem o horizonte de previsão (datas após a última observação, até horizon) com a covariável preenchida e a value_col (s) coluna(s) à esquerda NULL. ai_forecast prevê estas NULL-linhas alvo e condiciona a previsão pelos seus valores covariáveis.
  • Covariáveis apenas do passado: os valores são conhecidos apenas para o período histórico, como indicadores meteorológicos ou macroeconómicos observados. Preenche a covariada apenas em filas históricas. Se não fornecer valores de covariáveis ao longo do horizonte de previsão, ai_forecast usar a covariável apenas como passado; isto não é um erro.
• prediction_interval_width (opcional) é um valor entre 0 e 1 que representa a largura do intervalo de previsão. Os valores previstos têm uma prediction_interval_width probabilidade % de cair entre {v}_upper e {v}_lower.
• frequency (opcional) é uma cadeia de alias de deslocamento pandas (por exemplo, 'D', 'W', 'ME', 'H') que especifica a granularidade temporal dos resultados da previsão. Se não for especificado, a granularidade da previsão é automaticamente inferida para cada grupo de forma independente. Se especificado, deve corresponder à granularidade inferida dos dados de entrada dentro de cada grupo.
  • A frequência inferida dentro de um grupo é o modo das observações mais recentes. Esta inferência é uma operação de conveniência que não é ajustável pelo utilizador.
  • Por exemplo, uma série temporal com 99 "segundas-feiras" e 1 "terça-feira" resulta na frequência inferida da "semana".
• holiday_region (opcional) é um código de região que permite a modelação automática dos efeitos de feriados para essa região, como 'US'. Quando não especificado, não são modelados efeitos festivos.
• positive_only (opcional) quando definido para TRUE, restringe os valores previstos a serem não negativos. Use este argumento para métricas que não podem ser negativas, como vendas, contagens ou inventário. A predefinição é FALSE.
• version (opcional): Mudança de versão para suportar migração ('1' para comportamento da versão 1, '2' para comportamento da versão 2). Se não especificado, por defeito é a versão 1. Os argumentos da versão 2 (covariate_col, holiday_region, positive_only) requerem version => '2'.

Versão 1

• observed é a entrada em formato de tabela que é usada como dados de treino para o procedimento de previsão.
  • Esta relação de entrada deve conter uma coluna de "tempo" e uma ou mais colunas de "valor". As colunas "Group" e "parameters" são opcionais. Todas as colunas adicionais na relação de entrada são ignoradas.
• horizon é uma quantidade associada ao tempo que representa o término do intervalo de tempo exclusivo à direita dos resultados da previsão. Dentro de um grupo (ver group_col) os resultados da previsão abrangem o tempo entre a última observação e o horizonte. Se o horizonte for menor do que o último tempo de observação, então nenhum resultado é gerado.
• time_col é uma cadeia que faz referência à "coluna de tempo" em observed. A coluna referenciada por time_col deve ser a DATE ou a TIMESTAMP.
• value_col é uma cadeia de caracteres ou uma matriz de cadeias de caracteres que fazem referência a colunas de valor em observed. As colunas referenciadas por este argumento devem ser lançadas para DOUBLE.
• group_col (opcional) é uma cadeia de caracteres ou uma matriz de cadeias de caracteres que representam as colunas do grupo em observed. Se especificado, as colunas de grupo são usadas como critérios de particionamento e as previsões são geradas para cada grupo de forma independente. Se não forem especificados, os dados de entrada completos são tratados como um único grupo.
• prediction_interval_width (opcional) é um valor entre 0 e 1 que representa a largura do intervalo de previsã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 uma string de alias de deslocamento do pandas que especifica a granularidade temporal dos resultados da previsão. Se não for especificado, a granularidade da previsão é automaticamente inferida 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 dentro de um grupo é o modo das observações mais recentes. Esta inferência é uma operação de conveniência que não é ajustável pelo utilizador.
  • Por exemplo, uma série temporal com 99 "segundas-feiras" e 1 "terça-feira" resulta na frequência inferida da "semana".
• seed (opcional) é um número usado para iniciar quaisquer geradores de números pseudoaleatórios 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 suportados:
  • global_cap e global_floor podem ser usados juntos ou independentemente para definir o possível domínio dos valores métricos. {"global_floor": 0}, por exemplo, pode ser usado para restringir uma métrica como o custo a ser sempre positiva. Estas restrições aplicam-se globalmente aos dados de treino e aos dados previstos, e não podem ser usadas apenas para fornecer restrições apertadas sobre os valores previstos.
  • daily_order e weekly_order definem a ordem de Fourier para os componentes de sazonalidade diária e semanal.
• version (opcional): Mudança de versão para suportar migração ('1' para comportamento da versão 1, '2' para comportamento da versão 2). Se não especificado, por defeito é a versão 1. Os argumentos da versão 2 (covariate_col, holiday_region, positive_only) requerem version => '2'.

Devoluções

Versão 2 (recomendada)

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

A tabela seguinte mostra alguns exemplos da inferência de esquemas realizada por 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 os seus tipos inalterados. Por exemplo, se a coluna de tempo de entrada tem tipo DATE, então o tipo de coluna de tempo de saída também DATEé . Para cada coluna de valor, há três colunas de saída com o padrão {v}_forecast, {v}_uppere {v}_lower. Independentemente dos tipos de valor de entrada, as colunas de valor previsto são sempre tipo DOUBLE. A tabela de saída contém apenas os valores previstos, abrangendo o intervalo de tempo entre o fim dos dados observados e o horizonte.

A tabela seguinte mostra alguns exemplos da inferência de esquemas realizada por AI_FORECAST:

Exemplos

Versão 2 (recomendada)

O seguinte exemplo de previsões 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 seguinte exemplo modela os efeitos das férias para os Estados Unidos e limita 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 seguinte utiliza uma covariável externa. A observed tabela (daily_sales) inclui uma promotion coluna preenchida tanto para o período histórico como para o horizonte de previsão, com revenue a esquerda NULL nas linhas do horizonte de previsão, sendo promotion assim usada como covariável futura:

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'
)

Segue-se 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, é melhor prática unir valores em falta ou fornecer explicitamente um valor de frequência para evitar saídas inesperadas da inferência de frequência "automática". Por exemplo, a inferência de frequência "automática" em duas entradas separadas por 14 dias implica uma frequência de "14D", mesmo que a frequência "real" possa ser semanal com 1 valor em falta. A aglutinação das entradas em falta elimina esta ambiguidade.

O exemplo seguinte 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. Esta abordagem permite aos utilizadores armazenar JSONs de parâmetros previamente determinados numa tabela e reutilizá-los 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 (recomendada)

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

• A versão 2 está em Beta e não é a padrão. Para usar a versão 2, opte por definir version => '2'. A versão 1, que está em Pré-visualização Pública, mantém-se como padrão.
• O procedimento padrão de previsão é um modelo de fundação de séries temporais. Este modelo é o único procedimento de previsão suportado disponível.
• As mensagens de erro são entregues através do mecanismo UDTF do Python e contêm informações de rastreio do Python. O final do rastreio contém a mensagem de erro real.
• Cada invocação de ai_forecast realiza uma inferência independente. Se chamar ai_forecast várias vezes com valores diferentes prediction_interval_width para produzir intervalos de previsão aninhados, os intervalos resultantes não têm garantia de serem devidamente aninhados. Para comparar intervalos de previsão, use uma única ai_forecast chamada com um valor prediction_interval_width .

Versão 1

As seguintes limitações aplicam-se durante a Pré-visualização Pública:

• A versão 1 está em Pré-visualização Pública e é a versão padrão. A versão 2, que está em Beta, está disponível definindo version => '2'.
• A versão 1 está num caminho de descontinuação. Numa próxima versão, a versão padrão muda para a versão 2, e a versão 1 fica obsoleta. Para continuar a usar 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 por partes linear e sazonal, semelhante ao Prophet. Este modelo é o único procedimento de previsão suportado disponível.
• As mensagens de erro são entregues através do mecanismo UDTF do Python e contêm informações de rastreio do Python. O final do rastreio contém a mensagem de erro real.
• Cada invocação de ai_forecast realiza uma regressão quantil independente. Se chamar ai_forecast várias vezes com valores diferentes prediction_interval_width para produzir intervalos de previsão aninhados, os intervalos resultantes não têm garantia de serem devidamente aninhados porque os quantiles são calculados independentemente entre chamadas, sem qualquer restrição para verificar a ordem correta. Para comparar intervalos de previsão, use uma única ai_forecast chamada com um valor prediction_interval_width .