Python semantic layer
A semantic layer you write in Python, not YAML
hypequery is an open-source semantic layer for ClickHouse that lives in your codebase. Define what revenue, buyers, and enterprise customers mean as Python code, then query those definitions from any part of your app, with tenant isolation enforced on every query.
Model format
Python code
Runtime
Inside your app
License
Apache 2.0
Definitions drift between services
When each team writes its own SQL for the same KPI, dashboards and APIs disagree. A semantic layer only helps if every consumer actually reads from it.
Config files sit outside your workflow
Models kept in separate YAML files or a separate platform miss the tools your team already relies on: type checks, tests, refactoring, and review alongside the code that uses them.
Another server is another thing to run
A standalone semantic-layer service adds deployment, networking, and auth to keep in sync, before it answers a single query.
Model
Your model is Python objects
Datasets, dimensions, measures, and relationships are immutable Python objects, validated when you create them. They import like any other module and change through the same pull requests as your application.
- Dimensions and measures with labels and descriptions for catalogs and tools
- Filtered measures and to-one relationships with automatic joins
- Tenant keys enforced from trusted context, never from the query
- A catalog of what each dataset exposes, shared with TypeScript
Model
Two datasets and a relationship
Relationship targets are datasets themselves, so the model is checked when it loads.
Use
Query by name, wherever the code runs
The same definitions serve a nightly job, a notebook, and a FastAPI endpoint. hypequery plans parameterized ClickHouse SQL, joins related datasets, and scopes every query to one tenant.
There is no separate service to deploy. The semantic layer is a library in your process, so it uses your ClickHouse connection, your auth, and your deployment.
Because Python and TypeScript implement the same specifications, a TypeScript service can serve the same model your Python jobs use.
Query
Group revenue by a related customer field
A tenant-bound client runs every query as that tenant.
Where teams usually get stuck
Questions teams ask
Who this is for
Engineering teams who want shared analytics definitions without adopting a BI platform or running another service.
Analytics as code
Definitions are versioned, reviewed, and tested like application code, because they are application code.
Open source
Apache 2.0 licensed and currently in beta. Run it entirely in your own infrastructure against your own ClickHouse.
Serving is optional
Query datasets in-process, or add the FastAPI router when dashboards, customers, or agents need HTTP access. The same endpoints feed type-safe React hooks and MCP tools.
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
Defining datasets
The Python dataset model and its fields.
Open guide
Relationships
Join related datasets and query their fields by name.
Open guide
ClickHouse semantic layer
The semantic layer concept and the TypeScript side of hypequery.
Open guide
ClickHouse FastAPI
Serve your Python model as authenticated HTTP endpoints.
Open guide
React and MCP clients
Generated, type-safe React hooks and agent tools over your Python endpoints.
Open guide
Next step
Define your most-used metric as a measure
Start with the number your team argues about most, model it once in Python, and point every consumer at the definition.
Open source, and it runs in your own backend. Want it hosted?