Compare
hypequery vs clickhouse-connect: Driver or Semantic Layer?
clickhouse-connect runs the SQL you write. hypequery runs on top of it and adds shared measures, validation, and tenant isolation. Here is when you need each in Python.
Decision type
Architecture and workflow fit
Audience
TypeScript teams building on ClickHouse
Outcome
Choose a path and move into implementation
What it is
A semantic layer in Python, built on clickhouse-connect
You write
Datasets: measures, dimensions, tenant key
Tenant isolation
Added to every query; fails closed without a tenant
HTTP and agents
FastAPI endpoints, typed React hooks, MCP bridge
Results
Rows as dicts; decimals and dates as strings
Inserts
Not supported; read-only queries
What this page is for
Use this page when the real question is how one tool changes the shape of your ClickHouse application code, not just which syntax looks nicer.
What this page is not
It is not a broad ecosystem roundup. It stays narrow on the tradeoff a ClickHouse-heavy TypeScript team is actually deciding.
Recommended next move
If the tradeoff already looks clear, stop reading comparisons and test the fit against one real query in your own schema.
clickhouse-connect is the official ClickHouse driver for Python. It sends SQL over HTTP, binds parameters on the server, and hands results back as Python values, NumPy arrays, pandas DataFrames, or Arrow tables. It also does fast bulk inserts. If you run ClickHouse from Python, you probably already use it.
hypequery is not a different driver. Its Python package runs on clickhouse-connect. What it adds sits above the driver: a definition of what your numbers mean, and rules about who may ask for them.
So this isn't really a choice between two tools. The question is whether your analytics SQL needs a layer on top.
What clickhouse-connect gives you
- Any SQL you can write. Queries, DDL, inserts, settings, and system tables.
- Server-side parameters. Values are bound by ClickHouse, not interpolated into strings.
- Data-science output.
query_dfandquery_arrowreturn DataFrames and Arrow tables directly. - Bulk inserts. Columnar inserts and async inserts for ingestion.
It does not know what "revenue" means, which customer a request belongs to, or which fields a caller should be allowed to group by. That knowledge lives in your SQL strings.
What hypequery adds
You describe a dataset once: its table, dimensions, measures, time column, and tenant key.
Callers then ask for measures by name:
hypequery plans the SQL, rejects fields the dataset doesn't declare, and adds the tenant filter. A query without a tenant fails instead of reading every customer. The same dataset can be served from FastAPI, consumed by generated React hooks, and exposed to AI agents through the MCP bridge.
Where each one fits
Use clickhouse-connect directly for:
- inserts and ingestion
- schema changes and admin scripts
- one-off analysis where
query_dfon arbitrary SQL is exactly what you want
Use hypequery when:
- the same measure is queried from several places: an API, a job, a notebook, a dashboard
- customers see the results, so tenant isolation can't depend on each query remembering a filter
- you want HTTP endpoints, typed frontend hooks, or agent access without writing them by hand
Trade-offs to know
hypequery returns rows as dictionaries, with decimals, dates, and timestamps as strings so nothing loses precision. That's the right default for APIs, but in a notebook you'll convert columns yourself, where query_df would hand you typed columns straight away.
hypequery is read-only. Inserts stay with the driver.
Using both
They can share one client. ClickHouseExecutor accepts an existing clickhouse-connect client:
Most teams end up with both: the driver for writing and exploring, hypequery for the numbers they share.
Decision checkpoint
If the tradeoff is already clear, move into implementation
Most teams do not need another round of comparison content after this point. The better test is whether the workflow holds up on your own schema and your own query complexity.
Related content
Continue into implementation
Python quick start
Define a dataset and run your first semantic query from Python.
ClickHouse with Python
How hypequery fits next to the driver you already use.
Python semantic layer
Datasets served from FastAPI, Django, or Flask, and used from notebooks.
Compare more options
Return to the comparison hub if you want to evaluate the other path next.
FAQ
Does hypequery replace clickhouse-connect?
No. hypequery uses clickhouse-connect to talk to ClickHouse. It replaces the analytics SQL you would otherwise write and maintain by hand, not the driver.
When should I use clickhouse-connect directly?
For inserts, schema changes, one-off scripts, and data science work where you want `query_df` or Arrow output for arbitrary SQL. Use hypequery when the same measure is queried from several places or by customers.
Can they share a connection?
Yes. `ClickHouseExecutor` accepts an existing clickhouse-connect client, so you can reuse one you already create.
Next step
Move from evaluation to your first Python dataset
Define a dataset over a table you already have, query it by name, and serve it from FastAPI, Django, or Flask.