Why hypequery

The Problem: Analytics Logic Shouldn't Live in Five Different Places

Teams scatter SQL across API endpoints, dashboards and background jobs. Every service reimplements "active users" or "revenue" slightly differently.

The core issues:

• Changes require updating raw SQL in multiple places
• No single source of truth
• Type safety doesn't extend to analytics
• No version control for metric definitions
• Coordination overhead between teams

What hypequery Does

Define Analytics Once. Import Everywhere.

hypequery turns analytics queries into typed TypeScript functions that you define once and reuse across your entire stack.

// analytics/queries.ts
const { query, serve } = initServe({
  context: () => ({ db }),
});

const weeklyRevenue = query({
  input: z.object({ startDate: z.string() }),
  query: ({ ctx, input }) =>
    ctx.db
      .table('orders')
      .where('created_at', 'gte', input.startDate)
      .sum('total', 'revenue')
      .execute(),
});

export const api = serve({
  queries: { weeklyRevenue },
});

Now use it everywhere:

// In a cron job, background job or called by an AI agent
const digest = await api.run('weeklyRevenue', { input: { startDate: lastWeek } });

// In React
const { data } = useQuery('weeklyRevenue', { startDate: '2024-01-01' });

// via HTTP
// POST /weekly-revenue

When to Use hypequery

Use hypequery when you...

Build TypeScript applications with ClickHouse

• You're using ClickHouse as your analytics database
• Your backend is written in TypeScript
• You want to leverage existing TypeScript tooling

Need analytics in multiple places

• APIs need to expose analytics endpoints
• Background jobs compute metrics
• Dashboards display real-time data
• AI agents query your data
• Internal tools need metric access

Want type safety for your analytics layer

• Catch bugs at compile time, not in production
• Auto-completion for columns and tables
• Refactoring with confidence
• Clear contracts between data and application code

Need to expose analytics to AI agents safely

• Agents can discover available metrics
• Structured inputs prevent SQL injection
• Type schemas guide agent behavior
• No raw database access required

Run multi-tenant SaaS applications

• Auto-inject tenant filters at query level
• Impossible to leak data between customers
• Same metric definitions across all tenants
• Tenant isolation built into the framework

Want analytics logic in version control

• Metrics tracked in Git, not config files
• Code review for analytics changes
• Rollback capabilities
• Clear ownership and documentation

When NOT to Use hypequery

hypequery might not be right if you...

Don't use ClickHouse

• Currently ClickHouse-only
• If you need multi-database support, consider Cube.dev

Only need ad-hoc SQL queries

• Use a BI tool like Metabase or Superset
• hypequery is for reusable metrics, not one-off exploration
• BI tools excel at visual query building and exploration

Prefer GUI-based metric builders over code

• If your team doesn't write code, hypequery isn't the right fit
• Consider semantic layers with UI builders (Cube.dev, dbt)
• hypequery is code-first by design

Need a fully-managed hosted platform

• hypequery is a library, not a hosted service
• You manage your own infrastructure
• If you need managed infrastructure, consider cloud semantic layers

How hypequery Compares

vs. Direct SQL

✅ hypequery is better for:

• Type safety and IDE autocomplete
• Reusability across services
• Version control and code review
• Preventing SQL injection

❌ Trade-offs:

• Slight learning curve vs. raw SQL
• Abstraction layer adds minimal overhead

💡 When to use both:

• Use hypequery for reusable metrics
• Use direct SQL for one-off data exploration

vs. Query Builders (Prisma, Drizzle, Kysely)

✅ hypequery is better for:

• ClickHouse-specific features and optimizations
• Metrics layer on top of query building
• HTTP + OpenAPI generation
• Multi-tenancy patterns

❌ Query builders are better for:

• General CRUD operations
• Multi-database support (Postgres, MySQL, etc.)
• ORM-style workflows

💡 When to choose:

• Use hypequery for analytics/metrics
• Use Prisma/Drizzle for CRUD operations
• They solve different problems

vs. Semantic Layers (Cube.dev, dbt Semantic Layer)

✅ hypequery is better for:

• Embedded execution (no server required)
• Pure TypeScript (no YAML configs)
• Simpler setup without orchestration
• Static type-safe queries

❌ Semantic layers are better for:

• Pre-built integrations with 50+ BI tools
• Multi-database support
• Managed infrastructure options
• Larger teams with dedicated data platforms

💡 When to choose:

• Use hypequery for application-embedded analytics
• Use Cube/dbt for organization-wide semantic layer
• Consider hypequery if you want to avoid YAML/config files

Core Philosophy

Code-First, Not Config-First

hypequery treats analytics as code, not configuration:

• Metrics are TypeScript functions, not YAML definitions
• Changes go through code review, not UI forms
• Testing is part of your normal test suite
• Deployment uses your existing CI/CD pipeline

Embedded-First, Not Server-First

hypequery runs in-process by default:

• No required server or runtime dependency
• Execute queries directly in your application
• HTTP exposure is optional, not required
• Scales with your application, not a separate service

Composable Primitives, Not All-in-One Platform

hypequery provides opt-in building blocks:

• Use only what you need
• No required architecture
• Start with static queries, add HTTP later
• Add caching, multi-tenancy, or observability as needed

What hypequery Replaces (and What it Doesn't)

✅ Replaces

• Scattered SQL strings across your codebase
• Duplicated metric logic in different services
• Manual OpenAPI specs for analytics endpoints
• Custom API layers for exposing analytics
• Ad-hoc agent integrations without guardrails

❌ Doesn't Replace

• Your BI tool (use both together)
• Your ClickHouse instance (it's a SDK, not a database)
• Your data warehouse (complements, doesn't replace)
• Ad-hoc exploration tools (different use case)
• ETL pipelines (hypequery is for querying, not transformation)