Função ai_forecast

Aplica-se a: Databricks SQL

ai_forecast() é uma função com valor de tabela projetada para extrapolar dados de séries temporais para o futuro. Consulte Argumentos para obter argumentos disponíveis para configurar esta função.

Necessidade

Armazém SQL Pro ou sem servidor

Sintaxe

ai_forecast(
  observed TABLE,
  horizon DATE | TIMESTAMP | STRING,
  time_col STRING,
  value_col STRING | ARRAY<STRING>,
  group_col STRING | ARRAY<STRING> | NULL DEFAULT NULL,
  prediction_interval_width DOUBLE DEFAULT 0.95,
  frequency STRING DEFAULT 'auto',
  seed INTEGER | NULL DEFAULT NULL,
  parameters STRING DEFAULT '{}'
)

Argumentos

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

Os seguintes argumentos estão disponíveis para esta função:

• observed é a entrada com valor de tabela que é usada como dados de treinamento para o procedimento de previsão.
  • Esta relação de entrada deve conter uma coluna "tempo" e uma ou mais colunas "valor". As colunas "Grupo" e "parâmetros" são opcionais. Todas as colunas adicionais na relação de entrada são ignoradas.
• horizon é uma quantidade passível de carimbo de data/hora que representa a hora de término exclusiva 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 de caracteres 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 convertidas em 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 futuros 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 de tempo 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 é uma operação de conveniência que não é ajustável pelo usuário.
  • Como 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 inicializar 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 pode ser usado em conjunto ou de forma independente 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. Estes aplicam-se globalmente aos dados de formação e aos dados previstos, e não podem ser utilizados para fornecer restrições apertadas apenas aos valores previstos.
  • daily_order e weekly_order definir a ordem fourier dos componentes de sazonalidade diária e semanal.

Devoluções

Um novo conjunto de linhas contendo os dados previstos. O esquema de saída conterá as colunas de tempo e grupo com seus tipos inalterados. Por exemplo, se a coluna de tempo de entrada tiver tipo DATE, então o tipo de coluna de tempo de saída também será 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 do tipo DOUBLE. A tabela de saída contém apenas valores futuros, abrangendo o intervalo de tempo entre o final dos dados observados até o horizonte.

Veja alguns exemplos da inferência de esquema realizada por AI_FORECAST abaixo:

Exemplos

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

Note que é muito comum que as tabelas não materializem 0s ou entradas vazias. Se os valores das entradas ausentes podem ser inferidos, por exemplo 0, então esses valores devem ser aglutinados antes de chamar a função de previsão. Se os valores estiverem realmente ausentes ou desconhecidos, eles podem ser deixados como NULL.

Para dados muito esparsos, é uma prática recomendada aglutinar valores ausentes ou fornecer um valor de frequência explicitamente para evitar saídas inesperadas da inferência de frequência "automática". Como exemplo, a inferência de frequência "automática" em duas entradas com 14 dias de intervalo inferirá uma frequência de "14D", mesmo que a frequência "real" possa ser semanal com 1 valor ausente. A aglutinação das entradas em falta elimina esta ambiguidade.

Finalmente, mostramos um exemplo em que diferentes parâmetros de previsão são aplicados a diferentes grupos na tabela de entrada:

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

Observe o uso de um identificador de coluna como parameters argumento. Isso permite que os usuários armazenem JSONs de parâmetros determinados anteriormente em uma tabela e os reutilizem em novos dados.

Limitações

As seguintes limitações aplicam-se durante a pré-visualização:

• O procedimento de previsão padrão é um modelo linear e sazonal semelhante a um profeta. Este é 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.