Why hypequery

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

Most 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
export const api = defineServe({
  queries: {
    weeklyRevenue: query
      .input(z.object({ startDate: z.string() }))
      .query(({ ctx, input }) =>
        ctx.db
          .table('orders')
          .where('created_at', 'gte', input.startDate)
          .sum('total', 'revenue')
      ),
  },
});

Now use it everywhere:

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

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

// via HTTP
// POST /analytics/api/weeklyRevenue

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)

Next Steps

Continue: Installation Options - Choose serve or standalone

Or jump to: Quickstart - Start building (uses serve framework)