EXECUTE NOTEBOOK PROJECT

Exécute un notebook stocké dans un projet de notebook (NPO). Cette commande exécute le notebook en mode non interactif (sans tête) et est utile pour les pipelines CI/CD et autres workflows orchestrés dans lesquels vous souhaitez transmettre des paramètres ou verrouiller des versions de dépendances pour des exécutions répétables. La commande peut être exécutée à partir de :

  • Fichiers SQL.

  • Autres exécutables Snowflake (tâches).

  • Orchestrateurs externes qui émettent du SQL (par exemple, Airflow, Prefect, Dagster, systèmes CI/CD).

La commande exécute le fichier de notebook que vous spécifiez en tant que MAIN_FILE à l’aide de l’environnement d’exécution, du pool de calcul, de l’entrepôt et des intégrations d’accès externes que vous configurez.

Important

Avant de déclencher une exécution non interactive, assurez-vous que votre notebook définit son contexte d’exécution (base de données et schéma) ou utilise des noms d’objets entièrement qualifiés. Pour plus d’informations, voir Modifier et exécuter des notebooks dans les espaces de travail.

Voir aussi : CREATE NOTEBOOK PROJECT, CREATE TASK, scénario de flux de travail CI/CD, Observabilité et journalisation pour les notebooks dans les espaces de travail, Exécution de notebooks avec des paramètres

Syntaxe

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

Paramètres requis

database_name.schema_name.project_name

Identificateur pleinement qualifié du projet de notebook à exécuter.

Doit faire référence à un projet de notebook existant créé avec CREATE NOTEBOOK PROJECT.

Doit être pleinement qualifié, sauf s’il réside dans la DATABASE et le SCHEMA actuels.

Pour plus d’informations, voir Exigences relatives à l’identificateur.

MAIN_FILE = 'notebook_file_name.ipynb'

Spécifie le fichier de notebook principal dans l’espace de travail à exécuter (path/to/notebook.ipynb).

Doit être un fichier de notebook .ipynb situé dans l’espace de travail référencé par le projet.

Le chemin est relatif à la racine de l’espace de travail.

COMPUTE_POOL = 'compute_pool_name'

Spécifie le pool de calcul utilisé lors de l’exécution du notebook sur une exécution de conteneur.

Requis lorsque l’exécution du notebook utilise Snowpark Container Services.

QUERY_WAREHOUSE = 'warehouse_name'

Spécifie l’entrepôt virtuel utilisé pour l’exécution des requêtes SQL et Snowpark du notebook.

Requis si le notebook effectue des opérations SQL ou Snowpark et qu’aucun entrepôt n’est configuré autrement.

Lors de l’utilisation d’exécutions de conteneur, l’entrepôt gère le pushdown des requêtes ; Python s’exécute sur le pool de calcul.

RUNTIME = 'runtime_version'

Spécifie l’image/la version d’exécution pour l’exécution du notebook (par exemple, '1.0' or '2.2-CPU-PY3.11').

Détermine la version de Python et l’environnement d’exécution utilisés pour l’exécution du notebook.

Correspond à une image d’exécution de conteneur (CPU ou GPU) ou à une variante d’exécution d’entrepôt.

Paramètres facultatifs

Selon la configuration du projet et du runtime, vous devrez peut-être définir les paramètres suivants. Les descriptions ci-dessous définissent leur objectif et leur utilisation typique.

ARGUMENTS = 'parameter_string'

Il est possible de transmettre un ou plusieurs arguments de chaîne au notebook lors de l’exécution, qui apparaissent sous forme d’arguments de ligne de commande dans la liste sys.argv. Les arguments sont utiles pour rendre dynamique la logique du notebook (par exemple, la sélection d’un environnement tel que env prod).

Pour passer plusieurs arguments, spécifiez-les dans une seule chaîne séparée par des espaces. Les arguments sont analysés dans sys.argv en utilisant l’espace comme délimiteur. Dans une cellule Python, accédez aux arguments en utilisant sys.argv[0] pour le nom du notebook, sys.argv[1] pour le premier argument, et ainsi de suite.

