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 @@ -101,6 +101,7 @@ replacements:
TimePart,
TimeUnit,
UnnestOptions,
WindowSpec,
)
from google.cloud.firestore_v1.query import CollectionGroup, Query
from google.cloud.firestore_v1.query_profile import (
Expand Down Expand Up @@ -230,6 +231,7 @@ replacements:
"types",
"UnnestOptions",
"Watch",
"WindowSpec",
"WriteBatch",
"WriteOption",
]
Expand Down Expand Up @@ -307,6 +309,7 @@ replacements:
Transaction,
UnnestOptions,
Watch,
WindowSpec,
WriteBatch,
WriteOption,
async_transactional,
Expand Down Expand Up @@ -377,6 +380,7 @@ replacements:
"types",
"UnnestOptions",
"Watch",
"WindowSpec",
"WriteBatch",
"WriteOption",
]
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -80,6 +80,7 @@
Transaction,
UnnestOptions,
Watch,
WindowSpec,
WriteBatch,
WriteOption,
async_transactional,
Expand Down Expand Up @@ -150,6 +151,7 @@
"types",
"UnnestOptions",
"Watch",
"WindowSpec",
"WriteBatch",
"WriteOption",
]
Original file line number Diff line number Diff line change
Expand Up @@ -78,6 +78,7 @@
TimePart,
TimeUnit,
UnnestOptions,
WindowSpec,
)
from google.cloud.firestore_v1.query import CollectionGroup, Query
from google.cloud.firestore_v1.query_profile import (
Expand Down Expand Up @@ -207,6 +208,7 @@
"types",
"UnnestOptions",
"Watch",
"WindowSpec",
"WriteBatch",
"WriteOption",
]
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,7 @@
Field,
FunctionExpression,
Selectable,
WindowFunction,
_PipelineValueExpression,
)
from google.cloud.firestore_v1.types.pipeline import (
Expand Down Expand Up @@ -176,6 +177,60 @@ def add_fields(self, *fields: Selectable) -> "_BasePipeline":
"""
return self._append(stages.AddFields(*fields))

def add_window_fields(
self,
*fields: AliasedExpression[AggregateFunction]
| AliasedExpression[WindowFunction],
window: types.WindowSpec | None = None,
Comment thread
ohmayr marked this conversation as resolved.
Resolved
) -> "_BasePipeline":
"""
Evaluates window and aggregate functions over a window of related documents
and adds the results as new fields on each input document.

Unlike :meth:`aggregate`, which collapses documents into summary rows,
``add_window_fields`` preserves every input document and attaches computed
values (such as partition totals, running aggregates, or rankings) to each row.

When ``window`` specifies ``sort`` without an explicit frame, aggregates evaluate
as a running window from the start of the partition through the current sort
value. When ``sort`` is omitted, aggregates evaluate across all documents in the
partition.

.. note::
This feature is in preview until the backend feature launches and is
subject to change.

Example:
>>> from google.cloud.firestore_v1.pipeline_expressions import Field, Rank
>>> from google.cloud.firestore_v1.pipeline_types import WindowSpec
>>> pipeline = client.pipeline().collection("books")
>>> # Partition-wide average rating (unsorted window covers the whole partition)
>>> pipeline = pipeline.add_window_fields(
... Field.of("rating").average().as_("genre_avg_rating"),
... window=WindowSpec(partition=["genre"]),
... )
>>> # Rank and running total within each genre (sorted default frame)
>>> pipeline = pipeline.add_window_fields(
... Rank().as_("genre_rank"),
... Field.of("price").sum().as_("running_price_total"),
... window=WindowSpec(
... partition=["genre"],
... sort=[Field.of("rating").descending()],

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.

IIUC, having this sort here means that the value under genre_total_price is a running total, not the genre total

We should update the example, and make sure this sort detail is mentioned in this docstring, and in the WindowSpec

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.

Good catch! Updated the example to show both an unsorted partition average and a sorted rank + running total.

... ),
... )

Args:
*fields: Aliased `AggregateFunction` or `WindowFunction` expressions defining
the window calculations and their output field aliases.

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.

It seems like other languages require at least one field. Should we do the same here?

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.

Kept *fields to match the other variadic stages in base_pipeline.py (add_fields, aggregate, select, sort, etc.), which all rely on backend validation. Happy to require a first arg here if you feel strongly though.

window: Optional `WindowSpec` specifying how documents are partitioned and
ordered. If `None`, evaluates over a single unsorted global partition
covering all input documents (equivalent to ``WindowSpec()``).

Returns:
A new Pipeline object with this stage appended to the stage list.
"""
return self._append(stages.AddWindowFields(*fields, window=window))

def remove_fields(self, *fields: Field | str) -> "_BasePipeline":
"""
Removes fields from outputs of previous stages.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -2682,6 +2682,15 @@ def _to_pb(self):
)


