How to Keep Hex Notebooks Fast and Reviewable on a Data Team
A Hex project that everyone likes in month one becomes an abandoned notebook by month six. The cells are slow, nobody remembers which filter was intentional, and the person who wrote it changed teams.
Most of that is structure, not tooling. Five conventions fix the common failures, and each one is a habit rather than a feature.
Why do notebook projects get slow?
Because every cell that depends on a query re-runs it, and outputs render every time the project opens. A naive Hex project with a 40-second aggregation feeding six charts reruns that aggregation for each dependent cell unless caching is set.
Hex runs cells in dependency order and lets you cache a cell’s result. Two settings do most of the work:
- Cache the expensive cell — the join or aggregation — with a reasonable TTL. Charts then read cached output. – Split heavy transformations into SQL. A Python cell doing a groupby on 5 million rows is 30 times slower than the same groupby pushed to the warehouse, and it also bills compute on the wrong machine.
The rule that holds: push filtering and aggregation to SQL, use Python for modelling and plotting.
How do you stop a project from becoming one giant cell?
Name every cell after what it produces, not after what it does. revenue_by_region_monthly is referenceable by other cells and legible in a dependency graph; Query 4 is neither.
A workable structure for a project that answers one question:
- Parameters — region, date range, segment. One cell, referenced everywhere. 2. Base dataset — one SQL cell with all the joins, cached. 3. Derived tables — a few mid-level SQL cells, each named. 4. Analysis — Python for statistics and plots, reading the derived tables. 5. Output — the charts and tables that go in the app layout.
Five layers, and a new teammate can follow the flow by reading names. Projects where a single SQL cell is 300 lines long are the ones nobody dares edit.
How do you make a number trustworthy?
Notebooks fail audits because the number on the chart has no trail. Three habits:
- Assert your totals. A cell that checks row count and sum against the source table, and visually fails if they differ. Cheap, catches join fan-out, which is the most common silent error. – Comment the non-obvious filter. “Excluding internal accounts” written in a cell comment survives; the same knowledge in someone’s head does not. – Pin the data snapshot when the number matters. Warehouse tables change. A report that said 4.2M last month and says 4.1M today for the same period is a data question, not an analysis error, and saying so in the project saves a day of investigation.
How does review work for a notebook?
Hex projects do not have pull requests everywhere, but the version history is per-project and cells show who last edited them. Make review a habit:
- Before publishing to an app, have someone who did not write the project open it cold and try to explain the top-line number from the cells alone. – Any cell that changed a headline number gets a comment stating why. – Delete dead cells. A project with nine exploratory cells that were abandoned is worse than the version with three.
The cold-open test catches more problems than reading a diff, because notebook diffs are hard to read and nobody actually does it.
What is the AI assistant’s role in a reviewed project?
The assistant is most useful at the start of a project — scaffolding a query against an unfamiliar schema — and least useful at the end, where it will happily rewrite a working chart.
Where it genuinely helps in maintenance: generating the assertion cell, explaining what an inherited query does, and proposing a SQL version of a slow Python transformation. Those are read-heavy tasks on existing code, which is the assistant’s best mode.
Do not let it rename or restructure cells in a project others depend on. That produces a diff nobody can follow and breaks downstream references.
What does this cost the team?
Hex bills per editor on team plans; viewers of published apps are typically not billed. The hidden cost is warehouse compute from notebooks that re-run large queries on open.
A quarterly pass over active projects, checking which cells lack caching and which SQL scans full tables, is a half-day of work that usually removes a meaningful slice of warehouse spend. It is also a good moment to delete the abandoned cells.
When is a notebook the wrong home for this?
If the output is a number someone checks daily, it belongs in a scheduled BI dashboard, not a notebook that a person opens. If it is a repeatable transformation feeding a production table, it belongs in dbt or a scheduled job.
Hex is for the work between: exploring, deciding, and presenting a conclusion that will be revisited.
Quick Summary
-
Notebooks get slow when expensive aggregations re-run per dependent cell; cache the heavy cell and push aggregation into SQL instead of pandas.
-
Name cells after their output and use a five-layer structure — parameters, base, derived, analysis, output — so the project is readable.
-
Add an assertion cell comparing row count and totals to the source; join fan-out is the most common silent error.
-
Review with a cold open: someone who did not write it explains the headline number from the cells alone.
-
Use the AI assistant for scaffolding and explanation, not for restructuring a project others depend on.
