Porting a data story or notebook into a workflow
Source: studio_guide("porting") (GET /api/studio/v1/guide/porting) rendered at origin/platform (1afd83f), synced 2026-09-28. Do not edit this page here; change the source and run yarn sync:studio.
A notebook runs in a shell: pip install, local files, bicycle.query() in a loop, often a slide deck at the end.
A workflow is declared steps Studio runs as the tenant. Map every stage first, agree the map with the person, and
say plainly what will not come across.
Which stage becomes which step
| In the notebook | In the workflow |
|---|---|
load data (bicycle.query, SQL on the model) | a query step on a query in the workflow's queries block. Prove it with query_run. A step reads at most its row cap and drops the rest silently: aggregate in SQL and set maxLimit |
| pandas reshaping, joins, filters | a sql step (DuckDB, SELECT only) |
| model code (numpy, scikit-learn, statsmodels, torch, Chronos-2) | a code function called by a function step; heavy models on bda-python-ml:1 |
| a written summary | an llm step |
| sorting text into fixed labels | a classify step |
| a chart or picture | a data app that shows it, then a snapshot step |
| email, Slack, a ticket | an action (send) step, approved by a person |
| files kept between runs (a model) | workflow blobs, written and read by the function |
| setup checks | asserts at the top of the handler, plus tests |
| a backtest over many origins | a function step mapped over partitions, reduced by sql |
What cannot be ported
- Other packages. The images are fixed: check
function_kindsbefore porting a line. If a package is missing, tell the person; do not ship a weaker substitute without their say-so. - Shell, local files, network. Pass tables between steps, keep files in workflow blobs, bundle small reference
data in the package's
data/. - Slide decks. Build an app, snapshot it, send the picture.
- Waiting for a person mid-run. Only a send's approval waits.
Before anyone publishes
Run the workflow once on preview as a try run and compare its numbers with the notebook's for the same dates. Show the person both, and the list of what was not ported.
Working examples: example-train-predict (train, then predict with blobs) and example-backtest (mapped
partitions).
guide_version bb2461328de4