EXECUTE NOTEBOOK PROJECT

Executa um notebook armazenado em um projeto de notebook (notebook project, NPO). Esse comando executa o notebook em modo não interativo (sem interface gráfica) e é útil para pipelines CI/CD e outros fluxos de trabalho orquestrados nos quais você deseja passar parâmetros ou bloquear versões de dependências para execuções repetíveis. É possível executar o comando a partir de:

  • Arquivos SQL.

  • Outros executáveis do Snowflake (tarefas);

  • Orquestradores externos que emitem SQL (por exemplo, Airflow, Prefect, Dagster, sistemas de CI/CD).

O comando executa o arquivo de notebook que você especifica como MAIN_FILE usando o tempo de execução, o pool de computação, o warehouse e as integrações de acesso externo que você configura.

Importante

Antes de iniciar uma execução não interativa, certifique-se de que seu notebook defina o contexto de execução (banco de dados e esquema) ou use nomes de objetos totalmente qualificados. Para obter mais informações, consulte Editando e executando notebooks no Workspaces.

Consulte também: CREATE NOTEBOOK PROJECT, CREATE TASK, cenário de fluxo de trabalho de CI/CD, Observabilidade e registro em log para Notebooks no Workspaces, Execução de notebooks com parâmetros

Sintaxe

EXECUTE NOTEBOOK PROJECT <database_name>.<schema_name>.<project_name>
  MAIN_FILE = 'notebook.ipynb'
  COMPUTE_POOL = '<compute_pool_name>'
  QUERY_WAREHOUSE = '<warehouse_name>'
  RUNTIME = '<runtime_version>'
  [ ARGUMENTS = '<parameter_string>' ]
  [ REQUIREMENTS_FILE = '<path/to/requirements.txt>' ]
  [ EXTERNAL_ACCESS_INTEGRATIONS = ( <integration_name> [ , ... ] ) ];
Copy

Parâmetros obrigatórios

database_name.schema_name.project_name

Identificador totalmente qualificado do projeto de notebook a ser executado.

Deve fazer referência a um projeto de notebook existente criado com CREATE NOTEBOOK PROJECT.

Deve ser totalmente qualificado, a menos que resida no DATABASE e SCHEMA atuais.

Para obter mais informações, consulte Requisitos para identificadores.

MAIN_FILE = 'notebook_file_name.ipynb'

Especifica o arquivo de notebook principal a ser executado no espaço de trabalho (path/to/notebook.ipynb).

Deve ser um arquivo de notebook .ipynb localizado no espaço de trabalho referenciado pelo projeto.

O caminho é relativo à raiz do espaço de trabalho.

COMPUTE_POOL = 'compute_pool_name'

Especifica o pool de computação usado ao executar o notebook em um tempo de execução de contêiner.

Obrigatório quando o tempo de execução do notebook usa Snowpark Container Services.

QUERY_WAREHOUSE = 'warehouse_name'

Especifica o warehouse virtual usado para executar as consultas SQL e Snowpark do notebook.

Obrigatório se o notebook executar operações SQL ou Snowpark e nenhum warehouse foi configurado de outra forma.

Ao usar tempos de execução de contêiner, o warehouse processa o pushdown das consultas. O Python é executado no pool de computação.

RUNTIME = 'runtime_version'

Especifica a imagem/versão do tempo de execução para executar o notebook (por exemplo, '1.0' or '2.2-CPU-PY3.11').

Determina a versão do Python e o ambiente de execução usados para a execução do notebook.

Corresponde a uma imagem do tempo de execução de contêiner (CPU ou GPU) ou à variante do tempo de execução de warehouse.

Parâmetros opcionais

Dependendo de como o projeto e o tempo de execução estão configurados, você pode precisar definir os seguintes parâmetros. As descrições abaixo definem a finalidade e o uso comum deles.

ARGUMENTS = 'parameter_string'

Opcionalmente, passa um ou mais argumentos de cadeia de caracteres para o notebook em tempo de execução, que aparecem como argumentos de linha de comando na lista sys.argv. Os argumentos são úteis para deixar a lógica do notebook dinâmica (por exemplo, selecionar um ambiente como env prod).

Para passar vários argumentos, especifique-os em uma única cadeia de caracteres separada por espaços. Os argumentos são analisados ​ em sys.argv usando espaços em branco como delimitadores. Em uma célula Python, acesse os argumentos usando sys.argv[0] para o nome do notebook, sys.argv[1] para o primeiro argumento e assim por diante.

