: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 { deepEqual as equal } from 'fast-equals'
import { useActions, useMountedLogic, useValues } from 'kea'
import { type CSSProperties, useEffect, useMemo, useRef, useState } from 'react'
import { wasNotebookNodeJustInserted } from 'lib/components/MarkdownNotebook/freshlyInserted'
import { TreeDataItem } from 'lib/lemon-ui/LemonTree/LemonTree'
import { OutputTab, outputPaneLogic } from 'scenes/data-warehouse/editor/outputPaneLogic'
import { SQLEditor, SQLEditorPanel } from 'scenes/data-warehouse/editor/SQLEditor'
import { sqlEditorLogic } from 'scenes/data-warehouse/editor/sqlEditorLogic'
import { SQLEditorMode } from 'scenes/data-warehouse/editor/sqlEditorModes'
import { isDataVisualizationNode, isHogQLQuery } from '~/queries/schema/node-guards'
import { DataVisualizationNode, HogQLQuery, NodeKind, ProductKey, QuerySchema } from '~/queries/schema/schema-general'
import { convertDataTableNodeToDataVisualizationNode } from '~/queries/utils'
import { ChartDisplayType } from '~/types'
import { notebookKernelInfoLogic } from '../../Notebook/notebookKernelInfoLogic'
import { NotebookNodeAttributeProperties, NotebookNodeAttributes, NotebookNodeProps } from '../../types'
import { notebookNodeLogic } from '../notebookNodeLogic'
import { buildDataframeTreeSection } from './notebookDataframeTree'
export const EMBEDDED_SQL_EDITOR_DEFAULT_HEIGHT = 333
export const EMBEDDED_SQL_EDITOR_EDIT_DEFAULT_HEIGHT = 150
export const EMBEDDED_SQL_EDITOR_MIN_HEIGHT = 200
export const EMBEDDED_SQL_EDITOR_EDIT_MIN_HEIGHT = 150
// Floor for a dragged editor, so a cell that holds one line of SQL can shrink to about two
// lines. The SQL editor scene keeps its own, taller floor.
export const EMBEDDED_SQL_EDITOR_QUERY_PANE_MIN_HEIGHT = 44
export const getNotebookSqlEditorTabId = (nodeId: string | null | undefined, suffix: string | null = null): string =>
`notebook-sql-${suffix ? `${suffix}-` : ''}${nodeId ?? 'new'}`
/**
* The "Dataframes" section this node contributes to the shared database tree (Journey 7).
*
* Reads only logics notebookLogic already mounts — the document for the names its cells bind,
* and notebookKernelInfoLogic for the kernel's catalog — so it adds no requests. It deliberately
* does not read queryDatabaseLogic for the search term: reading a logic mounts it, and that one's
* afterMount fans out to the warehouse loaders (drafts, joins, tab state), which every notebook
* with a SQL cell would then pay on open even with the browser closed. QueryDatabase already
* holds the search term and filters these sections itself.
*/
function useNotebookDataframeTreeSections(): TreeDataItem[] {
const nodeLogic = useMountedLogic(notebookNodeLogic)
const { notebookLogic } = useValues(nodeLogic)
const { frameNodeSummaries } = useValues(notebookLogic)
const { localFrames } = useValues(
notebookKernelInfoLogic({
shortId: notebookLogic.props.shortId,
isShared: !!notebookLogic.props.cachedNotebook,
})
)
return useMemo(() => buildDataframeTreeSection(frameNodeSummaries, localFrames), [frameNodeSummaries, localFrames])
}
const withNotebookHogQLTags = (query: DataVisualizationNode): DataVisualizationNode => ({
...query,
source: {
...query.source,
tags: {
...query.source.tags,
productKey: query.source.tags?.productKey ?? ProductKey.NOTEBOOKS,
scene: query.source.tags?.scene ?? 'Notebook',
},
},
})
export const getSqlEditorSourceQuery = (query: QuerySchema): DataVisualizationNode | null => {
const convertedQuery = convertDataTableNodeToDataVisualizationNode(query)
if (
isDataVisualizationNode(convertedQuery) &&
convertedQuery.kind === NodeKind.DataVisualizationNode &&
isHogQLQuery(convertedQuery.source)
) {
return withNotebookHogQLTags(convertedQuery)
}
if (isHogQLQuery(query)) {
return withNotebookHogQLTags({
kind: NodeKind.DataVisualizationNode,
source: query,
display: ChartDisplayType.ActionsTable,
})
}
return null
}
/**
* Which connection a code cell runs against, as the node persists it.
*
* The resolved form (no undefined, raw mode only alongside a connection) is whatever
* sqlEditorLogic's `selectedConnectionId` / `sendRawQueryEnabled` say — `setSourceQuery`
* normalizes every write through `normalizeRawQuerySource`, so there is nothing to
* normalize here beyond the persisted attributes.
*/
export interface NotebookSQLConnection {
connectionId?: string | null
sendRawQuery?: boolean | null
}
const buildSourceQuery = (query: string, connection: NotebookSQLConnection): DataVisualizationNode => ({
kind: NodeKind.DataVisualizationNode,
source: {
kind: NodeKind.HogQLQuery,
query,
connectionId: connection.connectionId ?? undefined,
sendRawQuery: connection.sendRawQuery ?? undefined,
tags: {
productKey: ProductKey.NOTEBOOKS,
scene: 'Notebook',
},
},
display: ChartDisplayType.ActionsTable,
})
const locallyPushedSqlEditorSourceQueryByTabId = new Map<string, DataVisualizationNode>()
export function getEmbeddedSqlEditorStyle(
height: string | number | undefined,
defaultHeight: string | number = EMBEDDED_SQL_EDITOR_DEFAULT_HEIGHT,
minHeight: string | number = EMBEDDED_SQL_EDITOR_MIN_HEIGHT
): CSSProperties {
return {
height: height ?? defaultHeight,
minHeight,
}
}
function getRunnableHogQLSource(source: HogQLQuery): Omit<HogQLQuery, 'tags'> {
const { tags: _tags, ...runnableSource } = {
...source,
sendRawQuery: source.connectionId ? source.sendRawQuery || undefined : undefined,
}
return runnableSource
}
export function hasAlreadyRunSqlEditorSourceQuery(
editorSourceQuery: DataVisualizationNode,
lastRunQuery: DataVisualizationNode | null
): boolean {
return (
!!lastRunQuery &&
equal(getRunnableHogQLSource(editorSourceQuery.source), getRunnableHogQLSource(lastRunQuery.source))
)
}
export function useNotebookQuerySQLEditorSync<T extends { query: QuerySchema }>({
attributes,
updateAttributes,
tabId,
autoRunOnFirstSeed = true,
}: NotebookNodeAttributeProperties<T> & { tabId: string; autoRunOnFirstSeed?: boolean }): DataVisualizationNode | null {
const editorSourceQuery = useMemo(() => getSqlEditorSourceQuery(attributes.query), [attributes.query])
const logic = sqlEditorLogic({ tabId, mode: SQLEditorMode.Embedded })
const { queryInput, sourceQuery, lastRunQuery } = useValues(logic)
const { initialize, runQuery, setQueryInput, setSourceQuery } = useActions(logic)
// Sync Tiptap node attributes with sqlEditorLogic kea state. Two refs let us tell apart
// a remote attribute update (pull into kea) from a local edit (push to Tiptap).
const lastAttrRef = useRef<DataVisualizationNode | null>(null)
const lastLocalRef = useRef<DataVisualizationNode | null>(null)
useEffect(() => {
initialize()
}, [initialize])
useEffect(() => {
if (!editorSourceQuery) {
return
}
const localQuery: DataVisualizationNode = {
...sourceQuery,
source: {
...sourceQuery.source,
query: queryInput ?? '',
},
display: sourceQuery.display ?? editorSourceQuery.display ?? ChartDisplayType.ActionsTable,
}
if (equal(localQuery, editorSourceQuery)) {
lastAttrRef.current = editorSourceQuery
lastLocalRef.current = localQuery
return
}
if (!equal(editorSourceQuery, lastAttrRef.current)) {
// Attribute moved — pull (overrides any in-flight typing: last write wins).
// On first mount `lastAttrRef.current` is null, so seed kea and auto-run if
// this tab has not already run the same data-bearing SQL source. The output
// and edit panels mount separate sync hooks for the same tab, so the edit panel
// must not reload data just because it mounted with fresh refs.
const isFirstSeed = lastAttrRef.current === null
lastAttrRef.current = editorSourceQuery
lastLocalRef.current = editorSourceQuery
setQueryInput(editorSourceQuery.source.query)
setSourceQuery(editorSourceQuery)
if (
autoRunOnFirstSeed &&
isFirstSeed &&
!hasAlreadyRunSqlEditorSourceQuery(editorSourceQuery, lastRunQuery)
) {
runQuery(editorSourceQuery.source.query, undefined, true)
}
return
}
if (!equal(localQuery, lastLocalRef.current)) {
// Editor moved — push to Tiptap.
lastLocalRef.current = localQuery
locallyPushedSqlEditorSourceQueryByTabId.set(tabId, localQuery)
updateAttributes({ query: localQuery } as Partial<NotebookNodeAttributes<T>>)
return
}
// Tiptap hasn't propagated a push we already made — wait for the next render.
}, [
editorSourceQuery,
autoRunOnFirstSeed,
lastRunQuery,
queryInput,
sourceQuery,
runQuery,
setQueryInput,
setSourceQuery,
tabId,
updateAttributes,
])
return editorSourceQuery
}
function useNotebookQuerySQLEditorOutputSync<T extends { query: QuerySchema }>({
attributes,
tabId,
}: Pick<NotebookNodeAttributeProperties<T>, 'attributes'> & { tabId: string }): DataVisualizationNode | null {
const editorSourceQuery = useMemo(() => getSqlEditorSourceQuery(attributes.query), [attributes.query])
const logic = sqlEditorLogic({ tabId, mode: SQLEditorMode.Embedded })
const { lastRunQuery } = useValues(logic)
const { initialize, runQuery, setQueryInput, setSourceQuery } = useActions(logic)
const lastAttrRef = useRef<DataVisualizationNode | null>(null)
useEffect(() => {
initialize()
}, [initialize])
useEffect(() => {
if (!editorSourceQuery || equal(editorSourceQuery, lastAttrRef.current)) {
return
}
const isFirstSeed = lastAttrRef.current === null
lastAttrRef.current = editorSourceQuery
if (!isFirstSeed && equal(editorSourceQuery, locallyPushedSqlEditorSourceQueryByTabId.get(tabId))) {
return
}
setQueryInput(editorSourceQuery.source.query)
setSourceQuery(editorSourceQuery)
if (isFirstSeed && !hasAlreadyRunSqlEditorSourceQuery(editorSourceQuery, lastRunQuery)) {
runQuery(editorSourceQuery.source.query, undefined, true)
}
}, [editorSourceQuery, lastRunQuery, runQuery, setQueryInput, setSourceQuery, tabId])
return editorSourceQuery
}
export function useNotebookCodeSQLEditorSync<T extends { code: string } & NotebookSQLConnection>({
attributes,
updateAttributes,
tabId,
persistConnection = false,
}: NotebookNodeAttributeProperties<T> & { tabId: string; persistConnection?: boolean }): void {
const code = typeof attributes.code === 'string' ? attributes.code : ''
const logic = sqlEditorLogic({ tabId, mode: SQLEditorMode.Embedded })
// The editor's own resolved view of the connection — already normalized, since
// `setSourceQuery` runs every write through `normalizeRawQuerySource`.
const { queryInput, selectedConnectionId, sendRawQueryEnabled } = useValues(logic)
const { initialize, setQueryInput, setSourceQuery } = useActions(logic)
// Tracks the last `code` and `queryInput` we observed in sync. A real attribute change
// (remote step, undo, programmatic) shows up as `code !== lastCodeRef` → pull. A real
// local edit shows up as `queryInput !== lastQueryRef` → push. A transient mismatch
// right after a push (Tiptap hasn't propagated yet) shows up as neither → wait.
// One ref isn't enough: after a push it would falsely classify the lag as a remote change.
const lastCodeRef = useRef<string | null>(null)
const lastQueryRef = useRef<string | null>(null)
const editorConnectionId = selectedConnectionId ?? null
const attributeConnectionId = attributes.connectionId ?? null
// Mirrors the `sendRawQueryEnabled` selector: raw mode only counts alongside a connection.
const attributeSendRawQuery = !!attributeConnectionId && !!attributes.sendRawQuery
// Same two-ref reconciliation as the code sync above, for the connection the cell runs on.
// Compared as a key so the pair is one scalar — the refs never hold a stale object identity.
const attributeConnectionKey = `${attributeConnectionId}:${attributeSendRawQuery}`
const editorConnectionKey = `${editorConnectionId}:${sendRawQueryEnabled}`
const lastAttributeConnectionRef = useRef<string | null>(null)
const lastEditorConnectionRef = useRef<string | null>(null)
useEffect(() => {
initialize()
}, [initialize])
useEffect(() => {
if (queryInput === code) {
lastCodeRef.current = code
lastQueryRef.current = queryInput
return
}
if (code !== lastCodeRef.current) {
// Attribute moved — pull into kea (overrides any in-flight typing: last write wins).
lastCodeRef.current = code
lastQueryRef.current = code
setQueryInput(code)
setSourceQuery(
buildSourceQuery(code, { connectionId: attributeConnectionId, sendRawQuery: attributeSendRawQuery })
)
return
}
if (queryInput !== lastQueryRef.current) {
// Editor moved — push to Tiptap and keep sourceQuery in step with the new SQL so
// "Run query" uses what the user is actually looking at. Skip the push when
// queryInput resets to null (e.g. a re-initialize while `code` hasn't changed) —
// otherwise we'd write `code: null` and clear the cell on the next round-trip.
// Rebuild from the live sourceQuery, not from scratch: a connection the user picked
// moments ago may not have round-tripped through Tiptap yet, and rebuilding from the
// attributes would drop it (this is what reset the selector on every keystroke).
lastQueryRef.current = queryInput
if (queryInput !== null) {
setSourceQuery(
buildSourceQuery(queryInput, {
connectionId: editorConnectionId,
sendRawQuery: sendRawQueryEnabled,
})
)
updateAttributes({ code: queryInput } as Partial<NotebookNodeAttributes<T>>)
}
return
}
// Both sides match what we last observed but each other doesn't — Tiptap is still
// catching up to a push we already made. Do nothing; the next render will reconcile.
}, [
code,
queryInput,
attributeConnectionId,
attributeSendRawQuery,
editorConnectionId,
sendRawQueryEnabled,
setQueryInput,
setSourceQuery,
updateAttributes,
])
useEffect(() => {
if (!persistConnection || attributeConnectionKey === editorConnectionKey) {
lastAttributeConnectionRef.current = attributeConnectionKey
lastEditorConnectionRef.current = editorConnectionKey
return
}
if (attributeConnectionKey !== lastAttributeConnectionRef.current) {
lastAttributeConnectionRef.current = attributeConnectionKey
lastEditorConnectionRef.current = attributeConnectionKey
setSourceQuery(
buildSourceQuery(queryInput ?? code, {
connectionId: attributeConnectionId,
sendRawQuery: attributeSendRawQuery,
})
)
return
}
if (editorConnectionKey !== lastEditorConnectionRef.current) {
// The connection selector writes straight into sqlEditorLogic; persist it on the cell
// so the next run targets it and a reload keeps it.
lastEditorConnectionRef.current = editorConnectionKey
updateAttributes({
connectionId: editorConnectionId,
sendRawQuery: sendRawQueryEnabled,
} as Partial<NotebookNodeAttributes<T>>)
}
}, [
persistConnection,
attributeConnectionKey,
editorConnectionKey,
attributeConnectionId,
attributeSendRawQuery,
editorConnectionId,
sendRawQueryEnabled,
code,
queryInput,
setSourceQuery,
updateAttributes,
])
}
export const getNotebookSqlEditorOutputTab = (outputTab: unknown): OutputTab => {
if (Object.values(OutputTab).includes(outputTab as OutputTab)) {
return outputTab as OutputTab
}
return OutputTab.Results
}
export function useNotebookSQLOutputTabSync<T extends { outputTab?: OutputTab | null }>({
attributes,
updateAttributes,
tabId,
}: NotebookNodeAttributeProperties<T> & { tabId: string }): void {
const attributeOutputTab = getNotebookSqlEditorOutputTab(attributes.outputTab)
const logic = outputPaneLogic({ tabId })
const { activeTab } = useValues(logic)
const { setActiveTab } = useActions(logic)
const lastAttrRef = useRef<OutputTab | null>(null)
const lastLocalRef = useRef<OutputTab | null>(null)
useEffect(() => {
if (activeTab === attributeOutputTab) {
lastAttrRef.current = attributeOutputTab
lastLocalRef.current = activeTab
return
}
if (attributeOutputTab !== lastAttrRef.current) {
lastAttrRef.current = attributeOutputTab
lastLocalRef.current = attributeOutputTab
setActiveTab(attributeOutputTab)
return
}
if (activeTab !== lastLocalRef.current) {
lastLocalRef.current = activeTab
updateAttributes({ outputTab: activeTab } as Partial<NotebookNodeAttributes<T>>)
}
}, [activeTab, attributeOutputTab, setActiveTab, updateAttributes])
}
export function NotebookSQLEditorOutput<T extends { query: QuerySchema; outputTab?: OutputTab | null }>({
attributes,
updateAttributes,
showOutputToolbar,
}: NotebookNodeProps<T> & { showOutputToolbar: boolean }): JSX.Element | null {
const tabId = useMemo(() => getNotebookSqlEditorTabId(attributes.nodeId), [attributes.nodeId])
const editorSourceQuery = useNotebookQuerySQLEditorOutputSync({ attributes, tabId })
useNotebookSQLOutputTabSync({ attributes, updateAttributes, tabId })
if (!editorSourceQuery) {
return null
}
return (
<div
className="flex min-h-0 flex-col overflow-hidden"
// eslint-disable-next-line react/forbid-dom-props
style={getEmbeddedSqlEditorStyle(attributes.height)}
onMouseDown={(event) => event.stopPropagation()}
onDragStart={(event) => event.stopPropagation()}
>
<SQLEditor
tabId={tabId}
mode={SQLEditorMode.Embedded}
panel={SQLEditorPanel.Output}
defaultShowDatabaseTree={false}
showOutputToolbar={showOutputToolbar}
/>
</div>
)
}
export function NotebookSQLEditorSettings<T extends { query: QuerySchema }>({
attributes,
updateAttributes,
}: NotebookNodeAttributeProperties<T>): JSX.Element {
const tabId = useMemo(() => getNotebookSqlEditorTabId(attributes.nodeId), [attributes.nodeId])
const editorSourceQuery = useNotebookQuerySQLEditorSync({
attributes,
updateAttributes,
tabId,
autoRunOnFirstSeed: false,
})
// Focus the editor only when this user just inserted the node - a node mounting on
// notebook load or after a structural re-render must never steal the caret.
const [autoFocusQueryPane] = useState(() => wasNotebookNodeJustInserted(attributes.nodeId))
if (!editorSourceQuery) {
return <></>
}
return (
<div
className="h-full min-h-0 overflow-hidden"
// eslint-disable-next-line react/forbid-dom-props
style={getEmbeddedSqlEditorStyle(
attributes.height,
EMBEDDED_SQL_EDITOR_EDIT_DEFAULT_HEIGHT,
EMBEDDED_SQL_EDITOR_EDIT_MIN_HEIGHT
)}
onMouseDown={(event) => event.stopPropagation()}
onDragStart={(event) => event.stopPropagation()}
>
<SQLEditor
tabId={tabId}
mode={SQLEditorMode.Embedded}
panel={SQLEditorPanel.Query}
defaultShowDatabaseTree={false}
hostProduct={ProductKey.NOTEBOOKS}
queryPaneDefaultHeight={EMBEDDED_SQL_EDITOR_EDIT_DEFAULT_HEIGHT}
queryPaneMinHeight={EMBEDDED_SQL_EDITOR_QUERY_PANE_MIN_HEIGHT}
autoFocusQueryPane={autoFocusQueryPane}
/>
</div>
)
}
export function NotebookCodeSQLEditorSettings<T extends { code: string } & NotebookSQLConnection>({
attributes,
updateAttributes,
tabIdSuffix,
onRunQuery,
runQueryLoading,
runQueryDisabledReason,
runQueryTooltip,
onCancelQuery,
cancelQueryLoading,
hideRunButton,
persistConnection,
}: NotebookNodeAttributeProperties<T> & {
tabIdSuffix: string
/** Called with the live editor text and connection — the attributes can lag both by a Tiptap round-trip. */
onRunQuery?: (code: string, connection: { connectionId: string | null; sendRawQuery: boolean }) => void
runQueryLoading?: boolean
runQueryDisabledReason?: string
runQueryTooltip?: string
/** With onRunQuery: flips the run button to Cancel while runQueryLoading. */
onCancelQuery?: () => void
cancelQueryLoading?: boolean
/** Drop the editor toolbar's run button, for cells that run from the notebook's own top row. */
hideRunButton?: boolean
/** Store the picked connection on the cell. Only for cells whose run actually honors it. */
persistConnection?: boolean
}): JSX.Element {
const tabId = useMemo(
() => getNotebookSqlEditorTabId(attributes.nodeId, tabIdSuffix),
[attributes.nodeId, tabIdSuffix]
)
useNotebookCodeSQLEditorSync({ attributes, updateAttributes, tabId, persistConnection })
const extraTreeSections = useNotebookDataframeTreeSections()
const editorLogic = sqlEditorLogic({ tabId, mode: SQLEditorMode.Embedded })
const { queryInput } = useValues(editorLogic)
// Prefer what the user sees in the editor; fall back to the attribute before the first sync.
const liveCode = queryInput ?? (typeof attributes.code === 'string' ? attributes.code : '')
// Focus the editor only when this user just inserted the node - a node mounting on
// notebook load or after a structural re-render must never steal the caret.
const [autoFocusQueryPane] = useState(() => wasNotebookNodeJustInserted(attributes.nodeId))
return (
<div
className="h-full min-h-0 overflow-hidden"
// eslint-disable-next-line react/forbid-dom-props
style={getEmbeddedSqlEditorStyle(
attributes.height,
EMBEDDED_SQL_EDITOR_EDIT_DEFAULT_HEIGHT,
EMBEDDED_SQL_EDITOR_EDIT_MIN_HEIGHT
)}
onMouseDown={(event) => event.stopPropagation()}
onDragStart={(event) => event.stopPropagation()}
>
<SQLEditor
tabId={tabId}
mode={SQLEditorMode.Embedded}
panel={SQLEditorPanel.Query}
defaultShowDatabaseTree={false}
extraTreeSections={extraTreeSections}
hostProduct={ProductKey.NOTEBOOKS}
autoFocusQueryPane={autoFocusQueryPane}
// Read the editor's current text and connection imperatively at run time. The
// Cmd+Enter keybinding fires a stale closure (and Monaco's keybinding value can come
// through empty), so a captured `liveCode` would run the previous query. The mounted
// logic is the same source the Run button uses; fall back to `liveCode` before first
// sync. The connection is read here too because a just-picked one may not have
// round-tripped through Tiptap into the attributes yet.
onRunQuery={
onRunQuery
? () => {
const current = editorLogic.values.queryInput
onRunQuery(typeof current === 'string' && current.trim() ? current : liveCode, {
connectionId: editorLogic.values.selectedConnectionId ?? null,
sendRawQuery: editorLogic.values.sendRawQueryEnabled,
})
}
: undefined
}
runQueryLoading={runQueryLoading}
runQueryDisabledReason={runQueryDisabledReason}
runQueryTooltip={runQueryTooltip}
onCancelQuery={onCancelQuery}
cancelQueryLoading={cancelQueryLoading}
hideRunButton={hideRunButton}
queryPaneDefaultHeight={EMBEDDED_SQL_EDITOR_EDIT_DEFAULT_HEIGHT}
queryPaneMinHeight={EMBEDDED_SQL_EDITOR_QUERY_PANE_MIN_HEIGHT}
/>
</div>
)
}