:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
"""Drive every runnable cell of one markdown notebook, in document order.
The orchestration lives in the backend, so the editor and an agent over MCP start the same
run through the same endpoints. This module owns the run record: planning the cells,
starting the workflow, reading the run back, stopping it, and closing it out. The Temporal
workflow in `temporal/notebook_run.py` is the loop that walks the plan, and it calls the
same `dispatch_node_run` a person's click does.
Document order is dependency order: a cell can only read exports of earlier cells, which is
the rule the editor's staleness chain already relies on. So the plan needs no sorting.
"""
from typing import Any, TypedDict
from uuid import UUID
from django.db import IntegrityError, transaction
from django.utils import timezone
import structlog
from posthog.dataclasses import frozen
from posthog.models import Team, User
from products.notebooks.backend.models import Notebook, NotebookNodeRun, NotebookRun
from products.notebooks.backend.sql_v2 import SQLV2KernelNotRunning, interrupt_sql_v2_run
from products.notebooks.backend.sql_v2_direct import cancel_direct_run
from products.notebooks.backend.sql_v2_dispatch import (
NodeRunRequest,
RefSpec,
resolve_team_notebook,
resolve_user,
sandbox_disclosure,
)
from products.notebooks.backend.sql_v2_metrics import (
OUTCOME_TIMED_OUT,
outcome_for_status,
record_notebook_run_terminal,
)
from products.notebooks.backend.sql_v2_runs import finish_node_run
from products.notebooks.backend.sql_v2_state import MAX_NOTEBOOK_CELLS, NotebookCellLimitExceeded, extract_cells
from products.notebooks.backend.sql_v2_variables import build_notebook_variables
logger = structlog.get_logger(__name__)
RUNNABLE_CELL_TYPES = ("sql", "python")
_NOTHING_TO_RUN = (
"This notebook has no SQL or Python cells with code in them, so there is nothing to run. Add a cell first."
)
_ALREADY_RUNNING = "This notebook is already running. Wait for it to finish, or stop it first."
class PlannedCell(TypedDict):
"""One entry of `NotebookRun.cell_plan`, as it is stored in JSON."""
node_id: str
cell_type: str
dataframe_name: str
code: str
connection_id: str | None
send_raw_query: bool
class NotebookRunNothingToRun(Exception):
"""The notebook holds no cell this run could execute."""
class NotebookRunAlreadyRunning(Exception):
"""A whole-notebook run is already in flight for this notebook."""
@frozen
class NotebookRunStart:
"""What the caller has to tell the user once a whole-notebook run is on its way."""
notebook_run: NotebookRun
cell_count: int
starts_sandbox: bool
sandbox_hourly_price: float | None
def plan_notebook_cells(notebook: Notebook, *, include_prepared_insights: bool = False) -> list[PlannedCell]:
"""The cells this run will execute, in document order, as the plan is stored.
The whole cell is frozen here, code included, not just which cells run. Two reasons, and
the security one decides it: notebook write access and query access are separate grants,
so an editor who cannot run queries could otherwise swap a later cell's code after
somebody else starts the run, and the workflow would execute it under the initiator's
access. Reading the code once, at the moment the starting request passes the query-access
check, closes that. It also makes the run reproducible — a cell edited or deleted
mid-run still executes what the plan captured, which is what the record claims it ran.
"""
plan = [
PlannedCell(
node_id=cell.node_id,
cell_type="sql" if cell.cell_type == "saved_insight" else cell.cell_type,
dataframe_name=cell.dataframe_name,
code=cell.code,
connection_id=cell.connection_id,
send_raw_query=cell.send_raw_query,
)
for cell in extract_cells(notebook.content)
if (cell.cell_type in RUNNABLE_CELL_TYPES or (include_prepared_insights and cell.cell_type == "saved_insight"))
and cell.code.strip()
]
if len(plan) > MAX_NOTEBOOK_CELLS:
raise NotebookCellLimitExceeded(
f"A notebook run can execute at most {MAX_NOTEBOOK_CELLS} cells. Remove cells before running it again."
)
return plan
def _create_notebook_run(
notebook: Notebook,
user: User | None,
team: Team,
*,
trigger: str,
include_prepared_insights: bool = False,
) -> NotebookRunStart:
"""Create the run record for `notebook` and price the sandbox it may start.
The caller saves any new variables before calling this, so the snapshot the run binds
matches the document a reader will compare the results against. Starting the workflow is
the caller's last step, once the record exists.
"""
cell_plan = plan_notebook_cells(notebook, include_prepared_insights=include_prepared_insights)
if not cell_plan:
raise NotebookRunNothingToRun(_NOTHING_TO_RUN)
try:
# The savepoint keeps the IntegrityError from poisoning a caller's transaction: the
# start endpoint wraps this together with its variable save, so a refused run has to
# leave that transaction usable enough to roll back cleanly.
with transaction.atomic():
notebook_run = NotebookRun.objects.create(
team_id=team.id,
notebook=notebook,
user=user,
trigger=trigger,
variables=notebook.variables or [],
cell_plan=cell_plan,
)
except IntegrityError as e:
# The partial unique constraint, not a lock: one running row per notebook.
raise NotebookRunAlreadyRunning(_ALREADY_RUNNING) from e
starts_sandbox, hourly_price = sandbox_disclosure(
notebook,
user,
uses_sandbox=any(cell["cell_type"] == "python" for cell in cell_plan),
)
return NotebookRunStart(
notebook_run=notebook_run,
cell_count=len(cell_plan),
starts_sandbox=starts_sandbox,
sandbox_hourly_price=hourly_price,
)
@frozen
class NotebookRunStarted:
"""What a caller needs once the run record exists, without handing over the row.
`node_ids` is the frozen plan's order, which is what the workflow input carries.
"""
run_id: UUID
node_ids: list[str]
cell_count: int
starts_sandbox: bool
sandbox_hourly_price: float | None
def start_notebook_run(
*,
team_id: int,
notebook_short_id: str,
user_id: int | None,
trigger: str,
include_prepared_insights: bool = False,
) -> NotebookRunStarted:
"""Create the run record for a notebook addressed by id, and price the sandbox it may start.
Raises `NotebookRunNothingToRun` when the notebook holds no runnable cell, and
`NotebookRunAlreadyRunning` when one is already in flight.
"""
notebook = resolve_team_notebook(team_id, notebook_short_id)
start = _create_notebook_run(
notebook,
resolve_user(user_id),
notebook.team,
trigger=trigger,
include_prepared_insights=include_prepared_insights,
)
return NotebookRunStarted(
run_id=start.notebook_run.id,
node_ids=[cell["node_id"] for cell in start.notebook_run.cell_plan],
cell_count=start.cell_count,
starts_sandbox=start.starts_sandbox,
sandbox_hourly_price=start.sandbox_hourly_price,
)
def read_notebook_run(*, team_id: int, notebook_short_id: str, run_id: str | UUID) -> dict[str, Any] | None:
"""One run as a client reads it, or None when this notebook has no such run."""
notebook = resolve_team_notebook(team_id, notebook_short_id)
notebook_run = get_notebook_run(team_id, notebook, run_id)
return notebook_run_status(notebook_run) if notebook_run is not None else None
@frozen
class NotebookRunStopped:
"""The outcome of a stop request: whether it stopped the run, and where the run landed."""
interrupted: bool
status: str
def stop_notebook_run(*, team_id: int, notebook_short_id: str, run_id: str | UUID) -> NotebookRunStopped | None:
"""Stop a run. `interrupted` is False when it had already finished, which is not an error.
None means this notebook has no such run, which the caller reports as a 404.
"""
notebook = resolve_team_notebook(team_id, notebook_short_id)
notebook_run = get_notebook_run(team_id, notebook, run_id)
if notebook_run is None:
return None
interrupted = interrupt_notebook_run(notebook, notebook_run)
notebook_run.refresh_from_db(fields=["status"])
return NotebookRunStopped(interrupted=interrupted, status=notebook_run.status)
def fail_notebook_run(*, team_id: int, run_id: str | UUID, error: str) -> None:
"""Close out a run nothing will ever drive, so the notebook is not left blocked."""
notebook_run = NotebookRun.objects.for_team(team_id).filter(id=run_id).first()
if notebook_run is not None:
finish_notebook_run(notebook_run, NotebookRun.Status.FAILED, error=error)
def node_run_request_for(notebook_run: NotebookRun, index: int) -> NodeRunRequest:
"""Build the dispatch request for the cell at `index` of the frozen plan.
Refs follow the run-ref convention the clients use: every earlier SQL cell with a valid
dataframe name is a `hogql` ref, every earlier Python cell is a `local` ref, and SQL wins
a name collision. `dispatch_node_run` then keeps only the names the code reads.
"""
plan: list[PlannedCell] = notebook_run.cell_plan
cell = plan[index]
refs: dict[str, RefSpec] = {}
for earlier in plan[:index]:
if earlier["cell_type"] == "sql" and earlier["dataframe_name"]:
refs.setdefault(earlier["dataframe_name"], RefSpec(node_id=earlier["node_id"], kind="hogql"))
for earlier in plan[:index]:
if earlier["cell_type"] == "python" and earlier["dataframe_name"]:
refs.setdefault(earlier["dataframe_name"], RefSpec(node_id=earlier["node_id"], kind="local"))
# Only a SQL cell carries a connection; python always runs in the kernel against PostHog,
# which is the same rule the single-cell endpoint applies.
is_python = cell["cell_type"] == "python"
connection_id = cell.get("connection_id") if not is_python else None
return NodeRunRequest(
node_id=cell["node_id"],
node_type="python" if is_python else "hogql",
code=cell["code"],
output_name=cell["dataframe_name"],
refs=refs,
variables=build_notebook_variables(notebook_run.variables or []),
connection_id=UUID(connection_id) if connection_id else None,
send_raw_query=bool(cell.get("send_raw_query")) and connection_id is not None,
notebook_run_id=notebook_run.id,
)
def notebook_run_status(notebook_run: NotebookRun) -> dict[str, Any]:
"""The whole run as a client reads it: its state, and one line per planned cell.
Cheap by design. It carries no result envelopes — a client fetches the one cell it wants
to show from the existing run-result endpoint.
"""
plan: list[PlannedCell] = notebook_run.cell_plan or []
latest_by_node: dict[str, Any] = {}
for node_run in (
NotebookNodeRun.objects.for_team(notebook_run.team_id)
.filter(notebook_run=notebook_run)
.order_by("node_id", "-created_at")
# Columns, not rows. A run row carries its whole result envelope and its code, and
# this response uses neither, so loading rows would drag every earlier cell's output
# back on every two-second poll — megabytes per cell, fifty cells at the ceiling.
# `values` rather than `only` so a later edit cannot quietly fetch one per cell.
.values("id", "node_id", "status", "error", "connection_id", "send_raw_query")
):
latest_by_node.setdefault(node_run["node_id"], node_run)
cells = []
for cell in plan:
latest = latest_by_node.get(cell["node_id"])
cells.append(
{
"node_id": cell["node_id"],
"cell_type": cell["cell_type"],
"dataframe_name": cell["dataframe_name"],
"run_id": str(latest["id"]) if latest else None,
"status": latest["status"] if latest else None,
"error": (latest["error"] or None) if latest else None,
# Not part of the response: the view reads it to decide whether this
# caller may see the cell's error, which can carry engine detail.
"connection_id": str(latest["connection_id"]) if latest and latest["connection_id"] else None,
"send_raw_query": bool(latest["send_raw_query"]) if latest else False,
}
)
current = plan[notebook_run.current_index] if notebook_run.current_index < len(plan) else None
return {
"run_id": str(notebook_run.id),
"status": notebook_run.status,
"trigger": notebook_run.trigger,
"variables": notebook_run.variables or [],
"cell_count": len(plan),
"current_index": notebook_run.current_index,
"current_node_id": current["node_id"] if current else None,
"failed_node_id": notebook_run.failed_node_id,
"error": notebook_run.error,
"cells": cells,
"created_at": notebook_run.created_at,
"finished_at": notebook_run.finished_at,
}
def finish_notebook_run(
notebook_run: NotebookRun,
status: str,
*,
failed_node_id: str | None = None,
error: str | None = None,
outcome: str | None = None,
) -> bool:
"""Move a RUNNING run to a terminal state; return whether this call won the transition.
Guarded on the current status, the same pattern as `finish_node_run`, so a retried
activity and a racing interrupt stay idempotent and report the run's outcome once.
"""
updated = (
NotebookRun.objects.for_team(notebook_run.team_id)
.filter(id=notebook_run.id, status=NotebookRun.Status.RUNNING)
.update(
status=status,
failed_node_id=failed_node_id,
error=error,
finished_at=timezone.now(),
updated_at=timezone.now(),
)
)
notebook_run.refresh_from_db(
from_queryset=NotebookRun.objects.for_team(notebook_run.team_id).select_related("user", "notebook")
)
if updated:
record_notebook_run_terminal(notebook_run, outcome or outcome_for_status(status))
return bool(updated)
def interrupt_notebook_run(notebook: Notebook, notebook_run: NotebookRun) -> bool:
"""Stop a running notebook run; return whether this call stopped it.
Marks the run first, so the workflow reads `interrupted` before it dispatches the next
cell even if stopping the current one is slow. Idempotent: interrupting a run that
already finished changes nothing.
"""
if not finish_notebook_run(notebook_run, NotebookRun.Status.INTERRUPTED, error="Run stopped."):
return False
stop_current_cell(notebook, notebook_run)
return True
def stop_current_cell(notebook: Notebook, notebook_run: NotebookRun) -> None:
"""Stop the cell this run left in flight, whichever lane it is on.
The kernel is resolved for the run's own user, never for whoever asked to stop it:
runtimes are per user, so signalling the caller's kernel would leave the initiator's
Python cell running and still burning compute after a successful interrupt.
"""
run = (
NotebookNodeRun.objects.for_team(notebook_run.team_id)
.filter(notebook_run=notebook_run, status=NotebookNodeRun.Status.RUNNING)
.order_by("-created_at")
.first()
)
if run is None:
return
if run.node_type == NotebookNodeRun.NodeType.HOGQL:
# A direct run has no kernel to signal, so stop it at the query manager. Mark the row
# first, so the stop is durable even if the cancellation below is slow or fails.
if finish_node_run(run, NotebookNodeRun.Status.INTERRUPTED, error="Run stopped."):
cancel_direct_run(run)
return
owner = notebook_run.user if isinstance(notebook_run.user, User) else None
try:
if not interrupt_sql_v2_run(notebook, owner, run):
# The kernel has never heard of this run, so its dispatch is still queued and
# there is nothing there to interrupt. Marking the row terminal is the
# cancellation: `dispatch_sql_v2_run_activity` reads it before handing the code
# over, so the cell never starts. Left RUNNING, it would start after the user
# was told it had stopped, and a repeat Stop returns early because the run is
# already terminal.
finish_node_run(run, NotebookNodeRun.Status.INTERRUPTED, error="Run stopped.")
except SQLV2KernelNotRunning:
# No reachable kernel, so the callback can never arrive. A late one simply overwrites
# this with the real outcome.
finish_node_run(
run, NotebookNodeRun.Status.INTERRUPTED, error="Kernel is not reachable, so the run was stopped."
)
except Exception:
logger.exception("notebook_run_interrupt_cell_failed", notebook_run_id=str(notebook_run.id))
def get_notebook_run(team_id: int, notebook: Notebook, run_id: str | UUID) -> NotebookRun | None:
return NotebookRun.objects.for_team(team_id).filter(id=run_id, notebook=notebook).first()
def active_notebook_run(team_id: int, notebook: Notebook) -> NotebookRun | None:
return (
NotebookRun.objects.for_team(team_id)
.filter(notebook=notebook, status=NotebookRun.Status.RUNNING)
.order_by("-created_at")
.first()
)
__all__ = [
"OUTCOME_TIMED_OUT",
"NotebookRunAlreadyRunning",
"NotebookRunNothingToRun",
"NotebookRunStart",
"active_notebook_run",
"finish_notebook_run",
"get_notebook_run",
"interrupt_notebook_run",
"node_run_request_for",
"notebook_run_status",
"plan_notebook_cells",
"start_notebook_run",
"stop_current_cell",
]