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 @@ -16,6 +16,7 @@

import datetime
from abc import ABC, abstractmethod
from dataclasses import dataclass
from enum import Enum
from typing import (
TYPE_CHECKING,
Expand All @@ -31,8 +32,10 @@

from google.cloud.firestore_v1._helpers import GeoPoint, decode_value, encode_value
from google.cloud.firestore_v1.pipeline_types import (
DocumentWindowFrame,
Ordering,
PipelineDataType,
RangeWindowFrame,
TimeGranularity,
TimePart,
TimeUnit,
Expand Down Expand Up @@ -2685,6 +2688,38 @@ def _to_pb(self):
class WindowFunction(FunctionExpression):
"""A base class for window functions that operate over a window of documents."""

def over(

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.

Chosen Design: Define over(frame) directly on WindowFunction (inherited by AggregateFunction, which subclasses WindowFunction), returning a WindowFunction and letting the backend reject invalid pairings like Rank().over(frame) (verified in window.yaml).

Alternatives Considered & Why Rejected:

  • Placing over(frame) only on AggregateFunction: Excludes upcoming non-aggregate window functions that do accept frames (e.g., first_value, last_value) or requires a third intermediate class solely for framing.
  • Client-side rejection of Rank().over(frame): Duplicates backend validation and risks drifting as window function support evolves; aligns with Node.js and Java.

self,
frame: DocumentWindowFrame | RangeWindowFrame,
) -> "WindowFunction":
"""Configures a window frame over which this function is evaluated.

Example:
>>> from google.cloud.firestore_v1.pipeline_expressions import Field
>>> from google.cloud.firestore_v1.pipeline_types import (
... DocumentWindowFrame,
... WindowBound,
... )
>>> expr = (
... Field.of("rating")
... .average()
... .over(DocumentWindowFrame(1, WindowBound.CURRENT))
... .as_("moving_avg")
... )

Args:
frame: A `DocumentWindowFrame` or `RangeWindowFrame` specifying the
window frame override for this function.

Returns:
A `WindowFunction` with the specified window frame override.
"""
return WindowFunction(
"over",
[self, _WindowFrameExpression(frame)],
repr_function=lambda _: f"{self!r}.over({frame!r})",
)


class AggregateFunction(WindowFunction):
"""A base class for aggregation functions that operate across multiple inputs."""
Expand Down Expand Up @@ -2878,6 +2913,16 @@ def _to_pb(self) -> Value:
return Value(pipeline_value=pipeline_pb)


@dataclass
class _WindowFrameExpression(Expression):

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.

Chosen Design: Wrap frame in a small @dataclass Expression adapter (_WindowFrameExpression, mirroring _PipelineValueExpression directly above) so over() constructs WindowFunction("over", [self, _WindowFrameExpression(frame)], repr_function=...). This keeps FunctionExpression untouched (params: Sequence[Expression]), avoids importing WindowSpec here, gives WindowFunction zero dunder/_to_pb boilerplate, and lets the backend reject chained .over(f1).over(f2) (over(over(...))) rather than silently overwriting f1.

Alternatives Considered & Why Rejected:

  • Passing WindowSpec(frame=frame) and widening FunctionExpression.params: Leaks window-stage configuration types into the generic FunctionExpression base class.
  • Storing self._frame on WindowFunction with custom __init__, __repr__, __eq__, _to_pb: Adds four overrides to WindowFunction solely for over(), and risks silently dropping f1 if chained.
  • Dedicated _OverExpression(WindowFunction) subclass: Still introduces an internal class while requiring manual __init__, __eq__, and _to_pb instead of reusing FunctionExpression + @dataclass.

"""Internal wrapper to represent a window frame as an expression."""

frame: DocumentWindowFrame | RangeWindowFrame

def _to_pb(self) -> Value:
return Value(map_value={"fields": self.frame._to_dict()})


class Array(FunctionExpression):
"""
Creates an expression that creates a Firestore array value from an input list.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -302,3 +302,172 @@ tests:
- Count
- "window_count"
assert_error: ".*range.*"
- description: "testAddWindowFields - accumulator-level over() frames"
pipeline:
- Collection: books
- Where:
- FunctionExpression.equal_any:
- Field: genre
- [Science Fiction, Dystopian]
- AddWindowFields:
window:
WindowSpec:
sort:
- Ordering:
- Field: published
- ASCENDING
fields:
- AliasedExpression:
- WindowFunction.over:
- Count
- RangeWindowFrame:
preceding: 20
following: current
- "books_within_20_years"
- AliasedExpression:
- WindowFunction.over:
- FunctionExpression.array_agg:
- Field: title
- DocumentWindowFrame:
preceding: 1
following: 1
- "nearby_titles"
- Sort:
- Ordering:
- Field: published
- ASCENDING
- Select:
- title
- published
- books_within_20_years
- nearby_titles
assert_results:
- title: "1984"
published: 1949
books_within_20_years: 1
nearby_titles:
- "1984"
- "Dune"
- title: "Dune"
published: 1965
books_within_20_years: 2
nearby_titles:
- "1984"
- "Dune"
- "The Hitchhiker's Guide to the Galaxy"
- title: "The Hitchhiker's Guide to the Galaxy"
published: 1979
books_within_20_years: 2
nearby_titles:
- "Dune"
- "The Hitchhiker's Guide to the Galaxy"
- "The Handmaid's Tale"
- title: "The Handmaid's Tale"
published: 1985
books_within_20_years: 3
nearby_titles:
- "The Hitchhiker's Guide to the Galaxy"
- "The Handmaid's Tale"
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:
sort:
arrayValue:
values:
- mapValue:
fields:
direction:
stringValue: ascending
expression:
fieldReferenceValue: published
- mapValue:
fields:
books_within_20_years:
functionValue:
args:
- functionValue:
name: count
- mapValue:
fields:
range:
mapValue:
fields:
following:
stringValue: current
preceding:
integerValue: '20'
name: over
nearby_titles:
functionValue:
args:
- functionValue:
args:
- fieldReferenceValue: title
name: array_agg
- mapValue:
fields:
documents:
mapValue:
fields:
following:
integerValue: '1'
preceding:
integerValue: '1'
name: over
name: add_window_fields
- args:
- mapValue:
fields:
direction:
stringValue: ascending
expression:
fieldReferenceValue: published
name: sort
- args:
- mapValue:
fields:
books_within_20_years:
fieldReferenceValue: books_within_20_years
nearby_titles:
fieldReferenceValue: nearby_titles
published:
fieldReferenceValue: published
title:
fieldReferenceValue: title
name: select
- description: "testAddWindowFields - error on rank() with over() frame"
pipeline:
- Collection: books
- AddWindowFields:
window:
WindowSpec:
sort:
- Ordering:
- Field: published
- ASCENDING
fields:
- AliasedExpression:
- WindowFunction.over:
- Rank
- DocumentWindowFrame:
preceding: unbounded
following: current
- "pub_rank"
assert_error: ".*rank.*"
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,11 @@
Rank,
WindowFunction,
)
from google.cloud.firestore_v1.pipeline_types import (
DocumentWindowFrame,
RangeWindowFrame,
WindowBound,
)
from google.cloud.firestore_v1.types import document as document_pb
from google.cloud.firestore_v1.types import query as query_pb
from google.cloud.firestore_v1.types.document import Value
Expand Down Expand Up @@ -2271,6 +2276,44 @@ class TestWindowExpressions:
def test_window_function_hierarchy(self):
assert issubclass(AggregateFunction, WindowFunction)
assert not issubclass(Expression, WindowFunction)
assert not hasattr(Field.of("rating"), "over")

def test_over_repr_and_equality(self):
agg = Field.of("rating").sum()
frame = DocumentWindowFrame(1, WindowBound.CURRENT)
win_fn = agg.over(frame)
assert isinstance(win_fn, WindowFunction)
assert not isinstance(win_fn, AggregateFunction)
assert (
repr(win_fn)
== "Field.of('rating').sum().over(DocumentWindowFrame(preceding=1, following=<WindowBound.CURRENT: 'current'>))"
)
assert (
repr(expr.Count().over(frame))
== "Count().over(DocumentWindowFrame(preceding=1, following=<WindowBound.CURRENT: 'current'>))"
)
assert win_fn == agg.over(DocumentWindowFrame(1, WindowBound.CURRENT))
assert win_fn != agg.over(RangeWindowFrame(1, WindowBound.CURRENT))
assert win_fn != agg
assert win_fn != object()

def test_over_to_pb(self):
agg = Field.of("rating").sum()
doc_frame = DocumentWindowFrame(-1, WindowBound.CURRENT)
doc_pb = agg.over(doc_frame)._to_pb()
assert doc_pb.function_value.name == "over"
assert list(doc_pb.function_value.args) == [
agg._to_pb(),
Value(map_value={"fields": {"documents": doc_frame._to_pb()}}),
]

range_frame = RangeWindowFrame(-5, 5, "day")
range_pb = agg.over(range_frame)._to_pb()
assert range_pb.function_value.name == "over"
assert list(range_pb.function_value.args) == [
agg._to_pb(),
Value(map_value={"fields": {"range": range_frame._to_pb()}}),
]

def test_rank(self):
rank = Rank()
Expand Down
Loading