Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -92,6 +92,7 @@ replacements:
)
from google.cloud.firestore_v1.pipeline_source import PipelineSource
from google.cloud.firestore_v1.pipeline_types import (
DocumentWindowFrame,
FindNearestOptions,
Ordering,
PipelineDataType,
Expand All @@ -101,6 +102,7 @@ replacements:
TimePart,
TimeUnit,
UnnestOptions,
WindowBound,
WindowSpec,
)
from google.cloud.firestore_v1.query import CollectionGroup, Query
Expand Down Expand Up @@ -199,6 +201,7 @@ replacements:
"DocumentReference",
"DocumentSnapshot",
"DocumentTransform",
"DocumentWindowFrame",
"ExistsOption",
"ExplainOptions",
"FieldFilter",
Expand Down Expand Up @@ -231,6 +234,7 @@ replacements:
"types",
"UnnestOptions",
"Watch",
"WindowBound",
"WindowSpec",
"WriteBatch",
"WriteOption",
Expand Down Expand Up @@ -280,6 +284,7 @@ replacements:
DocumentReference,
DocumentSnapshot,
DocumentTransform,
DocumentWindowFrame,
ExistsOption,
ExplainOptions,
FieldFilter,
Expand Down Expand Up @@ -309,6 +314,7 @@ replacements:
Transaction,
UnnestOptions,
Watch,
WindowBound,
WindowSpec,
WriteBatch,
WriteOption,
Expand Down Expand Up @@ -348,6 +354,7 @@ replacements:
"DocumentReference",
"DocumentSnapshot",
"DocumentTransform",
"DocumentWindowFrame",
"ExistsOption",
"ExplainOptions",
"FieldFilter",
Expand Down Expand Up @@ -380,6 +387,7 @@ replacements:
"types",
"UnnestOptions",
"Watch",
"WindowBound",
"WindowSpec",
"WriteBatch",
"WriteOption",
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -51,6 +51,7 @@
DocumentReference,
DocumentSnapshot,
DocumentTransform,
DocumentWindowFrame,
ExistsOption,
ExplainOptions,
FieldFilter,
Expand Down Expand Up @@ -80,6 +81,7 @@
Transaction,
UnnestOptions,
Watch,
WindowBound,
WindowSpec,
WriteBatch,
WriteOption,
Expand Down Expand Up @@ -119,6 +121,7 @@
"DocumentReference",
"DocumentSnapshot",
"DocumentTransform",
"DocumentWindowFrame",
"ExistsOption",
"ExplainOptions",
"FieldFilter",
Expand Down Expand Up @@ -151,6 +154,7 @@
"types",
"UnnestOptions",
"Watch",
"WindowBound",
"WindowSpec",
"WriteBatch",
"WriteOption",
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -69,6 +69,7 @@
)
from google.cloud.firestore_v1.pipeline_source import PipelineSource
from google.cloud.firestore_v1.pipeline_types import (
DocumentWindowFrame,
FindNearestOptions,
Ordering,
PipelineDataType,
Expand All @@ -78,6 +79,7 @@
TimePart,
TimeUnit,
UnnestOptions,
WindowBound,
WindowSpec,
)
from google.cloud.firestore_v1.query import CollectionGroup, Query
Expand Down Expand Up @@ -176,6 +178,7 @@
"DocumentReference",
"DocumentSnapshot",
"DocumentTransform",
"DocumentWindowFrame",
"ExistsOption",
"ExplainOptions",
"FieldFilter",
Expand Down Expand Up @@ -208,6 +211,7 @@
"types",
"UnnestOptions",
"Watch",
"WindowBound",
"WindowSpec",
"WriteBatch",
"WriteOption",
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,7 @@

from __future__ import annotations

from dataclasses import dataclass, fields
from enum import Enum
from typing import Optional, Sequence

Expand Down Expand Up @@ -329,12 +330,69 @@ def __repr__(self):
return f"{self.__class__.__name__}(index_field={self.index_field.path!r})"


class WindowBound(str, Enum):
"""Enumeration of symbolic window frame boundary keywords."""

CURRENT = "current"
UNBOUNDED = "unbounded"


@dataclass
class _WindowFrame:
"""Base class for window frame specifications."""

def _to_pb(self) -> Value:
pb_fields = {
f.name: pipeline_expressions.Expression._cast_to_expr_or_convert_to_constant(
getattr(self, f.name)
)._to_pb()
for f in fields(self)
if getattr(self, f.name) is not None
}
return Value(map_value={"fields": pb_fields})


