: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
import {
MakeLogicType,
actions,
afterMount,
beforeUnmount,
connect,
kea,
key,
listeners,
path,
props,
reducers,
selectors,
} from 'kea'
import posthog from 'posthog-js'
import api from 'lib/api'
import { ApiError } from 'lib/api-error'
import { JSONContent } from 'lib/components/RichContentEditor/types'
import { FEATURE_FLAGS } from 'lib/constants'
import { lemonToast } from 'lib/lemon-ui/LemonToast/LemonToast'
import { FeatureFlagsSet, featureFlagLogic } from 'lib/logic/featureFlagLogic'
import { notebookResultPreview } from 'products/notebooks/notebookResultPreview'
import { notebookJupyterLogic } from '../Notebook/notebookJupyterLogic'
import { notebookKernelInfoLogic } from '../Notebook/notebookKernelInfoLogic'
import {
NotebookNodeRunTerminalStatus,
NotebookStaleReason,
notebookNodeStalenessLogic,
} from '../Notebook/notebookNodeStalenessLogic'
import { NotebookOperation, notebookOperationsLogic } from '../Notebook/notebookOperationsLogic'
import { notebookSettingsLogic } from '../Notebook/notebookSettingsLogic'
import { NotebookVariable } from '../Notebook/notebookVariables'
import { sandboxStartMessage } from '../Notebook/SandboxStartMessage'
import { NotebookNodeType } from '../types'
import {
buildNotebookDependencyGraph,
collectNotebookDataframeNodes,
extractDuckSqlTables,
} from './notebookNodeContent'
import { NotebookNodeSQLV2Result } from './NotebookNodeSQLV2'
export type SqlV2RunRef = {
node_id: string
// 'hogql' is a SQL node's query definition; 'local' is a dataframe a Python cell bound in
// the kernel namespace. The backend routes a SQL run to ClickHouse or the sandbox's DuckDB
// based on which kinds the query actually references.
kind: 'hogql' | 'local'
}
// Turn a run/result request failure into a message the user can act on. The browser endpoints
// render every 404 as DRF's generic {"detail": "Not found."}, so the response can't say what is
// gone — the caller does, via notFoundKind: a run dispatch that 404s means the notebook itself is
// gone, while a result poll or page fetch that 404s means that run's result is gone. Every other
// failure keeps its original message.
export function sqlV2RunErrorMessage(
error: unknown,
fallback: string,
notFoundKind: 'notebook' | 'result' = 'result'
): string {
if (error instanceof ApiError && error.status === 404) {
return notFoundKind === 'notebook'
? 'This notebook could not be found. It may have been deleted.'
: 'This query result is no longer available. Run the cell again.'
}
return error instanceof Error ? error.message : fallback
}
// Map every sibling cell's dataframe name -> {node id, kind}, excluding the running node itself.
// SQLV2 siblings delegate to collectSqlV2Nodes so duplicate names get the same disambiguated
// form the dependency graph shows (sql_df, sql_df_2, …) — raw attributes would let a later
// duplicate silently shadow the node the user actually referenced. Python siblings contribute
// their returnVariable verbatim (it IS the kernel variable); on a name collision the SQL ref
// wins, since SQL names are already disambiguated in the UI and kernel variables are not.
// The backend resolves each referenced hogql node to its last-run query — the frontend only
// supplies the wiring.
export function collectSqlV2Refs(doc: JSONContent | null | undefined, selfNodeId: string): Record<string, SqlV2RunRef> {
const refs: Record<string, SqlV2RunRef> = {}
for (const { node, nodeId, exportedName } of collectNotebookDataframeNodes(doc)) {
if (nodeId !== selfNodeId && exportedName) {
refs[exportedName] = { node_id: nodeId, kind: node.type === NotebookNodeType.PythonV2 ? 'local' : 'hogql' }
}
}
return refs
}
// How often the poller re-checks a run, by how long it already waited. A cell that
// materializes a large frame can legitimately run for many minutes, and a flat one-second
// cadence across that window costs hundreds of requests for a single cell, so the interval
// widens once nobody is plausibly still watching the first result land.
const POLL_INTERVAL_STEPS_MS = [
{ afterMs: 120_000, intervalMs: 5_000 },
{ afterMs: 30_000, intervalMs: 2_000 },
{ afterMs: 0, intervalMs: 1_000 },
]
export function pollIntervalMs(waitedMs: number): number {
return POLL_INTERVAL_STEPS_MS.find(({ afterMs }) => waitedMs >= afterMs)?.intervalMs ?? 1_000
}
// Must outlast every backend run budget, so the client reports the run's real outcome rather
// than inventing one. The backend expires a stalled run itself, and a kernel cell may execute
// for up to 6 hours. Under that, a run the backend goes on to finish still reads here as a
// client timeout, and the cell renders as errored while the server is still working on it.
export const MAX_POLL_WAIT_MS = 7 * 60 * 60 * 1000
export const SQL_V2_DEFAULT_PAGE_SIZE = 50
export type NotebookNodeSQLV2Page = {
columns: string[]
types: [string, string][]
rows: (string | number | null)[][]
has_more: boolean
}
// The full capped row set a direct (ClickHouse, no-sandbox) run returns with its result,
// held in memory for client-side paging — never persisted into the document.
export type NotebookNodeSQLV2DirectRows = {
columns: string[]
types: [string, string][]
rows: (string | number | null)[][]
}
export interface RunQueryOptions {
nodeType?: 'hogql' | 'python'
outputName?: string
// SQL cells only: the data source to run against instead of PostHog, and whether to send the
// code to it verbatim. Absent means PostHog's own ClickHouse.
connectionId?: string | null
sendRawQuery?: boolean
}
// What an open editor holds right now, for the callers that can read it — the document only
// catches up to a keystroke or a just-picked connection on a later render.
export interface RunNodeOverrides {
code?: string
connectionId?: string | null
sendRawQuery?: boolean
}
export interface NotebookNodeSQLV2LogicProps {
nodeId: string
notebookShortId: string
// Current node attributes, so a fresh mount can recover an in-flight/finished run by its runId.
runId?: string | null
hasResult?: boolean
hasResultMetadata?: boolean
prepareInsightDataframes?: (code: string, nodeType: 'python' | 'hogql') => Promise<void>
updateAttributes: (attrs: {
nodeId?: string
returnVariable?: string
runId?: string | null
result?: NotebookNodeSQLV2Result | null
runStatus?: NotebookNodeRunTerminalStatus | null
}) => void
// The live notebook document, for staleness marking and chain-dispatched runs (Journey 10).
getContent?: () => JSONContent | null
// The notebook's variables, already filtered to the valid ones. A notebook property rather
// than document content, so it does not come out of getContent.
getVariables?: () => NotebookVariable[]
}
// Generated by kea-typegen. Update if you're an agent, ignore if you're human.
export interface notebookNodeSQLV2LogicValues {
featureFlags: FeatureFlagsSet // featureFlagLogic
isJupyterModeActive: boolean // notebookJupyterLogic
chainQueue: string[] // notebookNodeStalenessLogic
isChainRunning: boolean // notebookNodeStalenessLogic
lastRunNodeId: string | null // notebookNodeStalenessLogic
lastRunStaleDownstreamNodeIds: string[] // notebookNodeStalenessLogic
staleNodeIds: Record<string, NotebookStaleReason> // notebookNodeStalenessLogic
activeOperation: NotebookOperation | null // notebookOperationsLogic
isBusy: boolean // notebookOperationsLogic
runQueue: string[] // notebookOperationsLogic
directRows: NotebookNodeSQLV2DirectRows | null
isInterrupting: boolean
isQueued: boolean
isRestoringResult: boolean
isRunning: boolean
isSandboxComputeFree: boolean
isStale: boolean
operationBlockReason: string | null
page: number
pageLoading: boolean
pageResult: NotebookNodeSQLV2Page | null
pageSize: number
pendingKernelStart: boolean
result: NotebookNodeSQLV2Result | null
resultRestoreUnavailable: boolean
runError: string | null
staleDownstreamCount: number
staleReason: NotebookStaleReason | null
}
// Generated by kea-typegen. Update if you're an agent, ignore if you're human.
export interface notebookNodeSQLV2LogicActions {
adoptChainRun: (
nodeId: string,
runId: string
) => {
nodeId: string
runId: string
} // notebookNodeStalenessLogic
dispatchChainRun: (nodeId: string) => {
nodeId: string
} // notebookNodeStalenessLogic
nodeRunFinished: (
nodeId: string,
status: NotebookNodeRunTerminalStatus,
content: JSONContent | null
) => {
content: JSONContent | null
nodeId: string
status: NotebookNodeRunTerminalStatus
} // notebookNodeStalenessLogic
registerChainNode: (nodeId: string) => {
nodeId: string
} // notebookNodeStalenessLogic
runStaleChain: (
content: JSONContent | null,
rootNodeId?: string | null | undefined
) => {
content: JSONContent | null
rootNodeId: string | null
} // notebookNodeStalenessLogic
unregisterChainNode: (nodeId: string) => {
nodeId: string
} // notebookNodeStalenessLogic
dequeueRun: (nodeId: string) => {
nodeId: string
} // notebookOperationsLogic
enqueueRun: (nodeId: string) => {
nodeId: string
} // notebookOperationsLogic
finishNodeOperations: (nodeId: string) => {
nodeId: string
} // notebookOperationsLogic
finishOperation: (id: string) => {
id: string
} // notebookOperationsLogic
releaseQueuedRun: (nodeId: string) => {
nodeId: string
} // notebookOperationsLogic
settleReleasedRun: (nodeId: string) => {
nodeId: string
} // notebookOperationsLogic
startOperation: (operation: NotebookOperation) => {
operation: NotebookOperation
} // notebookOperationsLogic
setShowKernelInfo: (showKernelInfo: boolean) => {
showKernelInfo: boolean
} // notebookSettingsLogic
announceSandboxStart: (hourlyPrice: number | null) => {
hourlyPrice: number | null
}
interruptRun: () => {
value: true
}
pollResult: (runId: string) => {
runId: string
}
resetPaging: () => {
value: true
}
resultRestoreFailed: () => {
value: true
}
runNode: (overrides?: RunNodeOverrides) => {
overrides: RunNodeOverrides
}
runQuery: (
code: string,
refs?: Record<string, SqlV2RunRef>,
opts?: RunQueryOptions
) => {
code: string
opts: RunQueryOptions
refs: Record<string, SqlV2RunRef>
}
setDirectRows: (directRows: NotebookNodeSQLV2DirectRows | null) => {
directRows: NotebookNodeSQLV2DirectRows | null
}
setIsInterrupting: (isInterrupting: boolean) => {
isInterrupting: boolean
}
setIsRunning: (isRunning: boolean) => {
isRunning: boolean
}
setPage: (page: number) => {
page: number
}
setPageLoading: (pageLoading: boolean) => {
pageLoading: boolean
}
setPageResult: (pageResult: NotebookNodeSQLV2Page | null) => {
pageResult: NotebookNodeSQLV2Page | null
}
setPageSize: (pageSize: number) => {
pageSize: number
}
setPendingKernelStart: (pendingKernelStart: boolean) => {
pendingKernelStart: boolean
}
setResult: (result: NotebookNodeSQLV2Result | null) => {
result: NotebookNodeSQLV2Result | null
}
setRunError: (runError: string | null) => {
runError: string | null
}
startPolling: (
runId: string,
restoring?: boolean
) => {
restoring: boolean
runId: string
}
stopPolling: () => {
value: true
}
}
// Generated by kea-typegen. Update if you're an agent, ignore if you're human.
export interface notebookNodeSQLV2LogicMeta {
key: string
__keaTypeGenInternalSelectorTypes: {
isSandboxComputeFree: (featureFlags: FeatureFlagsSet) => boolean
isQueued: (runQueue: string[]) => boolean
operationBlockReason: (activeOperation: NotebookOperation | null) => string | null
isStale: (staleNodeIds: Record<string, NotebookStaleReason>) => boolean
staleReason: (staleNodeIds: Record<string, NotebookStaleReason>) => NotebookStaleReason | null
staleDownstreamCount: (lastRunNodeId: string | null, lastRunStaleDownstreamNodeIds: string[]) => number
}
}
export type notebookNodeSQLV2LogicType = MakeLogicType<
notebookNodeSQLV2LogicValues,
notebookNodeSQLV2LogicActions,
NotebookNodeSQLV2LogicProps,
notebookNodeSQLV2LogicMeta
>
export const notebookNodeSQLV2Logic = kea<notebookNodeSQLV2LogicType>([
path((key) => ['scenes', 'notebooks', 'Nodes', 'notebookNodeSQLV2Logic', key]),
props({} as NotebookNodeSQLV2LogicProps),
key((props) => props.nodeId),
connect((props: NotebookNodeSQLV2LogicProps) => ({
values: [
featureFlagLogic,
['featureFlags'],
notebookOperationsLogic({ shortId: props.notebookShortId }),
['activeOperation', 'isBusy', 'runQueue'],
notebookJupyterLogic({ shortId: props.notebookShortId }),
['isActive as isJupyterModeActive'],
notebookNodeStalenessLogic({ shortId: props.notebookShortId }),
['staleNodeIds', 'chainQueue', 'isChainRunning', 'lastRunNodeId', 'lastRunStaleDownstreamNodeIds'],
],
actions: [
notebookOperationsLogic({ shortId: props.notebookShortId }),
[
'startOperation',
'finishOperation',
'finishNodeOperations',
'enqueueRun',
'dequeueRun',
'releaseQueuedRun',
'settleReleasedRun',
],
notebookNodeStalenessLogic({ shortId: props.notebookShortId }),
[
'nodeRunFinished',
'dispatchChainRun',
'adoptChainRun',
'runStaleChain',
'registerChainNode',
'unregisterChainNode',
],
notebookSettingsLogic,
['setShowKernelInfo'],
],
})),
actions({
setResult: (result: NotebookNodeSQLV2Result | null) => ({ result }),
// refs maps each named sibling cell's dataframe name to {node id, kind}. A SQL node
// inlines referenced hogql refs as CTEs (Journey 3) — or runs locally in DuckDB when
// it references a local frame (Journey 5); a python node materializes the hogql refs
// its code reads as pandas frames (Journey 4).
runQuery: (code: string, refs: Record<string, SqlV2RunRef> = {}, opts: RunQueryOptions = {}) => ({
code,
refs,
opts,
}),
// Run this cell the way its own Run button does, deriving the code, the refs and the run
// options from the live document rather than from the caller. The single entry point for
// every run trigger — the toolbar button, Cmd+Enter, a chain dispatch — so a cell runs the
// same way whether or not its editor is on screen.
runNode: (overrides: RunNodeOverrides = {}) => ({ overrides }),
startPolling: (runId: string, restoring: boolean = false) => ({ runId, restoring }),
resultRestoreFailed: true,
pollResult: (runId: string) => ({ runId }),
stopPolling: true,
interruptRun: true,
setIsInterrupting: (isInterrupting: boolean) => ({ isInterrupting }),
setIsRunning: (isRunning: boolean) => ({ isRunning }),
setRunError: (runError: string | null) => ({ runError }),
setPage: (page: number) => ({ page }),
setPageSize: (pageSize: number) => ({ pageSize }),
setPageResult: (pageResult: NotebookNodeSQLV2Page | null) => ({ pageResult }),
setPageLoading: (pageLoading: boolean) => ({ pageLoading }),
resetPaging: true,
setDirectRows: (directRows: NotebookNodeSQLV2DirectRows | null) => ({ directRows }),
setPendingKernelStart: (pendingKernelStart: boolean) => ({ pendingKernelStart }),
announceSandboxStart: (hourlyPrice: number | null) => ({ hourlyPrice }),
}),
reducers({
isRestoringResult: [
false,
{ startPolling: (_, { restoring }) => restoring, stopPolling: () => false, runQuery: () => false },
],
resultRestoreUnavailable: [
false,
{ resultRestoreFailed: () => true, runQuery: () => false, startPolling: () => false },
],
result: [
null as NotebookNodeSQLV2Result | null,
{
runQuery: () => null,
setResult: (_, { result }) => result,
},
],
// Tracks the run being in progress; driven by the run's status, not a socket lifecycle.
isRunning: [
false,
{
runQuery: () => true,
startPolling: (_, { restoring }) => !restoring,
setIsRunning: (_, { isRunning }) => isRunning,
},
],
runError: [
null as string | null,
{
runQuery: () => null,
startPolling: () => null,
setRunError: (_, { runError }) => runError,
},
],
// The interrupt POST (or the wait for its effect) is in flight; guards the Cancel
// button against double submission; any terminal poll state resets it.
isInterrupting: [
false,
{
interruptRun: () => true,
setIsInterrupting: (_, { isInterrupting }) => isInterrupting,
stopPolling: () => false,
runQuery: () => false,
},
],
page: [
1,
{
setPage: (_, { page }) => Math.max(1, page),
setPageSize: () => 1,
resetPaging: () => 1,
runQuery: () => 1,
},
],
pageSize: [
SQL_V2_DEFAULT_PAGE_SIZE as number,
{
setPageSize: (_, { pageSize }) => pageSize,
resetPaging: () => SQL_V2_DEFAULT_PAGE_SIZE,
},
],
// Rows fetched for the current page; null means "show the envelope's first page".
pageResult: [
null as NotebookNodeSQLV2Page | null,
{
setPageResult: (_, { pageResult }) => pageResult,
resetPaging: () => null,
runQuery: () => null,
},
],
pageLoading: [
false,
{
setPageLoading: (_, { pageLoading }) => pageLoading,
resetPaging: () => false,
},
],
// Session-local rows for client-side paging of direct runs; a new run invalidates them.
directRows: [
null as NotebookNodeSQLV2DirectRows | null,
{
setDirectRows: (_, { directRows }) => directRows,
runQuery: () => null,
},
],
// A kernel-lane run was submitted while no kernel was known to be up: the backend is
// provisioning the sandbox; drives the "Starting compute sandbox…" caption.
pendingKernelStart: [
false,
{
setPendingKernelStart: (_, { pendingKernelStart }) => pendingKernelStart,
stopPolling: () => false,
},
],
}),
listeners(({ props, actions, cache, values }) => {
// One operation at a time across the whole notebook (see notebookOperationsLogic);
// ids are per node + kind so re-registering our own operation stays idempotent.
const runOperation: NotebookOperation = { id: `${props.nodeId}:run`, nodeId: props.nodeId, kind: 'run' }
const pageOperation: NotebookOperation = { id: `${props.nodeId}:page`, nodeId: props.nodeId, kind: 'page' }
// Slice a page out of the in-memory direct-run rows — no network, no operation lock.
const sliceDirectRows = (rows: NotebookNodeSQLV2DirectRows, page: number, pageSize: number): void => {
const start = (page - 1) * pageSize
actions.setPageResult({
columns: rows.columns,
types: rows.types,
rows: rows.rows.slice(start, start + pageSize),
has_more: start + pageSize < rows.rows.length,
})
}
const loadCurrentPage = async (): Promise<void> => {
const { page, pageSize } = values
const runId = props.runId
if (!runId) {
return
}
if (page === 1 && pageSize === SQL_V2_DEFAULT_PAGE_SIZE) {
// The envelope already carries this page — no round trip.
actions.setPageResult(null)
return
}
if (values.directRows) {
sliceDirectRows(values.directRows, page, pageSize)
return
}
// The pagination UI is disabled while the notebook is busy; this guards the
// programmatic path. A same-node re-page supersedes (stale response discarded below).
if (values.isBusy && values.activeOperation?.id !== pageOperation.id) {
lemonToast.info('Another operation is running in this notebook — wait for it to finish.')
actions.resetPaging()
return
}
actions.startOperation(pageOperation)
const fetchId = (cache.pageFetchId = (cache.pageFetchId ?? 0) + 1)
actions.setPageLoading(true)
try {
// A direct run keeps its full row set on the result endpoint while the backend's
// query result is alive — recover it once (e.g. after a reload) and page locally
// from then on. Kernel runs return no rows here and fall through to server paging.
try {
const recovered = await api.notebooks.sqlV2RunResult(props.notebookShortId, runId)
if (recovered.status === 'done' && recovered.rows) {
const directRows: NotebookNodeSQLV2DirectRows = {
columns: recovered.result?.columns ?? [],
types: recovered.result?.types ?? [],
rows: recovered.rows,
}
actions.setDirectRows(directRows)
if (cache.pageFetchId === fetchId) {
sliceDirectRows(directRows, page, pageSize)
}
return
}
} catch {
// Recovery is best-effort; the server page below reports real errors.
}
const pageResult = await api.notebooks.sqlV2RunPage(props.notebookShortId, runId, {
offset: (page - 1) * pageSize,
limit: pageSize,
})
if (cache.pageFetchId === fetchId) {
actions.setPageResult(pageResult)
}
} catch (error: any) {
if (cache.pageFetchId !== fetchId) {
return
}
if (error?.status === 409) {
lemonToast.info('This result was replaced by a newer run — showing the latest first page.')
} else {
lemonToast.error(sqlV2RunErrorMessage(error, 'Failed to fetch page'))
}
// Either way the requested page never arrived — fall back to the envelope's
// first page rather than showing old rows under a new page number.
actions.resetPaging()
} finally {
// A superseding fetch re-registered the same operation id — leave the release to it.
if (cache.pageFetchId === fetchId) {
actions.setPageLoading(false)
actions.finishOperation(pageOperation.id)
}
}
}
return {
setPage: loadCurrentPage,
setPageSize: loadCurrentPage,
runQuery: async ({ code, refs, opts }) => {
if (cache.preparingInputs) {
return
}
cache.isRestoringResult = false
cache.activeRunId = null
cache.disposables.dispose('pollResult')
if (!code.trim()) {
actions.setRunError('Nothing to run — type some code first.')
actions.setIsRunning(false)
actions.nodeRunFinished(props.nodeId, 'failed', null)
return
}
// The run button is disabled while the notebook is busy; this guards Cmd+Enter
// and programmatic dispatch. Re-running our own node supersedes as before.
if (values.isBusy && values.activeOperation?.nodeId !== props.nodeId) {
actions.setIsRunning(false)
if (values.isJupyterModeActive) {
// Jupyter queues a cell behind a busy kernel, so the cell waits its turn.
cache.queuedRun = { code, refs, opts }
actions.enqueueRun(props.nodeId)
return
}
lemonToast.info('Another operation is running in this notebook — wait for it to finish.')
actions.nodeRunFinished(props.nodeId, 'failed', null)
return
}
cache.queuedRun = null
// Which lane will this run take? Mirrors the backend's routing: python always
// needs the kernel; SQL needs it only when it reads a local (python-made) frame,
// and never when it targets an external connection (the sandbox can't reach one).
// The backend stays authoritative — this only drives the kernel panel, never
// dispatch.
if (props.prepareInsightDataframes) {
cache.preparingInputs = true
try {
await props.prepareInsightDataframes(code, opts.nodeType ?? 'hogql')
refs = collectSqlV2Refs(props.getContent?.() ?? null, props.nodeId)
} catch (error) {
actions.setRunError(sqlV2RunErrorMessage(error, 'Could not prepare insight dataframes'))
actions.setIsRunning(false)
// A run the queue released never took the notebook, so the next queued cell must not keep waiting for it.
actions.settleReleasedRun(props.nodeId)
actions.nodeRunFinished(props.nodeId, 'failed', null)
return
} finally {
cache.preparingInputs = false
}
}
const isKernelLane =
opts.nodeType === 'python' ||
(!opts.connectionId && extractDuckSqlTables(code).some((name) => refs[name]?.kind === 'local'))
if (isKernelLane) {
// The backend provisions the sandbox itself when none is running; open the
// kernel panel so the user can watch it come up instead of guessing.
const kernelKnownRunning =
notebookKernelInfoLogic.findMounted({ shortId: props.notebookShortId })?.values.isRunning ??
false
if (!kernelKnownRunning) {
actions.setShowKernelInfo(true)
actions.setPendingKernelStart(true)
}
}
// Read from the notebook rather than the caller: every run path (Run button,
// Cmd+Enter, chain dispatch) needs the same notebook-level values.
const variables = props.getVariables?.() ?? []
actions.startOperation(runOperation)
try {
const runResponse = await api.notebooks.sqlV2Run(props.notebookShortId, {
node_id: props.nodeId,
code,
refs,
// Omitted when the notebook declares none, so an unchanged notebook's
// run body stays byte-identical to before.
...(variables.length ? { variables } : {}),
node_type: opts.nodeType,
output_name: opts.outputName,
// Omitted entirely for a PostHog cell — the backend's defaults say the same
// thing, and every existing run body stays byte-identical.
...(opts.connectionId
? { connection_id: opts.connectionId, send_raw_query: !!opts.sendRawQuery }
: {}),
})
// Mark this as the active run so a still-in-flight poll from a previous run
// can't overwrite this result or stop this run's poller once it resolves.
const run_id = runResponse.run_id
cache.activeRunId = run_id
// The backend decides this at dispatch, so it is the only accurate source.
// A kernel poll is up to ten seconds old, which is long enough to miss a
// sandbox that stopped inside that window and start paid compute silently.
if (runResponse.starts_sandbox) {
actions.announceSandboxStart(runResponse.sandbox_hourly_price ?? null)
}
// Persisting nodeId pins the cell's identity: markdown-notebook cell ids are
// content fingerprints otherwise, so without the pin any later prop change
// would orphan this run's node_id and break refs to this cell.
props.updateAttributes({
nodeId: props.nodeId,
...(opts.outputName !== undefined ? { returnVariable: opts.outputName } : {}),
runId: run_id,
result: null,
runStatus: null,
})
actions.startPolling(run_id)
} catch (error) {
actions.setRunError(sqlV2RunErrorMessage(error, 'Failed to run query', 'notebook'))
actions.setIsRunning(false)
actions.finishOperation(runOperation.id)
actions.nodeRunFinished(props.nodeId, 'failed', null)
}
},
announceSandboxStart: ({ hourlyPrice }) => {
// The panel that shows the price is only just opening, so say the rate in the
// toast too. A user who runs a Python cell never opens the panel deliberately and
// would otherwise start paid compute without being told what it costs. The price
// is null for a local docker kernel, which is free.
lemonToast.info(sandboxStartMessage(hourlyPrice, values.isSandboxComputeFree))
},
runNode: ({ overrides }) => {
const content = props.getContent?.() ?? null
const self = content ? buildNotebookDependencyGraph(content).nodesById[props.nodeId] : null
if (!content || !self) {
// A cell the document no longer holds can never report a result, so tell the
// staleness chain now rather than leave it waiting on this node.
actions.nodeRunFinished(props.nodeId, 'failed', null)
return
}
// The graph's returnVariable is the disambiguated frame name (sql_df, sql_df_2, …)
// downstream cells reference, which is what a rerouted run has to bind.
const opts: RunQueryOptions =
self.nodeType === NotebookNodeType.PythonV2
? { nodeType: 'python', outputName: self.returnVariable }
: {
outputName: self.returnVariable,
connectionId:
overrides.connectionId !== undefined
? overrides.connectionId
: (self.connectionId ?? null),
sendRawQuery: overrides.sendRawQuery ?? !!self.sendRawQuery,
}
actions.runQuery(overrides.code ?? self.code ?? '', collectSqlV2Refs(content, props.nodeId), opts)
},
// A chain-dispatched run (Journey 10): only the matching node acts, and it runs itself
// exactly as its own Run button would.
dispatchChainRun: ({ nodeId }) => {
if (nodeId === props.nodeId) {
actions.runNode()
}
},
// A run the backend started for this cell as part of a whole-notebook run. The cell
// did not dispatch it, so it pins the run id into the document and picks up the
// existing poll path, which writes the result and reports the outcome as usual.
// A cell that is not mounted adopts nothing; its runId reaches the document on the
// next poll that still sees the run, and afterMount recovers it from there.
adoptChainRun: ({ nodeId, runId }) => {
if (nodeId !== props.nodeId || cache.activeRunId === runId) {
return
}
cache.activeRunId = runId
props.updateAttributes({ nodeId: props.nodeId, runId, result: null, runStatus: null })
actions.startPolling(runId)
},
startPolling: ({ runId, restoring }) => {
cache.isRestoringResult = restoring
// Idempotent re-register: also covers a remount resuming a persisted in-flight run.
if (!cache.isRestoringResult) {
actions.startOperation(runOperation)
}
cache.activeRunId = runId
cache.pollWaitedMs = 0
actions.pollResult(runId)
// Same key auto-disposes any previous poller; disposables clean up on unmount and pause on hidden tab.
cache.disposables.add(() => {
// Reschedules itself rather than using setInterval, because the cadence
// widens as the wait grows.
let timeoutId = 0
const scheduleNext = (): void => {
timeoutId = window.setTimeout(
() => {
actions.pollResult(runId)
// pollResult can stop the poller synchronously when it reaches the
// budget, which disposes this entry. Re-arm only while it still
// owns a live poller, or the new timer would outlive the disposable
// and loop the failure forever.
if (cache.disposables.registry.has('pollResult')) {
scheduleNext()
}
},
pollIntervalMs(cache.pollWaitedMs ?? 0)
)
}
scheduleNext()
return () => clearTimeout(timeoutId)
}, 'pollResult')
},
pollResult: async ({ runId }) => {
const restoring = !!cache.isRestoringResult
if (cache.pollInFlight) {
return
}
// Accumulated from the intervals the poller actually used, not from the clock:
// it pauses while the tab is hidden, so a clock-based budget would burn down
// during a pause the user never spent waiting.
cache.pollWaitedMs = (cache.pollWaitedMs ?? 0) + pollIntervalMs(cache.pollWaitedMs ?? 0)
if (cache.pollWaitedMs > MAX_POLL_WAIT_MS) {
// Past every backend budget, so the server is unreachable rather than slow.
// The run keeps whatever outcome the server gave it; only this client gave up.
if (restoring) {
actions.resultRestoreFailed()
} else {
actions.setRunError(
'Stopped checking for a result. Reload the page to see if the run finished.'
)
}
actions.stopPolling()
if (!restoring) {
actions.nodeRunFinished(props.nodeId, 'failed', null)
}
return
}
cache.pollInFlight = true
try {
const { status, result, error, rows } = await api.notebooks.sqlV2RunResult(
props.notebookShortId,
runId
)
// A newer run started while this poll was in flight — its result and poller
// must win, so drop this stale response instead of overwriting/stopping it.
if (runId !== cache.activeRunId) {
return
}
// Once the kernel panel reports the sandbox up, the wait is execution, not startup.
if (
values.pendingKernelStart &&
notebookKernelInfoLogic.findMounted({ shortId: props.notebookShortId })?.values.isRunning
) {
actions.setPendingKernelStart(false)
}
const envelopeResult: NotebookNodeSQLV2Result | null = result
? {
columns: result.columns ?? [],
types: result.types ?? [],
row_count: result.row_count ?? 0,
first_page: result.first_page ?? [],
has_more: result.has_more ?? false,
stdout: result.stdout ?? '',
stderr: result.stderr ?? '',
media: result.media ?? [],
...(result.result_text ? { result_text: result.result_text } : {}),
}
: null
const resultMetadata = envelopeResult ? notebookResultPreview(envelopeResult) : null
if (status === 'done') {
// A direct run's full capped row set arrives with the result — keep it
// in memory for client-side paging (kernel runs return no rows here).
actions.setDirectRows(
rows
? {
columns: result?.columns ?? [],
types: result?.types ?? [],
rows,
}
: null
)
// The outcome rides along with the result so a reload can tell a completed
// run from an interrupted one — both leave a result behind.
actions.setResult(envelopeResult)
if (!restoring) {
props.updateAttributes({ result: resultMetadata, runStatus: 'done' })
}
// A fresh envelope replaces whatever page the user had drilled into.
actions.resetPaging()
actions.stopPolling()
// Downstream cells now derive from outdated data — mark them stale
// against the document as it stands now (Journey 10).
if (!restoring) {
actions.nodeRunFinished(props.nodeId, 'done', props.getContent?.() ?? null)
}
} else if (status === 'interrupted') {
// A user-requested stop: the envelope still carries whatever stdout,
// stderr, and figures the cell produced before the interrupt landed.
actions.setResult(envelopeResult)
if (!restoring) {
props.updateAttributes({ result: resultMetadata, runStatus: 'interrupted' })
}
if (!restoring) {
actions.setRunError(error ?? 'Run interrupted.')
}
actions.resetPaging()
actions.stopPolling()
if (!restoring) {
actions.nodeRunFinished(props.nodeId, 'interrupted', null)
}
} else if (status === 'failed') {
if (restoring) {
actions.resultRestoreFailed()
} else {
actions.setRunError(error ?? 'Run failed')
}
actions.stopPolling()
if (!restoring) {
actions.nodeRunFinished(props.nodeId, 'failed', null)
}
}
// 'running' → keep polling
} catch (error) {
if (runId !== cache.activeRunId) {
return
}
if (restoring) {
actions.resultRestoreFailed()
} else {
actions.setRunError(sqlV2RunErrorMessage(error, 'Failed to fetch result'))
}
actions.stopPolling()
if (!restoring) {
actions.nodeRunFinished(props.nodeId, 'failed', null)
}
} finally {
cache.pollInFlight = false
}
},
releaseQueuedRun: ({ nodeId }) => {
if (nodeId === props.nodeId && cache.queuedRun) {
const { code, refs, opts } = cache.queuedRun
cache.queuedRun = null
actions.runQuery(code, refs, opts)
}
},
interruptRun: async () => {
if (values.isQueued) {
// Never sent to the server, so stopping it only takes it out of the queue.
cache.queuedRun = null
actions.dequeueRun(props.nodeId)
actions.setIsInterrupting(false)
// Only a waiting chain needs to hear about it. Reporting it otherwise would give
// a cell that never ran an execution count.
if (values.chainQueue[0] === props.nodeId) {
actions.nodeRunFinished(props.nodeId, 'interrupted', null)
}
return
}
const runId = cache.activeRunId ?? props.runId
if (!runId || !values.isRunning) {
actions.setIsInterrupting(false)
return
}
try {
const response = await api.notebooks.sqlV2RunInterrupt(props.notebookShortId, runId)
if (response.detail) {
// Nothing was stopped (e.g. the run hasn't reached the kernel yet), so
// let the user retry instead of wedging the button in loading.
lemonToast.info(response.detail)
actions.setIsInterrupting(false)
}
// Otherwise stay interrupting until the poll observes the terminal state.
} catch (error: any) {
actions.setIsInterrupting(false)
lemonToast.error(error?.detail || error?.message || 'Failed to stop the run')
}
},
resultRestoreFailed: () => {
posthog.capture('notebook result restore failed', {
notebook_short_id: props.notebookShortId,
node_id: props.nodeId,
})
},
stopPolling: () => {
cache.isRestoringResult = false
cache.disposables.dispose('pollResult')
actions.setIsRunning(false)
actions.finishOperation(runOperation.id)
},
}
}),
selectors(({ props }) => ({
isSandboxComputeFree: [
(s) => [s.featureFlags],
(featureFlags: FeatureFlagsSet): boolean => !!featureFlags[FEATURE_FLAGS.NOTEBOOK_SANDBOX_FREE_COMPUTE],
],
isQueued: [(s) => [s.runQueue], (runQueue: string[]): boolean => runQueue.includes(props.nodeId)],
// Set while another node's operation is in flight — wire into disabledReason props.
operationBlockReason: [
(s) => [s.activeOperation],
(activeOperation: NotebookOperation | null): string | null =>
activeOperation && activeOperation.nodeId !== props.nodeId
? (activeOperation.label ?? 'Another operation is running in this notebook')
: null,
],
// An upstream cell's run landed after this cell last ran (Journey 10).
isStale: [
(s) => [s.staleNodeIds],
(staleNodeIds: Record<string, NotebookStaleReason>): boolean => !!staleNodeIds[props.nodeId],
],
// What made it stale, so the banner names the actual cause.
staleReason: [
(s) => [s.staleNodeIds],
(staleNodeIds: Record<string, NotebookStaleReason>): NotebookStaleReason | null =>
staleNodeIds[props.nodeId] ?? null,
],
// Non-zero only on the cell whose run most recently landed: how many of its
// downstream cells are still stale. Drives the "run downstream cells" button.
staleDownstreamCount: [
(s) => [s.lastRunNodeId, s.lastRunStaleDownstreamNodeIds],
(lastRunNodeId: string | null, lastRunStaleDownstreamNodeIds: string[]): number =>
lastRunNodeId === props.nodeId ? lastRunStaleDownstreamNodeIds.length : 0,
],
})),
afterMount(({ props, actions }) => {
// Only registered cells are eligible for chain dispatch — a dispatch to an unmounted
// cell would be picked up by nobody and wedge the chain.
actions.registerChainNode(props.nodeId)
// Recover after a reload/remount: a persisted runId with no result means the run may still be
// in flight or already finished — poll to catch up rather than lose the result.
if (props.runId && !props.hasResult) {
actions.startPolling(props.runId, !!props.hasResultMetadata)
}
}),
beforeUnmount(({ props, actions, values }) => {
actions.unregisterChainNode(props.nodeId)
// A deleted or unmounted cell must never leave the notebook wedged as busy.
actions.finishNodeOperations(props.nodeId)
// Nor leave a stale-cell chain waiting forever on a run that can no longer report.
if (values.chainQueue[0] === props.nodeId) {
actions.nodeRunFinished(props.nodeId, 'failed', null)
}
}),
])