Skip to main content
hypequery is an open-source, Apache 2.0 semantic layer for teams building embedded analytics and AI agents on ClickHouse. You define datasets in TypeScript or Python, with their dimensions, measures, metrics, relationships, and tenant rules, and then query them by name. The same definitions can be served as authenticated HTTP endpoints with OpenAPI, typed React hooks, and Model Context Protocol (MCP) tools for AI agents. The TypeScript SDK also includes a type-safe ClickHouse query builder. hypequery isn’t a hosted BI tool or a separate semantic-layer server. It’s a set of libraries you install and deploy with your backend, so your ClickHouse credentials stay on your servers. It connects to ClickHouse over the HTTP interface, using @clickhouse/client in TypeScript and clickhouse-connect in Python.

Prerequisites

  • A ClickHouse service, either self-managed or on ClickHouse Cloud.
  • Node.js for the TypeScript SDK, or Python 3.11 or later for the Python SDK.
1

Gather your connection details

To connect to ClickHouse with HTTP(S) you need this information:The details for your ClickHouse Cloud service are available in the ClickHouse Cloud console. Select a service and click Connect:
ClickHouse Cloud service connect button
Choose HTTPS. Connection details are displayed in an example curl command.
ClickHouse Cloud HTTPS connection details
If you’re using self-managed ClickHouse, the connection details are set by your ClickHouse administrator.
2

Install hypequery

3

Configure the connection

Add the connection details from step 1 to your application’s environment. The two SDKs read different variables.
4

Generate datasets from your schema

The CLI connects to ClickHouse, reads your tables, and writes a dataset definition for each one:
This writes analytics/datasets.ts.
Review the generated definitions and rename dimensions and measures to match your product’s language. A curated dataset looks like this:
5

Query a dataset

Select dimensions and measures by name. hypequery validates the request, generates parameterized SQL, and runs it on ClickHouse. Because the dataset declares a tenantKey, every query must pass the caller’s tenant, and hypequery adds the matching WHERE tenant_id = ... filter. A query without a tenant is rejected:

Serve datasets to your application and agents

Once a dataset works in-process, you can expose it without writing more SQL:
  • HTTP endpoints: @hypequery/serve in TypeScript, or hypequery.serve in Python, turns each dataset into an authenticated endpoint with input validation and an OpenAPI document. Python APIs mount in FastAPI, Django, or Flask. See Serve and Python serving.
  • React hooks: @hypequery/react generates typed TanStack Query hooks for those endpoints, so browser code never holds ClickHouse credentials. See React.
  • MCP tools for AI agents: npx hypequery mcp starts an MCP server that lets agents discover your datasets and query named metrics, instead of running raw SQL. See MCP.
Every surface runs through the same dataset definition, so each one applies the same tenant scoping and returns the same numbers.

Run without a ClickHouse server

For local development and CI, hypequery can run the same datasets on chDB, the in-process ClickHouse engine, with no server and no credentials. See chDB in TypeScript and chDB in Python.

Learn more