diff --git a/packages/google-cloud-firestore/google/cloud/firestore_v1/pipeline_expressions.py b/packages/google-cloud-firestore/google/cloud/firestore_v1/pipeline_expressions.py index 0d9598fd6274..f3c3c72fb699 100644 --- a/packages/google-cloud-firestore/google/cloud/firestore_v1/pipeline_expressions.py +++ b/packages/google-cloud-firestore/google/cloud/firestore_v1/pipeline_expressions.py @@ -16,6 +16,7 @@ import datetime from abc import ABC, abstractmethod +from dataclasses import dataclass from enum import Enum from typing import ( TYPE_CHECKING, @@ -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, @@ -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( + 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.""" @@ -2878,6 +2913,16 @@ def _to_pb(self) -> Value: return Value(pipeline_value=pipeline_pb) +@dataclass +class _WindowFrameExpression(Expression): + """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. diff --git a/packages/google-cloud-firestore/tests/system/pipeline_e2e/window.yaml b/packages/google-cloud-firestore/tests/system/pipeline_e2e/window.yaml index a0e5519e5ffb..91481d699fed 100644 --- a/packages/google-cloud-firestore/tests/system/pipeline_e2e/window.yaml +++ b/packages/google-cloud-firestore/tests/system/pipeline_e2e/window.yaml @@ -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.*" diff --git a/packages/google-cloud-firestore/tests/unit/v1/test_pipeline_expressions.py b/packages/google-cloud-firestore/tests/unit/v1/test_pipeline_expressions.py index a8ca27278506..bf34ee358d26 100644 --- a/packages/google-cloud-firestore/tests/unit/v1/test_pipeline_expressions.py +++ b/packages/google-cloud-firestore/tests/unit/v1/test_pipeline_expressions.py @@ -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 @@ -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=))" + ) + assert ( + repr(expr.Count().over(frame)) + == "Count().over(DocumentWindowFrame(preceding=1, following=))" + ) + 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()