Data apps
Source: studio_guide("data-apps") (GET /api/studio/v1/guide/data-apps) rendered at origin/platform (1afd83f), synced 2026-09-28. Do not edit this page here; change the source and run yarn sync:studio.
A data app is a small web bundle (app.js, app.css, bda.manifest.json) that Studio hosts in a sandboxed frame,
bound to one semantic model. It reads data only through the queries it declares.
Compose or hand-build
| Compose from a spec (default) | Hand-build from template/ | |
|---|---|---|
| You write | a DataAppSpec v2 (JSON) | React + TypeScript and bda.manifest.json |
| Tools | design_model_card, design_recipes, design_spec_validate, design_compose | query_*, dataapp_start, dataapp_complete_upload |
| Calls functions or workflows | no | yes: manifest.functions + bda.fn |
| Skill | studio://skill/ask-show-ship | template/README-FOR-AGENTS.md, studio://skill/semantic-query |
Compose unless the app must call a function or workflow, or needs something no recipe draws.
The hand-build loop
git clone https://github.com/BicycleAI/data-app-template.git my-app && cd my-app/template && npm install
dataapp_start(name, title, model)returnsappId, version 1 and its upload step. PutappIdin the manifest.- Prove each query with
query_run, then declare it underqueries(semantic SQL: metrics are columns, a bounded time range, no JOIN, no OR). - Declare each function or workflow the app calls under
functions, pinned@<n>. An unpublished app version may pin a tested draft of a function you can edit, to build and preview; publishing the app needs published versions (function_unpublished: a person publishes the function first). Workflow imports are published only. npm run build, then zipbda.manifest.json,dist/app.jsanddist/app.cssat the zip root.- PUT the zip to the upload URL, then
dataapp_complete_upload(app_id, version, sha256, bytes). The version isvalidatedorinvalidwith per-query errors. An expired upload step:dataapp_upload_url. dataapp_publish(app_id, version). A version that adds or re-pins an import is refused with a link: a person with publish rights on the app confirms it in Studio. A version without new imports publishes at once: if the person should decide, give them theappUrlinstead of calling it.- Later changes:
dataapp_new_version(app_id)and repeat 4 to 6.
Working example: studio_guide("example-kpi-app").
Rules for app code
- Call a function or workflow by its local name through
bda.fn(the template has it insrc/studio/; an older clone gets the files fromdataapp_sdk). The call runs as the viewer and shows in Studio's Runs. - Page-load calls pass
reuse: '6h'and show "as of <time> · Refresh". - Start calls from a button's
onClick; render output as text; a workflow send is delivered only when its receipt says"sent". - Chat belongs to the host page: never build a chat UI. Wrap each card in
<Panel>so chat can see it.dataapp_settingsswitches whether chat may call the app's imports. Chat answers cite their sources, draw charts and offer files by themselves; nothing to build.
Schedules and sharing
dataapp_schedule_createemails one saved view as PNG or PDF on a cron; rehearse it first withdataapp_schedule_test(it mails no one by default).dataapp_shareshares the app. A workflowsnapshotstep can capture only an app shared with the whole workspace.dataapp_askasks a published app's chat;dataapp_summarysummarises its screen (both spend the chat budget).
bda.manifest.json fields (generated from AppManifest)
An unknown field fails the upload (extra=forbid).
| field | type | required |
|---|---|---|
appId | str | no |
entry | str | yes |
styles | list[str] | no |
title | `str | None` |
queries | list[DeclaredQuery] | no |
cache | `CacheDecl | None` |
blobs | list[BlobDecl] | no |
chat | `ChatDecl | None` |
views | `ViewsDecl | None` |
telemetry | `TelemetryDecl | None` |
analyses | list[AnalysisDecl] | no |
agents | list[AgentDecl] | no |
lookups | list[LookupDecl] | no |
calendar | `CalendarDecl | None` |
functions | dict[str, FunctionImport] | no |
notebooks | list[NotebookDataset] | no |
Limits: MAX_AGENTS 8, MAX_AGENT_DRIVERS 4, MAX_AGENT_INPUT_BYTES 8,192, MAX_ANALYSES 16, MAX_CUSTOM_AGENT_BYTES 65,536, MAX_CUSTOM_INSTRUCTIONS 12,000, MAX_DECLARED_QUERY_ROWS 100,000, MAX_FUNCTIONS 16, MAX_LOOKUPS 8, MAX_TABS 20.
An import is {"ref": ...} only, and its ref must match ^(fn:[a-z0-9-]{1,40}/[a-z][a-z0-9_]{0,55}@[0-9]{1,6}|app:app_[a-f0-9]{20}/fn/[a-z][a-z0-9_]{0,55}@[a-f0-9]{12}|wf:[a-z0-9-]{1,40}/[a-z][a-z0-9_]{0,55}@[0-9]{1,6})$ (pinned; never @latest).
The bda.fn SDK (generated from data_apps/app_sdk.py, SDK version 90dfd1ebf5dd)
bda.fn: call a published function or workflow from a template-built app.
- The template (kit 1.1.0 and later) has these files in
src/studio/. An older clone: put them at the paths shown. - Declare what the app calls in
bda.manifest.json, pinned:"functions": {"<local_name>": {"ref": "fn:<tenant>/<name>@<n>"}}for a function,{"ref": "wf:<tenant>/<slug>@<n>"}for a published workflow. Publishing a version that adds or re-pins one is confirmed by a person in Studio. - In app code, name the LOCAL name only (never a ref); start runs from a button's onClick (the sandbox has no forms):
import { bda } from './studio/bda.js'
const out = await bda.fn.call('<local_name>', input) // waits, returns the output (throws a BdaError in words)
const started = await bda.fn.call('<local_name>', input, { wait: false, reuse: '6h' }) // queued Invocation at once
const watch = bda.fn.watch(started.invocation_id, batch => show(batch.items)) // progress lines in words
const final = await watch.done // terminal Invocation (status, output, usage)
const value = bda.fn.outputOf(final) // output, or throws for failed / cancelled
await bda.fn.cancel(started.invocation_id) // a Cancel button
reuse ("6h", at most "24h") answers from the viewer's own recent run of the same call: always pass it for a call made
on page load and show "as of <created_at>" with a Refresh ({ refresh: true }). It does not apply to workflows. A
workflow's output is its run receipt; a send is not delivered until its state is "sent". Render output as text,
never as HTML. The run happens as the viewer, and shows in Studio's Runs with the same trace as any other caller.
Per-function snippets: the function's or workflow's "Use it in an app" tab in Studio (workflow_guide over MCP).
The files themselves: dataapp_sdk (or GET /api/data-apps/sdk).
guide_version bb2461328de4