proposal: trim query_range response to user-requested time window

[venkatchinmay]

Fixes #7289

What

Adds docs/proposals/query-range-response-trimming.md — a proposal for a new opt-in middleware that clips the query_range response to the exact [start, end] window requested by the user.

Problem

When querier.align-querier-with-step: true is enabled, StepAlignMiddleware floors the user's start time to the nearest step boundary before the rest of the middleware chain runs:

User requests:   start=09:01, end=10:00, step=10m
After alignment: start=09:00, end=10:00

The original start=09:01 is permanently lost — no downstream middleware can recover it to trim the response. The user receives data from 09:00 even though they asked for 09:01.

The same drift can occur from SplitByIntervalMiddleware's nextIntervalBoundary rounding.

Proposed Fix

A new RangeTrimMiddleware as the outermost middleware, enabled via:

querier:
  trim_response_to_requested_range: true  # default: false

It captures the original start/end before any mutation, lets the full stack run internally (alignment, splitting, caching, sharding), then trims the final response using the existing Extractor.Extract() interface — which already handles per-sample and per-step-stats trimming correctly.

Key Points

• Opt-in — default false, no behaviour change for existing deployments
• No cache impact — cache continues to operate with aligned times internally
• Reuses existing code — extractSampleStreams() + extractStats() already handle the trimming logic
• Implementation PR will follow once the proposal is approved

Related

• pkg/querier/tripperware/queryrange/step_align.go
• pkg/querier/tripperware/queryrange/results_cache.go

[dosubot]

Related Documentation

Checked 0 published document(s) in 1 knowledge base(s). No updates required.

^{How did I do? Any feedback?}  

[SungJin1212]

@venkatchinmay
Thanks for the proposal.
I have a question. The response contains [9:10, 9:20,... 10:00] in the above example, if we enable the trim option, right?

[venkatchinmay]

@venkatchinmay Thanks for the proposal. I have a question. The response contains [9:10, 9:20,... 10:00] in the above example, if we enable the trim option, right?

yes @SungJin1212

[friedrichg]

Sorry for the late response. I appreciate the detail

[friedrichg]

I prefer if we don't add any flag. It's a bugfix, if we are returning more samples than we should.

[friedrichg]

This looks like a bug to me. can you create a test case to trigger this behavior ?.

If you can trigger the behavior and is buggy, you don't need a proposal. You just need a unit test that triggers it and the fix.

The only thing though is what happens if we have increased CPU usage or less cache efficiency. Those things will matter in this case too