Merge branch 'main' into pipeline_cursors

Author: daniel-sanche

.librarian/state.yaml

@@ -1,7 +1,7 @@
 image: us-central1-docker.pkg.dev/cloud-sdk-librarian-prod/images-prod/python-librarian-generator@sha256:b8058df4c45e9a6e07f6b4d65b458d0d059241dd34c814f151c8bf6b89211209
 libraries:
   - id: google-cloud-firestore
-    version: 2.22.0
+    version: 2.23.0
     last_generated_commit: 1a9d00bed77e6db82ff67764ffe14e3b5209f5cd
     apis:
       - path: google/firestore/v1

CHANGELOG.md

@@ -4,6 +4,18 @@
 
 [1]: https://pypi.org/project/google-cloud-firestore/#history
 
+## [2.23.0](https://github.com/googleapis/python-firestore/compare/v2.22.0...v2.23.0) (2026-01-14)
+
+
+### Features
+
+* pipelines preview (#1156) ([9462d106dcda516e24a518dbd32a3ee5a39e40ca](https://github.com/googleapis/python-firestore/commit/9462d106dcda516e24a518dbd32a3ee5a39e40ca))
+
+
+### Bug Fixes
+
+* stream generator type (#1148) ([165d367c342cb4205f13cf6d4fcd001419f9e2da](https://github.com/googleapis/python-firestore/commit/165d367c342cb4205f13cf6d4fcd001419f9e2da))
+
 ## [2.22.0](https://github.com/googleapis/python-firestore/compare/v2.21.0...v2.22.0) (2025-12-16)
 
 

google/cloud/firestore/gapic_version.py

@@ -13,4 +13,4 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 #
-__version__ = "2.22.0"  # {x-release-please-version}
+__version__ = "2.23.0"  # {x-release-please-version}

google/cloud/firestore_admin_v1/gapic_version.py

@@ -13,4 +13,4 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 #
-__version__ = "2.22.0"  # {x-release-please-version}
+__version__ = "2.23.0"  # {x-release-please-version}

google/cloud/firestore_bundle/gapic_version.py

@@ -13,4 +13,4 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 #
-__version__ = "2.22.0"  # {x-release-please-version}
+__version__ = "2.23.0"  # {x-release-please-version}

google/cloud/firestore_v1/async_pipeline.py

@@ -11,6 +11,11 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
+"""
+.. warning::
+    **Preview API**: Firestore Pipelines is currently in preview and is
+    subject to potential breaking changes in future releases
+"""
 
 from __future__ import annotations
 from typing import TYPE_CHECKING
@@ -50,6 +55,10 @@ class AsyncPipeline(_BasePipeline):
         ...         print(result)
 
     Use `client.pipeline()` to create instances of this class.
+
+    .. warning::
+        **Preview API**: Firestore Pipelines is currently in preview and is
+        subject to potential breaking changes in future releases
     """
 
     def __init__(self, client: AsyncClient, *stages: stages.Stage):
@@ -68,7 +77,6 @@ async def execute(
         transaction: "AsyncTransaction" | None = None,
         read_time: datetime.datetime | None = None,
         explain_options: PipelineExplainOptions | None = None,
-        index_mode: str | None = None,
         additional_options: dict[str, Value | Constant] = {},
     ) -> PipelineSnapshot[PipelineResult]:
         """
@@ -87,10 +95,8 @@ async def execute(
             explain_options (Optional[:class:`~google.cloud.firestore_v1.query_profile.PipelineExplainOptions`]):
                 Options to enable query profiling for this query. When set,
                 explain_metrics will be available on the returned list.
-            index_mode (Optional[str]): Configures the pipeline to require a certain type of indexes to be present.
-                Firestore will reject the request if there is not appropiate indexes to serve the query.
             additional_options (Optional[dict[str, Value | Constant]]): Additional options to pass to the query.
-                These options will take precedence over method argument if there is a conflict (e.g. explain_options, index_mode)
+                These options will take precedence over method argument if there is a conflict (e.g. explain_options)
         """
         kwargs = {k: v for k, v in locals().items() if k != "self"}
         stream = AsyncPipelineStream(PipelineResult, self, **kwargs)
@@ -103,7 +109,6 @@ def stream(
         read_time: datetime.datetime | None = None,
         transaction: "AsyncTransaction" | None = None,
         explain_options: PipelineExplainOptions | None = None,
-        index_mode: str | None = None,
         additional_options: dict[str, Value | Constant] = {},
     ) -> AsyncPipelineStream[PipelineResult]:
         """
@@ -122,10 +127,8 @@ def stream(
             explain_options (Optional[:class:`~google.cloud.firestore_v1.query_profile.PipelineExplainOptions`]):
                 Options to enable query profiling for this query. When set,
                 explain_metrics will be available on the returned generator.
-            index_mode (Optional[str]): Configures the pipeline to require a certain type of indexes to be present.
-                Firestore will reject the request if there is not appropiate indexes to serve the query.
             additional_options (Optional[dict[str, Value | Constant]]): Additional options to pass to the query.
-                These options will take precedence over method argument if there is a conflict (e.g. explain_options, index_mode)
+                These options will take precedence over method argument if there is a conflict (e.g. explain_options)
         """
         kwargs = {k: v for k, v in locals().items() if k != "self"}
         return AsyncPipelineStream(PipelineResult, self, **kwargs)

google/cloud/firestore_v1/base_aggregation.py

@@ -361,8 +361,12 @@ def _build_pipeline(self, source: "PipelineSource"):
         """
         Convert this query into a Pipeline
 
+        Queries containing a `cursor` or `limit_to_last` are not currently supported
+
         Args:
             source: the PipelineSource to build the pipeline off of
+        Raises:
+            - NotImplementedError: raised if the query contains a `cursor` or `limit_to_last`
         Returns:
             a Pipeline representing the query
         """

google/cloud/firestore_v1/base_collection.py

@@ -608,8 +608,12 @@ def _build_pipeline(self, source: "PipelineSource"):
         """
         Convert this query into a Pipeline
 
+        Queries containing a `cursor` or `limit_to_last` are not currently supported
+
         Args:
             source: the PipelineSource to build the pipeline off o
+        Raises:
+            - NotImplementedError: raised if the query contains a `cursor` or `limit_to_last`
         Returns:
             a Pipeline representing the query
         """

google/cloud/firestore_v1/base_query.py

@@ -1134,8 +1134,12 @@ def _build_pipeline(self, source: "PipelineSource"):
         """
         Convert this query into a Pipeline
 
+        Queries containing a `cursor` or `limit_to_last` are not currently supported
+
         Args:
             source: the PipelineSource to build the pipeline off of
+        Raises:
+            - NotImplementedError: raised if the query contains a `cursor` or `limit_to_last`
         Returns:
             a Pipeline representing the query
         """
@@ -1158,10 +1162,9 @@ def _build_pipeline(self, source: "PipelineSource"):
 
         # Orders
         orders = self._normalize_orders()
-
-        exists = []
-        orderings = []
         if orders:
+            exists = []
+            orderings = []
             for order in orders:
                 field = pipeline_expressions.Field.of(order.field.field_path)
                 exists.append(field.exists())
@@ -1175,59 +1178,23 @@ def _build_pipeline(self, source: "PipelineSource"):
             # Add exists filters to match Query's implicit orderby semantics.
             if len(exists) == 1:
                 ppl = ppl.where(exists[0])
-            elif len(exists) > 1:
+            else:
                 ppl = ppl.where(pipeline_expressions.And(*exists))
 
-        if orderings:
-            # Normalize cursors to get the raw values corresponding to the orders
-            start_at_val = None
-            if self._start_at:
-                start_at_val = self._normalize_cursor(self._start_at, orders)
-
-            end_at_val = None
-            if self._end_at:
-                end_at_val = self._normalize_cursor(self._end_at, orders)
-
-            # If limit_to_last is set, we need to reverse the orderings to find the
-            # "last" N documents (which effectively become the "first" N in reverse order).
-            if self._limit_to_last:
-                actual_orderings = _reverse_orderings(orderings)
-                ppl = ppl.sort(*actual_orderings)
-
-            # Apply cursor conditions.
-            # Cursors are translated into filter conditions (e.g., field > value)
-            # based on the orderings.
-            if start_at_val:
-                ppl = ppl.where(
-                    _where_conditions_from_cursor(
-                        start_at_val, orderings, is_start_cursor=True
-                    )
-                )
-
-            if end_at_val:
-                ppl = ppl.where(
-                    _where_conditions_from_cursor(
-                        end_at_val, orderings, is_start_cursor=False
-                    )
-                )
+            # Add sort orderings
+            ppl = ppl.sort(*orderings)
 
-            if not self._limit_to_last:
-                ppl = ppl.sort(*orderings)
-
-            if self._limit is not None:
+        # Cursors, Limit and Offset
+        if self._start_at or self._end_at or self._limit_to_last:
+            raise NotImplementedError(
+                "Query to Pipeline conversion: cursors and limit_to_last is not supported yet."
+            )
+        else:  # Limit & Offset without cursors
+            if self._offset:
+                ppl = ppl.offset(self._offset)
+            if self._limit:
                 ppl = ppl.limit(self._limit)
 
-            # If we reversed the orderings for limit_to_last, we must now re-sort
-            # using the original orderings to return the results in the user-requested order.
-            if self._limit_to_last:
-                ppl = ppl.sort(*orderings)
-        elif self._limit is not None and not self._limit_to_last:
-            ppl = ppl.limit(self._limit)
-
-        # Offset
-        if self._offset:
-            ppl = ppl.offset(self._offset)
-
         return ppl
 
     def _comparator(self, doc1, doc2) -> int:

google/cloud/firestore_v1/gapic_version.py

@@ -13,4 +13,4 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 #
-__version__ = "2.22.0"  # {x-release-please-version}
+__version__ = "2.23.0"  # {x-release-please-version}