DataStoria
An AI-native ClickHouse console for cluster diagnostics, query generation, evidence-based optimization, and visualization.
- Source repo
- FrankChen021/datastoria
- Stars
- ★ 328
- Last updated
- 4mo ago
- License
- NOASSERTION
- Primary language
- TypeScript
- FA score
- 45/100 · Major gaps
At a glance
- How it runs
- Works with
- Universal · cross-platform
- Cost
- Free tier plus a paid hosted plan
- Setup effort
- Medium · a few setup steps
- You'll need
- Typical use
- A data engineer debugging a slow query inspects the System Log timeline and topology, then evaluates AI optimization suggestions before rewriting.
- Not a fit if
- Teams that do not run ClickHouse and have no cluster diagnostics needs
- Teams that need a fully offline UI with no LLM provider connection at all
- Users who need a general-purpose multi-database admin tool rather than a ClickHouse console
- Website
- datastoria.app ↗ set on GitHub
- Maintenance
- Commits in the last 6 monthslast commit 2026-07-21
- Source review
- 45/100 · Major gaps 1 safety controls not found
What does this agent do, and when should you use it?
DataStoria is an AI-native ClickHouse console built on Next.js 16 and React 19 that combines a SQL editor, cluster monitoring dashboards, and chart visualization in one web interface. Users can describe data needs in plain English and receive validated ClickHouse SQL, along with optimization suggestions grounded in schema inspection and collected execution evidence. The console also provides visual explain plans, dependency graphs, a System Log inspector, and multi-node, multi-cluster monitoring panels. Queries execute from the browser directly against your ClickHouse server, and for AI-generated visualizations the model only emits SQL plus a chart spec while the browser fetches and renders the data locally. It can be used through the hosted site, built from source, or self-hosted via the official Docker image.
The end-to-end flow: a user either writes SQL in the editor and sends it to a connected ClickHouse instance, or states a requirement in natural language, which a configured model (via the Vercel AI SDK, supporting OpenAI, Anthropic Claude, Gemini, GitHub Copilot, OpenRouter, Groq, Cerebras, Nebius and more) turns into ClickHouse SQL. In optimization mode the AI inspects the schema, validates the SQL, and collects evidence before recommending concrete performance improvements. In visualization mode the model produces SQL and a chart spec (time series, bar, pie, table) while the browser pulls and renders the data. The console additionally offers one-click Explain with AST and pipeline views, a dependency graph across materialized views and distributed tables, System Log timeline and topology views, and dashboards for node metrics, merge operations, and replication status. A SKILL-based agent architecture and the official ClickHouse Agent Skills help save tokens across multi-turn conversations.
- A data engineer debugging a slow query inspects the System Log timeline and topology, then evaluates AI optimization suggestions before rewriting.
- An analyst who does not write SQL describes the metric and time range, and gets a runnable ClickHouse query plus a chart.
- An SRE checks a cluster through the multi-node dashboard for real-time metrics, merge progress, and replication status across clusters.
- A warehouse maintainer traces lineage through the dependency graph across materialized views, distributed tables, and external systems.
- A security-conscious team keeps credentials in the browser with direct ClickHouse connections and its own LLM API key.
- A developer with an existing GitHub Copilot subscription signs in via GitHub device flow and reuses it for query assistance.
Key setup facts
Pulled from the install and usage notes below. The project README has the current values.
- Install / run
npm install --forcedocker run -d -p 3000:3000 frankchen021/datastoria:latest
- Ports
3000- Install notes cover
- Linux · Docker
How do you install or deploy this agent?
Option 1 — build from source (requires Node.js v22 or later and pnpm):
git clone --recurse-submodules https://github.com/FrankChen021/datastoria.git
cd datastoria
npm install --force
npm run devThen open http://localhost:3000 and connect to your ClickHouse instance.
Option 2 — self-host with the official Docker image (supports linux/amd64 and linux/arm64):
docker run -d -p 3000:3000 frankchen021/datastoria:latestAI features require an LLM provider API key; see doc/dev/llm-provider-api-key.md. OAuth setup for Google, GitHub, and Microsoft is documented in doc/dev/authentication.md.
How do you use this agent?
Open the console (http://localhost:3000 locally or dataStoria.app for the hosted experience), add your ClickHouse connection, and queries will go straight from the browser to that instance. For AI features, supply your own API key in settings or sign in with GitHub device flow to use a Copilot subscription.
A typical session:
1. Write and format a query in the SQL editor; syntax errors are highlighted by line and column
2. Ask in plain English, e.g. "requests per hour over the last 7 days", and get SQL plus a chart
3. Click Explain on a query to see the AST and execution pipeline
4. Request optimization suggestions so the model reads schema and execution evidence
5. Open cluster dashboards and the dependency graph to check node metrics, merges, replication, and table lineageWhat are this agent's strengths and limitations?
- Queries run directly from the browser to ClickHouse, so credentials and results never pass through a third-party server.
- AI optimization inspects schema, validates SQL, and gathers execution evidence before recommending changes rather than only rewriting text.
- Broad model-provider coverage including OpenAI, Anthropic, Gemini, GitHub Copilot, OpenRouter, Groq, Cerebras, and Nebius.
- SQL editing, explain plans, System Log, dependency graph, and cluster monitoring live in one interface, reducing tool switching.
- Docker image supports both amd64 and arm64, making self-hosting straightforward.
- ClickHouse only — it cannot manage other databases, so multi-database shops still need additional tooling.
- AI features depend on an external LLM service and your own API key, adding per-use cost and network requirements.
- Building from source requires Node.js v22+ and npm install --force, which implies dependency-resolution workarounds.
- The repository license field reports NOASSERTION while the README states Apache License 2.0 — confirm before any compliance review.
- No clear documentation of role-based access control or multi-user governance for enterprise use.
How does this agent compare with similar options?
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| DataStoria This agent | 45 · Major gaps | Web appFreemium | ★ 328 | 4mo ago | TypeScript | — |
| WhoDB | 54 · Major gaps | Self-hosted serviceFreemium | ★ 5.1k | 1d ago | Go | — |
| Lumen Data Exploration Framework | 46 · Major gaps | CLI | ★ 355 | 1d ago | Python | — |
| ChatLab — Chat History Analyzer | 70 · Some gaps | Desktop appFree + model costs | ★ 7.7k | 2d ago | TypeScript | — |
How does FollowAgents rate this agent?
Why each dimension lost points
least_privilege: AGENTS.md asks for server-only secrets and input validation at API boundaries, but no concrete permission model or least-privilege implementation is shown; principle-level only, deducted. user_confirmation: AGENTS.md mandates showing changed files and waiting for explicit user approval before push/PR, a verifiable confirmation gate, but it covers the dev workflow rather than product runtime, so 2. data_flow_transparency: README states SQL runs browser-to-ClickHouse, credentials and results stay local, bring-your-own API key; direction is clear but what is sent to LLM providers is not detailed, deducted. sensitive_data_handling: authentication.md covers NEXTAUTH_SECRET, OAuth secrets and not committing .env, but ALLOW_ANONYMOUS_USER defaults to true and no data redaction is described, deducted. dependency_security: CI generates SLSA provenance and SBOM and overrides pin some deps, but next-auth is beta, file: local deps and npm install --force are used, and no vulnerability scan step exists, deducted. external_effects: the product executes queries against ClickHouse and calls LLM providers, but no interception of write or destructive SQL is described, deducted. rollback: no rollback or undo mechanism is documented, 0. source_attribution: SKILL.md carries author metadata and LICENSE names a copyright holder, but publisher identity is unverified, deducted.
self_consistency: README, AGENTS.md, package.json scripts and CI steps largely agree (dev/build/test/lint/typecheck all exist), but README requires Node v22 while authentication.md says Node 18+, an inconsistency, deducted. dependency_availability: many file: local submodule deps and external/ build scripts require --recurse-submodules and --force install, so availability depends on external submodules, deducted. failure_messages: SKILL.md and authentication.md give some error-handling guidance (best-effort when skill_resource is empty, troubleshooting section), but product-level error messaging evidence is limited, deducted.
audience_and_scenarios: README targets ClickHouse ops and query workflows; SKILL.md covers system-table queries, cluster diagnosis, error diagnosis and SQL optimization, scenarios are clear, 2. capability_boundaries: several SKILL.md files state When Not To Use, tool boundaries and fallbacks to other skills, boundaries are well handled, 2. trigger_precision: SKILL.md descriptions and trigger words are fairly specific (system tables, query_log, error code), but some triggering relies on model judgment, deducted. environment_fit: Docker multi-arch and local build are supported, but Node 22, pnpm, submodules and --force install raise environment cost, deducted.
information_architecture: README is well sectioned and docs plus AGENTS.md describe structure, 2. install_notes: README and authentication.md give build, Docker and OAuth setup steps, fairly complete, 2. naming_stability: package.json version is 0.0.0 and no versioning policy is visible, deducted. examples_and_faq: SQL examples and a troubleshooting section exist, but examples and FAQ are sparse overall, deducted. known_limitations: SKILL.md notes Phase 1 supports only some RCA symptoms, a local limitation, but product-level known limitations are absent, deducted. license: LICENSE is full Apache 2.0 and README matches, 2. versioning_changelog: no CHANGELOG or release notes found, 0. maintenance_responsibility: CI and release flow exist, but publisher identity is unverified and no maintainer statement is given, deducted.
output_usability: SKILL.md prescribes mandatory output formats (tables, RCA structure, SQL examples), outputs are directly usable, 2. marginal_value: an AI-native ClickHouse console combining diagnostics, optimization and visualization adds incremental value over generic tools, 2. cost_benefit: requires self-hosting a Next.js app, configuring multiple LLM keys and OAuth, so deployment and maintenance cost is high, deducted.
claim_traceability: README feature claims mostly lack corresponding code or test references; only SKILL.md and tool names are partly traceable, deducted. cross_source_corroboration: README, AGENTS.md, package.json and CI corroborate each other on scripts and tech, but feature claims lack cross-source support, deducted. fact_inference_separation: docs mix factual statements with promotional claims (e.g. 100% local execution) without clear separation, deducted.
- Not found in source: rollback or recovery pathBack up first, or work on a git branch or snapshot, so its changes can be undone.
- ALLOW_ANONYMOUS_USER defaults to true, so the app is accessible anonymously without OAuth; explicitly disable it before production deployment.
- README claims 100% local execution, but AI features send query and schema context to third-party LLM providers; assess the data egress scope yourself.
- Dependencies include next-auth beta, file: local submodules and npm install --force; supply-chain and reproducibility risks need independent review.
- No interception or rollback mechanism for write or destructive SQL is documented; be cautious when connecting to production clusters.
- Publisher identity is unverified; evaluate trust independently before using the Docker image or the hosted dataStoria.app site.
FAQ
Which port does DataStoria use?
Is DataStoria free?
Is DataStoria open source?
Is DataStoria safe to use?
Is DataStoria still maintained?
Who makes DataStoria?
What is DataStoria's official website?
Thanks — we use this to improve the page.