Repository navigation
fix(planner): give MetricsQL roots the series identity - #1339
Merged
Merged
Conversation
zzylol
force-pushed
the
fix/metricsql-series-identity
branch
from
November 16, 2026 01:45
b2da40d to
04d6a92
Compare
…as PromQL Four queries over 1,000 series at 1 Hz, every 10 s within relative error 0.01, written in both languages: each MetricsQL query plans and installs, selects the PromQL form's DAG, and answers what the PromQL form answers on synthetic samples (and the hand-worked answers). They fail on main: MetricsQL roots never get the series identity. The answer-row helper moves to the shared time_series test module.
Stage1ToStage3Pass added the series-identity column only to PromQL roots, so MetricsQL per-series queries had no installable plan. One rule now decides which languages carry it: QueryLanguage::has_series_identity (PromQL and MetricsQL). Closes #1337
…time_series - QueryLanguage::has_series_identity becomes reads_time_series: the language reads time series (PromQL, MetricsQL) or tables (SQL, DataFusion, ElasticDSL). The identity-column explanation moves to its one call site in Stage1ToStage3Pass::optimize. - The planner tests' time_series module now holds sample, query_roots, run(dag, store, ids, scope) and assert_answers_near (absolute) / assert_answers_near_relative; runtime_install and metricsql_workloads use them and drop their copies. The write-only read counter (CountingStore, RAW_DATA_READS) that no test read is deleted. - New test: MetricsQL avg by (job)(latency) answers j1 9, j2 29 as PromQL does. Without the identity it planned and ran without error but answered 14 and 34.
zzylol
force-pushed
the
fix/metricsql-series-identity
branch
from
November 16, 2026 03:55
04d6a92 to
562e50b
Compare
This was referenced Nov 16, 2026
Merged
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
sum by (job)(rate(requests_total[5m])),increase(requests_total[5m]),max_over_time(latency[5m])andsum(latency{job="j1"})(1,000 series at 1 Hz, every 10 s, relative error 0.01) had no installable plan, while the same text as PromQL plans.QueryLanguage::reads_time_series()(PromQL and MetricsQL), decides which roots get the identity inStage1ToStage3Pass::optimize.avg by (job)(latency), no longer give wrong answers without any error (j1 14 → 9 on the test's samples).Closes #1337.
Review guide
Base:
main(6b4847c9a). Head:562e50b00. Three commits:the regression tests first (they fail on
main), then the fix, then the round-1 review fixes (rename, shared test helpers, the wrong-answer test).crates/types/src/workload/query.rs(QueryLanguage::reads_time_series) andcrates/planner/src/run.rs(Stage1ToStage3Pass::optimize), about 15 changed lines.crates/planner/tests/metricsql_workloads.rs.Answer,answers,sample,query_roots,run(dag, store, ids, scope)andassert_answers_nearmove fromruntime_install.rsto the sharedcrates/planner/tests/time_series/mod.rs, plus a newassert_answers_near_relative. Both test files use the one copy.runtime_install.rs'sCountingStore/RAW_DATA_READSread counter is deleted: it was written but no test read it.Other places checked for a PromQL-only gate:
Stage1ToStage3Pass::optimize(crates/planner/src/run.rs)language == PromQLlanguage.reads_time_series()promql_series(crates/frontend-common/src/resolve.rs)closed), shared by both frontendshas_promql_series_identityon schemas)lower_promql_roots(crates/devtools/src/planning_stages.rs)asap_plannerCLIlowered,lowered_togetherPromQLor else SQL lowering; devtools has no MetricsQL frontendRebase onto main
6b4847c9aRebased from
3e434c760ontomainat6b4847c9a, after the merge of #1242. The 3 commits stay; the previous head04d6a9214is kept asbackup/fix/metricsql-series-identity-04d6a9214. #1242 had already movedsampleandrun(dag, store, ids, scope)intocrates/planner/tests/time_series/mod.rs. Conflicts:crates/planner/tests/main.rsmod reduce_aggregates;and this PR'smod metricsql_workloads;crates/planner/src/run.rspromql_root(node, with_promql_series_identity(node))?(a realization defect is an error) and this PR'smatch series_identitypromql_rootinside this PR'sreads_time_seriesmatch; its doc now says "PromQL or MetricsQL root"crates/planner/tests/time_series/mod.rslabels()andsample()and main'srunat the top; this PR'ssample()andrunafterquery_rootslabels()andsample()(main'sreduce_aggregates.rsuses them); this PR's oneruncrates/planner/tests/runtime_install.rsCountingStorewrappers at bothruncallsCountingStore/RAW_DATA_READSis deleted (nothing reads the count), and the calls passtime_series_tables(...)Checked on the rebased head
562e50b00, by test name againstmain6b4847c9a:cargo check --workspace --all-targets,cargo fmt --all -- --checkandcargo clippy -p asap-planner -p asap-types --all-targets -- -D warningsare clean.cargo test -p asap-planner -p asap-types: 319 passed, 1 failed, 1 ignored. The 1 (summary_sharing::identical_ungrouped_queries_share_their_producers) fails onmaintoo. All 4metricsql_workloadstests pass.Rebase onto main
3e434c760Rebased from
59365ce80ontomainat3e434c760, after the merge of the Stage 3 execution-contexts refactor (#1237). Same 3 commits. Conflicts:crates/planner/tests/main.rs: bothmod exact_only_reads;andmod metricsql_workloads;.crates/planner/tests/runtime_install.rsimports: keptmain'suse asap_types::ir::{ASAPOp, NonASAPOp, Operator};(its newone_chain_serves_two_evaluation_contextstest reads them) and droppedSource, which only the helpers this PR moved totime_seriesread.Checked on the rebased head, by test name against
main3e434c760:cargo check --workspace --all-targets,cargo fmt --all -- --checkandcargo clippy -p asap-planner -p asap-types --all-targets -- -D warningsare clean.cargo test -p asap-planner -p asap-types: 285 passed, 2 failed, 1 ignored. The 2 (runtime_install::check_compiles_reports_the_executors_error,summary_sharing::identical_ungrouped_queries_share_their_producers) fail onmaintoo. All 4metricsql_workloadstests pass.Behavior: before → after
The workload (MetricsQL):
{"query_workload": {"language": "metricsql", "repeating_queries": [{ "query": "sum by (job)(rate(requests_total[5m]))", "demand": {"fixed_interval_at": {"interval": 10000, "evaluation_phase": 0}}, "requirements": {"accuracy": {"max_error": 0.01}}, "predictability": {"predictable": {"known_at": null}}}]}, "data_workload": {"arrival": {"ingesting": {"rows_per_second": 2000.0}}, "sources": { "requests_total": {"series_count": 1000, "metric_type": "counter", "sample_interval": 1000}, "latency": {"series_count": 1000, "metric_type": "gauge", "sample_interval": 1000}}}}planned with
plan_installable(UserInput::new(&workload, FrontendInput::Metricsql, PlanningModels::builtin())):sum by (job)(rate(requests_total[5m]))installable plan: the executor cannot compile the plan's query run: invalid DAG: per-entity summary requires complete source identityincrease(requests_total[5m])max_over_time(latency[5m])sum(latency{job="j1"})... invalid DAG: node 2: invalid DAG: native output type differs from Planner outputavg by (job)(latency)The last row is the dangerous case: without the identity, MetricsQL rows of different series under one job are not told apart, so the average is wrong and nothing reports an error. (A review run on other synthetic data saw j1 14.05 where 9.05 is correct.)
This serves correctness: a workload's language must not change whether it plans when both languages lower to the same time-series IR.
Interfaces
crates/types/src/workload/query.rsUsage (the flow
crates/planner/tests/metricsql_workloads.rsruns at the linked commit; its helpersworkload,plan_promql,samplesandquery_answersare defined there):Algorithm changes
None. The series-identity realization (
with_promql_series_identity) is unchanged; only which languages reach it changes.Design scope
QueryLanguage::reads_time_series(method, no new type or file). Scope: workload description (asap_types::workload), read by the planner facade before Stage 0. It states a property of the query language (time series vs tables), so it sits onQueryLanguage, the type whose data it reads; what the planner does with it (the identity column) is explained at the call site inrun.rs. A future time-series language opts in here instead of at each call site.crates/planner/tests/time_series/mod.rs(functions only, no new types):sample,query_roots,run,assert_answers_near,assert_answers_near_relative. Scope: the planner tests' stand-in runtime (bind raw samples, run a plan, compare answer rows), shared by every planner test that executes a plan.crates/planner/tests/metricsql_workloads.rs(new test file). Scope: planner end-to-end tests by input language, next tosql_table_scans.rs; it covers MetricsQL workloads in general, not one query.Decisions and open questions
Needs reviewer decision: None.
Decided:
QueryLanguagerather than amatches!at the call site, so every caller uses one definition. The identity column keeps itsPROMQL_SERIES_IDENTITY/with_promql_series_identitynames; renaming them is out of scope.with_promql_series_identityonly changesSource::TimeSeriesscans, so calling it on every root would also work today. The gate is kept because it states the rule where it is decided (the language reads time series), so it does not depend on no table frontend ever emitting a time-series scan. Rejected: dropping the gate and the method.reads_time_series(what the language is), nothas_series_identity(what the planner does with it).Verification
Commands (dedicated
CARGO_TARGET_DIR):cargo test -p asap-planner,cargo test -p asap-types --lib workload::,cargo test -p asap-frontend-metricsql,cargo clippy -p asap-types -p asap-planner -p asap-frontend-metricsql --all-targets -- -D warnings,cargo fmt --all -- --check.mainasap-planner --test planner metricsql_workloads::onmain(tests only)metricsql_grouped_average_averages_every_series_of_each_groupfails with[j1 14, j2 34] vs [j1 9, j2 29]asap-planner --test planner metricsql_workloads::with the fixasap-planner --test planner(all)summary_sharing::identical_ungrouped_queries_share_their_producersandruntime_install::check_compiles_reports_the_executors_errorfail identically onmainasap-planner --libasap-frontend-metricsqlasap-types --lib workload::cargo fmt --all -- --checkcargo clippy ... --all-targets -D warningsNew tests and what each catches:
metricsql_queries_plan_and_install: each of the four MetricsQL queries plans and its plan compiles in the executor; catches a MetricsQL root planned without the series identity (all four fail onmain).metricsql_queries_select_the_promql_plan: each MetricsQL query's selected DAG equals its PromQL form's; catches any language-dependent difference left between the two frontends' roots before Stage 0.metricsql_queries_answer_as_promql_does: each MetricsQL plan's answers on synthetic samples equal the PromQL plan's and the hand-worked values (increase: 20/40/60/80,max_over_time: 6/16/26/36,sum: 18); catches a plan that installs but computes something else.metricsql_grouped_average_averages_every_series_of_each_group: MetricsQLavg by (job)(latency)answers j1 9, j2 29, as PromQL does; catches the case where the query plans and runs without error but answers wrong (14 and 34 onmain).only_promql_and_metricsql_read_time_series(asap-types): the rule is true for PromQL and MetricsQL and false for SQL, DataFusion and ElasticDSL.Review status
Round 1 (two reviews at
79f5c74df: abstraction/layering and functional/efficiency). Both approved with small changes; no blockers. All findings are addressed inb2da40df2:sample,query_roots,run,assert_answers_near(+assert_answers_near_relative) moved totime_series/mod.rs; copies deletedreads_time_series; identity explanation moved torun.rsquery_rootsavg by (job)(latency))mainrate[5m] / rate[10m]execution error), #1342 (MetricsQLand/or/unless)The functional review's 59-query harness found MetricsQL equal to PromQL (same DAG, same answers) on every query whose PromQL form plans, and planning time within noise (1452.7 ms vs 1449.6 ms over 38 queries).
Follow-ups
sum by (job)(rate|increase(counter[5m]))plans and installs but answers no rows, in PromQL too, so the answer test checks only that the languages agree for that query; it can assert the values j1 0.2 / j2 0.4667 once sum by (job)(rate|increase(counter[5m])) plans and installs but answers no rows #1338 is fixed.rate/increaseuse Prometheus semantics; once VictoriaMetrics semantics land,metricsql_queries_answer_as_promql_doesmust expect different counter answers.main; these tests are the end-to-end MetricsQL planning test it asks for, so it may be closable.asap_plannerCLI lowers MetricsQL workloads as SQL inloweredandlowered_together. Not changed here.rate(requests_total[5m]) / rate(requests_total[10m])plans but fails at execution ("counter samples must have strictly increasing timestamps within each group"), in PromQL too.and/or/unlesswith no written modifier ("binary vector matching modifiers"); PromQL plans them.