Exploring

Next up

In Progress

Done

hypequery roadmap

A command to re-generate types, identify schema drift, smoke test the queries with performance testing and differences. Something like the below: <code>$ npx hypequery test</code><code>🔍 Schema Check </code><code>✓ All types match database schema </code><code>⚠️ New column 'users.deleted_at' detected</code><code>🧪 Smoke Test (running queries) </code><code>✓ activeUsers (45ms, 12 rows) </code><code>✓ revenueByMonth (120ms, 24 rows) </code><code>✓ topCustomers (2100ms, 50 rows)</code><code>📊 Performance Check </code><code>✓ All queries within thresholds </code><code>⚠️ topCustomers is slow (2100ms &gt; 1000ms threshold)</code>

In Review

hypequery test package for query testing

Luke

ContextCurrently only the underlying query builder supports streaming, we need first class support through <code>defineServe.</code>GoalSupport for streaming large result sets. Integration with serve package for HTTP streaming responses.

Streaming query support in datasets serve package

ContextFor successful adoption and deployment GoalComprehensive deployment guides for Kubernetes (Helm chart), Docker Compose, AWS ECS/Fargate, Vercel Edge, and Cloudflare Workers. Include reference architectures and best practices. Currently NO deployment guides exist.

Production Deployment Guides

ContextEnable easier adoption of hypequery from existing toolingGoalBuild automated migration tools from Cube.js (data model converter), Metabase (question importer), and custom SQL (translator to query builder). Include side-by-side comparison guides. Lower barrier to adoption.

Migration Tools from Alternatives

ContextPublish performance benchmarks for comparisonGoal Benchmark hypequery performance to raw ClickHouse queries, Cube.js, and custom APIs. Include cache effectiveness analysis, query latency comparisons, and type safety overhead measurements.

Performance Benchmarks

ContextEnable first class caching support in defineServe for better control and loggingGoalCurrently, caching is managed just at the underlying query builder level, which does not enable observability at the query definition layer.By managing this instead where users defined queries we can improve the management of cache controls, observability and reporting

Caching support in serve package

ContextImprove developer experienceGoalCurrently the hypequery dev server just provides documentation for the generated endpoints, it would be great to have further features for tracing, observability and debugging.<ul><li>Query list for inspection (raw sql &amp; query builder syntax) and running via a UI to test the output with parameterised inputs</li><li>Logs showing run query history, completion status, cache status</li></ul>

Planned

Expand hypequery dev server feature set

Some thoughts on implementation and rollout:<ul><li>Phase 1: Define Scope</li></ul> - Support typed row inserts into existing ClickHouse tables. - Start with JSONEachRow only. - Exclude schema migrations, table creation, INSERT ... SELECT, and bulk file ingestion from v1.<ul><li>Phase 2: Add Adapter Support</li></ul> - Extend the internal database adapter with an insert capability. - Implement it in the ClickHouse adapter using the native ClickHouse client’s insert API. - Preserve existing query, stream, raw SQL, and cache behavior unchanged. <ul><li>Phase 3: Add Public API</li></ul> - Add a direct db.insert(table, rows, options) API. - Accept either a single row or an array of rows. - Support per-insert options like queryId and ClickHouse settings. - Keep insertion separate from the existing select query builder.<ul><li>Phase 4: Add Type Safety</li></ul> - Reuse existing schema inference so insert rows are typed from table columns. - Validate table names at compile time. - Validate row field names and value types at compile time. - Decide whether v1 rows are strict or partially optional.<ul><li>Phase 5: Improve Generated Types</li></ul> - Enrich schema generation with ClickHouse column metadata. - Detect nullable columns, defaults, materialized columns, alias columns, and generated expressions. - Use that metadata to make insert row types more accurate. - Mark server-generated columns as omitted or readonly for inserts.<ul><li>Phase 6: Runtime Guards</li></ul> - Throw a clear error if an adapter does not support inserts. - Normalize single-row inserts into arrays. - Reject empty row arrays unless there is a deliberate no-op policy. - Add useful logging around insert execution and failures.<ul><li>Phase 7: Tests</li></ul> - Unit test adapter insert forwarding. - Unit test public db.insert() behavior. - Type test valid and invalid insert rows. - Integration test insert rows into a temporary ClickHouse table and read them back with the existing query builder.<ul><li>Phase 8: Documentation</li></ul> - Document simple row insertion. - Document batching guidance. - Document supported formats and current limitations. - Add examples for generated schemas and hand-written schemas.<ul><li> Phase 9: Advanced Insert Support</li></ul> - Add optional support for custom insert formats. - Consider insertFromSelect or raw insert helpers. - Consider batch helpers for high-volume ingestion. - Consider dataset-level write APIs only after core insert support is stable.

Completed

hypequery insertion support

ContextRe-enable automated deploymentGoalRe-enable automated releases with Changesets (currently disabled). Set up automated NPM publishing on merge to main, changelog generation, release notes, and pre-release channels (beta, rc).

Automated Release Pipeline

ContextUsers can only currently define standalone queries which limits the following use cases :<ul><li>AI Agents: Can't accurately generate queries based on natural language questions, without a pre-defined query</li><li>Dashboard Builders: Users can't drag-and-drop dimensions/measures</li><li>BI Tool Integration: Can't accept dynamic SQL/GraphQL queries</li><li>Multi-Tenant Custom Views: Each tenant can't define their own metrics</li></ul>GoalCreate dynamic API for runtime queries, with a separate entry point to queries.I imagine the API looking something like the below: <pre><code>// generated-datasets.ts (auto-generated)
export const datasets = {
 trips: defineDataset({
 table: 'trips',
 dimensions: {
 pickup_datetime: dimension.datetime('pickup_datetime'),
 pickup_date: dimension.date('toDate(pickup_datetime)'),
 payment_type: dimension.string('payment_type'),
 // ... all columns from schema
 },
 measures: {
 count: measure.count(),
 total_revenue: measure.sum('total_amount'),
 avg_distance: measure.avg('trip_distance'),
 // ... common aggregations
 },
 }),
} as const;

// ===== DYNAMIC QUERIES =====
const dynamicResults = await db.queryDataset(datasets.trips, {
 dimensions: ['pickup_date', 'payment_type'] as const,
 measures: ['count', 'total_revenue'] as const,
});
// Type: Array&lt;{ pickup_date: Date; payment_type: string; count: number; total_revenue: number }&gt;

// ===== FULLY DYNAMIC (No Type Inference) =====
const aiResults = await db.queryDataset(datasets.trips, parseUserInput(query));
// Type: DynamicQueryResult (Record&lt;string, any&gt; with metadata)

// ===== AI AGENT TOOL GENERATION =====
const tools = db.generateTools(datasets.trips, {
 mode: 'per-query', // One tool per predefined query
 // OR
 mode: 'catalog', // Single tool with dimension/measure selection
});

export const api = defineServe({
 queries: {
 // Auto-generated from dataset
 ...datasets.trips.toQueries(),
 }
});</code></pre>

Add dynamic dataset api

ContextHelp users get started faster with hypequeryGoalCreate a github repo of hypequery runnable examples to get users up to speed faster. This should include the major use cases:<ul><li>Frontend integration (next, vite)</li><li>Background jobs and scheduled reports</li><li>AI agent integration (langchain, ai sdk)</li><li>Data export APIs</li><li>Analytics microservices</li></ul>

Community Examples Library

ContextEnable users to start using hypequery faster, with no frictionGoalExpand the documentation quickstart and recipes sections with the following:<ul><li>Authentication</li><li>Cron</li><li>Background jobs</li><li>Multi-tenancy</li></ul>