Seules les chaînes sont prises en charge. les autres types de données (tels que les entiers ou les booléens) sont interprétés comme NULL.

Exemples :

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

Spécifie éventuellement un fichier requirements.txt dans un espace de travail ou sur une zone de préparation pour préinstaller des versions exactes de bibliothèques (telles que pandas ou scikit-learn) et d’autres dépendances Python avant l’exécution du notebook. Le verrouillage des dépendances est essentiel pour garantir l’idempotence et rendre les exécutions de notebooks plus reproductibles, en réduisant les erreurs dues aux changements de versions des bibliothèques. Le fichier doit être accessible au rôle d’exécutant.

EXTERNAL_ACCESS_INTEGRATIONS = ( integration_name [ , ... ] )

Spécifie une ou plusieurs intégrations d’accès externes que le notebook peut utiliser pendant l’exécution.

Requis lorsque le notebook effectue des appels réseau sortants (par exemple, vers des APIs externes).

Chaque nom d’intégration doit faire référence à une intégration d’accès externe existante.

Plusieurs intégrations d’accès externes peuvent être spécifiées dans une liste séparée par des virgules à l’intérieur des parenthèses.

Exemple :

EXTERNAL_ACCESS_INTEGRATIONS = (http_eai, s3_eai);
Copy

Note

La règle réseau PyPI gérée par Snowflake SNOWFLAKE.EXTERNAL_ACCESS.PYPI_RULE est uniquement accessible au rôle ACCOUNTADMIN. Par conséquent, l’utilisation de cette règle dans une intégration d’accès externe (EAI) pour les objets de notebook ou les tâches planifiées peuvent entraîner leur échec. Pour éviter ce cas de figure, créez une règle réseau définie par l’utilisateur pour PyPI et faites-y référence dans votre intégration d’accès externe. Pour plus d’informations, voir Règles de réseau de sortie gérées par Snowflake.

Exigences en matière de contrôle d’accès

Le rôle exécutant EXECUTE NOTEBOOK PROJECT doit disposer de privilèges suffisants sur le projet de notebook.

En outre, le rôle d’exécution doit disposer de USAGE et MONITOR sur l’entrepôt de requêtes, et de USAGE ou OWNERSHIP sur :

  • Le pool de calcul.

  • La base de données et le schéma contenant le projet de notebook.

  • Les tâches et les intégrations d’accès externes référencées par la commande.

Pour obtenir des instructions sur la création d’un rôle personnalisé avec un ensemble spécifique de privilèges, voir Création de rôles personnalisés.

Pour des informations générales sur les rôles et les privilèges accordés pour effectuer des actions SQL sur des objets sécurisables, voir Aperçu du contrôle d’accès.

Notes sur l’utilisation

  • Il n’est pas possible d’utiliser la commande EXECUTE NOTEBOOK PROJECT à partir d’un notebook.

  • Vous pouvez appeler EXECUTE NOTEBOOK PROJECT à partir de tâches, ce qui permet d’exécuter le notebook dans le cadre de workflows plus importants.

  • Snowflake ne prend pas en charge l’intégration de la commande EXECUTE NOTEBOOK PROJECT dans une tâche qui est configurée pour s’exécuter à l’aide de la clause EXECUTE AS USER. Vous ne verrez pas de message d’erreur lors de la création d’une telle tâche, mais lorsque la tâche sera exécutée, elle échouera.

  • Lorsque vous exécutez un notebook à l’aide de la commande EXECUTE NOTEBOOK PROJECT :

  • Le code du notebook s’exécute sur le pool de calcul spécifié par le paramètre COMPUTE_POOL en utilisant l’exécution spécifiée par le paramètre RUNTIME.

  • Les requêtes SQL et Snowpark s’exécutent en utilisant l’entrepôt spécifié dans le paramètre QUERY_WAREHOUSE.

Exemples

Exécuter un projet 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