@dataclass
class DocumentWindowFrame(_WindowFrame):
"""Defines a document-count based window frame relative to the current document.

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.

A bit more context to include:

    Bounds count documents, not values. `WindowBound.CURRENT` refers only to the
    current document's position, so documents with the same sort value are not
    automatically included in the frame.

    `sort` on the enclosing `WindowSpec` is optional for a document frame. If it
    is omitted, documents are processed in the order they reach the stage.

Example:
>>> from google.cloud.firestore_v1.pipeline_expressions import Field
>>> from google.cloud.firestore_v1.pipeline_types import (
... DocumentWindowFrame,
... WindowBound,
... WindowSpec,
... )
>>> window = WindowSpec(
... sort=Field.of("published").ascending(),
... frame=DocumentWindowFrame(
... WindowBound.UNBOUNDED, WindowBound.CURRENT

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.

nit: the example could be more clear with preceding and following kwargs present

... ),
... )

Args:
preceding: The lower bound of the frame (an integer offset, `WindowBound`, or `Expression`).
A positive integer includes up to that many documents before the current document.
A negative integer indicates a boundary following the current document.
following: The upper bound of the frame (an integer offset, `WindowBound`, or `Expression`).
A positive integer includes up to that many documents after the current document.
A negative integer indicates a boundary preceding the current document.
"""

preceding: WindowBound | str | int | pipeline_expressions.Expression
following: WindowBound | str | int | pipeline_expressions.Expression
Comment on lines +355 to +383

@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 — DocumentWindowFrame Dataclass & _to_dict():

  • Chosen Design: DocumentWindowFrame(preceding, following) is a standalone @dataclass (inheriting _to_pb() from _WindowFrame and exposing _to_dict() -> {"documents": self._to_pb()}) passed to WindowSpec(frame=...), with symbolic bounds represented by WindowBound(str, Enum) (matching TimeUnit/PipelineDataType in this module).
  • Alternatives Considered & Why Rejected:
    • Builder method on WindowSpec (e.g., WindowSpec().documents(preceding, following) as in Java): Python pipeline option types (FindNearestOptions, SearchOptions, UnnestOptions) use keyword-argument constructors rather than fluent builders. A standalone frame class is also reusable directly in per-function .over(DocumentWindowFrame(...)) overrides in a follow-up PR.
    • Raw tuple or dict (frame=(-1, "current") or frame={"preceding": -1, "following": "current"}): A tuple hides which bound is preceding vs following and doesn't extend cleanly when RangeWindowFrame adds unit=...; a dict loses type annotations and autocomplete.


def _to_dict(self) -> dict[str, Value]:
return {"documents": self._to_pb()}


class WindowSpec:
"""Configuration for a window in an `AddWindowFields` pipeline stage.

Args:
partition: Field paths or expressions used to partition documents into independent windows.
sort: Orderings specifying how documents are sorted within each partition.
frame: A `DocumentWindowFrame` defining a document-count window frame.

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.

What happens if None?

"""

