io.github.hypequery/hypequery

Embedded analytics on ClickHouse.

Define your metrics once, in the codebase you already have. Dashboards, APIs, and AI agents all answer from that one definition. Run it in your own backend today. A hosted option, hypequery cloud, is coming soon.

hypequery is an open-source embedded analytics toolkit for ClickHouse that runs inside your own application. You define datasets in TypeScript or Python (beta), with their dimensions, measures, metrics, and tenant rules, then query them by name and serve them as authenticated HTTP endpoints with OpenAPI, typed React hooks, and MCP tools for AI agents. The TypeScript SDK also includes a type-safe ClickHouse query builder. It is for engineers building dashboards, APIs, and agent tools on their own ClickHouse. hypequery is not a hosted BI tool, not a database, and not a separate semantic-layer server: it is a set of Apache 2.0 libraries you install and deploy with your backend.

TypeScript quick start · Python quick start · Capabilities · Examples · MCP

One definition, every surface

import { dataset, dimension, measure } from '@hypequery/datasets';

export const Orders = dataset('orders', {
  source: 'orders',
  tenantKey: 'tenant_id',
  timeKey: 'created_at',
  dimensions: {
    region: dimension.string(),
    status: dimension.string(),
    createdAt: dimension.timestamp({ column: 'created_at' }),
  },
  measures: {
    revenue: measure.sum('amount'),
    orderCount: measure.count('id'),
    p95OrderValue: measure.percentile('amount', 0.95),
  },
});

export const revenue = Orders.metric('revenue', {
  measure: 'revenue',
});

That dataset can run in a worker, become a validated HTTP endpoint, power a typed React dashboard, or appear as a bounded MCP tool. Tenant scope and metric meaning stay in one place.

Start in minutes (TypeScript)

npm install -D @hypequery/cli
npx hypequery init
npx hypequery dev

Or add only the ClickHouse query builder:

npm install @hypequery/clickhouse

const revenueByRegion = await db
  .table('orders')
  .select(['region'])
  .where('status', 'eq', 'completed')
  .sum('amount', 'revenue')
  .groupBy('region')
  .orderBy('revenue', 'DESC')
  .execute();

No hand-written result interface. No any[]. The result is inferred from your real schema and the query itself.

Python (beta)

The Python SDK implements the same datasets and Serve protocol, checked against the same conformance fixtures. Serve it from FastAPI, Django, Flask, or any ASGI or WSGI server.

pip install "hypequery[clickhouse]==0.1.0b2"

from hypequery.datasets import Dataset, DatasetQuery, ExecutionContext, create_dataset_client, dimension, measure, tenant
from hypequery.execution import ClickHouseConnection, create_clickhouse_executor

orders = Dataset(
    name="orders",
    source="orders",
    tenant_key="tenant_id",
    dimensions={"country": dimension("string")},
    measures={"revenue": measure.sum("amount")},
)

analytics = create_dataset_client(executor=create_clickhouse_executor(ClickHouseConnection.from_env()))
result = analytics.execute(
    orders,
    DatasetQuery(dimensions=("country",), measures=("revenue",)),
    context=ExecutionContext(tenant=tenant("org_123")),
)

See the Python docs and python/hypequery.

ClickHouse MCP server

[`@hypeque

... View full README on GitHub