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.

重要

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

语法¶

EXECUTE NOTEBOOK PROJECT <database_name>.<schema_name>.<project_name>
  MAIN_FILE = 'snow://workspace/<workspace_hash>/path/to/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

必填参数¶

database_name.schema_name.project_name

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

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

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

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

MAIN_FILE = 'notebook_file_name.ipynb'

指定要执行的工作区中的主笔记本文件（例如 'main.ipynb'）。

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

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

COMPUTE_POOL = 'compute_pool_name'

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

当笔记本运行时使用 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），或一个仓库运行时变体。

可选参数¶

Depending on how the project and runtime are configured, you may need to set the following parameters. The descriptions below define their purpose and typical usage.

ARGUMENTS = 'parameter_string'

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

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

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

Examples:

ARGUMENTS = 'env prod';

Copy

import sys
print(sys.argv)

Copy

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);

Copy

备注

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

访问控制要求¶

执行 EXECUTE NOTEBOOK PROJECT 的角色必须对该笔记本项目拥有足够的权限。

此外，执行角色还必须对以下对象拥有 USAGE/OWNERSHIP 权限：

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

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

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

使用说明¶

It is not possible to use the EXECUTE NOTEBOOK PROJECT command from a notebook.
You can call EXECUTE NOTEBOOK PROJECT from tasks, thus enabling notebook runs as part of larger workflows.
Snowflake 不支持将 EXECUTE NOTEBOOK PROJECT 命令嵌入配置为使用 EXECUTE AS USER 子句运行的任务中。创建此类任务时不会看到错误消息，但任务在执行时会失败。
当您使用 EXECUTE NOTEBOOK PROJECT 命令运行笔记本时：
Notebook code is executed on the compute pool specified by the COMPUTE_POOL parameter using the runtime specified by the RUNTIME parameter.
SQL and Snowpark queries are executed using the warehouse specified by the QUERY_WAREHOUSE parameter.

示例¶

Execute a notebook project:

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