Agendando fluxos de trabalho por cenário¶

Cenário A: desenvolvimento em um espaço de trabalho privado¶

1. No menu de navegação, selecione Projects » Workspaces.

2. Selecione (+ Add new) » Notebook para criar um novo notebook ou abra um existente para agendar.

   Nota

   Certifique-se de ter especificado o contexto de execução (banco de dados e esquema) no notebook que você está agendando. Para obter mais informações, consulte Definir o contexto de execução.

3. Na parte superior do editor de notebook, selecione Scheduled runs .

   • Se esta for a primeira tarefa do notebook, o ícone será um calendário.

   • Se já existir um cronograma, o ícone será um calendário com um relógio.

4. Selecione Create Schedule.

5. Na caixa de diálogo Schedule a Notebook Task, insira as seguintes informações:

   Configurações básicas

   • Nome da tarefa: o nome exclusivo da tarefa agendada. O nome padrão é {notebook-name}_task_#, mas pode ser atualizado se necessário.

   • Função de proprietário: a função do Snowflake sob a qual a tarefa é executada. Selecione uma função com as permissões necessárias para executar todas as operações realizadas pelo notebook agendado. Essa função deve ter permissões para:

     • Ler/gravar os objetos de banco de dados que o notebook usa;

     • Acessar warehouses, pools de computação e integrações;

     • Criar/atualizar os objetos de tarefa e de projeto.

   • Local: o banco de dados e o esquema em que o objeto da tarefa e o objeto do projeto do notebook associado são criados. Escolha um esquema em que sua função tenha privilégios CREATE, TASK e USAGE. Se a sua função tiver apenas privilégios USAGE no esquema, certifique-se de que ela também tenha os privilégios CREATE, NOTEBOOK e PROJECT.

   • Frequência: com que frequência o notebook deve ser executado. Escolha entre: por hora, diariamente, semanalmente, mensalmente ou personalizado (agendamento Cron). Todos os horários de execução usam seu fuso horário local.

   Configurações avançadas (todos os campos são obrigatórios, a menos que especificado de outra forma)

   • Nome do projeto do notebook: um nome exclusivo para o contêiner de projetos do notebook que o Snowflake cria para execução de tarefas. Se não for editado, o Snowflake dará um nome padrão.

   • Parâmetros (opcional): os parâmetros de chave-valor são passados para o notebook em tempo de execução e aparecem como argumentos de linha de comando (em sys.argv). Os parâmetros são úteis para passar datas, sinalizadores de ambiente, limites ou versões de modelo. Os parâmetros podem ser passados ​ ​no Snowsight como valores separados por espaços em branco ou no comando EXECUTE NOTEBOOK PROJECT como ARGUMENTS = 'env prod'. Para obter mais informações, consulte Execução de notebooks com parâmetros.

   • Variante de tempo de execução: o ambiente de tempo de execução utilizado para a execução do notebook. Escolha entre:

     • CPU: usa um ambiente do Container Runtime da CPU e é executado em um pool de computação da CPU (por exemplo, o SYSTEM_COMPUTE_POOL_CPU provisionado automaticamente).

     • GPU: usa um ambiente do Container Runtime da GPU que inclui bibliotecas aceleradas por GPU e é executado em um pool de computação da GPU (como SYSTEM_COMPUTE_POOL_GPU).

     • Versão do Python: a versão do Python utilizada durante a execução da tarefa.

     • Versão do tempo de execução: a imagem base do Container Runtime. Escolher a versão correta do tempo de execução garante que seu notebook seja executado de modo consistente entre o desenvolvimento e a execução agendada.

   • Pool de computação: o pool de computação que executa a tarefa do notebook. Certifique-se de que o pool de computação tenha capacidade (nós livres) no momento da execução agendada. Para evitar falhas nas execuções agendadas, recomendamos que você use um pool de computação dedicado para garantir que nenhum outro serviço do SPCS ocupe toda a capacidade.

   • Warehouse de consultas: o warehouse Snowflake usado para todas as consultas SQL no notebook.

   • Integrações de acesso externo (opcional): define quais integrações de acesso externo (External Access Integrations, EAIs) o notebook pode usar. As EAIs serão necessários se o notebook precisar de APIs externas, serviços de terceiros ou armazenamento em nuvem fora das áreas de preparação internas do Snowflake. Se não houver EAIs na lista, a função selecionada não tem privilégios em nenhuma integração.

   • Arquivo de requisitos (opcional): pré-instale as dependências do Python para execuções repetíveis usando o parâmetro REQUIREMENTS_FILE. Para obter mais informações, consulte Gerenciando pacotes e tempo de execução.

6. Revise a versão preliminar do cronograma e selecione Create.

Cenário B: produção (CI/CD)¶

