How to Analyze a CSV in a Hex Notebook with the AI Assistant
Hex is a notebook workspace for data analysis that runs SQL and Python in the same document, with an AI assistant that writes queries against your actual schema.
The difference from a local notebook is collaboration and publishing: two people can edit at once, and the finished analysis can be shared as an interactive app rather than a file someone has to re-run.
How do you get a CSV into Hex?
Create a project, then upload. There is a drag-and-drop upload in the project sidebar; behind it is a table in Hex’s data warehouse layer.
Two paths, and the right one depends on size:
- Small file, under about 100 MB — upload directly and query it as a table. – Anything larger, or recurring — put the file in S3, BigQuery, Snowflake or Postgres and connect to it. Uploading a 2 GB CSV will work eventually and then make every query slow, because the uploaded table lives in a shared environment.
Connect a warehouse if you have one. The assistant is much better when it can read real column types and table comments rather than inferring from a sample.
How do you ask the assistant to write the first query?
Open a SQL cell and describe the analysis in plain language: “monthly revenue by region for 2025, excluding refunds.”
The assistant generates SQL against the connected schema and shows the result inline. It is worth knowing what it does poorly: joins across more than three tables, window functions with unusual ordering, and anything that depends on business definitions you have not written down (“revenue” means different things to finance and to product).
Define those terms in a cell comment or a markdown cell above the query. The assistant reads them, and — more importantly — so does the next person who opens the project.
Why is the generated SQL usually close but wrong?
Because schema names are ambiguous and the assistant has to guess. Real examples:
- A table with both
created_atandactivated_at; the assistant picks one. – Astatuscolumn with values it has not seen in the sample, so the filter misses three states. – Currency columns with mixed units, which silently sums different things.
Fix: before trusting any generated query, run it with SELECT * LIMIT 20 on the filtered set and read the rows. Thirty seconds of eyeballing catches most of these. Then convert the assumptions into an explicit WHERE clause so the query says what it means.
How does Hex handle Python alongside SQL?
A Python cell can reference any previous SQL result by name as a dataframe. So df = revenue_by_region and then pandas or plotting on top.
The environment is managed — pandas, matplotlib, plotly, scikit-learn and a broad set of common libraries are pre-installed, with version pinning per project. Adding a package that is not available requires the project to use a custom environment, which on the paid tiers is a configuration step, not a pip install line.
That constraint surprises people coming from Jupyter. Pin the versions you need in the project environment config rather than installing at runtime.
How do you turn the analysis into something other people use?
Switch the cell outputs to app layout: choose which charts and tables appear, arrange them, add input filters. The project then publishes as an app with its own URL and permissions.
This is where Hex earns its keep over a notebook export. A shared spreadsheet goes stale; an app re-runs the query on open. A parameterised filter turning a static report into a self-serve one saves a weekly request in most teams.
Watch the cost side: an app opened by 50 people a day runs the queries 50 times unless you enable caching on the underlying cells, which caches results for a set period. Cache the expensive aggregation, not the cheap filter.
What does it cost?
Hex has a free community tier for individual work with limited project history and no private projects on some plans; team plans are per-editor with published apps usually free for viewers. The warehouse cost is yours regardless — a badly written query in Hex costs the same as a badly written query anywhere.
Who should not use this?
If your analysis is a fixed daily metric, a BI tool with a scheduled dashboard is simpler and cheaper than a notebook. If you only ever run something once, a local Python script plus a CSV file needs no account.
Hex fits the middle: exploratory work that will be revisited, shared, or turned into a small app by a team where not everyone writes SQL.
Quick Summary
-
Hex runs SQL and Python in one notebook; upload CSVs under about 100 MB or connect a warehouse for anything larger or recurring.
-
The AI assistant writes decent queries against a real schema, but guesses on ambiguous columns and undefined business terms.
-
Verify generated SQL by reading 20 rows of the filtered output, then make assumptions explicit in the WHERE clause.
-
Python cells read previous SQL results as dataframes; packages come from a pinned project environment, not runtime installs.
-
Publishing as an app with cached expensive cells turns a one-off analysis into a self-serve report.
