Turn Your ClickHouse Schema Into a Type-Safe Analytics Layer in 5 Minutes

ClickHouse is fast. Your developer experience with it? Not so much.

The old way: Raw SQL strings in TypeScript

No autocomplete. No type safety. Refactors are a game of find-and-replace across string literals. Errors show up in production, not at compile time.

Here's the new way:

Full autocomplete. Compile-time type checking. Refactor-friendly.

What makes this possible is a schema-driven analytics layer, and it takes about 30 seconds to set up with ClickHouse.

In this post, you'll go from a plain ClickHouse schema to a schema-driven analytics layer (typed SDK + HTTP API + React hooks) in about 5 minutes.

Step 1: Point hypequery at your ClickHouse (30 seconds)

Run one command:

The CLI prompts for your connection details:

That's it. You now have:

• Full TypeScript SDK for your ClickHouse schema
• Example query already set up
• Serve layer (the built-in HTTP server) pre-configured and ready to run
• Type-safe API endpoints

Step 2: Start Your Dev Server (Instant HTTP API)

The CLI already generated a server setup in analytics/queries.ts:

Start the server:

That's it. You now have:

• HTTP endpoint: http://localhost:4000/sessionsQuery
• Interactive docs: http://localhost:4000/docs (try it)
• OpenAPI spec: http://localhost:4000/openapi.json

Add more queries to queries.ts and they automatically become HTTP endpoints with zero additional code.

Step 3: Your Schema Becomes a TypeScript SDK (Auto-Generated)

Open analytics/schema.ts. You'll see typed interfaces for every table.

Note: This file is generated. You don't edit it by hand; rerun npx @hypequery/cli generate when your schema changes.

Open analytics/client.ts:

You're ready. Type db. and your IDE shows all 47 tables. Pick one and you get every column with autocomplete.

Step 4: Real Queries, Real Types

Simple query with full autocomplete

Note: Here we're passing a typed Date boundary. You can still use SQL expressions when needed, but this pattern keeps filters strongly typed end-to-end.

What you get:

• Autocomplete for table names
• Autocomplete for column names within each table
• Compile-time checking that created_at exists
• Full type inference for the result

Joins with type safety

Complex aggregations

Errors caught at compile time

No more runtime surprises. Your IDE tells you what's wrong before you run the code.

Step 5: Schema Regenerate in One Command

Here's where schema-driven SDKs shine: your schema evolves, and your types stay in sync automatically.

Scenario: Add a column to ClickHouse

Scenario: Rename a column

Your interface now has device instead of device_type.

TypeScript tells you every query that broke. Fix them with confidence, then deploy.

Step 6: Add More Queries (Instant API Endpoints)

Add new queries to analytics/queries.ts:

Save the file and the dev server auto-reloads.

Everything is available at /docs with interactive Swagger UI.

Same query works everywhere:

For the React dashboard, create hooks in a few lines:

Get Started in 30 Seconds

You'll have a full TypeScript SDK for your ClickHouse database before your coffee gets cold.