Skip to content

feat(firestore): add RangeWindowFrame for pipeline windows - #19119

Open
ohmayr wants to merge 5 commits into
feat/firestore-window-2-document-framefrom
feat/firestore-window-3-range-frame
Open

ohmayr wants to merge 5 commits into
feat/firestore-window-2-document-framefrom
feat/firestore-window-3-range-frame

Conversation

@ohmayr

@ohmayr ohmayr commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Goal

Add value-based and time-range window frame support (RangeWindowFrame) to WindowSpec, building on DocumentWindowFrame from #19117.

Background: What Are Range Window Frames?

While a DocumentWindowFrame bounds 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]:

  • Numeric range: For WindowSpec(sort=Field.of("price").ascending(), frame=RangeWindowFrame(1000, WindowBound.CURRENT)), a document with price = 2000 includes all documents in the partition whose price falls within [2000 - 1000, 2000] ([1000, 2000]).
  • Time-unit range: When the sort field is a timestamp, an optional unit (e.g., TimeUnit.HOUR, TimeGranularity.MONTH, or "hour") defines a duration offset—such as a 12-hour trailing window:
    WindowSpec(
        sort=Field.of("time").ascending(),
        frame=RangeWindowFrame(12, WindowBound.CURRENT, unit=TimeUnit.HOUR),
    )
  • Because a range frame is computed from the current document's sort value, the backend requires sort to be specified whenever a RangeWindowFrame is used.

Summary of Changes

  • Add RangeWindowFrame(preceding, following, unit=None) in google/cloud/firestore_v1/pipeline_types.py (inheriting _to_pb() from _WindowFrame and exposing _to_dict() -> {"range": self._to_pb()}) and export it from google.cloud.firestore and google.cloud.firestore_v1 (plus .librarian/generator-input/client-post-processing/firestore-integration.yaml).
  • Widen WindowSpec(frame=...) to Optional[DocumentWindowFrame | RangeWindowFrame] = None.
  • Add unit tests in tests/unit/v1/test_pipeline_stages.py covering RangeWindowFrame serialization (with and without unit), _to_dict(), and WindowSpec(frame=RangeWindowFrame(...)).
  • Add testAddWindowFields - range frame with time unit and testAddWindowFields - error on range frame without sort to tests/system/pipeline_e2e/window.yaml.

What We Will Follow Up On

Verification

  • Unit Tests: 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 on pipeline_types.py).
  • System Tests: pytest tests/system/test_pipeline_acceptance.py -k window.yaml (proto serialization check in default CI mode, plus live sync/async execution against test-firestore.sandbox.googleapis.com:443: 11 passed).
  • Linter & Typecheck: mypy, ruff check --select I, ruff format --check, and flake8 google tests all pass cleanly.

Add RangeWindowFrame and the range parameter on WindowSpec to support
value-based and time-range window frames in AddWindowFields stages.
@ohmayr
ohmayr requested review from a team as code owners November 18, 2026 02:18
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

@ohmayr ohmayr Nov 18, 2026 •

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Design Note — Separate RangeWindowFrame Dataclass & _to_dict():

  • Chosen Design: Keep RangeWindowFrame as a distinct @dataclass from DocumentWindowFrame (inheriting _to_pb() from _WindowFrame and exposing _to_dict() -> {"range": self._to_pb()}), and widen WindowSpec(frame=...) to Optional[DocumentWindowFrame | RangeWindowFrame] = None.
  • Alternatives Considered & Why Rejected:
    • Merging DocumentWindowFrame and RangeWindowFrame into a single class: RangeWindowFrame accepts float offsets and an optional unit (TimeUnit | TimeGranularity | str | Expression), whereas DocumentWindowFrame only accepts integer/symbolic row counts and has no unit. Keeping them separate prevents invalid combinations like passing a time unit or float offset to a document-count frame, while _to_dict() lets WindowSpec._to_pb() remain completely unchanged.

@gemini-code-assist gemini-code-assist Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@ohmayr
ohmayr added this pull request to stack #19118 November 18, 2026 02:20
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

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants