Diagnostics for ClickHouse queries that underperform. Trace, correlate, and turn the slow query, memory spike, or tangled materialized view chain into a dashboard you can act on.
Demo of Shinro Query Analyzer
$ cat what-it-is.md
What it is.
Shinro Query Analyzer for ClickHouse is a diagnostic tool for ClickHouse engineers. It runs your query with ClickHouse's trace logging enabled, captures the detailed execution log the server emits, pulls the matching records from system tables (query_log, query_views_log, and others), and correlates the trace output with the structured query metadata. The result renders as a single dashboard you can read at a glance. An AI companion agent, initialized with the diagnostic context and ClickHouse's agentic skills, lets you interrogate the trace data in plain English.
Built for engineering teams already operating ClickHouse, where slow queries, memory spikes, and tangled materialized view chains are a recurring tax on the roadmap. Replaces the usual workflow of switching between shell commands, trace files, and system table queries with a single integrated view.
Free and open source - Source code and binary releases on GitHub.
Part of the Shinro family— Quest1's umbrella brand for AI-assisted engineering tooling, built to accelerate adoption of the technologies we partner on.
$ ls deliverables/
What you get.
Integrated trace and diagnostics.
Native ClickHouse client integration runs the query, captures the trace log the server emits, and surfaces the result in a structured dashboard.
Materialized view chain visualization.
Walks the dependency graph of chained MVs and consolidates bytes read, written, and memory pressure for each step in the chain.
AI companion agent.
Conversational diagnostic assistant powered by ClickHouse's official agentic skills and your AI provider of choice. Ask plain-English questions about the trace data.
Downloadable PDF reports.
Share complete diagnostic runs with teammates, post to incident reviews, or attach to upstream tickets.
Local-first architecture.
Trace logs and structured data stay encrypted on your machine under ~/.shinro. No data is sent to Quest1 servers.
Open source.
Source code and binary releases on GitHub. Inspect it, fork it, contribute.
$ ls scenarios/
Built for.
Five common diagnostic scenarios where the tool shortens the path from symptom to root cause.
01
Debugging slow queries
Time-related metrics across query stages, presented in a format that supports decisions in seconds rather than minutes of log-scrolling.
02
Investigating memory spikes
Memory usage, read volumes, and write volumes captured at every stage of execution and surfaced together. The data needed to answer "what blew up and why" in one place.
03
Understanding complex MV chains
Materialized view chains are one of ClickHouse's most powerful patterns and one of the harder ones to reason about at scale. The tool renders the chain visually, with per-step metrics, so the structure and the cost are visible at the same time.
04
Optimizing production workloads
Captures the metrics most often used to pinpoint and remediate production performance issues, without manual data gathering across multiple tools.
05
Helping newcomers self-diagnose
The AI companion answers questions about the trace data in plain English, lowering the ClickHouse expertise required to identify a problem and propose a fix.
$ cat how-it-works.md
How it works.
The tool uses the ClickHouse native client already installed on your machine. It executes your query with trace logging enabled, captures the detailed execution log the server emits, extracts the query ID, and gathers the corresponding records from ClickHouse system tables. A purpose-built parser converts the unstructured trace output into structured data and correlates it with the system table metadata. The consolidated result renders as a dashboard with the data points needed to identify the bottleneck.
For materialized view chains, the tool walks the dependency graph and aggregates per-step read, write, and memory metrics so memory pressure across the full chain is visible in one view.
The AI companion is initialized with the gathered diagnostic context plus ClickHouse's official agentic skills, then connected to the AI model of your choice. Conversations operate over your real trace data, not synthetic examples.
$ cat data-and-privacy.md
Data and privacy.
Shinro Query Analyzer for ClickHouse is local-first and open source. The tool does not call Quest1 servers as part of normal diagnostic operation. Calls go only to your ClickHouse server and to the AI provider you configure. The source code is on GitHub for inspection and audit.
Data
Local System
Quest1 Servers
AI Provider
ClickHouse connection details and credentials
Yes
No
No
ClickHouse queries gathered
Yes
No
No
Trace log data
Yes
No
Yes
ClickHouse system table data
Yes
No
Yes
MV fanout data
Yes
No
Yes
Query output rows
No
No
No
Feedback and feature requests
No
Yes
No
Structured diagnostic data stored locally is encrypted. Trace logs are written to ~/.shinro on the local filesystem only.
$ cat roadmap.md
Roadmap.
What's coming next, in order of likely release.
01
Sub-query level split analysis.
Decompose complex queries into stages and analyze each independently.
02
Full execution graph.
Single-pane view of the complete execution graph with all correlated metrics inline.
03
Expanded AI companion.
Deeper diagnostic reasoning for more complex query patterns.
04
JOIN analysis and recommendations.
Targeted analysis and suggestions for JOIN-heavy workloads.
05
Windows and Linux support.
Currently macOS ARM only; cross-platform builds in scope.
$ cat faq.md
FAQ.
How is the tool distributed?
Open source on GitHub. Clone the repo and build from source, or download a pre-built binary from the releases page. Requires a windowing system, the ClickHouse native command-line client, and a GUI browser.
What's the license?
Apache License Version 2.0
Is my data safe?
Yes. The tool makes no calls to Quest1 servers or services as part of diagnostic operation. All processing is local. Calls go only to the AI provider you configure and to your ClickHouse server. Local data is encrypted at rest. The source code is on GitHub if you want to verify any of this yourself.
What platforms are supported today?
macOS on Apple Silicon (ARM). Windows and Linux are on the roadmap.
Does it support both self-hosted (OSS) and ClickHouse Cloud?
Yes.
What ClickHouse versions are supported?
The tool supports version 25.x and above.
What query types are supported?
SELECT, INSERT, and UPDATE.
How are asynchronous inserts supported?
Async inserts are hard to trace by design — they execute in a separate scope with a different query ID from the one the client submitted, which breaks trace correlation. For diagnostic runs, the tool sets async_insert = 0 for the session, forcing the insert to execute synchronously so its trace and system table records line up with the query you submitted. The setting is scoped to the diagnostic session; your cluster's default async behavior is unaffected.
How do I get the tool?
See the GitHub link in the CTA below. Clone, build, or download a release binary.
Can I contribute?
Yes. Issues, pull requests, and bug reports welcome on the GitHub repo.
$ cat next-steps.md
Two ways forward.
Get the Tool
Free and open source. Clone the repo, build from source, or grab a binary from the releases page.
Already running ClickHouse at scale and need engineers in the room? Our team co-delivers with the ClickHouse engineering team on Ignite Tier engagements.
