OptiHouseDocs
Open app
Getting started

OptiHouse documentation

OptiHouse is a read-only observability and optimization platform for ClickHouse. It connects to your cluster, scans the system tables, and turns what it finds into ranked, copy-paste-ready fixes — each with an expected impact and a confidence score.

What it does

Every 15 minutes OptiHouse collects a snapshot from query_log, system.parts, system.replicas, system.columns and a handful of other system tables. It compares the snapshot against the previous one, runs ~40 analyzers over it, and produces three kinds of output:

Recommendations
Ranked findings — zombie materialized views, fragmented storage, missing PREWHERE, codec opportunities — each with diagnostic SQL and a runbook.
SQL Optimizer
Paste any query and get a before/after rewrite that is PARTITION-friendly, FINAL-free and index-aware.
Anomaly detection
Scan-over-scan diffing flags queries that suddenly read 10× more bytes or run 5× longer than yesterday.
Cluster health
Replicas, mutations, merges and disk capacity at a glance — with days-until-full forecasts on every disk.

How a scan works

  1. 1
    Connect read-only
    Add a ClickHouse host with a read-only user. An SSH bastion is supported for VPC-locked clusters.
  2. 2
    Collect
    OptiHouse pulls a snapshot from system.*. No agents run on your boxes — the platform connects out to the cluster, not the other way round.
  3. 3
    Analyze
    Storage, query, schedule and cluster analyzers run over the snapshot. Each produces zero or more recommendations.
  4. 4
    Rank & explain
    Findings are ranked by expected impact in dollars and severity, then attached to an auto-generated runbook.

Is it safe?

OptiHouse only ever issues SELECT statements against system.* tables. It never writes data, never alters schema and never touches your application tables. The recommended ClickHouse user has readonly = 1 set, so the database itself enforces this.

Read-only by design
No agents, no writes, no schema changes — ever. See Security & privacy for the full threat model and the read-only user recipe.

Where to next

  • Quick start — connect a cluster and see your first recommendations in under five minutes.
  • Connecting ClickHouse — the five connectivity modes and the read-only user recipe.
  • Recommendation catalog — every finding the platform can produce, grouped into ten waves.
  • API reference — drive scans and read findings programmatically.