EXECUTE NOTEBOOK PROJECT¶

执行存储在笔记本项目 (NPO) 中的笔记本。此命令以非交互式（无头）模式运行笔记本，适用于 CI/CD 管道和其他协调工作流，在这些工作流中，您可能需要传递参数或锁定依赖版本以确保可重复的运行。该命令可以从以下位置运行：

SQL 文件。
其他 Snowflake 可执行对象（任务）。
可发出 SQL 的外部编排工具（例如 Airflow、Prefect、Dagster 以及 CI/CD 系统）。

The command runs the notebook file you specify as MAIN_FILE using the runtime, compute pool, warehouse, and external access integrations you configure.

Important

Before triggering a non-interactive run, ensure that your notebook sets its execution context (database and schema) or uses fully qualified object names. For more information, see Editing and running notebooks in Workspaces.

语法

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> [ , ... ] ) ]
  [ SECRETS = ( <database_name>.<schema_name>.<secret_name> [ , ... ] ) ];

必填参数

database_name.schema_name.project_name

要执行的笔记本项目的完全限定标识符。

Must reference an existing notebook project created with CREATE NOTEBOOK PROJECT.

除非该项目位于当前的 DATABASE 和 SCHEMA 中，否则必须使用完全限定名称。

For more information, see Identifier requirements.

MAIN_FILE = 'notebook_file_name.ipynb'

Specifies the main notebook file within the workspace to execute (path/to/notebook.ipynb).

Must be an .ipynb notebook file located in the workspace referenced by the project.

该路径为相对于工作区根目录的相对路径。

COMPUTE_POOL = 'compute_pool_name'

指定在容器运行时中执行笔记本时所使用的计算池。

Required when the notebook runtime uses Snowpark Container Services.

QUERY_WAREHOUSE = 'warehouse_name'

指定用于执行 SQL 以及来自笔记本的 Snowpark 查询的虚拟仓库。

如果笔记本执行 SQL 或 Snowpark 操作，且未通过其他方式配置仓库，则此参数为必填项。

在使用容器运行时时，查询下推由仓库处理，而 Python 代码在计算池上执行。

RUNTIME = 'runtime_version'

Specifies the runtime image/version for executing the notebook (for example, '1.0' or '2.2-CPU-PY3.11').

决定笔记本执行时使用的 Python 版本及其执行环境。

对应一个容器运行时镜像（CPU 或 GPU），或一个仓库运行时变体。

可选参数

根据项目和运行时的配置方式，您可能需要设置以下参数。以下说明介绍了这些参数的用途及其常见使用方式。

ARGUMENTS = 'parameter_string'

Optionally passes one or more string arguments to the notebook at runtime, which appear as command-line arguments in the sys.argv list. Arguments are useful for making notebook logic dynamic (for example, selecting an environment such as env prod).

To pass multiple arguments, specify them in a single string separated by spaces. The arguments are parsed into sys.argv using whitespace as the delimiter. In a Python cell, access the arguments using sys.argv[0] for the notebook name, sys.argv[1] for the first argument, and so on.

仅支持字符串；其他数据类型（例如整数或布尔）会被解释为 NULL。

示例：

ARGUMENTS = 'env prod';

import sys
print(sys.argv)

REQUIREMENTS_FILE = '<path/to/requirements.txt>'

Optionally specifies a requirements.txt file in a workspace or on a stage to pre-install exact versions of libraries (such as pandas or scikit-learn) and other Python dependencies before notebook execution. Pinning dependencies is critical for idempotency and helps make notebook runs more repeatable, reducing errors caused by changes in library versions. The file must be accessible to the executing role.

EXTERNAL_ACCESS_INTEGRATIONS = ( integration_name [ , ... ] )

指定笔记本在执行过程中可以使用的一个或多个外部访问集成。

当笔记本需要进行出站网络调用时（例如访问外部 APIs），该参数为必填项。

每个集成名称都必须指向一个已存在的外部访问集成。

可以在括号中使用逗号分隔的列表形式指定多个外部访问集成。

示例：

EXTERNAL_ACCESS_INTEGRATIONS = (http_eai, s3_eai);

Note

The Snowflake-managed PyPI network rule SNOWFLAKE.EXTERNAL_ACCESS.PYPI_RULE is only accessible to the ACCOUNTADMIN role. Consequently, using this rule in an External Access Integration (EAI) for notebook objects or scheduled tasks may cause them to fail. To avoid this, create a user-defined network rule for PyPI and reference it in your external access integration. For more information, see Snowflake-managed egress network rules.

SECRETS = ( database_name.schema_name.secret_name [ , ... ] )

Optionally lists one or more secrets that the notebook may read during execution (for example, API keys or OAuth tokens referenced from Snowpark or mounted files).

Each entry must be a fully qualified secret name. Include this parameter (together with EXTERNAL_ACCESS_INTEGRATIONS) when the notebook performs authenticated outbound access that relies on secrets attached to the notebook service in Snowsight.

For setup, UI scheduling, and Python examples, see Using secrets in Notebooks in Workspaces.

访问控制要求

The role executing EXECUTE NOTEBOOK PROJECT must have either OWNERSHIP or USAGE privileges on the notebook project object (NPO).

此外，执行角色必须对查询仓库拥有 USAGE 和 MONITOR 权限，并对以下对象拥有 USAGE 或 OWNERSHIP 权限：

计算池。
包含该笔记本项目的数据库和架构。
Tasks, external access integrations, and secrets referenced by the command.

For instructions on creating a custom role with a specified set of privileges, see Creating custom roles.

For general information about roles and privilege grants for performing SQL actions on securable objects, see Overview of Access Control.

使用说明

无法使用来自笔记本的 EXECUTE NOTEBOOK PROJECT 命令。
You can call EXECUTE NOTEBOOK PROJECT from tasks, thus enabling notebook runs as part of larger workflows.
Snowflake doesn’t support embedding the EXECUTE NOTEBOOK PROJECT command in a task that is configured to run using the EXECUTE AS USER clause. You will not see an error message when creating such a task, but when the task is executed, it will fail.
单元格输出可见性仅限于发起执行的用户。其他用户无法查看通过此命令执行的单元格的输出。
When you run a notebook using the EXECUTE NOTEBOOK PROJECT command:
- 笔记本代码会在 COMPUTE_POOL 参数指定的计算池上执行，并使用 RUNTIME 参数指定的运行时。
- SQL 以及 Snowpark 查询将使用 QUERY_WAREHOUSE 参数指定的虚拟仓库执行。

示例

执行笔记本项目：

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')
  SECRETS = (sales_detection_db.schema.my_api_secret);