def __init__(
Expand All @@ -346,6 +404,7 @@ def __init__(
| str
] = None,
sort: Optional[Sequence[Ordering] | Ordering] = None,
frame: Optional[DocumentWindowFrame] = None,

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 — WindowSpec(frame=...) & Backend-Enforced sort Validation:

  • Chosen Design:
    1. WindowSpec accepts a single frame= parameter (widened to DocumentWindowFrame | RangeWindowFrame in the next PR) and delegates wire-key dispatch via self.frame._to_dict().
    2. WindowSpec.__init__ does not raise a client-side ValueError when frame is provided without sort.
  • Alternatives Considered & Why Rejected:
    • Separate documents= and range= keyword arguments (as in Node's plain-object OneOf): In Python, the frame argument is already a nominally typed class (DocumentWindowFrame vs RangeWindowFrame), so repeating the frame kind in the keyword name (documents=DocumentWindowFrame(...), range=RangeWindowFrame(...)) stutters, shadows built-in range, and requires runtime mutual-exclusivity validation (if documents is not None and range is not None: raise ValueError(...)). A single frame= parameter makes passing two frames syntactically impossible and matches WindowFunction.over(frame).
    • Raising ValueError in WindowSpec.__init__ when frame is set and sort is omitted: Rejected per the cross-SDK Window Functions spec—sort requirement checks are intentionally enforced by the backend at execution time rather than in WindowSpec.__init__ (which also avoids duplicating backend validation rules when per-function .over(frame) overrides are used).

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.

This seems reasonable to me, but the fact that all the other libraries use a different pattern makes me a bit nervous. WindowSpec(documents=DocumentWindowFrame(1, "current")) seems more consistent with others, and I don't think a mutual exclusion check is too much of a burden. Maybe types could be simplified more if you wanted to avoid the naming stutter

But that said, I can't think of any real concerns with this current approach, and it does seem cleaner/nicer to me in isolation. So LGTM if you want to keep it as-is

):
if partition is None:
partition_list = []
Expand All @@ -363,6 +422,8 @@ def __init__(
else:
self.sort = [sort] if isinstance(sort, Ordering) else list(sort)

self.frame: Optional[DocumentWindowFrame] = frame

def __eq__(self, other: object) -> bool:
if not isinstance(other, WindowSpec):
return NotImplemented
Comment thread
daniel-sanche marked this conversation as resolved.
Resolved
Expand All @@ -374,6 +435,8 @@ def __repr__(self):
args.append(f"partition={self.partition!r}")
if self.sort:
args.append(f"sort={self.sort!r}")
if self.frame is not None:
args.append(f"frame={self.frame!r}")
return f"{self.__class__.__name__}({', '.join(args)})"

def _to_pb(self) -> Value:
Expand All @@ -386,4 +449,6 @@ def _to_pb(self) -> Value:
fields["sort"] = Value(
array_value={"values": [s._to_pb() for s in self.sort]}
)
if self.frame is not None:
fields.update(self.frame._to_dict())
return Value(map_value={"fields": fields})
Original file line number Diff line number Diff line change
@@ -1,4 +1,129 @@
tests:
- description: "testAddWindowFields - partition, sort, documents frame, and multiple accumulators"
pipeline:
- Collection: books
- Where:
- FunctionExpression.equal_any:
- Field: genre
- [Science Fiction, Dystopian]
- AddWindowFields:
window:
WindowSpec:
partition:
- Field: genre
sort:
- Ordering:
- Field: published
- ASCENDING
frame:
DocumentWindowFrame:
preceding: unbounded
following: current

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.

can we have a test with a numeric offset? (Maybe ask gemini for more test cases too)

fields:
- AliasedExpression:
- FunctionExpression.sum:
- Field: rating
- "running_rating"
- AliasedExpression:
- Count
- "running_count"
- Sort:
- Ordering:
- Field: published
- ASCENDING
- Select:
- title
- genre
- running_rating
- running_count
assert_results:
- title: "1984"
genre: "Dystopian"
running_rating: 4.2
running_count: 1
- title: "Dune"
genre: "Science Fiction"
running_rating: 4.6
running_count: 1
- title: "The Hitchhiker's Guide to the Galaxy"
genre: "Science Fiction"
running_rating: 8.8
running_count: 2
- title: "The Handmaid's Tale"
genre: "Dystopian"
running_rating: 8.3
running_count: 2
assert_proto:
pipeline:
stages:
- args:
- referenceValue: /books
name: collection
- args:
- functionValue:
args:
- fieldReferenceValue: genre
- functionValue:
args:
- stringValue: Science Fiction
- stringValue: Dystopian
name: array
name: equal_any
name: where
- args:
- mapValue:
fields:
documents:
mapValue:
fields:
following:
stringValue: current
preceding:
stringValue: unbounded
partition:
arrayValue:
values:
- fieldReferenceValue: genre
sort:
arrayValue:
values:
- mapValue:
fields:
direction:
stringValue: ascending
expression:
fieldReferenceValue: published
- mapValue:
fields:
running_count:
functionValue:
name: count
running_rating:
functionValue:
args:
- fieldReferenceValue: rating
name: sum
name: add_window_fields
- args:
- mapValue:
fields:
direction:
stringValue: ascending
expression:
fieldReferenceValue: published
name: sort
- args:
- mapValue:
fields:
genre:
fieldReferenceValue: genre
running_count:
fieldReferenceValue: running_count
running_rating:
fieldReferenceValue: running_rating
title:
fieldReferenceValue: title
name: select
- description: "testAddWindowFields - rank with ties"
pipeline:
- Collection: books
Expand Down
Loading
Loading