Why hypequery
What hypequery is for, who it fits, and when to choose it.
The problem
Analytics logic often ends up spread across API routes, background jobs, dashboards, notebooks, and internal tools.
That creates a few predictable problems:
- the same metric gets reimplemented in slightly different ways
- changes require updating SQL in multiple places
- there is no single source of truth for analytics logic
- type safety usually stops at the application boundary and does not extend into analytics queries
- analytics definitions are harder to review, version, and evolve with confidence
What hypequery is
hypequery is a ClickHouse-first TypeScript toolkit for building reusable analytics queries in code.
It starts with a typed query builder and can grow into reusable query definitions and optional runtime delivery when you need them.
That means you can:
- build typed ClickHouse queries directly in your application
- turn important queries into reusable contracts
- expose those contracts through routes, docs, auth, and framework integrations only when needed
hypequery is not:
- an ORM
- a generic multi-database abstraction
- a hosted platform
When hypequery fits well
Use hypequery when:
- your analytics database is ClickHouse
- your application code is in TypeScript
- analytics queries need to live in more than one place
- you want stronger type safety around query construction and query interfaces
- you want analytics logic in normal version-controlled application code
- you want HTTP exposure, docs, or runtime features to stay optional
When hypequery is a poor fit
hypequery is probably the wrong tool when:
- you do not use ClickHouse
- you only need ad hoc SQL exploration
- you want a GUI-based semantic layer instead of code
- you need a managed hosted analytics platform
How it compares
Versus direct SQL
hypequery is a better fit when the same query needs reuse, type safety, reviewability, and a stable interface.
Raw SQL is still fine for one-off exploration or very local query logic.
Versus generic query builders
Generic query builders are better for broad CRUD and multi-database work.
hypequery is better when the problem is specifically ClickHouse analytics and you want ClickHouse-first behavior rather than a lowest-common-denominator abstraction.
Versus semantic layers
Semantic layers are a better fit when you need a broader cross-tool or cross-database platform.
hypequery is a better fit when you want application-embedded analytics in TypeScript without adopting a separate config-heavy system.
The core idea
hypequery keeps analytics close to application code:
- define queries in TypeScript
- reuse them where they matter
- add runtime delivery only when you actually need it
Read Core Concepts for the builder, reusable query definition, and runtime layers.