The type-safe analytics backend for ClickHouse

Define metrics once, execute them anywhere (inline, HTTP, React, agents), and keep everything backed by your ClickHouse schema.

Docs • Roadmap • Examples

Why hypequery

• 🔁 Reuse metrics across SSR routes, background jobs, cron tasks, and agents
• 🧩 Built-in HTTP server with docs + OpenAPI (hypequery dev)
• 🔐 Auth, multi-tenant helpers, and lifecycle hooks
• ⚡ Query-level caching, logging, streaming, and analytics
• 🧪 Type-safe execution + schema-aware validation

Quick Start

No installation needed — run directly with npx:

npm install -D @hypequery/cli
npx hypequery init

Query Builder

Get started with type-safe ClickHouse queries in seconds. Generate TypeScript types from your schema, then build queries with full autocomplete and compile-time safety.

# Generate types from your ClickHouse schema
npm install @hypequery/clickhouse
npx hypequery generate

import { createQueryBuilder } from '@hypequery/clickhouse';
import type { IntrospectedSchema } from './generated-schema';

const db = createQueryBuilder<IntrospectedSchema>({
  host: 'your-clickhouse-host',
  username: 'default',
  password: '',
  database: 'default',
});

// Fully type-safe — columns, operators, and return types are all inferred
const revenue = await db
  .table('orders')
  .where('created_at', 'gte', '2026-01-01')
  .sum('total', 'revenue')
  .groupBy(['region'])
  .execute();

No SQL strings. No runtime surprises when your schema changes.

Going Further: Governed APIs with @hypequery/serve

Need to share metrics across services, expose HTTP endpoints, or give AI agents structured access to your data? @hypequery/serve wraps your queries into a governed, reusable API layer.

import { initServe, type InferQueryResult } from '@hypequery/serve';
import { z } from 'zod';
import { db } from './analytics/client';

const serve = initServe({
  context: () => ({ db }),
});

export const api = serve.define({
  queries: serve.queries({
    activeUsers: serve.query
      .describe('List active users')
      .input(z.object({ region: z.string() }))
      .query(async ({ ctx, input }) =>
        ctx.db
          .table('users')
          .where('status', 'eq', 'active')
          .where('region', 'eq', input.region)
      ),
  }),
});

// Export typed helpers for downstream usage
export type ActiveUsersResult = InferQueryResult<typeof api, 'activeUsers'>;

Execute everywhere

Inline

const users = await api.run('activeUsers', { input: { region: 'EU' } });

HTTP API

GET /api/activeUsers?region=EU

React

const { data } = useQuery('activeUsers', { region: 'EU' });

AI Agent

const catalog = api.describe();
const result = await api.run('activeUsers', { input: { region: 'EU' } });

One definition. Every consumer.

CLI

# Scaffold analytics folder + env vars
npx @hypequery/cli init

# Dev server with docs & OpenAPI
npx @hypequery/cli dev

# Regenerate schema types
npx @hypequery/cli generate

See the CLI documentation for all options.

Features

• Type-safe definitions – strong typing for inputs, outputs, joins, filters
• SQL expression helpers – raw, rawAs, selectExpr, toDateTime, etc.
• Advanced filtering – predicate builders, nested whereGroup, custom operators
• Caching & observability – SWR cache modes, deduplication, query logging
• Streaming – Web Streams for large datasets

License

Copyright 2026 hypequery

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

See LICENSE for the full license text.