Repository navigation
Conversation
Add RangeWindowFrame and the range parameter on WindowSpec to support value-based and time-range window frames in AddWindowFields stages.
ohmayr
commented
Nov 18, 2026
Comment on lines
+406
to
+410
| preceding: WindowBound | str | int | float | pipeline_expressions.Expression | ||
| following: WindowBound | str | int | float | pipeline_expressions.Expression | ||
| unit: Optional[ | ||
| TimeUnit | TimeGranularity | str | pipeline_expressions.Expression | ||
| ] = None |
Contributor
Author
There was a problem hiding this comment.
Design Note — Separate RangeWindowFrame Dataclass & _to_dict():
- Chosen Design: Keep
RangeWindowFrameas a distinct@dataclassfromDocumentWindowFrame(inheriting_to_pb()from_WindowFrameand exposing_to_dict()->{"range": self._to_pb()}), and widenWindowSpec(frame=...)toOptional[DocumentWindowFrame | RangeWindowFrame] = None. - Alternatives Considered & Why Rejected:
- Merging
DocumentWindowFrameandRangeWindowFrameinto a single class:RangeWindowFrameacceptsfloatoffsets and an optionalunit(TimeUnit | TimeGranularity | str | Expression), whereasDocumentWindowFrameonly accepts integer/symbolic row counts and has nounit. Keeping them separate prevents invalid combinations like passing a timeunitorfloatoffset to a document-count frame, while_to_dict()letsWindowSpec._to_pb()remain completely unchanged.
- Merging
Contributor
There was a problem hiding this comment.
Code Review
This pull request introduces the RangeWindowFrame class to support value-based or time-range window frames in Firestore pipeline queries. This includes updating WindowSpec to accept a range parameter, exporting the new class, and adding corresponding unit and system tests. The feedback suggests updating the docstring example for RangeWindowFrame to include a sort parameter, as the backend requires sorting when using range-based window frames.
Merge updated DocumentWindowFrame base branch and widen WindowSpec's frame parameter to accept RangeWindowFrame, adding _to_dict() on RangeWindowFrame to serialize under the "range" wire key.
This branch has not been deployed
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.
Goal
Add value-based and time-range window frame support (
RangeWindowFrame) toWindowSpec, building onDocumentWindowFramefrom #19117.Background: What Are Range Window Frames?
While a
DocumentWindowFramebounds a window by counting rows before and after the current document, a range window frame (frame=RangeWindowFrame(preceding, following, unit=None)) bounds the window by comparing the sort key's value against[current_value - preceding, current_value + following]:WindowSpec(sort=Field.of("price").ascending(), frame=RangeWindowFrame(1000, WindowBound.CURRENT)), a document withprice = 2000includes all documents in the partition whosepricefalls within[2000 - 1000, 2000]([1000, 2000]).unit(e.g.,TimeUnit.HOUR,TimeGranularity.MONTH, or"hour") defines a duration offset—such as a 12-hour trailing window:sortto be specified whenever aRangeWindowFrameis used.Summary of Changes
RangeWindowFrame(preceding, following, unit=None)ingoogle/cloud/firestore_v1/pipeline_types.py(inheriting_to_pb()from_WindowFrameand exposing_to_dict()->{"range": self._to_pb()}) and export it fromgoogle.cloud.firestoreandgoogle.cloud.firestore_v1(plus.librarian/generator-input/client-post-processing/firestore-integration.yaml).WindowSpec(frame=...)toOptional[DocumentWindowFrame | RangeWindowFrame] = None.tests/unit/v1/test_pipeline_stages.pycoveringRangeWindowFrameserialization (with and withoutunit),_to_dict(), andWindowSpec(frame=RangeWindowFrame(...)).testAddWindowFields - range frame with time unitandtestAddWindowFields - error on range frame without sorttotests/system/pipeline_e2e/window.yaml.What We Will Follow Up On
.over(frame)onWindowFunctionexpressions.window.yamlsystem execution tests in CI (firestore: enable live window.yaml pipeline system tests once add_window_fields is in production #19115) once theadd_window_fieldsbackend rollout is live in production.Verification
pytest tests/unit/v1/test_pipeline_stages.py tests/unit/v1/test_pipeline_expressions.py tests/unit/v1/test_pipeline.py tests/unit/v1/test_async_pipeline.py(473 passed, 100% statement/branch coverage onpipeline_types.py).pytest tests/system/test_pipeline_acceptance.py -k window.yaml(proto serialization check in default CI mode, plus live sync/async execution againsttest-firestore.sandbox.googleapis.com:443: 11 passed).mypy,ruff check --select I,ruff format --check, andflake8 google testsall pass cleanly.