Query Tuning Playbook

Query Tuning Playbook

A repeatable performance method using PROFILE, schema assertions, and controlled rewrites.

Why it matters

Most teams tune Cypher by folklore. A disciplined playbook turns query tuning into measurable engineering work.

Going deeper

A disciplined loop turns tuning into measurable engineering:

1. Baseline — PROFILE the query, record db hits per operator.
2. One change — add an index, constrain a relationship type/direction, or tighten a pattern. Never two at once.
3. Re-profile — compare db hits, not wall-clock (which is polluted by cache state and network).
4. Keep or revert — keep only changes that cut db hits and keep the query readable.

The highest-yield findings are almost always: a NodeByLabelScan that should be a NodeIndexSeek (missing index), an unbounded/untyped Expand(All), or an Eager operator forcing the whole result to materialize. If db hits don't move, you changed syntax, not the plan.

Query tuning by folklore is adjusting a recipe by smell; the PROFILE playbook is a kitchen scale. You change one ingredient, weigh the result (db hits), keep it only if the number improved. Anecdote — 'it felt faster' — is exactly how teams ship changes that did nothing but warm the cache.

A practical tuning loop is deterministic, not anecdotal.

1. Capture a baseline PROFILE (db hits per operator).
2. Apply one change only (index, pattern tightening, relationship-type constraint).
3. Re-profile and compare db hits — not wall-clock.
4. Keep only changes that improve both cost and readability.

If db hits don't drop, you changed syntax, not the execution plan.

• Tuning on wall-clock. Warm vs cold cache makes it lie. Fix: compare db hits from PROFILE.
• Changing several things at once. You can't attribute the win. Fix: one change per measurement.
• Adding memory before profiling. Hides the real bottleneck. Fix: profile first.