class WindowFunction(FunctionExpression):
"""A base class for window functions that operate over a window of documents.

.. note::
This feature is in preview until the backend feature launches and is
subject to change.
"""


class AggregateFunction(FunctionExpression):
"""A base class for aggregation functions that operate across multiple inputs."""

Expand Down Expand Up @@ -3197,3 +3206,32 @@ def __init__(self):
[],
repr_function=FunctionExpression._build_standalone_repr(),
)


class Rank(WindowFunction):
"""Creates a window function that computes the rank of each document within a window.

Documents with equal sort values receive the same rank, with gaps in the subsequent
ranking numbers. The window must specify exactly one sort ordering.

.. note::
This feature is in preview until the backend feature launches and is
subject to change.

Example:
>>> # Rank documents by price descending within each category
>>> db.pipeline().collection("products").add_window_fields(
... Rank().as_("price_rank"),
... window=WindowSpec(
... partition=["category"],
... sort=[Field.of("price").descending()],
... ),
... )
"""

def __init__(self):
super().__init__(
"rank",
[],
repr_function=FunctionExpression._build_standalone_repr(),
)
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,7 @@
Expression,
Field,
Selectable,
WindowFunction,
)
from google.cloud.firestore_v1.types.document import Pipeline as Pipeline_pb
from google.cloud.firestore_v1.types.document import Value
Expand All @@ -42,6 +43,7 @@
SampleOptions,
SearchOptions,
UnnestOptions,
WindowSpec,
)


Expand Down Expand Up @@ -86,6 +88,37 @@ def _pb_args(self):
return [Selectable._to_value(self.fields)]


class AddWindowFields(Stage):
"""Adds new fields computed by window functions over a window of documents.

.. note::
This feature is in preview until the backend feature launches and is
subject to change.
"""

def __init__(
self,
*args: AliasedExpression[AggregateFunction] | AliasedExpression[WindowFunction],
fields: Sequence[
AliasedExpression[AggregateFunction] | AliasedExpression[WindowFunction]
] = (),
window: WindowSpec | None = None,
):
super().__init__("add_window_fields")
if args and fields:
raise ValueError(
"AddWindowFields stage contains both positional and keyword fields"
)
self.fields = list(args or fields)

@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 Decision (add_window_fields & AddWindowFields Signature):

  • Chosen Design: pipeline.add_window_fields(*fields, window: WindowSpec | None = None) (expressions first as *fields, optional window as a keyword argument).
  • Alternatives Considered & Why Rejected:
    1. Putting window as the first positional argument (add_window_fields(window, *fields), like Java/Web): Rejected for two reasons:
      • In Python's existing pipeline.aggregate(*accumulators, groups=...), the expressions come first as *args and the grouping config is a keyword argument at the end.
      • Because window is optional (when omitted, all documents form a single unpartitioned window), putting *fields first lets callers write pipeline.add_window_fields(Field.of("x").sum().as_("total")) without having to pass WindowSpec() or None as a first argument.
    2. Why AddWindowFields.__init__ accepts both *args and fields=(): Python callers pass expressions positionally (*args), while the YAML acceptance test runner (test_pipeline_acceptance.py) unpacks AddWindowFields: {window: ..., fields: [...]} from window.yaml as **kwargs. Accepting either (and raising ValueError if both are passed at once) matches Aggregate.__init__ right below.

