ClickHouse Studio Mind

Inspiration

Studio executives make greenlight, marketing, and renewal decisions on numbers they can't interrogate — a dashboard says viewers dropped 12%, and the meeting stalls on "where did that come from?" We built ClickHouse Studio Mind for exactly that moment: every number in the brief carries its receipt — the SQL, the query plan, the rows returned, and what the scan cost, straight from ClickHouse's own system.query_log.

What it does

Ask in plain English — "Which genres keep viewers past episode 3 in EMEA?" — and get a one-page decision brief in which no number exists without a SQL receipt. Each claim cites a query ID, clickable through to the statement, its result, and its scan cost (wall ms, server ms, rows read, bytes).

Beyond on-demand asks, a 7 a.m. brief compares yesterday to the trailing week with z-scores and a watchlist. In the demo, a CDN rebuffer spike is flagged and attributed (NA · mobile, 20.5s median) before support even notices — "observability for decisions."

How we built it

• ClickHouse-native by construction. A 50-million-row viewing_events fact table (MergeTree, bloom-filter indices, materialized date column); uniqExact DAU, countIf churn windows, and QoE rollups computed in-engine.
• One door to the warehouse. Every call — asks and the morning brief alike — goes through the official mcp-clickhouse server, read-only by construction (sqlguard + server-side readonly role).
• Gemini 2.5 Flash on Vertex AI. Planning, diagnosis, and write-up run on Google Cloud — zero OpenAI/Anthropic code paths.
• Evidence registry + span trees. Each run emits a Langfuse-shaped span tree (stages → LLM generations → MCP tool calls with scan facts) rendered in the UI, so the pipeline narrates itself.
• Deployed on Vercel — hosted, no login, live 50M-row asks on camera.

Challenges we ran into

• Attributing scan costs reliably. system.query_log flushes asynchronously (~10s on ClickHouse Cloud), so receipts had to match queries by SQL fragment with a bounded backfill — fail-open, never blocking the brief.
• Making "read-only" actually mean it. Guards live in three layers: sqlguard validation, the MCP server's read-only role, and the ClickHouse user's grants.
• Exec-grade latency. Heavy asks run ~50s on camera; we kept users inside a statusline that narrates each pipeline stage, turning wait into storytelling.

Accomplishments we're proud of

A decision brief where the trust layer is the product: every claim clickable to SQL + plan + scan cost, and a live hosted demo on real 50M-row data with no login.

What we learned

Judges and executives share one instinct: trust is earned per number, not per demo. Citing system.query_log inside the answer itself — not in a docs appendix — changed how people argued with the brief.

Built With

• 2.5
• ai
• clickhouse
• cloud
• context
• fastapi
• flash
• gemini
• google
• mcp-clickhouse
• model
• protocol
• python
• typescript
• vercel
• vertex