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.
Collection of examples demonstrating how to use hypequery with different frameworks and architectures for building type-safe analytics applications with ClickHouse.
| Example | Framework | Use Case | Key Features |
|---|---|---|---|
| next-js | Next.js 15 | Full-stack analytics dashboard with API routes | • Server-side API routes with Next.js App Router • React Query integration for data fetching • Real-time analytics dashboard • Type-safe queries with Zod validation • Route handlers at /api/analytics |
| node-js | Node.js + Hono | Backend API server for analytics queries | • REST API with Hono framework • In-process query execution • Lightweight, fast HTTP server • Easy deployment to Node.js hosting • Direct query integration with routes |
| vite | React + Vite | Client-side app with dev API server | • Modern React build with Vite • Development API server with hot reload • Client-side mutations with React hooks • Fast development experience • Separate API and frontend processes |
Each example is self-contained. Navigate to the example directory and follow its specific setup instructions:
cd next-js # or node-js or vite
npm install
npm run devFull-featured analytics dashboard demonstrating:
- API Routes: Server-side route handlers at
/api/analytics/[...path] - Queries: Daily stats, top pickup locations, revenue by payment type
- Frontend: Dashboard pages with charts and data tables
- Best for: Production applications with both frontend and backend
Run:
cd next-js
npm install
npm run dev
# Visit http://localhost:3000Lightweight backend API demonstrating:
- Framework: Hono for fast HTTP routing
- Usage: In-process query execution
- Deployment: Simple Node.js server
- Best for: API-only applications, microservices
Run:
cd node-js
npm install
npm run dev
# API available at http://localhost:3000Client-side application demonstrating:
- Build Tool: Vite for fast development
- API: Separate dev server for analytics queries
- Frontend: React with hooks for mutations
- Best for: SPA development, prototyping
Run:
cd vite
npm install
npm run dev:all # Runs both Vite and API server
# Visit http://localhost:5173All examples use ClickHouse with the NYC Taxi dataset. Configure your environment variables:
# In each example directory, create .env.local:
CLICKHOUSE_HOST=your-clickhouse-host:8443
CLICKHOUSE_DATABASE=nyc_taxi
CLICKHOUSE_USERNAME=default
CLICKHOUSE_PASSWORD=your-passwordSee .env.example in each directory for reference.
- Type-Safe Queries: End-to-end type safety from database to frontend
- Query Definitions: Declarative query definitions with Zod schemas
- Multiple Runtimes: Works with Next.js, Node.js, and React
- ClickHouse Integration: Native ClickHouse query builder
- API Generation: Automatic API route generation from query definitions
Apache 2.0