EXECUTE NOTEBOOK PROJECT

Executes a notebook stored in a notebook project outside the Notebooks editor. This command runs the notebook in a non-interactive (headless) mode and can be run from:

  • Worksheets or SQL files.

  • Other Snowflake executables (Tasks).

  • External orchestrators that issue SQL (for example, Airflow, Prefect, Dagster, CI/CD systems).

The command runs the notebook file you specify as MAIN_FILE using the runtime, compute pool, warehouse, and external access integrations you configure. Notebooks running on a Container Runtime execute on compute pools, while SQL/Snowpark queries run on a warehouse.

See also:

CREATE NOTEBOOK PROJECT, EXECUTE NOTEBOOK, CREATE TASK

Syntax

EXECUTE NOTEBOOK PROJECT <database_name>.<schema_name>.<project_name>
  [ MAIN_FILE = '<notebook_file_name>.ipynb' ]
  [ COMPUTE_POOL = '<compute_pool_name>' ]
  [ RUNTIME = '<runtime_version>' ]          -- e.g., 'V2.2-CPU-PY3.12'
  [ QUERY_WAREHOUSE = '<warehouse_name>' ]
  [ EXTERNAL_ACCESS_INTEGRATIONS = ('<integration_name>' [ , ... ]) ];
Copy

Required parameters

database_name.schema_name.project_name

Fully qualified identifier of the notebook project to execute.

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

Must be fully qualified unless it resides in the current DATABASE and SCHEMA.

For more information, see Identifier requirements.

Optional parameters

Depending on how the project and runtime are configured, some of these parameters may be required in practice. The descriptions below define their purpose and typical usage.

MAIN_FILE = 'notebook_file_name.ipynb'

Specifies the main notebook file within the workspace to execute (for example, 'main.ipynb').

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

The path is relative to the workspace root.

COMPUTE_POOL = 'compute_pool_name'

Specifies the compute pool used when executing the notebook on a Container Runtime.

Required when the notebook runtime uses Snowpark Container Services.

RUNTIME = 'runtime_version'

Specifies the runtime image/version for executing the notebook (for example, 'V2.2-CPU-PY3.12').

Determines the Python version and execution environment used for the notebook execution.

Corresponds to a Container Runtime image (CPU or GPU) or warehouse runtime variant.

QUERY_WAREHOUSE = 'warehouse_name'

Specifies the virtual warehouse used for executing SQL and Snowpark queries from the notebook.

Required if the notebook performs SQL or Snowpark operations and no warehouse is otherwise configured.

When using container runtimes, the warehouse handles query pushdown; Python executes on the compute pool.

EXTERNAL_ACCESS_INTEGRATIONS = ( integration_name [ , ... ] )

Specifies one or more external access integrations that the notebook can use during execution.

Required when the notebook makes outbound network calls (for example, to external APIs).

Each integration name must reference an existing external access integration.

Multiple external access integrations can be specified in a comma-separated list inside the parentheses.

Example:

EXTERNAL_ACCESS_INTEGRATIONS = ('http_eai', 's3_eai');
Copy

Access control requirements

The role executing EXECUTE NOTEBOOK PROJECT must have sufficient privileges on the notebook project.

In addition, the executing role must have USAGE/OWNERSHIP privileges on:

  • The query warehouse.

  • The compute pool.

  • The database and schema containing the notebook project.

  • Tasks and external access integrations 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.

Usage notes

You can call EXECUTE NOTEBOOK PROJECT from tasks, enabling notebook runs as part of larger workflows.

When you run a notebook using the EXECUTE NOTEBOOK PROJECT command:

  • Notebook code executes on the compute pool specified by the COMPUTE_POOL parameter using the runtime specified by the RUNTIME parameter.

  • SQL and Snowpark queries execute using the warehouse specified by the QUERY_WAREHOUSE parameter.

Examples

Execute a notebook project with all parameters:

EXECUTE NOTEBOOK PROJECT "sales_detection_db"."schema"."DEFAULT_PROJ_B32BCFD4"
  MAIN_FILE = 'notebook_file.ipynb'
  COMPUTE_POOL = 'test_X_CPU'
  RUNTIME = 'V2.2-CPU-PY3.10'
  QUERY_WAREHOUSE = 'ENG_INFRA_WH'
  EXTERNAL_ACCESS_INTEGRATIONS = ('test_EAI');
Copy

Execute a notebook project using only a warehouse:

EXECUTE NOTEBOOK PROJECT analytics_db.workflow_schema.workflow_proj
  MAIN_FILE = 'jobs/nightly_etl.ipynb'
  QUERY_WAREHOUSE = 'ETL_WH';
Copy
Language: English