Quickstart

Launch a type-safe analytics API in minutes. You only need four steps:

  1. Install the runtime packages
  2. Run hypequery init to scaffold analytics files
  3. Define a real query
  4. Preview docs with hypequery dev (optional)

Prerequisites

  • Node.js 18+
  • Access to a ClickHouse instance with credentials

Step 1 – Install the runtime

# Core packages (required)
npm install @hypequery/clickhouse @hypequery/serve

# Optional: install the CLI locally (otherwise keep using npx @hypequery/cli)
npm install -D @hypequery/cli

Step 2 – Scaffold analytics with hypequery init

From your project root run:

# Without CLI installed
npx @hypequery/cli init

# Or if CLI is installed
npx hypequery init

Pick ClickHouse, supply your connection settings, and choose a destination folder (analytics/ by default). The CLI will:

  • Validate the ClickHouse connection
  • Generate analytics/schema.ts, analytics/client.ts, and analytics/queries.ts
  • Write/append .env with your credentials
  • Populate an example query (optional) and register it in the queries file

Open analytics/queries.ts to see the scaffolded initServe export with the fluent builder. You can start editing immediately.

Step 3 – Define your first query

Replace the placeholder query in analytics/queries.ts with something real. For example:

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

const { define, queries, query } = initServe({
  context: () => ({ db }),
});

export const api = define({
  queries: queries({
    activeUsers: query
      .describe('Most recent active users')
      .input(z.object({ limit: z.number().min(1).max(500).default(50) }))
      .query(({ ctx, input }) =>
        ctx.db
          .table('users')
          .select(['id', 'email', 'created_at'])
          .where('status', 'eq', 'active')
          .orderBy('created_at', 'DESC')
          .limit(input.limit)
          .execute()
      ),
  }),
});

// Run embedded (jobs, SSR, scripts)
const latest = await api.run('activeUsers', { limit: 25 });

// Or expose over HTTP
api.route('/active-users', api.queries.activeUsers, { method: 'POST' });

Remember

  • Use ctx.db inside serve queries (it carries per-request context)
  • Return the promise; hypequery awaits it for you
  • Always finish query builder chains with .execute()

Save the file and, if you’re running hypequery dev, the docs immediately show the new metric with typed inputs/outputs.

Step 4 – Preview docs with hypequery dev (optional)

Run the dev server whenever you want docs plus an OpenAPI description for the HTTP surface area of your queries:

# Without CLI installed
npx @hypequery/cli dev

# Or if CLI is installed
npx hypequery dev

The command watches your analytics files, refreshes docs, and exposes:

Leave this running while you iterate or while teammates need to hit the HTTP preview locally.

Next Steps

Continue learning: Installation Options - Choose your path (serve vs standalone)

Or dive into: