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