Run a notebook

How-to guideApplies to: Unified engine deployments

Create an inline SQL notebook, open its SQL kernel session, execute a cell, read outputs, and close the session. The notebook service and SQL kernel must be enabled.

Run an inline SQL notebook

Create a saved notebook, open a SQL session, run its cell, inspect outputs, then close its session.

Placeholder	Value
`{{create_submission}}`	A new UUID for this request; reuse it when recovering the same submission.
`{{session_submission}}`	A new UUID for this request; reuse it when recovering the same submission.
`{{run_submission}}`	A new UUID for this request; reuse it when recovering the same submission.

Replace the placeholders in your client. Keep returned IDs for later requests. Paths below use the native API prefix; adjust it for your deployment.

1. Create a SQL notebook

POST /api/v1/notebooks
Host: <ENGINE_HOST>
Content-Type: application/json

{
  "submission_id": "{{create_submission}}",
  "name": "HTTP example - orders notebook",
  "document": {
    "nbformat": 4,
    "nbformat_minor": 5,
    "metadata": {
      "kernelspec": {
        "name": "sql",
        "display_name": "SQL",
        "language": "sql"
      }
    },
    "cells": [
      {
        "cell_type": "code",
        "id": "orders-summary",
        "metadata": {},
        "source": "WITH orders(id, category, region, amount) AS (VALUES (1, 'Books', 'North', 20), (2, 'Games', 'South', 30), (3, 'Games', 'North', 15), (4, 'Books', 'North', 40), (5, 'Garden', 'South', 25), (6, 'Garden', 'North', 10)) SELECT category, SUM(amount) AS sales FROM orders GROUP BY category ORDER BY category",
        "execution_count": null,
        "outputs": []
      }
    ]
  },
  "settings": {
    "query": {
      "current_catalog": "default",
      "namespace": [
        "default"
      ],
      "time_zone": "UTC",
      "case_sensitive": false,
      "ansi_enabled": true
    },
    "options": {
      "execution_target": "DuckDb"
    }
  }
}

From the response, keep notebook_id from /notebook/notebook_id, notebook_revision from /notebook/revision. Endpoint reference.

2. Open the SQL kernel

POST /api/v1/notebooks/{{notebook_id}}/sessions
Host: <ENGINE_HOST>
Content-Type: application/json

{
  "submission_id": "{{session_submission}}",
  "kernel_name": "sql"
}

From the response, keep notebook_session from /session/session_id. Endpoint reference.

3. Run the notebook

POST /api/v1/notebooks/{{notebook_id}}/runs
Host: <ENGINE_HOST>
Content-Type: application/json

{
  "submission_id": "{{run_submission}}",
  "session_id": "{{notebook_session}}",
  "expected_revision": {{notebook_revision}}
}

From the response, keep notebook_run from /run/run_id. Endpoint reference.

4. Follow cell execution

GET /api/v1/notebooks/{{notebook_id}}/runs/{{notebook_run}}
Host: <ENGINE_HOST>

From the response, keep execution_id from /run/cells/0/execution_id. Repeat this read until /run/status reaches a terminal state: Succeeded, Failed, Cancelled, OutcomeUnknown, Skipped. Endpoint reference.

5. Read cell outputs

GET /api/v1/notebooks/{{notebook_id}}/runs/{{notebook_run}}/cells/{{execution_id}}/outputs
Host: <ENGINE_HOST>

Endpoint reference.

6. Close the notebook session

DELETE /api/v1/notebooks/{{notebook_id}}/sessions/{{notebook_session}}
Host: <ENGINE_HOST>

Endpoint reference. The document follows the notebook JSON format. Creation returns a notebook identity and revision. Session creation returns a notebook session identity, which is different from an interactive SQL session ID. Follow the notebook run. Read the returned cell execution IDs before requesting cell outputs or events; a document cell ID is not an execution ID. The sample query should return three category totals: Books 60, Games 45, and Garden 35. Close the notebook session after execution finishes. Keep or delete the saved notebook using its current revision. If you export it, choose whether outputs should be included; retained outputs can make the export much larger.

Transformation Engine

Learn Laminar

Workloads

SQL reference

HTTP API

Recipes

Operations

Run an inline SQL notebook

1. Create a SQL notebook

2. Open the SQL kernel

3. Run the notebook

4. Follow cell execution

5. Read cell outputs

6. Close the notebook session

​Run an inline SQL notebook

​1. Create a SQL notebook

​2. Open the SQL kernel

​3. Run the notebook

​4. Follow cell execution

​5. Read cell outputs

​6. Close the notebook session

Run an inline SQL notebook

1. Create a SQL notebook

2. Open the SQL kernel

3. Run the notebook

4. Follow cell execution

5. Read cell outputs

6. Close the notebook session