> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Connecting hypequery to ClickHouse

> hypequery is an open-source semantic layer for embedded analytics on ClickHouse. Define metrics once in TypeScript or Python and serve them to dashboards, APIs, and AI agents from your own backend.

Community maintained

[hypequery](https://hypequery.com) 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`](https://clickhouse.com/docs/integrations/language-clients/js/index) in TypeScript and [`clickhouse-connect`](https://clickhouse.com/docs/integrations/language-clients/python/index) in Python.

## Prerequisites

* A ClickHouse service, either self-managed or on [ClickHouse Cloud](https://clickhouse.com/docs/get-started/setup/cloud.md).
* 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:

| Parameter(s) | Description |
| - | - |
| `HOST` and `PORT` | Typically, the port is 8443 when using TLS or 8123 when not using TLS. |
| `DATABASE NAME` | Out of the box, there is a database named `default`, use the name of the database that you want to connect to. |
| `USERNAME` and `PASSWORD` | Out of the box, the username is `default`. Use the username appropriate for your use case. |

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](https://mintcdn.com/private-7c7dfe99/EDr8ydtGBgFPOQea/images/_snippets/cloud-connect-button.webp?fit=max\&auto=format\&n=EDr8ydtGBgFPOQea\&q=85\&s=97d6a020a443f1b365b017488b39d0c8)

Choose **HTTPS**. Connection details are displayed in an example `curl` command.

![ClickHouse Cloud HTTPS connection details](https://mintcdn.com/private-7c7dfe99/EDr8ydtGBgFPOQea/images/_snippets/connection-details-https.webp?fit=max\&auto=format\&n=EDr8ydtGBgFPOQea\&q=85\&s=80369fc90cd1ac3108fe455f2426c19a)

If you're using self-managed ClickHouse, the connection details are set by your ClickHouse administrator.

**2. Install hypequery**

> [tab] TypeScript
>
> ```bash theme={null}
> npm install @hypequery/datasets @hypequery/clickhouse
> npm install -D @hypequery/cli
> ```

> [tab] Python
>
> ```bash theme={null}
> pip install "hypequery[clickhouse]"
> ```

**3. Configure the connection**

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

> [tab] TypeScript
>
> ```bash theme={null}
> CLICKHOUSE_URL=https://<your-service>.clickhouse.cloud:8443
> CLICKHOUSE_DATABASE=analytics
> CLICKHOUSE_USERNAME=<username>
> CLICKHOUSE_PASSWORD=<password>
> ```

> [tab] Python
>
> ```bash theme={null}
> CLICKHOUSE_HOST=<your-service>.clickhouse.cloud
> CLICKHOUSE_PORT=8443
> CLICKHOUSE_SECURE=true
> CLICKHOUSE_DATABASE=analytics
> CLICKHOUSE_USERNAME=<username>
> CLICKHOUSE_PASSWORD=<password>
> ```
>
> Set `CLICKHOUSE_SECURE=true` for ClickHouse Cloud and any other service that uses TLS.

**4. Generate datasets from your schema**

The CLI connects to ClickHouse, reads your tables, and writes a dataset definition for each one:

> [tab] TypeScript
>
> ```bash theme={null}
> npx hypequery generate:datasets
> ```
>
> This writes `analytics/datasets.ts`.

> [tab] Python
>
> ```bash theme={null}
> hypequery init
> ```

Review the generated definitions and rename dimensions and measures to match your product's language. A curated dataset looks like this:

> [tab] TypeScript
>
> ```typescript theme={null}
> import { dataset, dimension, measure } from '@hypequery/datasets';
>
> export const Orders = dataset('orders', {
>   source: 'orders',
>   tenantKey: 'tenant_id',
>   timeKey: 'created_at',
>   dimensions: {
>     country: dimension.string(),
>     status: dimension.string(),
>     createdAt: dimension.timestamp({ column: 'created_at' }),
>   },
>   measures: {
>     revenue: measure.sum('amount'),
>     orderCount: measure.count('id'),
>   },
> });
> ```

> [tab] Python
>
> ```python theme={null}
> from hypequery.datasets import dataset, dimension, measure
>
> orders = dataset(
>     "orders",
>     source="orders",
>     tenant_key="tenant_id",
>     time_key="created_at",
>     dimensions={
>         "country": dimension.string(),
>         "status": dimension.string(),
>         "createdAt": dimension.timestamp(column="created_at"),
>     },
>     measures={
>         "revenue": measure.sum("amount"),
>         "orderCount": measure.count("id"),
>     },
> )
> ```

**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:

> [tab] TypeScript
>
> ```typescript theme={null}
> import { createQueryBuilder } from '@hypequery/clickhouse';
> import { createDatasetClient, eq } from '@hypequery/datasets';
> import { Orders } from './analytics/datasets';
>
> const db = createQueryBuilder({
>   url: process.env.CLICKHOUSE_URL!,
>   username: process.env.CLICKHOUSE_USERNAME!,
>   password: process.env.CLICKHOUSE_PASSWORD!,
>   database: process.env.CLICKHOUSE_DATABASE!,
> });
>
> const analytics = createDatasetClient({ queryBuilder: db });
>
> const result = await analytics.execute(Orders, {
>   dimensions: ['country'],
>   measures: ['revenue', 'orderCount'],
>   filters: [eq('status', 'completed')],
>   orderBy: [{ field: 'revenue', direction: 'desc' }],
>   limit: 10,
> }, {
>   runtime: { tenant: 'org_123' },
> });
>
> console.log(result.data);
> ```

> [tab] Python
>
> ```python theme={null}
> from hypequery.datasets import (
>     DatasetQuery,
>     ExecutionContext,
>     create_dataset_client,
>     filter,
>     order,
>     tenant,
> )
> from hypequery.execution import ClickHouseConnection, create_clickhouse_executor
>
> analytics = create_dataset_client(
>     executor=create_clickhouse_executor(ClickHouseConnection.from_env()),
> )
>
> result = analytics.execute(
>     orders,
>     DatasetQuery(
>         dimensions=("country",),
>         measures=("revenue", "orderCount"),
>         filters=(filter.eq("status", "completed"),),
>         order_by=(order.desc("revenue"),),
>         limit=10,
>     ),
>     context=ExecutionContext(tenant=tenant("org_123")),
> )
>
> print(result.data)
> ```

## 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](https://hypequery.com/docs/datasets/serve-integration) and [Python serving](https://hypequery.com/docs/python/serving).
* **React hooks**: `@hypequery/react` generates typed TanStack Query hooks for those endpoints, so browser code never holds ClickHouse credentials. See [React](https://hypequery.com/docs/react/getting-started).
* **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](https://hypequery.com/docs/mcp/overview).

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](https://clickhouse.com/docs/chdb/index.md), the in-process ClickHouse engine, with no server and no credentials. See [chDB in TypeScript](https://hypequery.com/docs/chdb) and [chDB in Python](https://hypequery.com/docs/python/datasets/chdb).

## Learn more

* [TypeScript quick start](https://hypequery.com/docs/quick-start)
* [Python SDK](https://hypequery.com/docs/python)
* [Examples](https://github.com/hypequery/hypequery-examples)
* [hypequery on GitHub](https://github.com/hypequery/hypequery)
