From 15229f751cccd3513331f287f424ef9c3ab02e1c Mon Sep 17 00:00:00 2001 From: ohmayr Date: Wed, 18 Nov 2026 02:15:15 +0000 Subject: [PATCH 1/3] feat(firestore): add RangeWindowFrame for pipeline windows Add RangeWindowFrame and the range parameter on WindowSpec to support value-based and time-range window frames in AddWindowFields stages. --- .../firestore-integration.yaml | 2 + .../google/cloud/firestore/__init__.py | 2 + .../google/cloud/firestore_v1/__init__.py | 2 + .../cloud/firestore_v1/pipeline_types.py | 38 +++++++++ .../tests/system/pipeline_e2e/window.yaml | 77 +++++++++++++++++++ .../tests/unit/v1/test_pipeline_stages.py | 43 +++++++++++ 6 files changed, 164 insertions(+) diff --git a/.librarian/generator-input/client-post-processing/firestore-integration.yaml b/.librarian/generator-input/client-post-processing/firestore-integration.yaml index ca510eac81d8..cf24b715af2f 100644 --- a/.librarian/generator-input/client-post-processing/firestore-integration.yaml +++ b/.librarian/generator-input/client-post-processing/firestore-integration.yaml @@ -96,6 +96,7 @@ replacements: FindNearestOptions, Ordering, PipelineDataType, + RangeWindowFrame, SampleOptions, SearchOptions, TimeGranularity, @@ -221,6 +222,7 @@ replacements: "PipelineSource", "PipelineStream", "Query", + "RangeWindowFrame", "ReadAfterWriteError", "SERVER_TIMESTAMP", "SampleOptions", diff --git a/packages/google-cloud-firestore/google/cloud/firestore/__init__.py b/packages/google-cloud-firestore/google/cloud/firestore/__init__.py index af79d1f76be2..a45b406145db 100644 --- a/packages/google-cloud-firestore/google/cloud/firestore/__init__.py +++ b/packages/google-cloud-firestore/google/cloud/firestore/__init__.py @@ -71,6 +71,7 @@ PipelineSource, PipelineStream, Query, + RangeWindowFrame, ReadAfterWriteError, SampleOptions, SearchOptions, @@ -141,6 +142,7 @@ "PipelineSource", "PipelineStream", "Query", + "RangeWindowFrame", "ReadAfterWriteError", "SERVER_TIMESTAMP", "SampleOptions", diff --git a/packages/google-cloud-firestore/google/cloud/firestore_v1/__init__.py b/packages/google-cloud-firestore/google/cloud/firestore_v1/__init__.py index 402d0aef6bea..a5a2757afc57 100644 --- a/packages/google-cloud-firestore/google/cloud/firestore_v1/__init__.py +++ b/packages/google-cloud-firestore/google/cloud/firestore_v1/__init__.py @@ -73,6 +73,7 @@ FindNearestOptions, Ordering, PipelineDataType, + RangeWindowFrame, SampleOptions, SearchOptions, TimeGranularity, @@ -198,6 +199,7 @@ "PipelineSource", "PipelineStream", "Query", + "RangeWindowFrame", "ReadAfterWriteError", "SERVER_TIMESTAMP", "SampleOptions", diff --git a/packages/google-cloud-firestore/google/cloud/firestore_v1/pipeline_types.py b/packages/google-cloud-firestore/google/cloud/firestore_v1/pipeline_types.py index df684a53c4e4..6ee05c33207e 100644 --- a/packages/google-cloud-firestore/google/cloud/firestore_v1/pipeline_types.py +++ b/packages/google-cloud-firestore/google/cloud/firestore_v1/pipeline_types.py @@ -381,6 +381,35 @@ class DocumentWindowFrame(_WindowFrame): following: WindowBound | str | int | pipeline_expressions.Expression +@dataclass +class RangeWindowFrame(_WindowFrame): + """Defines a value-based or time-range window frame relative to the current document's sort value. + + Example: + >>> from google.cloud.firestore_v1.pipeline_types import ( + ... RangeWindowFrame, + ... TimeUnit, + ... WindowBound, + ... WindowSpec, + ... ) + >>> window = WindowSpec( + ... range=RangeWindowFrame(12, WindowBound.CURRENT, unit=TimeUnit.HOUR) + ... ) + + Args: + preceding: The lower bound of the frame (a numeric offset, `WindowBound`, or `Expression`). + following: The upper bound of the frame (a numeric offset, `WindowBound`, or `Expression`). + unit: Optional duration unit for time-range frames (e.g., `TimeUnit.DAY`, `TimeGranularity.MONTH`, + `"day"`, or an `Expression`). + """ + + 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 + + class WindowSpec: """Configuration for a window in an `AddWindowFields` pipeline stage. @@ -388,6 +417,9 @@ class WindowSpec: partition: Field paths or expressions used to partition documents into independent windows. sort: Orderings specifying how documents are sorted within each partition. documents: A `DocumentWindowFrame` defining a document-count window frame. + Mutually exclusive with `range`. + range: A `RangeWindowFrame` defining a value-based or time-range window frame. + Mutually exclusive with `documents`. """ def __init__( @@ -400,6 +432,7 @@ def __init__( ] = None, sort: Optional[Sequence[Ordering] | Ordering] = None, documents: Optional[DocumentWindowFrame] = None, + range: Optional[RangeWindowFrame] = None, ): if partition is None: partition_list = [] @@ -418,6 +451,7 @@ def __init__( self.sort = [sort] if isinstance(sort, Ordering) else list(sort) self.documents: Optional[DocumentWindowFrame] = documents + self.range: Optional[RangeWindowFrame] = range def __eq__(self, other: object) -> bool: if not isinstance(other, WindowSpec): @@ -432,6 +466,8 @@ def __repr__(self): args.append(f"sort={self.sort!r}") if self.documents is not None: args.append(f"documents={self.documents!r}") + if self.range is not None: + args.append(f"range={self.range!r}") return f"{self.__class__.__name__}({', '.join(args)})" def _to_pb(self) -> Value: @@ -446,4 +482,6 @@ def _to_pb(self) -> Value: ) if self.documents is not None: fields["documents"] = self.documents._to_pb() + if self.range is not None: + fields["range"] = self.range._to_pb() return Value(map_value={"fields": fields}) 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 62e989e200f2..bdb426ca0bfc 100644 --- a/packages/google-cloud-firestore/tests/system/pipeline_e2e/window.yaml +++ b/packages/google-cloud-firestore/tests/system/pipeline_e2e/window.yaml @@ -225,3 +225,80 @@ tests: title: fieldReferenceValue: title name: select + - description: "testAddWindowFields - range frame with time unit" + pipeline: + - Collection: timestamps + - AddWindowFields: + window: + WindowSpec: + sort: + - Ordering: + - Field: time + - ASCENDING + range: + RangeWindowFrame: + preceding: 12 + following: current + unit: hour + fields: + - AliasedExpression: + - Count + - "window_count" + - Select: + - window_count + assert_results: + - window_count: 1 + assert_proto: + pipeline: + stages: + - args: + - referenceValue: /timestamps + name: collection + - args: + - mapValue: + fields: + range: + mapValue: + fields: + following: + stringValue: current + preceding: + integerValue: '12' + unit: + stringValue: hour + sort: + arrayValue: + values: + - mapValue: + fields: + direction: + stringValue: ascending + expression: + fieldReferenceValue: time + - mapValue: + fields: + window_count: + functionValue: + name: count + name: add_window_fields + - args: + - mapValue: + fields: + window_count: + fieldReferenceValue: window_count + name: select + - description: "testAddWindowFields - error on range frame without sort" + pipeline: + - Collection: books + - AddWindowFields: + window: + WindowSpec: + range: + RangeWindowFrame: + preceding: unbounded + following: current + fields: + - AliasedExpression: + - Count + - "window_count" + assert_error: ".*range.*" diff --git a/packages/google-cloud-firestore/tests/unit/v1/test_pipeline_stages.py b/packages/google-cloud-firestore/tests/unit/v1/test_pipeline_stages.py index 763582e74d0a..4e8812ecd8fa 100644 --- a/packages/google-cloud-firestore/tests/unit/v1/test_pipeline_stages.py +++ b/packages/google-cloud-firestore/tests/unit/v1/test_pipeline_stages.py @@ -29,6 +29,9 @@ ) from google.cloud.firestore_v1.pipeline_types import ( DocumentWindowFrame, + RangeWindowFrame, + TimeGranularity, + TimeUnit, WindowBound, WindowSpec, ) @@ -1082,6 +1085,7 @@ def test_document_window_frame_to_pb(self): } assert frame == DocumentWindowFrame(1, "current") assert frame != DocumentWindowFrame(2, WindowBound.CURRENT) + assert frame != RangeWindowFrame(1, WindowBound.CURRENT) expr_pb = DocumentWindowFrame(Field.of("offset"), "unbounded")._to_pb() assert expr_pb.map_value.fields == { @@ -1089,6 +1093,28 @@ def test_document_window_frame_to_pb(self): "following": Value(string_value="unbounded"), } + @pytest.mark.parametrize( + "unit,expected_unit", + [ + (TimeUnit.DAY, "day"), + (TimeGranularity.MONTH, "month"), + ("hour", "hour"), + (Constant.of("minute"), "minute"), + ], + ) + def test_range_window_frame_to_pb(self, unit, expected_unit): + no_unit_pb = RangeWindowFrame(10, 20)._to_pb() + assert no_unit_pb.map_value.fields == { + "preceding": Value(integer_value=10), + "following": Value(integer_value=20), + } + pb = RangeWindowFrame(10.5, WindowBound.UNBOUNDED, unit)._to_pb() + assert pb.map_value.fields == { + "preceding": Value(double_value=10.5), + "following": Value(string_value="unbounded"), + "unit": Value(string_value=expected_unit), + } + def test_window_spec_coercions(self): order = Field.of("rating").descending() assert WindowSpec().partition == [] @@ -1122,6 +1148,17 @@ def test_window_spec_repr_and_equality(self): sort=[Field.of("rating").descending()], documents=DocumentWindowFrame(-1, "current"), ) + range_spec = WindowSpec( + sort=Field.of("published").ascending(), + range=RangeWindowFrame(-5, 5, "day"), + ) + assert repr(range_spec) == ( + "WindowSpec(" + "sort=[Field.of('published').ascending()], " + "range=RangeWindowFrame(preceding=-5, following=5, unit='day')" + ")" + ) + assert spec != range_spec assert spec != empty assert spec != object() @@ -1137,6 +1174,12 @@ def test_window_spec_to_pb(self): "sort": Value(array_value={"values": [order._to_pb()]}), "documents": doc_frame._to_pb(), } + range_frame = RangeWindowFrame(-5, 5, "day") + range_spec = WindowSpec(sort=order, range=range_frame) + assert range_spec._to_pb().map_value.fields == { + "sort": Value(array_value={"values": [order._to_pb()]}), + "range": range_frame._to_pb(), + } class TestAddWindowFields: From 50f636c73669529179b0e195a435842216509574 Mon Sep 17 00:00:00 2001 From: ohmayr Date: Wed, 18 Nov 2026 02:22:52 +0000 Subject: [PATCH 2/3] chore(firestore): add RangeWindowFrame to top-level librarian post-processing --- .../client-post-processing/firestore-integration.yaml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.librarian/generator-input/client-post-processing/firestore-integration.yaml b/.librarian/generator-input/client-post-processing/firestore-integration.yaml index 0a61ce41a2f8..18af4ae9800b 100644 --- a/.librarian/generator-input/client-post-processing/firestore-integration.yaml +++ b/.librarian/generator-input/client-post-processing/firestore-integration.yaml @@ -306,6 +306,7 @@ replacements: PipelineSource, PipelineStream, Query, + RangeWindowFrame, ReadAfterWriteError, SampleOptions, SearchOptions, @@ -376,6 +377,7 @@ replacements: "PipelineSource", "PipelineStream", "Query", + "RangeWindowFrame", "ReadAfterWriteError", "SERVER_TIMESTAMP", "SampleOptions", From 31e9dd3318a248463d56a82a7c8d31feb7827b37 Mon Sep 17 00:00:00 2001 From: ohmayr Date: Wed, 18 Nov 2026 02:25:09 +0000 Subject: [PATCH 3/3] docs(firestore): include sort in RangeWindowFrame docstring example --- .../google/cloud/firestore_v1/pipeline_types.py | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/packages/google-cloud-firestore/google/cloud/firestore_v1/pipeline_types.py b/packages/google-cloud-firestore/google/cloud/firestore_v1/pipeline_types.py index 6ee05c33207e..193eb50a28ea 100644 --- a/packages/google-cloud-firestore/google/cloud/firestore_v1/pipeline_types.py +++ b/packages/google-cloud-firestore/google/cloud/firestore_v1/pipeline_types.py @@ -386,6 +386,7 @@ class RangeWindowFrame(_WindowFrame): """Defines a value-based or time-range window frame relative to the current document's sort value. Example: + >>> from google.cloud.firestore_v1.pipeline_expressions import Field >>> from google.cloud.firestore_v1.pipeline_types import ( ... RangeWindowFrame, ... TimeUnit, @@ -393,7 +394,8 @@ class RangeWindowFrame(_WindowFrame): ... WindowSpec, ... ) >>> window = WindowSpec( - ... range=RangeWindowFrame(12, WindowBound.CURRENT, unit=TimeUnit.HOUR) + ... sort=Field.of("time").ascending(), + ... range=RangeWindowFrame(12, WindowBound.CURRENT, unit=TimeUnit.HOUR), ... ) Args: