chore: Pipeline queries cleanup

google/cloud/firestore_v1/async_pipeline.py

@@ -14,7 +14,7 @@
 
 from __future__ import annotations
 from typing import AsyncIterable, TYPE_CHECKING
-from google.cloud.firestore_v1 import _pipeline_stages as stages
+from google.cloud.firestore_v1 import pipeline_stages as stages
 from google.cloud.firestore_v1.base_pipeline import _BasePipeline
 
 if TYPE_CHECKING:  # pragma: NO COVER

google/cloud/firestore_v1/base_aggregation.py

@@ -36,7 +36,7 @@
 )
 from google.cloud.firestore_v1.pipeline_expressions import AggregateFunction
 from google.cloud.firestore_v1.pipeline_expressions import Count
-from google.cloud.firestore_v1.pipeline_expressions import AliasedExpr
+from google.cloud.firestore_v1.pipeline_expressions import AliasedExpression
 from google.cloud.firestore_v1.pipeline_expressions import Field
 
 # Types needed only for Type Hints
@@ -86,7 +86,7 @@ def _to_protobuf(self):
     @abc.abstractmethod
     def _to_pipeline_expr(
         self, autoindexer: Iterable[int]
-    ) -> AliasedExpr[AggregateFunction]:
+    ) -> AliasedExpression[AggregateFunction]:
         """
         Convert this instance to a pipeline expression for use with pipeline.aggregate()
 

google/cloud/firestore_v1/base_pipeline.py

@@ -14,7 +14,7 @@
 
 from __future__ import annotations
 from typing import Iterable, Sequence, TYPE_CHECKING
-from google.cloud.firestore_v1 import _pipeline_stages as stages
+from google.cloud.firestore_v1 import pipeline_stages as stages
 from google.cloud.firestore_v1.types.pipeline import (
     StructuredPipeline as StructuredPipeline_pb,
 )
@@ -23,10 +23,11 @@
 from google.cloud.firestore_v1.types.firestore import ExecutePipelineRequest
 from google.cloud.firestore_v1.pipeline_result import PipelineResult
 from google.cloud.firestore_v1.pipeline_expressions import (
-    AliasedAggregate,
-    Expr,
+    AggregateFunction,
+    AliasedExpression,
+    Expression,
     Field,
-    BooleanExpr,
+    BooleanExpression,
     Selectable,
 )
 from google.cloud.firestore_v1 import _helpers
@@ -146,7 +147,7 @@ def add_fields(self, *fields: Selectable) -> "_BasePipeline":
         The added fields are defined using `Selectable` expressions, which can be:
             - `Field`: References an existing document field.
             - `Function`: Performs a calculation using functions like `add`,
-              `multiply` with assigned aliases using `Expr.as_()`.
+              `multiply` with assigned aliases using `Expression.as_()`.
 
         Example:
             >>> from google.cloud.firestore_v1.pipeline_expressions import Field, add
@@ -193,7 +194,7 @@ def select(self, *selections: str | Selectable) -> "_BasePipeline":
         The selected fields are defined using `Selectable` expressions or field names:
             - `Field`: References an existing document field.
             - `Function`: Represents the result of a function with an assigned alias
-              name using `Expr.as_()`.
+              name using `Expression.as_()`.
             - `str`: The name of an existing field.
 
         If no selections are provided, the output of this stage is empty. Use
@@ -219,14 +220,14 @@ def select(self, *selections: str | Selectable) -> "_BasePipeline":
         """
         return self._append(stages.Select(*selections))
 
-    def where(self, condition: BooleanExpr) -> "_BasePipeline":
+    def where(self, condition: BooleanExpression) -> "_BasePipeline":
         """
         Filters the documents from previous stages to only include those matching
-        the specified `BooleanExpr`.
+        the specified `BooleanExpression`.
 
         This stage allows you to apply conditions to the data, similar to a "WHERE"
         clause in SQL. You can filter documents based on their field values, using
-        implementations of `BooleanExpr`, typically including but not limited to:
+        implementations of `BooleanExpression`, typically including but not limited to:
             - field comparators: `eq`, `lt` (less than), `gt` (greater than), etc.
             - logical operators: `And`, `Or`, `Not`, etc.
             - advanced functions: `regex_matches`, `array_contains`, etc.
@@ -251,7 +252,7 @@ def where(self, condition: BooleanExpr) -> "_BasePipeline":
 
 
         Args:
-            condition: The `BooleanExpr` to apply.
+            condition: The `BooleanExpression` to apply.
 
         Returns:
             A new Pipeline object with this stage appended to the stage list
@@ -260,7 +261,7 @@ def where(self, condition: BooleanExpr) -> "_BasePipeline":
 
     def find_nearest(
         self,
-        field: str | Expr,
+        field: str | Expression,
         vector: Sequence[float] | "Vector",
         distance_measure: "DistanceMeasure",
         options: stages.FindNearestOptions | None = None,
@@ -297,7 +298,7 @@ def find_nearest(
             ... )
 
         Args:
-            field: The name of the field (str) or an expression (`Expr`) that
+            field: The name of the field (str) or an expression (`Expression`) that
                    evaluates to the vector data. This field should store vector values.
             vector: The target vector (sequence of floats or `Vector` object) to
                     compare against.
@@ -457,28 +458,29 @@ def unnest(
         """
         return self._append(stages.Unnest(field, alias, options))
 
