Executing notebooks in Workspaces using SQL

Snowsight supports non-interactive (headless) execution of notebooks. This allows you to trigger a programmatic run of a notebook without opening Snowsight and without requiring a recurring schedule.

Headless execution is intended for tasks, scheduled tasks, or workflows orchestrated by tools such as Airflow, Prefect, Dagster, CI/CD pipelines, or external systems that need to execute a notebook programmatically.

Create a notebook project

If a notebook project does not yet exist, create one using the CREATE NOTEBOOK PROJECT command:

CREATE OR REPLACE NOTEBOOK PROJECT <database_name>.<schema_name>.<project_name>
  FROM 'snow://workspace/<workspace_path>'
  COMMENT = 'Notebook project for this workflow';
Copy

To find the workspace path:

  1. Sign in to Snowsight.

  2. In the navigation menu, select Projects » Workspaces.

  3. Select the workspace.

  4. Select the pin icon.

  5. Copy the location (for example, snow://workspace/USER$.schema."workspacename"/versions/head).

Execute a notebook using SQL

You can run a notebook from a worksheet, SQL file, or any SQL client using the EXECUTE NOTEBOOK PROJECT command:

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

Example

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

Viewing executions

This command runs the notebook and its dependencies using the version stored in the associated notebook project. To view execution results, navigate to the notebook project under the corresponding database and schema in Snowsight.

Language: English