EXECUTE NOTEBOOK PROJECT¶

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

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

该命令会使用您配置的运行时、计算池、仓库以及外部访问集成来运行您指定为 MAIN_FILE 的笔记本文件。

重要

在触发非交互式运行之前，请确保笔记本设置其执行上下文（数据库和架构）或使用完全限定的对象名称。有关更多信息，请参阅在工作区中编辑和运行笔记本。

另请参阅：CREATE NOTEBOOK PROJECT、CREATE TASK、CI/CD 工作流程场景、工作区中笔记本的可观察性和日志记录、带参数运行笔记本

语法¶

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> [ , ... ] ) ];

必填参数¶

database_name.schema_name.project_name

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

必须引用一个已存在的笔记本项目，该项目需通过 CREATE NOTEBOOK PROJECT 创建。

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

有关更多信息，请参阅标识符要求。

MAIN_FILE = 'notebook_file_name.ipynb'

指定工作区中要执行的主笔记本文件 (path/to/notebook.ipynb)。

必须是一个 .ipynb 笔记本文件，且位于该项目所引用的工作区中。

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

COMPUTE_POOL = 'compute_pool_name'

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

当笔记本运行时使用 Snowpark Container Services 时，此参数为必填项。

QUERY_WAREHOUSE = 'warehouse_name'

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

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

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

RUNTIME = 'runtime_version'

指定用于执行笔记本的运行时镜像/版本（例如 '1.0' or '2.2-CPU-PY3.11'）。

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

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

可选参数¶

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

ARGUMENTS = 'parameter_string'

（可选）在运行时将一个或多个字符串实参传递给笔记本，这些实参会作为命令行实参出现在 sys.argv 列表中。实参对于使笔记本逻辑动态化非常有用（例如，选择一个环境，例如 env prod）。

要传递多个实参，请在单个字符串中指定这些实参，并用空格分隔。实参被解析为 sys.argv，使用空格作为分隔符。在 Python 单元格中，访问实参，使用 sys.argv[0] 访问笔记本名称，使用 sys.argv[1] 访问第一个实参，依此类推。

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

示例：

ARGUMENTS = 'env prod';

import sys
print(sys.argv)

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

（可选）在工作区或暂存区中指定 requirements.txt，以便在笔记本执行之前预安装确切版本的库（例如 pandas 或 scikit-learn）和其他 Python 依赖项。固定依赖项对于幂等性至关重要，有助于提高笔记本运行的可重复性，减少因库版本变更而导致的错误。执行角色必须能够访问该文件。

EXTERNAL_ACCESS_INTEGRATIONS = ( integration_name [ , ... ] )

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

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

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

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

示例：

EXTERNAL_ACCESS_INTEGRATIONS = (http_eai, s3_eai);

备注

Snowflake 管理的 PyPI 网络规则 SNOWFLAKE.EXTERNAL_ACCESS.PYPI_RULE 只能访问 ACCOUNTADMIN 角色。因此，在外部访问集成 (EAI) 中对笔记本对象或计划任务使用此规则可能会导致它们失败。为避免这种情况，请为 PyPI 创建用户定义的网络规则,并在外部访问集成中引用它。有关更多信息，请参阅 Snowflake 管理的出口网络规则。

访问控制要求¶

执行 EXECUTE NOTEBOOK PROJECT 的角色必须对笔记本项目对象 (NPO) 具有 OWNERSHIP 或 USAGE 权限。

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

计算池。
包含该笔记本项目的数据库和架构。
命令中引用的任务以及外部访问集成。

有关创建具有指定权限集的自定义角色的说明，请参阅创建自定义角色。

有关对安全对象执行 SQL 操作的相应角色和权限授予的一般信息，请参阅访问控制概述。

使用说明¶

无法使用来自笔记本的 EXECUTE NOTEBOOK PROJECT 命令。
您可以在任务中调用 EXECUTE NOTEBOOK PROJECT，从而将笔记本运行纳入更大的工作流中。
Snowflake 不支持将 EXECUTE NOTEBOOK PROJECT 命令嵌入配置为使用 EXECUTE AS USER 子句运行的任务中。创建此类任务时不会看到错误消息，但任务在执行时会失败。
单元格输出可见性仅限于发起执行的用户。其他用户无法查看通过此命令执行的单元格的输出。
当您使用 EXECUTE NOTEBOOK PROJECT 命令运行笔记本时：
- 笔记本代码会在 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');