Skip to content

perf(query): bind rate/gauge window bounds to hit the compile cache - #496

Merged
vishr merged 1 commit into
mainfrom
fix/compile-cache-params
Nov 16, 2026
Merged

vishr merged 1 commit into
mainfrom
fix/compile-cache-params

Conversation

@vishr

@vishr vishr commented Nov 16, 2026

Copy link
Copy Markdown
Member

Problem

Rollup rate panels and all metric rate/gauge panels rendered the start, end, and FreshTo nanosecond window bounds as literals directly into the SQL text (coveredSecondsSQL in rollup_compile.go; metricSpreadCTE/metricCarryCandidatesCTE/metricGaugeCTE in metric_buckets.go). The snapshot-compile cache (file_snapshot.go compileSnapshot, keyed by statement text) therefore missed on every window, paying json_serialize_sql → Go decode → rewriteKeys → json_deserialize_sql (twice for metrics) on the read connection inside the panel slot. The cache also cleared wholesale when it reached 128 entries, evicting stable entries.

Closes #479.

Fix

Bind the nanosecond bounds as ? parameters instead of rendering them as literals, so the compiled statement text is identical across time windows of the same panel and the compile cache hits. Each CTE builder returns its window values in the exact left-to-right order of the placeholders it emits, and callers concatenate SQL and args in lockstep — the same discipline the existing buildWhere/metricSeriesCTE window placeholders already use. Bucket widths, window durations, and bucket origin stay literals because they are constant for a fixed relative range and do not vary the text. Every bound binds the exact value that was previously the literal, cast to the same type (::BIGINT/::DOUBLE), so results are byte-identical.

Switch the compile cache to an LRU. snapshotQueries is now a map[string]*list.Element over a container/list MRU list (stdlib, no new dependency) guarded by snapshotMu; at capacity (128) it evicts the single least-recently-used entry instead of clearing all of them.

Correctness

Positional ? survive the json_serialize_sql → rewriteKeys → json_deserialize_sql pipeline with indices intact (the snapshot-source CTEs bindSnapshot prepends contain only literals, never placeholders, so they do not shift indices). The decisive evidence is that the existing golden numeric tests — TestRollupCoveredSecondsAndInterval, TestMetricRateUsesCoveredElapsedTime, TestHistogramRateUsesPerSeriesCoveredElapsedTime, the gauge/carry/spread suites — all pass unchanged; a wrong positional order would bind wrong values and change those numbers.

New tests:

  • TestRatePanelCompiledTextIsWindowStable — rollup rate, metric rate, and metric gauge-avg panels produce identical compiled text across different windows, with ? count equal to args count and differing args.
  • TestCompileCacheEvictsOneEntryNotAll — fills the cache to 128, overflows by one, and asserts all 128 survivors hit and only the single LRU entry missed (fails against the old wholesale clear).

Measured improvement (Apple M3 Max, 200 sliding 1h windows, same metric rate panel)

  • Compile-cache hit rate: ~0.5% → 100%.
  • Read latency: ~102 ms/op → ~66 ms/op (~35% faster) — the delta is the avoided per-window recompile.

(Local micro-benchmark proving the mechanism; full throughput validation follows the usual Hetzner/release process.)

Verification

just test "./internal/query/..." and just test "./internal/engine/...", just vet, and just check-static (gofmt, deadcode, behavioral test names) all green. Arbitrary-SQL read-only single-SELECT guarantee intact — the new parameters are engine-internal window bounds, never user text.

@vishr
vishr enabled auto-merge November 16, 2026 01:13
@vishr
vishr force-pushed the fix/compile-cache-params branch from 937241e to 30667cf Compare November 16, 2026 01:17
Rollup rate panels and metric rate/gauge panels rendered their start,
end and rollup-freshness nanosecond bounds directly into the SQL text,
so every time window produced a unique statement. The engine's
snapshot-compile cache is keyed by that text, so each refresh missed and
paid json_serialize_sql, a Go decode, rewriteKeys and json_deserialize_sql
(twice for metrics) on the read connection inside the panel's slot.

Emit those bounds as ? placeholders and append their values to the
compiled Args in the left-to-right order the placeholders appear, so the
values ride as bind parameters while the statement text is identical
across windows of the same panel. The snapshot binder already tolerates
placeholders (window bounds in the WHERE clause were already parameters,
and the serialize/rewrite/deserialize round trip preserves positional
parameter order); this extends the same treatment to coveredSecondsSQL,
metricSpreadCTE, metricCarryCandidatesCTE and metricGaugeCTE. Bucket
widths and window durations stay literals because they are constant for a
fixed relative range, so they do not vary the text. Results are
unchanged: each placeholder binds the exact value that was the literal.

Also make the compile cache an LRU that evicts the single least-recently-
used entry at capacity instead of clearing all 128, so a burst of one-off
statements no longer discards a dashboard's stable, repeatedly-run ones.

Measured across 200 sliding one-hour windows of the same metric rate
panel: compile-cache hit rate rises from ~0.5% to 100% and end-to-end
read latency drops from ~102ms to ~66ms per refresh, with no result
change. Adds TestRatePanelCompiledTextIsWindowStable (text identical and
placeholder count equals arg count across windows),
TestCompileCacheEvictsOneEntryNotAll, and a hit-rate benchmark.

Closes #479
@vishr
vishr force-pushed the fix/compile-cache-params branch from 30667cf to f232683 Compare November 16, 2026 02:28
@vishr
vishr added this pull request to the merge queue Nov 16, 2026
Merged via the queue into main with commit d2ac1ca Nov 16, 2026
31 checks passed
@vishr
vishr deleted the fix/compile-cache-params branch November 16, 2026 02:45
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

perf: per-request nanosecond literals defeat the snapshot-compile cache

1 participant