-    def generic_stage(self, name: str, *params: Expr) -> "_BasePipeline":
+    def raw_stage(self, name: str, *params: Expression) -> "_BasePipeline":
         """
-        Adds a generic, named stage to the pipeline with specified parameters.
+        Adds a stage to the pipeline by specifying the stage name as an argument. This does not offer any
+        type safety on the stage params and requires the caller to know the order (and optionally names)
+        of parameters accepted by the stage.
 
-        This method provides a flexible way to extend the pipeline's functionality
-        by adding custom stages. Each generic stage is defined by a unique `name`
-        and a set of `params` that control its behavior.
+        This class provides a way to call stages that are supported by the Firestore backend but that
+        are not implemented in the SDK version being used.
 
         Example:
             >>> # Assume we don't have a built-in "where" stage
             >>> pipeline = client.pipeline().collection("books")
-            >>> pipeline = pipeline.generic_stage("where", [Field.of("published").lt(900)])
+            >>> pipeline = pipeline.raw_stage("where", Field.of("published").lt(900))
             >>> pipeline = pipeline.select("title", "author")
 
         Args:
-            name: The name of the generic stage.
-            *params: A sequence of `Expr` objects representing the parameters for the stage.
+            name: The name of the stage.
+            *params: A sequence of `Expression` objects representing the parameters for the stage.
 
         Returns:
             A new Pipeline object with this stage appended to the stage list
         """
-        return self._append(stages.GenericStage(name, *params))
+        return self._append(stages.RawStage(name, *params))
 
     def offset(self, offset: int) -> "_BasePipeline":
         """
@@ -530,7 +532,7 @@ def limit(self, limit: int) -> "_BasePipeline":
 
     def aggregate(
         self,
-        *accumulators: AliasedAggregate,
+        *accumulators: AliasedExpression[AggregateFunction],
         groups: Sequence[str | Selectable] = (),
     ) -> "_BasePipeline":
         """
@@ -546,7 +548,6 @@ def aggregate(
         - **Groups:** Optionally specify fields (by name or `Selectable`) to group
           the documents by. Aggregations are then performed within each distinct group.
           If no groups are provided, the aggregation is performed over the entire input.
-
         Example:
             >>> from google.cloud.firestore_v1.pipeline_expressions import Field
             >>> pipeline = client.pipeline().collection("books")
@@ -568,8 +569,8 @@ def aggregate(
 
 
         Args:
-            *accumulators: One or more `AliasedAggregate` expressions defining
-                           the aggregations to perform and their output names.
+            *accumulators: One or more expressions defining the aggregations to perform and their
+                           corresponding output names.
             groups: An optional sequence of field names (str) or `Selectable`
                     expressions to group by before aggregating.
 

google/cloud/firestore_v1/base_query.py

@@ -1151,7 +1151,7 @@ def pipeline(self):
         # Filters
         for filter_ in self._field_filters:
             ppl = ppl.where(
-                pipeline_expressions.BooleanExpr._from_query_filter_pb(
+                pipeline_expressions.BooleanExpression._from_query_filter_pb(
                     filter_, self._client
                 )
             )

google/cloud/firestore_v1/pipeline.py

@@ -14,7 +14,7 @@
 
 from __future__ import annotations
 from typing import Iterable, TYPE_CHECKING
-from google.cloud.firestore_v1 import _pipeline_stages as stages
+from google.cloud.firestore_v1 import pipeline_stages as stages
 from google.cloud.firestore_v1.base_pipeline import _BasePipeline
 
 if TYPE_CHECKING:  # pragma: NO COVER