ClickHouse developer hub
ClickHouse for TypeScript and Python developers
Guides for querying ClickHouse from application code: picking a client, typing results, writing the SQL patterns ClickHouse rewards, and serving the results to dashboards, APIs and AI agents.
Definition
What does using ClickHouse from application code involve?
ClickHouse is an open-source, column-oriented database built for analytical queries over large tables. Calling it from a backend means three jobs on top of the driver: keeping result types in step with the schema, writing queries that suit a columnar engine (sorting keys, PREWHERE, pre-aggregation), and putting a safe interface in front of it for the dashboards, APIs and agents that consume the numbers.
hypequery is an open-source library for those jobs. In TypeScript it adds a query builder typed from your schema. In TypeScript and Python (beta) it adds datasets, a semantic layer you serve over HTTP, React hooks and MCP.
Pick your language
Two lanes: TypeScript and Python
Both SDKs read the same ClickHouse tables and implement the same dataset and Serve protocol, so a Python backend and a TypeScript frontend can share one definition of a metric. The TypeScript SDK also includes a typed query builder; the Python SDK works at the dataset level.
TypeScript and JavaScript
- ClickHouse with TypeScriptGenerate types from your live schema and build typed queries, APIs and hooks on them.
- ClickHouse with Node.jsAdd ClickHouse to a Node.js backend you already run, such as Express or Nest.
- ClickHouse with JavaScriptUse ClickHouse from JavaScript without raw query strings and hand-written row types.
- ClickHouse query builderA schema-typed builder with joins, CTEs, PREWHERE and FINAL.
- ClickHouse ORMAn ORM-style workflow for ClickHouse: generated types, then typed queries and APIs.
- ClickHouse schema typesMap ClickHouse column types to TypeScript, including the 64-bit and Decimal edge cases.
- ClickHouse with Next.jsRun typed queries in route handlers and server components.
- ClickHouse with ReactTyped hooks over an analytics API, built on TanStack Query.
Python (beta)
- ClickHouse with PythonDefine measures, dimensions and tenant rules once in Python and query them by name.
- ClickHouse with pandasPull ClickHouse measures into pandas from the same definitions your product uses.
- ClickHouse with SQLAlchemySQLAlchemy for ad hoc SQL, hypequery for shared, tenant-scoped measures.
- ClickHouse with FastAPIAuthenticated, tenant-scoped endpoints with request validation and rate limiting.
- ClickHouse with DjangoCall shared measures from views and tasks, and keep the Django ORM for transactional data.
- ClickHouse with FlaskServe ClickHouse analytics from Flask with measures defined once in Python.
- Embedded ClickHouse with chDBRun Python datasets on chDB, in process, for tests, CI and local development.
- FastAPI and React analyticsServe Python datasets from FastAPI and get typed React hooks from the same definitions.
ClickHouse SQL guides
Query patterns that suit a columnar engine
ClickHouse rewards queries that read few columns and few granules. These guides cover the clauses and functions that come up once a ClickHouse table backs a real feature, each with SQL and a typed TypeScript version.
Materialized views
Why ClickHouse materialized views are insert triggers, not cached results, and how to use them.
Read
PREWHERE vs WHERE
When moving a filter into PREWHERE cuts the data ClickHouse reads, and when it does not.
Read
FINAL and ReplacingMergeTree
Duplicate rows stay visible until a merge. FINAL, argMax and LIMIT BY compared.
Read
Pagination
Offset, cursor and keyset pagination patterns and their costs.
Read
LIMIT BY
Top N rows per group in one pass, without a window function.
Read
Window functions
row_number, rank, dense_rank and lagInFrame in ClickHouse.
Read
Date functions
toStartOfDay, toStartOfQuarter and friends for time bucketing.
Read
toStartOfInterval with GROUP BY
Fixed-size time buckets such as 5 or 15 minutes for charts.
Read
GROUP BY and aggregations
Aggregate functions and grouping patterns, with typed results.
Read
JOIN types
LEFT, RIGHT, INNER and ARRAY JOIN, with performance notes.
Read
ASOF JOIN
Match each row to the closest earlier row, such as trades to quotes.
Read
CTEs
How WITH clauses behave in ClickHouse (inlined, not materialized).
Read
Function reference
ClickHouse functions with examples
The ClickHouse function reference covers 28 common functions for dates, aggregates, strings, conditionals, math and arrays. Each page has the signature, the return type, a SQL example and a typed query-builder example.
Serve the results
APIs, OpenAPI and MCP for agents
Once a query is right, other code needs to call it. These pages cover turning queries into HTTP endpoints with schemas, and giving AI agents tools over governed datasets rather than a SQL connection.
ClickHouse REST API
Turn typed queries into validated HTTP endpoints with request and response schemas.
Read
ClickHouse OpenAPI
Generate an OpenAPI spec from the same query definitions.
Read
ClickHouse MCP server
Give AI agents governed tools over your datasets instead of raw SQL.
Read
ClickHouse MCP from Python
Give MCP clients your Python datasets. Python keeps the SQL, auth and tenant.
Read
Choosing tools
Compare ClickHouse clients and layers
If you are still choosing a stack, these comparisons cover the official drivers, general SQL builders and hosted platforms.
hypequery vs @clickhouse/client
The official Node.js client compared with a typed layer on top of it.
Read
hypequery vs clickhouse-connect
The official Python driver compared with a semantic layer.
Read
hypequery vs Kysely
Two different bets on type safety, and where ClickHouse changes the tradeoffs.
Read
All comparisons
Drizzle, Prisma, Cube, Tinybird, dbt and more, side by side.
Read
Related hubs
Building analytics features on ClickHouse
Two topics come up as soon as ClickHouse powers a product feature: defining metrics once, and showing them to customers safely.
Run one typed query against your own schema
The CLI reads your ClickHouse schema and writes the types. Open source, and it runs in your own backend.