Para ambientes de produção, recomendamos gerenciar o código do notebook em um espaço de trabalho baseado em Git (para obter detalhes, consulte Integração de espaços de trabalho com um repositório Git) ou desenvolver localmente em seu IDE preferido. Você pode usar um pipeline de CI/CD (como o GitHub Actions) para implantar arquivos em um área de preparação interna ou temporária do Snowflake.

Para uma explicação passo a passo prática deste padrão, consulte o guia de início rápido de introdução à engenharia de dados usando o Snowflake Notebooks e o respectivo repositório de código no GitHub.

Depois que os arquivos estiverem na área de preparação, você poderá:

• Criar um Objeto de Projeto de Notebook (Notebook Project Object, NPO) com origem na localização dessa área de preparação.

• Agendar o NPO usando uma Tarefa do Snowflake para execução automatizada.

1. Criar uma área de preparação

   Use CREATE STAGE para criar uma área de preparação interna ou temporária:

   -- Ensure the landing zone exists
   CREATE STAGE IF NOT EXISTS <database_name>.<schema_name>.<stage_name>;
   

   Copy

2. Carregar/implantar arquivo(s) de notebook na área de preparação interna ou temporária

   Seu pipeline CI/CD deve carregar o(s) arquivo(s) .ipynb para uma área de preparação do Snowflake. Use o comando PUT para garantir que os arquivos de notebook sejam carregados em uma área de preparação legível pelo projeto de notebook.

   PUT file://<absolute_path_to_file>/ @<database_name>.<schema_name>.<stage_name> AUTO_COMPRESS=FALSE OVERWRITE=TRUE;
   

   Copy

   Exemplo:

   PUT file://notebooks/ml_model/train.ipynb @<database_name>.<schema_name>.<stage_name> AUTO_COMPRESS=FALSE OVERWRITE=TRUE;
   

   Copy

3. Criar ou atualizar o Objeto de Projeto de Notebook (NPO)

   Crie (ou atualize) o NPO para referenciar a área de preparação interna ou temporária que contém seus arquivos de notebook implantados:

   CREATE NOTEBOOK PROJECT IF NOT EXISTS <database_name>.<schema_name>.<project_name>
     FROM '@<database_name>.<schema_name>.<stage_name>';
   

   Copy

4. Alterar os detalhes do projeto de notebook

   Para alterações de código subsequentes, seu pipeline executa um comando ALTER. Isso atualiza o projeto para a versão mais recente do código sem precisar descartar e recriar o objeto:

   -- Update the project with the latest code from the stage
   ALTER NOTEBOOK PROJECT <database_name>.<schema_name>.<project_name>
     ADD VERSION FROM '@<database_name>.<schema_name>.<stage_name>';
   

   Copy

5. Executar o projeto de notebook (orquestrar com uma tarefa)

   Crie uma tarefa para agendar e executar o NPO. Use uma tarefa do Snowflake para definir o cronograma e os parâmetros de execução para o NPO.

   Nota

   Especifique o contexto de execução do seu notebook (use o banco de dados e o esquema do notebook que você deseja agendar). Para obter mais informações, consulte Definir o contexto de execução.

   -- Create or replace the task to orchestrate the notebook
   CREATE OR REPLACE TASK <database_name>.<schema_name>.<task_name>
     WAREHOUSE = '<warehouse_name>'
     SCHEDULE = 'USING CRON 0 9 * * * America/Los_Angeles'
   AS
     EXECUTE NOTEBOOK PROJECT <database_name>.<schema_name>.<project_name>
       MAIN_FILE = 'snow://workspace/<workspace_hash>/path/to/notebook.ipynb'
       COMPUTE_POOL = 'SYSTEM_COMPUTE_POOL_CPU'
       RUNTIME = 'V2.2-CPU-PY3.12'
       QUERY_WAREHOUSE = '<warehouse_name>'
       ARGUMENTS = '<db_name> <schema_name> <warehouse_name>';
   

   Copy

   Para obter informações sobre como passar parâmetros para notebooks agendados, consulte Execução de notebooks com parâmetros.

6. Exibir o histórico de execução ou a execução do seu notebook

   Após a execução da tarefa, você pode monitorar o sucesso ou a falha dela no Snowsight para garantir que a implantação de CI/CD esteja funcionando conforme o esperado. Para obter instruções detalhadas sobre como visualizar o histórico de execução, consulte Visualizar execuções de notebook agendadas.

O Snowsight oferece suporte à execução não interativa (headless) de notebooks. Isso permite acionar uma execução programática de um notebook sem abrir o Snowsight e nem exigir um cronograma recorrente.

A execução headless é destinada a tarefas, tarefas agendadas ou fluxos de trabalho orquestrados por ferramentas como Airflow, Prefect, Dagster, pipelines de CI/CD ou sistemas externos que precisam executar um notebook programaticamente. Para obter mais informações, consulte CREATE NOTEBOOK PROJECT.