Skip to main content

Data apps

Synced from bicycle-studio-api

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 writea DataAppSpec v2 (JSON)React + TypeScript and bda.manifest.json
Toolsdesign_model_card, design_recipes, design_spec_validate, design_composequery_*, dataapp_start, dataapp_complete_upload
Calls functions or workflowsnoyes: manifest.functions + bda.fn
Skillstudio://skill/ask-show-shiptemplate/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
  1. dataapp_start(name, title, model) returns appId, version 1 and its upload step. Put appId in the manifest.
  2. Prove each query with query_run, then declare it under queries (semantic SQL: metrics are columns, a bounded time range, no JOIN, no OR).
  3. 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.
  4. npm run build, then zip bda.manifest.json, dist/app.js and dist/app.css at the zip root.
  5. PUT the zip to the upload URL, then dataapp_complete_upload(app_id, version, sha256, bytes). The version is validated or invalid with per-query errors. An expired upload step: dataapp_upload_url.
  6. 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 the appUrl instead of calling it.
  7. 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 in src/studio/; an older clone gets the files from dataapp_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_settings switches 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_create emails one saved view as PNG or PDF on a cron; rehearse it first with dataapp_schedule_test (it mails no one by default).
  • dataapp_share shares the app. A workflow snapshot step can capture only an app shared with the whole workspace.
  • dataapp_ask asks a published app's chat; dataapp_summary summarises its screen (both spend the chat budget).

bda.manifest.json fields (generated from AppManifest)​

An unknown field fails the upload (extra=forbid).

fieldtyperequired
appIdstrno
entrystryes
styleslist[str]no
title`strNone`
querieslist[DeclaredQuery]no
cache`CacheDeclNone`
blobslist[BlobDecl]no
chat`ChatDeclNone`
views`ViewsDeclNone`
telemetry`TelemetryDeclNone`
analyseslist[AnalysisDecl]no
agentslist[AgentDecl]no
lookupslist[LookupDecl]no
calendar`CalendarDeclNone`
functionsdict[str, FunctionImport]no
notebookslist[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.

  1. The template (kit 1.1.0 and later) has these files in src/studio/. An older clone: put them at the paths shown.
  2. 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.
  3. 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