self.window: WindowSpec = window if window is not None else WindowSpec()

def _pb_args(self) -> list[Value]:
return [
self.window._to_pb(),
Selectable._to_value(self.fields),
]


class Aggregate(Stage):
"""Performs aggregation operations, optionally grouped."""

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -327,3 +327,83 @@ def __init__(self, index_field: pipeline_expressions.Field | str):

def __repr__(self):
return f"{self.__class__.__name__}(index_field={self.index_field.path!r})"


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

.. note::
This feature is in preview until the backend feature launches and is
subject to change.

Args:
partition: Optional field paths or expressions used to partition documents into
independent windows. If `None`, all input documents are treated as a single
global partition.
sort: Optional orderings specifying how documents are sorted within each
partition. If `None`, documents are unordered and aggregates evaluate across
all documents in the partition. When specified without an explicit frame,
aggregates default to a running window from the start of the partition
through the current sort value.
"""

def __init__(
self,
*,
partition: Optional[
Sequence[pipeline_expressions.Expression | str]
| pipeline_expressions.Expression
| str
] = None,
sort: Optional[Sequence[Ordering] | Ordering] = None,
):
if partition is None:
partition_list = []
elif isinstance(partition, (str, pipeline_expressions.Expression)):
partition_list = [partition]
else:
partition_list = list(partition)
self.partition: list[pipeline_expressions.Expression] = [
pipeline_expressions.Field.of(p) if isinstance(p, str) else p
for p in partition_list
]

if sort is None:
self.sort: list[Ordering] = []
elif isinstance(sort, Ordering):
self.sort = [sort]
elif (
isinstance(sort, (str, bytes))
or not isinstance(sort, Sequence)
or not all(isinstance(o, Ordering) for o in sort)
):
raise TypeError(
"sort must be an Ordering or a sequence of Ordering objects"
)
else:
self.sort = list(sort)

def __eq__(self, other: object) -> bool:
if not isinstance(other, WindowSpec):
return NotImplemented
return self._to_pb() == other._to_pb()

@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 Decision (WindowSpec):

  • Chosen Design: Keyword-only constructor WindowSpec(*, partition=None, sort=None) that accepts either a single value (partition="genre") or a sequence (partition=["genre", "author"]), and compares _to_pb() in __eq__.
  • Alternatives Considered & Why Rejected:
    1. Fluent builder methods (WindowSpec().partition("genre").sort(...), like Java/Kotlin): Rejected because every existing stage options class in the Python Firestore SDK (SearchOptions, FindNearestOptions, UnnestOptions) uses keyword-argument constructors rather than fluent method chaining.
    2. Passing partition and sort directly on add_window_fields(..., partition=..., sort=...) without WindowSpec: Rejected because bundling window configuration into WindowSpec keeps add_window_fields clean as documents= and range= frames are added in PRs 2–3, and aligns with the cross-SDK WindowSpec type.
    3. Positional arguments on WindowSpec(partition, sort): Rejected in favor of keyword-only (*) so callers cannot accidentally mix up argument order once documents= and range= are added.
    4. Comparing self.sort == other.sort in __eq__: Rejected because Ordering in pipeline_types.py does not implement __eq__ (so two identical Ordering instances compare as False). Comparing self._to_pb() == other._to_pb() (matching Selectable.__eq__) makes WindowSpec equality work without touching Ordering.


def __repr__(self):
args = []
if self.partition:
args.append(f"partition={self.partition!r}")
if self.sort:
args.append(f"sort={self.sort!r}")
return f"{self.__class__.__name__}({', '.join(args)})"

def _to_pb(self) -> Value:
fields: dict[str, Value] = {}
if self.partition:
fields["partition"] = Value(
array_value={"values": [p._to_pb() for p in self.partition]}
)
if self.sort:
fields["sort"] = Value(
array_value={"values": [s._to_pb() for s in self.sort]}
)
return Value(map_value={"fields": fields})
Loading
Loading