Overview
The most effective way to speed up a slow ClickHouse query is usually not to change the query itself, but to optimize the underlying data model it reads from. There are several strategies within the data modeling layer: reordering the ORDER BY to match your filter patterns, switching the table engine, or adding a materialized view. Often there is more than one approach worth trying, and you want to test each one to see which actually performs best.
This workflow gives your coding agent a performance testing harness to try different data model optimizations against the query you want to speed up. All benchmarking runs on databases isolated from production, and you review the results before anything ships.
What does the performance testing harness do?
The harness runs a controlled experiment on your behalf. The agent first profiles the slow query to understand where the bottleneck is, then proposes candidate data model changes based on what it finds and the ClickHouse best practices rules included in the harness. It applies each candidate on its own git branch, then uses Fiveonefour preview branches to deploy and benchmark that change against an isolated ClickHouse database. Every candidate is compared back to a frozen baseline using the same test. The agent picks the best performer and opens a pull request with the evidence.
Don't have a MooseStack project yet?
Why the workflow is structured this way
Why is the baseline frozen?
If the baseline branch picks up new commits while candidates are running, the comparison is no longer apples to apples. Freezing the baseline means every candidate is measured against the exact same schema and data state.
Why does each candidate get its own database?
ClickHouse schema changes like reordering an ORDER BY can trigger background data rewrites. If two candidates shared a database, one rewrite could interfere with the other's benchmark results. Isolation removes that variable.
Why use the same benchmark contract everywhere?
If the query, scenarios, or thresholds change between runs, you cannot tell whether a latency improvement came from the schema change or from a looser test. Running the same package against every database keeps the comparison honest.
Why does the workflow stop at a PR?
The experiment proves which schema change is faster in preview. It does not answer whether the migration is safe for production, whether a backfill is needed, or whether a phased rollout makes more sense. Those decisions are yours to make during PR review.
What is in the performance testing harness?
The harness is made up of four pieces that 514 agent init installs into your repo.
What the harness provides
A performance optimization skill
Tells the agent what to do at each stage of the optimization workflow and what evidence to collect. The tutorial covers each stage in detail.
ClickHouse best practices rules
Ground the agent's schema proposals. When the agent sees a full table scan, these rules help it propose specific changes like reordering a sorting key to match your filter columns, rather than guessing.
A benchmark test package
Scaffolded into your repo during setup. The package captures the slow query, wraps it with filter scenarios, and sets performance thresholds. The agent runs this package against every preview database so the only variable is the schema.
514 Platform tools
Let your agent provision, connect to, and tear down the isolated ClickHouse databases needed for each optimization candidate.