FORECAST

Nome completo: SNOWFLAKE.ML.FORECAST

Um modelo de previsão produz uma previsão para uma única série temporal ou para várias séries temporais. Você usa CREATE SNOWFLAKE.ML.FORECAST para criar treinar o modelo de previsão e depois usa o método <nome>!FORECAST do modelo para produzir previsões. O método <nome>!EXPLAIN_FEATURE_IMPORTANCE fornece informações sobre como cada recurso nos dados de treinamento influencia a previsão. O método <nome>!SHOW_TRAINING_LOGS fornece mensagens de erro para qualquer série temporal cujos modelos não foram ajustados. O método Exemplos fornece métricas de avaliação em dados fora da amostra.

Importante

Aviso legal. Esta função baseada em ML do Snowflake Cortex é alimentada por tecnologia de aprendizado de máquina. A tecnologia de aprendizado de máquina e os resultados fornecidos podem ser imprecisos, inadequados ou tendenciosos. As decisões baseadas em resultados de aprendizado de máquina, incluindo aquelas incorporadas em pipelines automáticos, devem ter supervisão humana e processos de revisão para garantir que o conteúdo gerado pelo modelo seja preciso. As consultas de função baseadas em ML do Snowflake Cortex serão tratadas como qualquer outra consulta SQL e podem ser consideradas metadados.

Metadados. Quando você usa funções baseadas em ML do Snowflake Cortex, o Snowflake registra mensagens de erro genéricas retornadas por uma função ML, além do que é mencionado em campos de metadados. Esses logs de erros nos ajudam a solucionar problemas que surgem e a melhorar essas funções para melhor atender você.

Para obter mais informações, consulte FAQ sobre confiança e segurança do Snowflake AI.

CREATE SNOWFLAKE.ML.FORECAST

Cria um novo modelo de previsão a partir dos dados de treinamento fornecidos ou substitui o modelo de previsão com o mesmo nome.

Sintaxe

