[hypequery](https://hypequery.com/) › hypequery | Embedded analytics on ClickHouse
Index for agents: https://hypequery.com/llms.txt
Canonical page: https://hypequery.com/

> hypequery (not hyperquery) is an open-source embedded analytics toolkit for ClickHouse: define metrics once in TypeScript or Python, serve dashboards, APIs and agents.

[npmdownloads / month232.4K](https://www.npmjs.com/org/hypequery)

[Open sourceApache 2.0](https://github.com/hypequery/hypequery)

# Connect ClickHouse. Ship analytics.

Embedded analytics and agents on a semantic layer you define in code. Run it in your own backend today. hypequery cloud, the hosted option, is in early access.

[Get started](https://hypequery.com/docs)

## Give your agents numbers you can trust.

[Read why](https://hypequery.com/blog/seven-companies-one-pattern-why-every-scaled-clickhouse-deployment-looks-the-same) Uber, Cloudflare, and Instacart each built their own analytics layer on ClickHouse. hypequery gives you that layer as code you own.

## One model behind every answer

Your dashboards, APIs and agents like Claude all query the same model, with the same tenant rules.

ClickHouse Cloud, chDB, or self-hosted

Published v1 · orders, customers, refunds, events

### APIs

Every dataset is an authenticated endpoint with OpenAPI, for any frontend, mobile app or service.

POST /api/analytics/datasets/orders/query

```
{
  "dimensions": ["country"],
  "measures": ["revenue"],
  "filters": [{ "field": "month",
    "operator": "eq", "value": "2026-09" }]
}
```

200 OKapplication/json

```
{ "data": [
  { "country": "GB", "revenue": "64000.00" },
  { "country": "US", "revenue": "48000.00" },
  { "country": "DE", "revenue": "16000.00" }
] }
```

[Ship an analytics API](https://hypequery.com/docs/quick-start/api-and-dashboard)

### Embedded analytics

Ship embedded analytics with typed React hooks and your own components.

Revenue

$128,000USD

1 Sep30 Sep

By country

GB$64,000

US$48,000

DE$16,000

[Build a customer dashboard](https://hypequery.com/docs/quick-start/api-and-dashboard#add-a-react-dashboard)

### AI agents

Connect Claude, ChatGPT, or your favourite model over MCP. They only see what you publish.

claude

Claude Code

hypequery MCP connected

\~/acme-app

\>

? for shortcuts

[Connect Claude in 5 minutes](https://hypequery.com/docs/mcp/quickstart)

### AI SDK tools

Give your own agent the model as tools, scoped to the signed-in customer. It never writes SQL.

app/api/chat/route.ts

```
const tools = await hypequeryTools({
  executor: createMCPExecutor({
    datasets,
    analytics,
    tenantId: session.tenantId,
  }),
});

streamText({ model, tools, messages });
```

[Add AI chat to your app](https://hypequery.com/docs/agents/quickstart)

### Embedded chat

Coming soon

Let customers ask about their own data inside your app, answered from the same model.

Acme

Ask about your data…

### Slack

Coming soon

Ask in a channel and get the same number your dashboard shows, without leaving Slack.

\# revenue

AK

Ana

@hypequery revenue by country last month?

hypequery APP

September revenue was **$128,000**.

GB$64,000

US$48,000

DE$16,000

## Runs where your app runs

hypequery is a library, not another service to deploy. Mount it in the framework you already use, hand it to your agents, and point it at the ClickHouse you already have.

### Your backend

Mount it beside your routes in TypeScript or Python, or let hypequery Cloud serve the same APIs and MCP for you.

TypeScript

- [Next.js](https://hypequery.com/docs/nextjs "Route handler")
- [React Router](https://hypequery.com/docs/fetch#react-router "Resource route")
- [SvelteKit](https://hypequery.com/docs/fetch#sveltekit "Server route")
- [Express](https://hypequery.com/docs/nodejs#express "Beside your routes")
- [Fastify](https://hypequery.com/docs/nodejs#fastify "Encapsulated plugin")
- [Hono](https://hypequery.com/docs/fetch#hono "Catch-all route")
- [Cloudflare Workers](https://hypequery.com/docs/fetch#cloudflare-workers "Fetch handler")
- [Bun and Deno](https://hypequery.com/docs/fetch#bun-and-deno "Built-in servers")
- [Node jobs](https://hypequery.com/docs/embedded-runtime "In-process, no HTTP")

Python

- [FastAPI](https://hypequery.com/docs/python/fastapi "Mounted ASGI app")
- [Django](https://hypequery.com/docs/python/django "URLconf, sync or async")
- [Flask](https://hypequery.com/docs/python/flask "Blueprint")
- [Starlette](https://hypequery.com/docs/python/serving#mount-in-any-asgi-or-wsgi-app "Mount")
- [Uvicorn, Gunicorn](https://hypequery.com/docs/python/serving#mount-in-any-asgi-or-wsgi-app "Any ASGI or WSGI server")
- [Notebooks and jobs](https://hypequery.com/docs/python/dataframes "Straight into pandas")

Or hosted for youComing soon

- [hypequery Cloud](https://hypequery.com/docs/cloud "Coming soon: the same APIs and MCP, hosted, querying your ClickHouse with a read-only user")

### Your agents

Tools for the agent in your product, or MCP for Claude and Cursor. They query your datasets, never raw SQL.

In your app

- [Vercel AI SDK](https://hypequery.com/docs/agents/quickstart "TypeScript: tools for streamText and generateText")
- [Pydantic AI](https://hypequery.com/clickhouse-pydantic "Python: tools for Agent(tools=...)")
- [Anthropic SDK](https://hypequery.com/docs/agents/quickstart#create-the-tools-for-one-request "TypeScript and Python: tool definitions and tool_result helpers")
- [OpenAI Agents SDK](https://hypequery.com/docs/agents/quickstart#create-the-tools-for-one-request "TypeScript and Python: function tools for an Agent")

Over MCP

- [Claude](https://hypequery.com/blog/clickhouse-mcp-claude-code "Claude Code and Claude Desktop")
- [Cursor](https://hypequery.com/blog/clickhouse-mcp-cursor "One project or every project")
- [Codex](https://hypequery.com/blog/clickhouse-mcp-codex "codex mcp add")
- [Any MCP client](https://hypequery.com/docs/mcp/clients "Over stdio or HTTP")

### Your ClickHouse

Cloud, self-hosted or embedded with chDB. Your data stays in your ClickHouse, wherever hypequery runs.

Where your data lives

- [ClickHouse Cloud](https://hypequery.com/docs/reference/connection "Connect over HTTPS")
- [Self-hosted](https://hypequery.com/docs/reference/connection "Your own servers or cluster")
- [chDB](https://hypequery.com/docs/chdb "ClickHouse embedded in your process, no server")

## Built for production from day one

Tenant isolation, joins, access control, and caching are part of the model, so every tool gets them for free.

01

### Keep customers isolated

Every query is scoped to the signed-in customer. No tenant context? The query is rejected.

Authenticated tenant`acme`

WHERE tenant_id = 'acme'

No tenant context? Query rejected.

[Explore tenant isolation](https://hypequery.com/docs/datasets/multi-tenancy)

02

### Encode your business logic

Ratios, period comparisons, and named segments. Bucket by day, week, or month, in any timezone.

Average order value$80

revenue / orders

Revenue vs. previous month+23.1%

EnterpriseMonthUTC

[Explore calculations](https://hypequery.com/docs/datasets/measures)

03

### Connect your business data

Declare relationships once. hypequery writes the joins.

orderscustomers

Measure`revenue`

Group by`customer.country`

[Explore relationships](https://hypequery.com/docs/datasets/relationships)

04

### Control what's queryable

Publish only the fields you choose. Agent tools reject anything else.

Published query contract

revenueDeclared measure

internal_marginNot exposed

[Explore query controls](https://hypequery.com/docs/datasets/tool-generation)

05

### Review changes like code

Every change is a diff you can read, whether AI or a person made it.

Refine net revenue

−revenue

+revenue − refunds

[Explore model definitions](https://hypequery.com/docs/datasets/defining-datasets)

06

### Fast, without leaking

Repeated questions are cached, with separate cache entries for every tenant.

Repeated queryCache hit

Fresh for60 seconds

Separate keys for every tenant

[Explore caching](https://hypequery.com/docs/datasets/caching)

## hypequery cloud: go live in minutes

Cloud turns your model into a hosted API and MCP server the moment you publish. Update the model in one click, and roll it back just as fast. It is in early access: join the waitlist and we will reach out when your project can go live.

Ask in plain English. Every answer comes from your published measures, scoped to the tenant, with the query one click away.

analytics/Publishedv42/Chatanswers from Published v42Connect

Which countries drove revenue growth in September?

Queried orders.revenue by countrySep vs Aug 2026

Scoped to tenantorg_id = acme

Revenue grew $59,853 (+4.5%) to $1,401,930. The United States drove over half of it, and Japan was the only country to dip.

Revenue change by countrySep vs Aug

United States+$31,240

Germany+$14,105

United Kingdom+$9,870

France+$6,412

Japan−$1,774

Answered from Published v42orders.revenueorders.countryView query

## Ship your analytics layer today

Start open source in your own backend. A hosted option, hypequery cloud, is coming soon.

[Get started](https://hypequery.com/docs)
