PATTERN Cited by 1 source
Intent-preserving query translation¶
When migrating queries (observability dashboards, alert expressions, SQL, etc.) from one system to another, translate what the user was trying to measure to the target system's canonical form — rather than producing a literal, token-for-token port of the source query.
Problem¶
Long-running query catalogs accumulate quietly-wrong expressions:
- Averaging a field that should be a p95.
- Summing a latency series that should be rate'd.
- Layering aggregations on top of a percentile, breaking its math.
Blind ("v1") translation carries every bug across to the new system and then codifies it as ground truth under a new UI. The migration window is the only cheap moment to correct these, because the user expects some friction from the system change.
The move¶
- Classify each source query by intent (p95 of X, error rate of Y, throughput of Z) via pattern matching and metric-type metadata (see concepts/metric-type-metadata).
- Emit a canonical target query for each intent class — e.g., any
p95 request becomes
histogram_quantile(0.95, ...)on the right histogram metric, regardless of the (often incorrect) aggregations the source query had on top. - Do not attempt to preserve structural quirks of the source query that didn't correspond to real intent.
Requires a type/unit metadata source of truth — otherwise you can't tell whether a given field is a counter, gauge, or histogram component. See concepts/metric-type-metadata.
Tradeoffs¶
- + Correctness. Downstream dashboards/alerts compute what humans actually meant.
- + Simpler target. Fewer compatibility shims to maintain long term.
- − Behavior change. Some dashboards will show different numbers post-migration; communicate this explicitly.
- − Requires classification effort. Has to scale across tens/hundreds of thousands of queries — Airbnb did it for 3,100 dashboards and 300,000 alerts.
Seen in¶
- sources/2026-03-17-airbnb-observability-ownership-migration — Airbnb's observability migration adapted its translator to ignore extra aggregations layered on a p95 and emit a canonical histogram query instead. Required a new metric-type metadata engine to make this classification reliable.