Executar e agendar notebooks no Workspaces¶

Agendando notebooks no Workspaces¶

Ao implementar notebooks para produção, o Snowflake oferece uma funcionalidade nativa para gerenciar a implantação, a orquestração e o monitoramento. Você desenvolve e itera em notebooks interativamente no Workspaces dentro do Snowsight. O agendamento de um notebook implanta seu conteúdo em um objeto de produção chamado objeto de projeto de notebook (Notebook Project Object, NPO), que encapsula o conteúdo do espaço de trabalho (por exemplo, arquivos .ipynb, scripts Python e arquivos SQL). Os NPOs oferecem suporte a implantações com controle de versão e são objetos no nível do esquema (por exemplo, db_name.schema_name.npo_name).

Após a implantação, você poderá orquestrar a execução do notebook usando as tarefas do Snowflake (que executam o código do notebook de cima para baixo usando um tempo de execução e um conjunto de dependências consistentes) ou qualquer ferramenta de orquestração de terceiros. O Snowflake captura a telemetria de execução que é possível monitorar no Snowsight ou consulta programaticamente em uma tabela de eventos. Para obter mais informações, consulte Observabilidade e registro em log para Notebooks no Workspaces.

Permissões e compartilhamento de NPOs¶

Para executar ou gerenciar um NPO, uma função deve ter os seguintes privilégios:

• Local: USAGE ou OWNERSHIP no banco de dados e esquema que contém o NPO.

• Acesso ao NPO: USAGE ou OWNERSHIP no NPO específico.

• Compute: USAGE and MONITOR on the warehouse, and USAGE on the compute pool (for Container Runtime).

• Cronograma: o privilégio EXECUTE TASK global no nível da conta é necessário se o NPO é acionado por uma tarefa.

• Integrações de acesso externo: USAGE em quaisquer EAIs usadas pelo notebook.

• Tarefas: quando o NPO é agendado por meio de uma tarefa, a função de proprietário da tarefa deve receber o privilégio USAGE em todos os objetos necessários (como NPOs, warehouses ou bancos de dados). A função de proprietário da tarefa também deverá ter privilégios para executar os comandos USE DATABASE e USE SCHEMA se o notebook definir o contexto de execução programaticamente.

Usando um NPO para agendar um notebook¶

Atualmente, há dois cenários possíveis para implantar e agendar notebooks. Em ambos os cenários, os notebooks devem ser empacotados no NPO. Cenário A é o agendamento de notebooks de um espaço de trabalho privado. Cenário B é a integração das ações do GitHub (ou de outro sistema de CI/CD) para automatizar a criação dos NPOs de uma área de preparação interna ou temporária, gerenciar o ciclo de vida por meio de atualizações com controle de versão e orquestrar a execução delas usando as tarefas do Snowflake.

Para conferir fluxos de trabalho detalhados referentes a cada cenário, consulte Agendando fluxos de trabalho por cenário.

Exibir as execuções de notebook agendadas¶

Você pode visualizar as tarefas agendadas em três lugares:

Pelo 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.

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

2. Abra um notebook agendado.

3. Na parte superior do editor de notebook, selecione Scheduled runs . Uma janela flutuante exibe as seguintes informações:

• Todas as execuções agendadas para o notebook.

• 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

• Open Run History: Opens the notebook’s project object showing all past runs, including status, duration, results, source file, logs, and metrics. Selecting a run’s result opens the executed notebook with its output. For more information, see Observabilidade e registro em log para Notebooks no Workspaces.

Pelo navegador de bancos de dados

Para visualizar o histórico de execuções de qualquer notebook agendado (incluindo aqueles implantados via CI/CD):

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

2. Selecione o banco de dados e o esquema com o objeto de projeto de notebook (NPO).

3. Selecione NPO.

4. Selecione Run history.

5. Selecione uma execução a partir da qual visualizar a saída do notebook, junto com logs e métricas (quando disponíveis). Para obter mais informações, consulte Observabilidade e registro em log para Notebooks no Workspaces.

Gerenciar tarefas agendadas¶

No popover Scheduled runs, você pode gerenciar suas tarefas agendadas selecionando as reticências (mais ações) ao lado de uma tarefa agendada:

• Run now: aciona uma execução imediata da tarefa agendada.

• Pause schedule: interrompe temporariamente a execução automática do cronograma. A tarefa permanece configurada, mas não será executada até ser retomada.

• Delete: remove a tarefa agendada permanentemente. Você poderá criar um novo cronograma com configurações diferentes (como uma função ou local de banco de dados diferente) depois de excluir o cronograma existente.

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. Se esta for a primeira tarefa do notebook, e um notebook tiver alterações que exijam a implantação, o ícone de cronograma (calendário) exibirá um indicador de relógio. Se já existir um cronograma, o ícone será um calendário com um 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 Deploy 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 (NPO) no navegador de objetos¶

Cada notebook agendado cria automaticamente um NPO que armazena seu código implantado, histórico de execuções e artefatos. Você pode localizar esses objetos no navegador de objetos do Snowsight.

Para localizar um NPO no Snowsight, siga estas etapas:

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

2. Navegar até Database » Schema » Notebook Project Objects para visualizar todos os NPOs nesse esquema.

Como alternativa, você pode:

1. Abrir o notebook relevante.

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

3. Selecione Open run history para abrir o NPO associado.

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

Esta seção descreve como visualizar os detalhes de execução e solucionar problemas de execuções de notebook após a criação de um cronograma. Se alguma etapa falhar durante a execução, o Snowflake interromperá 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 » Workspaces.

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

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

4. Selecione View run history no menu suspenso.

Run History mostra as seguintes informações do objeto de projeto do notebook:

• Resultados: visualize o notebook e a saída de execuções anteriores.

• Tarefas: veja quais tarefas executaram o NPO.

• Arquivo de origem: visualize o arquivo de notebook que foi executado.

• Logs e métricas: visualize logs de execução e métricas de desempenho (certifique-se de ter habilitado o registro em log e as tabelas de eventos). Para obter mais informações, consulte Observabilidade e registro em log para Notebooks no Workspaces.

• Detalhes da execução: horários de início e término, status da execução e detalhes de erro.

Agendar um notebook usando tarefas¶

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

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

-- Execute a notebook project using a task
CREATE OR REPLACE TASK <database_name>.<schema_name>.<name>
  WAREHOUSE = <string>
  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 notebook project.
  EXECUTE NOTEBOOK PROJECT "<database_name>"."<schema_name>"."<project_name>"
    MAIN_FILE = 'notebook.ipynb'  -- Path to the notebook file
    COMPUTE_POOL = '<compute_pool_name>'
    RUNTIME = '<runtime_version>'  -- e.g. V2.2-CPU-PY3.11
    QUERY_WAREHOUSE = '<wh_name>'
    ARGUMENTS = '<string>'  -- Can pass a single string parsed in the notebook code
    REQUIREMENTS_FILE = '<path/to/requirements.txt>'  -- Pre-installs dependencies before the notebook runs
    EXTERNAL_ACCESS_INTEGRATIONS = ('integration_name');  -- e.g. ('http_eai', 's3_eai')

Copy

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

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

Copy

Se uma tarefa falhar porque sua função ativa não tem os privilégios necessários, o Snowsight exibirá as mensagens de erro relevantes para que você possa corrigir as permissões ausentes.

Para sintaxe, parâmetros e exemplos, consulte EXECUTE NOTEBOOK PROJECT. Para obter informações sobre como passar parâmetros para notebooks agendados, consulte Execução de notebooks com parâmetros.