Repository navigation
Description
Example
rate(m[5m] offset 1m) reads m through TimeShift(1m) -> TimeRange(5m). The executor's physical planner works out that window three times, with three walks:
| Walk | Where | What it does |
|---|---|---|
counter_window |
crates/executor/src/physical_planner/time_window.rs (about line 250) |
walks down from the counter evaluation to each TimeRange, sums the TimeShift offsets right below it by hand, and returns (offset, lookback) as a bare (i64, i64): here (60_000, 300_000) |
node_below_shifts |
same file (about line 211) | follows plan-node TimeShifts down to the first other node; None at an @ shift |
below_time_shifts |
same file (about line 233) | the same skip over the restored IR nodes, through a resolver |
The shared walks in asap_types::plan::time_window already compute this window: windows_below gives TimeWindow { end_offset_ms: 60_000, width_ms: 300_000 }, and end_offset_below sums the shifts below a node. The cost model, Stage 3, the installer and the rest of the executor (window_read_above, window_below, time_range_window) use them. These three do not.
Concrete maintenance problem
A change to how a window is read (for example, how an @ anchor or a negative offset is treated) has to be made in each copy, and the copies already differ:
counter_windowignores an@shift (it adds no offset and keeps walking);windows_belowandend_offset_belowreturnNonefor one.- At a chain reached without passing a
TimeRange,counter_windowkeeps walking below the chain (and finds no range over raw rows);windows_belowstops there and reports the chain's tumbling window. node_below_shiftsandbelow_time_shiftsare the same rule over two node types.
Behavior that must remain unchanged
- A counter evaluation still gets the union of the back-to-back windows it reads, and still errs ("ambiguous logical windows") when they are not back to back.
time_window_operator, the chain build (stale markers over a time series) and the per-entity summary build still find theScanor chain below the shifts.- Every executor test that runs a shifted or offset window gives the same answers.
Before and after structure
counter_windowbecomeswindows_belowplus the back-to-back check, and returns aTimeWindowinstead of(i64, i64). Where its answer must differ fromwindows_below(a chain reached without a range, an@shift), that difference is decided once and named in the shared walk's interface instead of in a copy.node_below_shiftsandbelow_time_shiftsbecome one walk next toend_offset_below(which already stops at the first node that is not a shift), generic over the node type with closures, as the other shared walks are.materialized_view/raw_data.rscheck_raw_window_belowalso re-walks the shifts below a range, but it needs its own error reasons; it can stay.
Why the proposed structure is minimally complex
It deletes code: the three walks become calls to the walks that already exist. No new type is needed, TimeWindow already exists.
Existing unit and end-to-end protection
The executor's offset and counter tests, crates/integration-tests (time_range, the PromQL execution tests) and the shared walks' own tests in asap_types::plan::time_window.
Compatibility or migration impact
None outside the executor: the functions are pub(super) / pub(crate).
Activity
zzylol commentedon Nov 14, 2026
Approved design: one fix for #1291 and #1292
This comment is posted on both #1291 and #1292. They are fixed together, in one PR that closes both, after #1300 merges. No code is written until then.
Problem, by example
Take f01's plan for
sum_over_time(m[5m] offset 1h), evaluated every 60 s, with no raw data kept:Measured on #1300's head (
48819b44a), with a hand-built plan of this shape and with the review harness on the forced plans f01–f03 and g01–g04/g13:(e, e], an empty request, and view 2 stores 0 rows.check_compilescompiles them)(T − 60 s, T](fromwindow_below) instead of(T − 65m, T − 60m], andTimeRange(5m)then drops every row[], 0 of 12 seriesWhat should happen: the refresh at e reads the chain's output keyed in
(e − 60 s, e], and the query at T reads view 2's outputs keyed in(T − 65m, T − 60m]. The result is Σ m over(T − 65m, T − 60m], which is equal to the exact answer.Why it happens
crates/types/src/plan/time_window.rs) already decides each reader's window, and Stage 3 charges retention for it.CompileGraph::current_time_read_needs_every_rowreturnstruefor every node, where the planner returnstrueonly for raw data;window_below;counter_window,node_below_shiftsandbelow_time_shifts([Refactor] Executor time walks (counter_window, node_below_shifts, below_time_shifts) should use the shared time_window walks #1292) are three more copies.{0, 0}, meaning "the newest output", and gives the chain retention 0. That relies on an unwritten rule: the store always keeps the newest output.{0, 0}into the empty request(e, e].InMemoryDataStore::read_materialized_viewreturns no rows, and no error, for(e, e].check_compilesaccepts the plan.Proposal (approved)
1. Every time window is over the time keys of stored outputs.
{o, w}at evaluation time t means the outputs whose key lies in(t − o − w, t − o].{o, output_interval}, which for a chain of width c is{o, c}.div_ceil(c, c)is 1 retained window, the same as with retention 0.newest − retention, drops the output keyed at exactly t − o.2. The planner computes each reader's window once and writes it into the plan.
Example, with the plan above:
read_windowoffset 1hshift{0, 60_000}(e − 60 s, e]TimeRange(5m){3_600_000, 300_000}(T − 65m, T − 60m]read_windowinto store requests. The executor's walks are deleted:CompileGraph's window walks,window_belowfor view reads, and [Refactor] Executor time walks (counter_window, node_below_shifts, below_time_shifts) should use the shared time_window walks #1292'scounter_window,node_below_shiftsandbelow_time_shifts.check_compileschecks statically that each edge's window lies within its producer's retention.3. Fail loudly.
Scope and acceptance
In scope (one PR):
read_windowonPhysicalASAPDAGEdge).plan_offillsread_window.read_window, and the executor's own walks are deleted ([Refactor] Executor time walks (counter_window, node_below_shifts, below_time_shifts) should use the shared time_window walks #1292).Acceptance:
[].check_compilesrefuses an edge whoseread_windowreaches past its producer's retention.Status and related work
{o, 0}from a stored shift as the chain's newest window". That option was prototyped against fix(executor): run each node by its plan Lifetime, so roots drain in any order #1300's head:Lifetime, which this builds on;@anchors cannot be executed or verified #1306:@range queries; a shift with@still reads every output (read_window: None);