Skip to content

The Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.

feat(studio): notebook content at the API boundary (#48815)

Charis957e9fec6717
diff --git a/apps/studio/components/interfaces/ProjectHome/CustomReportSection.tsx b/apps/studio/components/interfaces/ProjectHome/CustomReportSection.tsx
index 2e887f5f455..13af1c9a620 100644
--- a/apps/studio/components/interfaces/ProjectHome/CustomReportSection.tsx
+++ b/apps/studio/components/interfaces/ProjectHome/CustomReportSection.tsx
@@ -29,7 +29,7 @@ import { DEFAULT_CHART_CONFIG } from '@/components/ui/QueryBlock/QueryBlock'
import { AnalyticsInterval } from '@/data/analytics/constants'
import { useInvalidateAnalyticsQuery } from '@/data/analytics/utils'
import { useContentInfiniteQuery } from '@/data/content/content-infinite-query'
-import { Content } from '@/data/content/content-query'
+import { Content, ContentOfType } from '@/data/content/content-query'
import {
UpsertContentPayload,
useContentUpsertMutation,
@@ -58,7 +58,7 @@ export function CustomReportSection() {
{ projectRef: ref, type: 'report', name: 'Home', limit: 1 },
{ placeholderData: keepPreviousData }
)
- const homeReport = reportsData?.pages?.[0]?.content?.[0] as Content | undefined
+ const homeReport = reportsData?.pages?.[0]?.content?.[0] as ContentOfType<'report'> | undefined
const reportContent = homeReport?.content as Dashboards.Content | undefined
const [isRefreshing, setIsRefreshing] = useState<boolean>(false)
diff --git a/apps/studio/components/interfaces/Reports/Reports.tsx b/apps/studio/components/interfaces/Reports/Reports.tsx
index 347741a16d7..6b30023a10d 100644
--- a/apps/studio/components/interfaces/Reports/Reports.tsx
+++ b/apps/studio/components/interfaces/Reports/Reports.tsx
@@ -22,7 +22,7 @@ import { NoPermission } from '@/components/ui/NoPermission'
import { DEFAULT_CHART_CONFIG } from '@/components/ui/QueryBlock/QueryBlock'
import { AnalyticsInterval } from '@/data/analytics/constants'
import { analyticsKeys } from '@/data/analytics/keys'
-import { useContentQuery } from '@/data/content/content-query'
+import { ContentOfType, useContentQuery } from '@/data/content/content-query'
import {
UpsertContentPayload,
useContentUpsertMutation,
@@ -73,7 +73,9 @@ const Reports = () => {
})
const track = useTrack()
- const currentReport = userContents?.content.find((report) => report.id === reportId)
+ const currentReport = userContents?.content.find(
+ (report): report is ContentOfType<'report'> => report.id === reportId
+ )
const currentReportContent = currentReport?.content as Dashboards.Content
const { can: canReadReport, isLoading: isLoadingPermissions } = useAsyncCheckPermissions(
diff --git a/apps/studio/components/interfaces/Reports/UpdateModal.tsx b/apps/studio/components/interfaces/Reports/UpdateModal.tsx
index 2c1db9e9944..b9b46174e11 100644
--- a/apps/studio/components/interfaces/Reports/UpdateModal.tsx
+++ b/apps/studio/components/interfaces/Reports/UpdateModal.tsx
@@ -21,7 +21,7 @@ import {
import { FormItemLayout } from 'ui-patterns/form/FormItemLayout/FormItemLayout'
import * as z from 'zod'
-import { Content } from '@/data/content/content-query'
+import { ContentOfType } from '@/data/content/content-query'
import { useContentUpsertMutation } from '@/data/content/content-upsert-mutation'
const formSchema = z.object({
@@ -32,7 +32,7 @@ const formSchema = z.object({
type CustomReport = z.infer<typeof formSchema>
export interface UpdateCustomReportProps {
- selectedReport?: Content
+ selectedReport?: ContentOfType<'report'>
initialValues: CustomReport
onCancel: () => void
}
diff --git a/apps/studio/components/layouts/ObservabilityLayout/ObservabilityMenu.tsx b/apps/studio/components/layouts/ObservabilityLayout/ObservabilityMenu.tsx
index c9b9650ece0..1c5a0820fea 100644
--- a/apps/studio/components/layouts/ObservabilityLayout/ObservabilityMenu.tsx
+++ b/apps/studio/components/layouts/ObservabilityLayout/ObservabilityMenu.tsx
@@ -21,7 +21,7 @@ import { ButtonTooltip } from '@/components/ui/ButtonTooltip'
import { ProductMenu } from '@/components/ui/ProductMenu'
import { ProductMenuShortcuts } from '@/components/ui/ProductMenu/ProductMenuShortcuts'
import { useContentDeleteMutation } from '@/data/content/content-delete-mutation'
-import { Content } from '@/data/content/content-query'
+import { ContentOfType } from '@/data/content/content-query'
import { useAsyncCheckPermissions } from '@/hooks/misc/useCheckPermissions'
import { IS_PLATFORM } from '@/lib/constants'
import { useProfile } from '@/lib/profile'
@@ -57,8 +57,8 @@ export const ObservabilityMenu = () => {
'newReport',
parseAsBoolean.withDefault(false).withOptions({ history: 'push', clearOnDefault: true })
)
- const [selectedReportToDelete, setSelectedReportToDelete] = useState<Content>()
- const [selectedReportToUpdate, setSelectedReportToUpdate] = useState<Content>()
+ const [selectedReportToDelete, setSelectedReportToDelete] = useState<ContentOfType<'report'>>()
+ const [selectedReportToUpdate, setSelectedReportToUpdate] = useState<ContentOfType<'report'>>()
const onConfirmDeleteReport = () => {
if (ref === undefined) return console.error('Project ref is required')
diff --git a/apps/studio/data/content/content-infinite-query.ts b/apps/studio/data/content/content-infinite-query.ts
index 23ee425d22e..d6d2e9d84d3 100644
--- a/apps/studio/data/content/content-infinite-query.ts
+++ b/apps/studio/data/content/content-infinite-query.ts
@@ -27,7 +27,10 @@ export async function getContent(
params: {
path: { ref: projectRef },
query: {
- type,
+ // TODO — Charis 2026-08-06
+ // Cast until the generated query param type picks up 'notebook' (see ContentBase in
+ // content-query.ts)
+ type: type as 'sql' | 'report' | 'log_sql',
name,
sort_by: sort,
limit: limit.toString(),
diff --git a/apps/studio/data/content/content-query.ts b/apps/studio/data/content/content-query.ts
index 65ad09dc4ba..b555f21cdf7 100644
--- a/apps/studio/data/content/content-query.ts
+++ b/apps/studio/data/content/content-query.ts
@@ -4,7 +4,13 @@ import { components } from 'api-types'
import { remapSqlContentFields } from './content-remap'
import { contentKeys } from './keys'
import { get, handleError } from '@/data/fetchers'
-import type { Dashboards, LogSqlSnippets, SqlSnippets, UseCustomQueryOptions } from '@/types'
+import type {
+ Dashboards,
+ LogSqlSnippets,
+ Notebooks,
+ SqlSnippets,
+ UseCustomQueryOptions,
+} from '@/types'
// TODO — Charis 2026-08-06
// Temporary widening until we have API support for notebooks
@@ -27,10 +33,19 @@ export type Content = Omit<ContentBase, 'content' | 'type'> &
type: 'log_sql'
content: LogSqlSnippets.Content
}
+ | {
+ type: 'notebook'
+ content: Notebooks.Content
+ }
)
export type ContentType = Content['type']
+// Narrows the full Content union down to a single content type — for call sites that already
+// know (from the `type` they queried with) which member they're holding, since useContentQuery
+// et al. don't parameterize their return type by the `type` argument.
+export type ContentOfType<T extends ContentType> = Extract<Content, { type: T }>
+
interface GetContentVariables {
projectRef?: string
type: ContentType
@@ -48,7 +63,12 @@ export async function getContent(
}
const { data, error } = await get('/platform/projects/{ref}/content', {
- params: { path: { ref: projectRef }, query: { type, name, limit: limit.toString() } },
+ params: {
+ path: { ref: projectRef },
+ // TODO — Charis 2026-08-06
+ // Cast until the generated query param type picks up 'notebook' (see ContentBase above)
+ query: { type: type as 'sql' | 'report' | 'log_sql', name, limit: limit.toString() },
+ },
headers,
signal,
})
diff --git a/apps/studio/data/content/content-remap.test.ts b/apps/studio/data/content/content-remap.test.ts
index d14e5e283a8..e9ffd9c899b 100644
--- a/apps/studio/data/content/content-remap.test.ts
+++ b/apps/studio/data/content/content-remap.test.ts
@@ -4,6 +4,40 @@ import { afterEach, describe, expect, it, vi } from 'vitest'
import { remapSqlContentField, remapSqlContentFields, unmapSqlContentField } from './content-remap'
import { untrustedLogSql } from '@/data/logs/safe-analytics-sql'
+const MARKDOWN_CELL = {
+ _tag: 'markdown_cell' as const,
+ id: 'a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11',
+ text: '# Signup funnel',
+}
+
+const DATABASE_CELL = {
+ _tag: 'database_cell' as const,
+ id: 'b1ffcd88-8d1a-4de7-aa5c-5aa8ac270b22',
+ sql: 'select * from auth.users limit 100',
+ row_limit: 100,
+}
+
+const LOG_CELL = {
+ _tag: 'log_cell' as const,
+ id: 'c2001199-1e2b-4ef8-bb6d-6bb9bd380a33',
+ sql: "select timestamp, event_message from edge_logs where source = 'edge_logs' limit 10",
+ time_range: {
+ _tag: 'relative_time_range' as const,
+ unit: 'hour' as const,
+ amount: 1,
+ },
+}
+
+const NOTEBOOK = {
+ id: 'd3aadd77-7c3c-4de7-aa5c-5aa8ac270b44',
+ type: 'notebook' as const,
+ name: 'Signup funnel',
+ content: {
+ schema_version: 1 as const,
+ cells: [MARKDOWN_CELL, DATABASE_CELL, LOG_CELL],
+ },
+}
+
const SQL_SNIPPET = {
id: 'a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11',
type: 'sql' as const,
@@ -74,6 +108,40 @@ describe('remapSqlContentField', () => {
expect(remapSqlContentField(snippet)).toBe(snippet)
})
+
+ it('brands database_cell and log_cell sql per-cell for notebooks, leaving markdown_cell untouched', () => {
+ const result = remapSqlContentField(NOTEBOOK)
+
+ const [markdownCell, databaseCell, logCell] = result.content.cells
+ expect(markdownCell).toEqual(MARKDOWN_CELL)
+ expect(databaseCell).toEqual({
+ _tag: 'database_cell',
+ id: DATABASE_CELL.id,
+ row_limit: 100,
+ unchecked_sql: untrustedSql(DATABASE_CELL.sql),
+ })
+ expect(databaseCell).not.toHaveProperty('sql')
+ expect(logCell).toEqual({
+ _tag: 'log_cell',
+ id: LOG_CELL.id,
+ time_range: LOG_CELL.time_range,
+ unchecked_sql: untrustedLogSql(LOG_CELL.sql),
+ })
+ expect(logCell).not.toHaveProperty('sql')
+ })
+
+ it('throws when a notebook cell is missing a required field', () => {
+ const invalidNotebook = {
+ id: '1',
+ type: 'notebook' as const,
+ content: {
+ schema_version: 1 as const,
+ cells: [{ _tag: 'database_cell' as const, id: '1', sql: 'select 1' }],
+ },
+ }
+
+ expect(() => remapSqlContentField(invalidNotebook)).toThrow()
+ })
})
describe('remapSqlContentFields', () => {
@@ -175,4 +243,10 @@ describe('remap/unmap round-trip', () => {
expect(result.content).toEqual(LOG_SQL_SNIPPET.content)
})
+
+ it('returns the original content shape after remap then unmap for notebooks', () => {
+ const result = unmapSqlContentField(remapSqlContentField(NOTEBOOK))
+
+ expect(result.content).toEqual(NOTEBOOK.content)
+ })
})
diff --git a/apps/studio/data/content/content-remap.ts b/apps/studio/data/content/content-remap.ts
index e3f4b397ef1..2dfed9dd64f 100644
--- a/apps/studio/data/content/content-remap.ts
+++ b/apps/studio/data/content/content-remap.ts
@@ -5,8 +5,18 @@
// Both database (`type: 'sql'`) and logs (`type: 'log_sql'`) snippets carry user-authored SQL
// under the same wire field, but each is branded with its own untrusted brand so Postgres SQL
// and logs SQL can never cross execution paths. Branding is per-type and never mixed.
+//
+// Notebooks (`type: 'notebook'`) carry the same kind of untrusted SQL, but nested per-cell
+// rather than as a single top-level field, so they go through the dedicated notebook schemas
+// (data/content/notebooks/notebook-schema.ts) instead of the single-field swap below.
import { untrustedSql } from '@supabase/pg-meta'
+import {
+ notebookDomainSchema,
+ type Cell,
+ type CellWire,
+ type NotebookContent,
+} from './notebooks/notebook-schema'
import type { SnippetStatus } from './snippet-status'
import type { SnippetWithContent } from './sql-folders-query'
import { untrustedLogSql } from '@/data/logs/safe-analytics-sql'
@@ -15,7 +25,30 @@ function isSqlContentType(type: string): type is 'sql' | 'log_sql' {
return type === 'sql' || type === 'log_sql'
}
+function isNotebookContentType(type: string): type is 'notebook' {
+ return type === 'notebook'
+}
+
+// Reverse of the per-cell branding `notebookDomainSchema` applies on the way in: strips
+// `unchecked_sql` back to a plain `sql` field for the wire.
+function unmapNotebookCell(cell: Cell): CellWire {
+ switch (cell._tag) {
+ case 'markdown_cell':
+ return cell
+ case 'database_cell':
+ case 'log_cell': {
+ const { unchecked_sql, ...rest } = cell
+ return { ...rest, sql: unchecked_sql }
+ }
+ }
+}
+
export function remapSqlContentField<T extends { type: string }>(item: T): T {
+ if (isNotebookContentType(item.type)) {
+ if (!('content' in item)) return item
+ const content = notebookDomainSchema.parse(item.content)
+ return { ...item, content } as T
+ }
if (!isSqlContentType(item.type)) return item
if (!('content' in item)) return item
const content = item.content as Record<string, unknown>
@@ -43,6 +76,11 @@ export function remapWireSnippet(row: unknown, status: SnippetStatus): SnippetWi
// Reverse remap: `unchecked_sql` → `sql` before sending to the API.
export function unmapSqlContentField<T extends { type: string }>(item: T): T {
+ if (isNotebookContentType(item.type)) {
+ if (!('content' in item)) return item
+ const content = item.content as NotebookContent
+ return { ...item, content: { ...content, cells: content.cells.map(unmapNotebookCell) } } as T
+ }
if (!isSqlContentType(item.type)) return item
if (!('content' in item)) return item
const content = item.content as Record<string, unknown>
diff --git a/apps/studio/pages/project/[ref]/logs/explorer/index.tsx b/apps/studio/pages/project/[ref]/logs/explorer/index.tsx
index 65153b9cb3c..2e002bcca9e 100644
--- a/apps/studio/pages/project/[ref]/logs/explorer/index.tsx
+++ b/apps/studio/pages/project/[ref]/logs/explorer/index.tsx
@@ -42,7 +42,7 @@ import { CodeEditor } from '@/components/ui/CodeEditor/CodeEditor'
import { DiffEditor } from '@/components/ui/DiffEditor'
import LoadingOpacity from '@/components/ui/LoadingOpacity'
import ShimmerLine from '@/components/ui/ShimmerLine'
-import { useContentQuery } from '@/data/content/content-query'
+import { ContentOfType, useContentQuery } from '@/data/content/content-query'
import {
UpsertContentPayload,
useContentUpsertMutation,
@@ -150,7 +150,7 @@ export const LogsExplorerPage: NextPageWithLayout = () => {
const entitledToAuditLogDays = getEntitlementNumericValue()
const { data: content } = useContentQuery({ projectRef, type: 'log_sql' })
- const query = content?.content.find((x) => x.id === queryId)
+ const query = content?.content.find((x): x is ContentOfType<'log_sql'> => x.id === queryId)
const resolvedRange = useMemo(() => {
if (datePickerValue.isHelper) {