Somente cadeias de caracteres são compatíveis; outros tipos de dados (como inteiros ou booleanos) são interpretados como NULL.

Exemplos:

ARGUMENTS = 'env prod';
Copy
import sys
print(sys.argv)
Copy
REQUIREMENTS_FILE = '<path/to/requirements.txt>'

Opcionalmente, especifica um arquivo requirements.txt em um espaço de trabalho ou em uma área de preparação para pré-instalar versões exatas de bibliotecas (como pandas ou scikit-learn) e outras dependências do Python antes da execução do notebook. Fixar dependências é fundamental para a idempotência e ajuda a tornar as execuções de notebooks mais repetíveis, reduzindo erros causados ​ ​por alterações nas versões das bibliotecas. O arquivo deve ser acessível à função de execução.

EXTERNAL_ACCESS_INTEGRATIONS = ( integration_name [ , ... ] )

Especifica uma ou mais integrações de acesso externo que o notebook pode usar durante a execução.

Obrigatório quando o notebook faz chamadas de rede de saída (por exemplo, para APIs externas).

Cada nome de integração deve fazer referência a uma integração de acesso externo existente.

Várias integrações de acesso externo podem ser especificadas em uma lista separada por vírgulas entre parênteses.

Exemplo:

EXTERNAL_ACCESS_INTEGRATIONS = (http_eai, s3_eai);
Copy

Nota

A regra de rede PyPI gerenciada pelo Snowflake SNOWFLAKE.EXTERNAL_ACCESS.PYPI_RULE só é acessível à função ACCOUNTADMIN. Consequentemente, usar esta regra em uma integração de acesso externo (external access integration, EAI) para objetos de notebook ou tarefas agendadas pode causar falhas. Para evitar isso, crie uma regra de rede definida pelo usuário para PyPI e faça referência a ela em sua integração de acesso externo. Para obter mais informações, consulte Regras de rede de saída gerenciadas pelo Snowflake.

Requisitos de controle de acesso

A função que executa EXECUTE NOTEBOOK PROJECT deve ter privilégios suficientes no projeto de notebook.

Além disso, a função de execução deve ter USAGE e MONITOR no warehouse de consulta, e USAGE ouOWNERSHIP em:

  • No pool de computação;

  • No banco de dados e esquema que contêm o projeto de notebook;

  • Nas tarefas e integrações de acesso externo referenciadas pelo comando.

Para instruções sobre como criar uma função personalizada com um conjunto específico de privilégios, consulte Criação de funções personalizadas.

Para informações gerais sobre concessões de funções e privilégios para executar ações de SQL em objetos protegíveis, consulte Visão geral do controle de acesso.

Notas de uso

  • Não é possível usar o comando EXECUTE NOTEBOOK PROJECT de um notebook.

  • Você pode chamar EXECUTE NOTEBOOK PROJECT de tarefas, permitindo assim a execução de notebooks como parte de fluxos de trabalho maiores.

  • O Snowflake não oferece suporte à incorporação do comando EXECUTE NOTEBOOK PROJECT em uma tarefa configurada para ser executada usando a cláusula EXECUTE AS USER. Você não verá uma mensagem de erro ao criar uma tarefa assim, mas quando a tarefa for executada, ela falhará.

  • Ao executar um notebook usando o comando EXECUTE NOTEBOOK PROJECT:

  • O código do notebook é executado no pool de computação especificado pelo parâmetro COMPUTE_POOL usando o tempo de execução especificado pelo parâmetro RUNTIME.

  • As consultas do SQL e Snowpark são executadas usando o warehouse especificado pelo parâmetro QUERY_WAREHOUSE.

Exemplos

Executar um projeto de notebook:

EXECUTE NOTEBOOK PROJECT "sales_detection_db"."schema"."DEFAULT_PROJ_B32BCFD4"
  MAIN_FILE = 'notebook_file.ipynb'
  COMPUTE_POOL = 'test_X_CPU'
  QUERY_WAREHOUSE = 'ENG_INFRA_WH'
  RUNTIME = 'V2.2-CPU-PY3.10'
  ARGUMENTS = 'env prod'
  REQUIREMENTS_FILE = 'path/to/requirements.txt'
  EXTERNAL_ACCESS_INTEGRATIONS = ('test_EAI');
Copy