Executar e agendar notebooks no Workspaces¶

Agendando notebooks no Workspaces¶

Você pode automatizar os fluxos de trabalho de ciência de dados e de ML agendando notebooks no Workspaces para serem executados em intervalos recorrentes. As execuções agendadas usam as tarefas do Snowflake e executam os notebooks com todas as dependências em uma sequência consistente de cima para baixo.

Permissões necessárias¶

Para agendar um notebook, a função usada para criar o cronograma deve ter as seguintes permissões e concessões:

Nível da conta

• EXECUTE TASK na ACCOUNT: permite que a função execute tarefas associadas a notebooks agendados.

Nível do esquema

• CREATE TASK: necessária para criar a tarefa subjacente do Snowflake.

• USAGE no esquema de destino: para armazenar metadados de tarefas e objetos de projetos de notebook.

Permissões de computação e warehouse

• USAGE no pool de computação usado para execução do notebook.

• USAGE e MONITOR no warehouse de consulta usado para células SQL no notebook.

USAGE nas integrações de acesso externo (EAIs) para notebooks

• USAGE em qualquer EAI usada pelo notebook.

Agendar um notebook¶

Para agendar um notebook no Snowsight, siga estas etapas:

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

2. Crie um novo notebook ou abra um existente para agendar.

3. Selecione Schedule no canto superior direito do editor de notebook.

   • Se esta for a primeira tarefa do notebook, o botão Schedule será um ícone de 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 de tarefa e o objeto de projeto de notebook associado serão criados. Escolha um esquema em que sua função tenha CREATE TASK, USAGE e os privilégios relevantes.

   • 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

   • Nome do projeto: 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âmetro (opcional): parâmetros de chave-valor passados para o notebook em tempo de execução e que 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.

   Variante de tempo de execução

   • CPU: usa um ambiente de tempo de execução de contêiner da CPU e é executado em um pool de computação da CPU (por exemplo, a SYSTEM_COMPUTE_POOL_CPU provisionada automaticamente).

   • GPU: usa um ambiente de tempo de execução de contêiner 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 de tempo de execução: a imagem base do tempo de execução de contêiner. A escolha da versão de tempo de execução correta garante que seu notebook seja executado de forma consistente entre o desenvolvimento e a execução agendada.

   • Pool de computação: o pool de computação que executará 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 que as execuções agendadas falhem, recomendamos que você use um pool de computação dedicado para garantir que nenhum outro serviço do SPCS consuma toda a capacidade.

   • Warehouse de consulta: 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) do Snowflake 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.

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

Se uma tarefa falhar porque o usuário não tem as permissões necessárias, a caixa de diálogo permanecerá aberta e exibirá as mensagens de erro relevantes.

Exibir as execuções de notebook agendadas¶

Você pode visualizar as tarefas agendadas em dois lugares:

Pelo notebook

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

2. Abra um notebook agendado.

3. Selecione Schedule no canto superior direito do editor de notebook. Uma janela flutuante exibe as seguintes informações:

• Todas as execuções agendadas para o notebook. Para visualizar ou interagir com as execuções agendadas, é necessário usar uma função com acesso ao banco de dados e ao esquema em que o cronograma e o objeto de projeto foram criados.

• O próximo horário da execução agendada.

• Status das execuções anteriores. Passe cursor do mouse sobre um indicador de status para ver detalhes como ID da consulta, horário da última execução, duração e status.

Pelo menu de ações

• Abrir o histórico de execução: abre o objeto de projeto do notebook mostrando todas as execuções anteriores, incluindo status, duração e resultados. A seleção do resultado de uma execução abre o notebook executado com a respectiva saída.

Implantar atualizações em tarefas agendadas de notebook¶

Depois de editar um notebook, você deverá implantar suas alterações antes que as execuções agendadas usem a versão atualizada. A implantação garante a reprodutibilidade e impede que as tarefas agendadas executem um código diferente do que foi implantado pela última vez. Quando um notebook tem alterações que requerem implantação, o ícone de cronograma (calendário) exibe um indicador de relógio.

Após a modificação do código ou das células, o ícone indicará que há alterações não implantadas.

• Selecione Deployed Changes.

  O Snowflake atualiza o objeto de projeto do notebook associado, e todas as tarefas agendadas para esse notebook usarão a versão recém-implantada na próxima execução.

Encontrar um objeto de projeto de notebook no Explorador de objetos¶

Cada notebook agendado cria automaticamente um objeto de projeto de notebook que armazena o código implantado, o histórico de execução e os artefatos.

Para localizar um objeto de projeto de notebook no Snowsight, siga estas etapas:

1. No menu de navegação, selecione Catalog » Database Explorer.

2. Navigate to Database » Schema » Notebook Project Objects to view all project objects in that schema.

Como alternativa, você pode:

1. Abrir o notebook relevante.

2. Selecionar Schedule no canto superior direito.

3. No menu suspenso, selecionar Run history para abrir o objeto de projeto de notebook associado.

Visualizar o histórico de execução do notebook¶

Se alguma etapa falhar durante a execução, o Notebooks interrompe a execução para impedir resultados downstream parciais ou inconsistentes.

Para visualizar o histórico de execução, siga estas etapas:

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

2. Abra o notebook com o histórico de execução que você deseja revisar.

3. No canto superior direito do editor de notebook, selecione o ícone de cronograma (calendário).

4. Selecione View run history no menu suspenso.

Run History mostra os horários de início e de término, o status da execução e os detalhes do erro, como logs e métricas do objeto de projeto do notebook.

Agendar um notebook usando tarefas¶

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

2. Execute o seguinte comando em um arquivo/planilha SQL:

CREATE OR REPLACE TASK <database_name>.<schema_name>.<task_name>
    WAREHOUSE = <warehouse_name>
    SCHEDULE = 'USING CRON 10 13 * * * America/Los_Angeles'
    -- CRON format: <minute> <hour> <day_of_month> <month> <day_of_week> <timezone>
AS
    -- Execute a notebook stored within a Snowflake project.
    EXECUTE NOTEBOOK
        PROJECT = '<database_name>.<schema_name>.<project_name>'
        -- Notebook file to run
        MAIN_FILE = '<notebook_file_name>.ipynb'
        -- Compute pool used to run the notebook
        COMPUTE_POOL = '<compute_pool_name>'
        -- Runtime environment (Python version, CPU/GPU, etc.)
        RUNTIME = '<runtime_version>'
        -- Warehouse used for SQL statements inside the notebook
        QUERY_WAREHOUSE = <query_warehouse_name>;

Copy

Depois de criar a tarefa, execute o seguinte comando para ativar o cronograma:

ALTER TASK <database_name>.<schema_name>.<task_name> RESUME;

Copy