ClickHouse pandas
Get governed ClickHouse metrics into pandas, by name
Notebooks are where numbers drift. hypequery lets analysts query the same measures and dimensions your product and dashboards use, so a DataFrame of “revenue by month” matches what customers see.
Works in
Jupyter, scripts, jobs
Output
pandas, Polars, Arrow
Types
From your definitions
Every notebook has its own revenue
Analysts copy a SQL query from a dashboard, tweak it, and the number in the deck no longer matches the product.
Joins and filters get re-derived
Each analysis rediscovers which status counts as completed, which table holds refunds, and how to bucket by week.
Customer data needs a deliberate scope
A notebook that forgets the tenant filter silently mixes customers. Cross-customer analysis should be explicit.
Notebook
Query the definitions, not the tables
Import the datasets your application defines, query measures by name with a time grain, and call to_pandas().
- Measures, filters, and relationships come from reviewed code
- Time grains like
by="month"produce a timezone-awareperiodcolumn to_polars()andto_arrow()work the same way- The same query runs in a scheduled job without changes
notebook
Revenue by month into a DataFrame
ClickHouseConnection.from_env() reads CLICKHOUSE_URL or the CLICKHOUSE_* variables.
Types and scope
Typed columns, from the definition
Each column’s type comes from the dataset, not from guessing at values: time buckets become datetimes in the query’s timezone, counts nullable integers, other measures floats. An empty result gets the same dtypes.
Pass decimals="decimal" to keep ClickHouse decimals exact. Integers beyond Int64 become unsigned or exact columns rather than overflowing.
Tenant-scoped datasets require a tenant. For internal analysis across every customer, pass all_tenants() explicitly so the intent is visible in the code.
notebook
Typed columns and cross-customer analysis
Output shown from a sample orders table.
Where teams usually get stuck
Questions teams ask
ClickHouse to pandas DataFrame
Query measures through hypequery and call result.to_pandas() for typed columns.
Metrics layer for notebooks
Analysts and the product read the same definitions, so numbers match across decks and dashboards.
clickhouse-connect query_df
clickhouse-connect returns DataFrames for raw SQL. hypequery returns them for named measures, with validation and tenancy.
Polars or Arrow?
result.to_polars() and result.to_arrow() use the same column types. Install hypequery[polars] or hypequery[arrow].
Further reading
Go deeper where it actually helps
hypequery vs clickhouse-connect
When to keep the driver for ad hoc SQL, and when shared datasets earn their place.
Open guide
pandas, Polars and Arrow
Column types, timezones, and exact decimals.
Open guide
Python quick start
Install hypequery and define your first dataset.
Open guide
Time grains
Bucket measures by day, week, or month.
Open guide
Caching
Reuse results across notebook runs.
Open guide
Next step
Rebuild one notebook query on a dataset
Pick the query behind your most-shared chart, define it as a dataset, and compare the numbers.
Open source, and it runs in your own backend. Want it hosted?