CREATE [ OR REPLACE ] SNOWFLAKE.ML.FORECAST [ IF NOT EXISTS ] <name>(
  INPUT_DATA => <input_data>,
  [ SERIES_COLNAME => '<series_colname>', ]
  TIMESTAMP_COLNAME => '<timestamp_colname>',
  TARGET_COLNAME => '<target_colname>',
  [ CONFIG_OBJECT => <config_object> ]
)
[ [ WITH ] TAG ( <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' , ... ] ) ]
[ COMMENT = '<string_literal>' ]
Copy

Nota

O uso de argumentos nomeados torna a ordem dos argumentos irrelevante e resulta em um código mais legível. No entanto, você também pode usar argumentos posicionais, como no exemplo a seguir:

CREATE SNOWFLAKE.ML.FORECAST <name>(
  '<input_data>', '<series_colname>', '<timestamp_colname>', '<target_colname>'
);
Copy

Parâmetros

name

Especifica o identificador do modelo; deve ser único para o esquema no qual o modelo é criado.

Se o identificador do modelo não estiver totalmente qualificado (na forma de db_name.schema_name.name ou schema_name.name), o comando cria o modelo no esquema atual para a sessão.

Além disso, o identificador deve começar com um caractere alfabético e não pode conter espaços ou caracteres especiais, a menos que toda a cadeia de caracteres do identificador esteja entre aspas duplas (por exemplo, "My object"). Os identificadores delimitados por aspas duplas também diferenciam letras maiúsculas de minúsculas.

Para obter mais detalhes, consulte Requisitos para identificadores.

Argumentos do construtor

Obrigatório:

INPUT_DATA => input_data

Uma referência aos dados de entrada. O uso de uma referência permite que o processo de treinamento, executado com privilégios limitados, use seus privilégios para acessar os dados. Você pode usar uma referência a uma tabela ou exibição se seus dados já estiverem nessa forma ou pode usar uma referência de consulta para fornecer a consulta a ser executada para obter os dados.

Os dados referenciados são todos os dados de treinamento consumidos pelo modelo de previsão. Se input_data contiver qualquer coluna que não seja nomeada como timestamp_colname, target_colname ou series_colname, são consideradas variáveis exógenas (recursos adicionais). A ordem das colunas nos dados de entrada não é importante.

Seus dados de entrada devem ter colunas com tipos apropriados para seu caso de uso. Consulte Exemplos para obter detalhes sobre cada caso de uso.

Caso de uso

Colunas e tipos

Série temporal única

Série temporal múltipla

  • Coluna da série: VARIANT contendo valores numéricos e texto.

  • Coluna de carimbo de data/hora: TIMESTAMP_NTZ.

  • Coluna de valor de destino: FLOAT.

Série temporal única com variáveis exógenas

Série temporal múltipla com variáveis exógenas

  • Coluna da série: VARIANT contendo valores numéricos e texto.

  • Coluna de carimbo de data/hora: TIMESTAMP_NTZ.

  • Coluna de valor de destino: FLOAT.

  • Colunas de recurso exógeno: numérico ou texto.

TIMESTAMP_COLNAME => 'timestamp_colname'

Nome da coluna que contém os carimbos de data/hora em input_data.

TARGET_COLNAME => 'target_colname'

Nome da coluna que contém o destino (valor dependente) em input_data.

Opcional:

SERIES_COLNAME => 'series_colname'

Para modelos de séries temporais múltiplas, o nome da coluna que define as séries temporais múltiplas em input_data. Esta coluna pode ser um valor de qualquer tipo ou uma matriz de valores de uma ou mais colunas, conforme mostrado em Previsão em séries múltiplas.

Se você estiver fornecendo argumentos posicionalmente, este deve ser o segundo argumento.

CONFIG_OBJECT => config_object

Um OBJECT contendo pares chave-valor usados para configurar a tarefa de treinamento do modelo.

Chave

Tipo

Padrão

Descrição

on_error

STRING

'ABORT'

Cadeia de caracteres (constante) que especifica o método de tratamento de erros para a tarefa de treinamento do modelo. Isto é mais útil ao treinar múltiplas séries. Os valores suportados são:

  • 'abort': anula a operação de treinamento se um erro for encontrado em qualquer série temporal.

  • 'skip': ignore qualquer série temporal em que o treinamento encontre um erro. Isso permite que o treinamento do modelo seja bem-sucedido para outras séries temporais. Para ver quais séries falharam, use o método <nome>!SHOW_TRAINING_LOGS do modelo.

evaluate

BOOLEAN

TRUE

Se as métricas de avaliação devem ser geradas. Se TRUE, modelos adicionais serão treinados para validação cruzada usando os parâmetros em evaluation_config.

evaluation_config

OBJECT

Consulte Configuração de avaliação abaixo.

Um objeto de configuração opcional para especificar como as métricas de avaliação fora da amostra devem ser geradas.

Configuração de avaliação

O objeto evaluation_config contém pares chave-valor que configuram a validação cruzada. Esses parâmetros são do TimeSeriesSplit do scikit-learn.

Chave

Tipo

Padrão

Descrição

n_splits

INTEGER

5

Número de divisões.

max_train_size

INTEGER ou NULL (no máximo).

NULL

Tamanho máximo para um único conjunto de treinamento.

test_size

INTEGER ou NULL.

NULL

Usado para limitar o tamanho do conjunto de teste.

gap

INTEGER

0

Número de amostras a serem excluídas do fim de cada conjunto de treinamento antes do conjunto de teste.

prediction_interval

FLOAT

0,95

O intervalo de previsão usado no cálculo de métricas de intervalo.

Notas de uso

A replicação de instâncias de classe não é suportada atualmente.

SHOW SNOWFLAKE.ML.FORECAST

Lista todos os modelos de previsão.

Sintaxe

SHOW SNOWFLAKE.ML.FORECAST [ LIKE <pattern> ]
  [ IN
      {
        ACCOUNT                  |

        DATABASE                 |
        DATABASE <database_name> |

        SCHEMA                   |
        SCHEMA <schema_name>     |
        <schema_name>
      }
   ]
Copy

Parâmetros

LIKE 'pattern'

Opcionalmente, filtra a saída do comando pelo nome do objeto. O filtro utiliza correspondência de padrão que não diferencia maiúsculas e minúsculas, com suporte para caracteres curinga SQL (% e _).

Por exemplo, os seguintes padrões retornam os mesmos resultados:

... LIKE '%testing%' ...
... LIKE '%TESTING%' ...

. padrão: sem valor (nenhuma filtragem é aplicada à saída).

[ IN ... ]

Opcionalmente, especifica o escopo do comando. Especifique um dos seguintes:

ACCOUNT

Retorna registros para toda a conta.

DATABASE, . DATABASE db_name

Retorna registros do banco de dados atual em uso ou de um banco de dados especificado (db_name).

Se você especificar DATABASE sem db_name e nenhum banco de dados estiver em uso, a palavra-chave não terá efeito sobre a saída.

SCHEMA, . SCHEMA schema_name, . schema_name

Retorna registros do esquema atual em uso ou de um esquema especificado (schema_name).

SCHEMA é opcional se um banco de dados estiver em uso ou se você especificar o schema_name totalmente qualificado (por exemplo, db.schema).

Se nenhum banco de dados estiver em uso, a especificação SCHEMA não terá efeito sobre a saída.

Padrão: depende se a sessão tem ou não um banco de dados em uso no momento:

  • Banco de dados: DATABASE é o padrão (ou seja, o comando retorna os objetos nos quais você tem privilégios para visualizar no banco de dados).

  • Sem banco de dados: ACCOUNT é o padrão (ou seja, o comando retorna os objetos que você tem privilégios de visualização em sua conta).

Saída

A saída do comando fornece propriedades de modelo e metadados nas colunas a seguir:

Coluna

Descrição

criado_em

Data e hora em que o modelo foi criado

nome

Nome do modelo

nome_do_banco_de_dados

Banco de dados no qual o modelo está armazenado

nome_do_esquema

Esquema no qual o modelo está armazenado

versão_atual

A versão do algoritmo do modelo

comentário

Comentário para o modelo

proprietário

Nome da função proprietária do modelo

DROP SNOWFLAKE.ML.FORECAST

Remove o modelo especificado do esquema atual ou especificado. Os modelos descartados não podem ser recuperados; eles devem ser recriados.

Sintaxe

DROP SNOWFLAKE.ML.FORECAST [ IF EXISTS ] <name>;
Copy

Parâmetros

name

Especifica o identificador do modelo a ser descartado. Se o identificador contiver espaços, caracteres especiais ou caracteres com letras maiúsculas e minúsculas, toda a cadeia de caracteres deve ser delimitada por aspas duplas. Os identificadores delimitados por aspas duplas também diferenciam letras maiúsculas de minúsculas.

Se o identificador do modelo não estiver totalmente qualificado (na forma de db_name.schema_name.name ou schema_name.name), o comando procura o modelo no esquema atual para a sessão.

<nome>!FORECAST

Gera uma previsão do modelo previamente treinado name.

Sintaxe

Os argumentos necessários variam dependendo do caso de uso para o qual o modelo foi treinado.

Para modelos de série única sem variáveis exógenas:

<name>!FORECAST(
  FORECASTING_PERIODS => <forecasting_periods>,
  [ CONFIG_OBJECT => <config_object> ]
);
Copy

Para modelos de série única com variáveis exógenas:

<name>!FORECAST(
  INPUT_DATA => <input_data>,
  TIMESTAMP_COLNAME => '<timestamp_colname>',
  [ CONFIG_OBJECT => <config_object> ]
);
Copy

Para modelos de série múltipla sem variáveis exógenas:

<name>!FORECAST(
  SERIES_VALUE => <series>,
  FORECASTING_PERIODS => <forecasting_periods>,
  [ CONFIG_OBJECT => <config_object> ]
);
Copy

Para modelos de série múltipla com variáveis exógenas:

<name>!FORECAST(
  SERIES_VALUE => <series>,
  SERIES_COLNAME => <series_colname>,
  INPUT_DATA => <input_data>,
  TIMESTAMP_COLNAME => '<timestamp_colname>',
  [ CONFIG_OBJECT => <config_object> ]
);
Copy

Argumentos

Obrigatório:

Nem todos os argumentos a seguir são necessários para todos os casos de uso.

FORECASTING_PERIODS => forecasting_periods

Necessário para previsões sem variáveis exógenas.

O número de etapas à frente para a previsão. O intervalo entre as etapas é inferido pelo modelo durante o treinamento.

INPUT_DATA => input_data

Necessário para previsões com variáveis exógenas.

Uma referência a uma tabela, exibição ou consulta que contém os carimbos de data/hora futuros e os valores das variáveis exógenas (recursos adicionais fornecidos pelo usuário) que foram passados como input_data ao treinar o modelo. O uso de uma referência permite que o processo de previsão, executado com privilégios limitados, use seus privilégios para acessar os dados. As colunas são combinadas entre este argumento e os dados de treinamento exógenos originais por nome.

TIMESTAMP_COLNAME => 'timestamp_colname'

Necessário para previsões com variáveis exógenas.

O nome da coluna em input_data contendo os carimbos de data/hora.

SERIES_COLNAME => 'series_colname'

Necessário para previsões de série múltipla com variáveis exógenas.

O nome da coluna em input_data especificando a série.

SERIES_VALUE => series

Necessário para previsões de série múltipla.

A série temporal a ser prevista. Pode ser um valor único (por exemplo, 'Series A'::variant) ou um VARIANT, mas deve especificar uma série na qual o modelo foi treinado. Se não for especificado, todas as séries treinadas serão previstas.

Opcional:

CONFIG_OBJECT => config_object

Um OBJECT contendo pares chave-valor usados para configurar o trabalho de previsão.

Chave

Tipo

Padrão

Descrição

prediction_interval

FLOAT

0,95

Um valor maior ou igual a 0,0 e menor que 1,0. O valor padrão de 0,95 significa que 95% dos pontos futuros devem ficar dentro do intervalo [lower_bound, upper_bound] do resultado da previsão.

on_error

STRING

'ABORT'

Cadeia de caracteres (constante) especificando o método de tratamento de erros. Isto é mais útil ao prever múltiplas séries. Os valores suportados são:

  • 'abort': anula a operação de previsão do modelo se for encontrado um erro em qualquer série temporal.

  • 'skip': ignora qualquer série temporal em que a previsão encontre um erro. Isso permite que a previsão seja bem-sucedida para outras séries temporais. As séries que falharam estão ausentes da saída do modelo.

Saída

A coluna SERIES está presente apenas para previsões de série múltipla. As previsões de série única não têm esta coluna.

Coluna

Tipo

Descrição

SERIES

VARIANT

Valor da série (se o modelo foi treinado com várias séries temporais)

TS

TIMESTAMP_NTZ

Carimbo de data/hora.

FORECAST

FLOAT

Previsão do valor de destino.

LOWER_BOUND

FLOAT

Limite inferior do intervalo de predição.

UPPER_BOUND

FLOAT

Limite superior do intervalo de predição.

<nome>!EXPLAIN_FEATURE_IMPORTANCE

Retorna a importância relativa do recurso para cada recurso usado pelo modelo.

Sintaxe

<name>!EXPLAIN_FEATURE_IMPORTANCE();
Copy

Saída

A coluna SERIES está presente apenas para previsões de série múltipla. As previsões de série única não têm esta coluna.

Coluna

Tipo

Descrição

SERIES

VARIANT

Valor da série (se o modelo foi treinado com várias séries temporais)

RANK

INTEGER

A classificação de importância de um recurso para uma série específica.

FEATURE_NAME

VARCHAR

O nome do recurso usado para treinar o modelo. aggregated_endogenous_features representa todos os recursos derivados como transformações da variável de destino.

IMPORTANCE_SCORE

FLOAT

A pontuação de importância do recurso: um valor em [0, 1], com 0 sendo a importância mais baixa possível e 1 a mais alta.

FEATURE_TYPE

VARCHAR

A origem do recurso. Uma das opções:

  • user_provided: dados de recursos fornecidos pelo usuário.

  • derived_from_timestamp: recurso periódico (por exemplo, dia, semana ou mês) derivado de dados de carimbo de data/hora.

  • derived_from_endogenous: recursos derivados de uma transformação da variável de destino.

<nome>!SHOW_EVALUATION_METRICS

Retorna métricas de avaliação fora da amostra geradas usando validação cruzada de série temporal. As métricas estarão disponíveis somente se evaluate=TRUE estiver em CONFIG_OBJECT durante a criação do modelo (este é o padrão).

Sintaxe

<name>!SHOW_EVALUATION_METRICS();
Copy

Saída

A coluna SERIES está presente apenas para previsões de série múltipla. As previsões de série única não têm esta coluna.

Coluna

Tipo

Descrição

SERIES

VARIANT

Valor da série (presente apenas se o modelo foi treinado com várias séries temporais)

ERROR_METRIC

VARCHAR

O nome da métrica de erro usada. O método retorna as seguintes métricas:

Métricas de ponto:

Métricas de intervalo: essas métricas usam o argumento prediction_interval de Configuração de avaliação.

  • COVERAGE_INTERVAL: a proporção de valores reais que se enquadram no intervalo de previsão.

  • WINKLER_ALPHA: pontuação de Winkler.

LOGS

VARIANT

Contém mensagens de erro ou aviso.

<nome>!SHOW_TRAINING_LOGS

Retorna logs do treinamento do modelo. A saída é diferente de NULL somente quando 'ON_ERROR' = 'SKIP' é definido no treinamento CONFIG_OBJECT, caso contrário, todo o modelo falhará no treinamento.

Sintaxe

<name>!SHOW_TRAINING_LOGS();
Copy

Saída

A coluna SERIES está presente apenas para modelos de série múltipla. Os modelos de série única não possuem esta coluna.

Coluna

Tipo

Descrição

SERIES

VARIANT

Valor da série (se o modelo foi treinado com várias séries temporais)

LOGS

OBJECT

Objeto que contém erros encontrados durante o treinamento. Atualmente a única chave é Errors, uma matriz de erros. Se nenhum erro for encontrado, o objeto de logs será NULL.

Exemplos

Consulte Exemplos.