feat: Add subquery support in pipeline (#7736)

## Summary
This PR implements the Query Pipeline Subquery API in the Android SDK,
enabling complex data retrieval patterns including joins, aggregations
on related collections, and value binding.

## New API

### Pipeline
- **`define(aliasedExpression: AliasedExpression, ...)`**: Defines one
or more variables in the pipeline's scope for internal reuse.
- **`define(stage: DefineStage)`**: Overload for defining variables
using a `DefineStage` object.
- **`toScalarExpression()`**: Converts the pipeline into an expression
that evaluates to a single scalar result.
- **`toArrayExpression()`**: Converts the pipeline into an expression
that evaluates to an array of results.
- **[subcollection(path:
String)](cci:1://file:///Users/cheryllin/Desktop/firebase-sdk/firebase-android-sdk/firebase-firestore/src/main/java/com/google/firebase/firestore/Pipeline.kt:1132:4-1151:5)**:
Initializes a pipeline scoped to a subcollection for use in subqueries.
- **[subcollection(source:
SubcollectionSource)](cci:1://file:///Users/cheryllin/Desktop/firebase-sdk/firebase-android-sdk/firebase-firestore/src/main/java/com/google/firebase/firestore/Pipeline.kt:1132:4-1151:5)**:
Overload for creating subcollection pipelines with a specific source.

### Expression
- **[variable(name:
String)](cci:1://file:///Users/cheryllin/Desktop/firebase-sdk/firebase-android-sdk/firebase-firestore/src/main/java/com/google/firebase/firestore/pipeline/expressions.kt:5332:4-5346:70)**:
Creates an expression that refers to a variable defined in the pipeline
scope.
-
**[currentDocument()](cci:1://file:///Users/cheryllin/Desktop/firebase-sdk/firebase-android-sdk/firebase-firestore/src/main/java/com/google/firebase/firestore/pipeline/expressions.kt:5348:4-5363:94)**:
Creates an expression that refers to the current document being
processed.

## Implementation Details
- `toScalarExpression` and `toArrayExpression` handle the execution of
sub-pipelines and format the results based on the output structure
(unwrapping single fields or returning maps for multiple fields).
- Validations are added to ensure relative subcollection pipelines are
used correctly within a parent context.

---------

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

Author: cherylEnkidu

firebase-firestore/CHANGELOG.md

@@ -1,6 +1,8 @@
 # Unreleased
 
 - [feature] Pipeline operations are GA now.
+- [feature] Added support for Pipeline Subqueries, including `define` and `variable` expressions.
+  [#7736](https://github.com/firebase/firebase-android-sdk/pull/7736)
 - [feature] Added support for Pipeline expressions `nor` and `switchOn`.
   [#7903](https://github.com/firebase/firebase-android-sdk/pull/7903)
 - [feature] Added support for `first`, `last`, `arrayAgg`, and `arrayAggDistinct` Pipeline expressions.

firebase-firestore/api.txt

@@ -424,6 +424,7 @@ package com.google.firebase.firestore {
     method public com.google.firebase.firestore.Pipeline aggregate(com.google.firebase.firestore.pipeline.AggregateStage aggregateStage);
     method public com.google.firebase.firestore.Pipeline aggregate(com.google.firebase.firestore.pipeline.AggregateStage aggregateStage, com.google.firebase.firestore.pipeline.AggregateOptions options);
     method public com.google.firebase.firestore.Pipeline aggregate(com.google.firebase.firestore.pipeline.AliasedAggregate accumulator, com.google.firebase.firestore.pipeline.AliasedAggregate... additionalAccumulators);
+    method public com.google.firebase.firestore.Pipeline define(com.google.firebase.firestore.pipeline.AliasedExpression aliasedExpression, com.google.firebase.firestore.pipeline.AliasedExpression... additionalExpressions);
     method public com.google.firebase.firestore.Pipeline distinct(com.google.firebase.firestore.pipeline.Selectable group, java.lang.Object... additionalGroups);
     method public com.google.firebase.firestore.Pipeline distinct(String groupField, java.lang.Object... additionalGroups);
     method public com.google.android.gms.tasks.Task<com.google.firebase.firestore.Pipeline.Snapshot> execute();
@@ -443,6 +444,8 @@ package com.google.firebase.firestore {
     method public com.google.firebase.firestore.Pipeline select(com.google.firebase.firestore.pipeline.Selectable selection, java.lang.Object... additionalSelections);
     method public com.google.firebase.firestore.Pipeline select(String fieldName, java.lang.Object... additionalSelections);
     method public com.google.firebase.firestore.Pipeline sort(com.google.firebase.firestore.pipeline.Ordering order, com.google.firebase.firestore.pipeline.Ordering... additionalOrders);
+    method public com.google.firebase.firestore.pipeline.Expression toArrayExpression();
+    method public com.google.firebase.firestore.pipeline.Expression toScalarExpression();
     method public com.google.firebase.firestore.Pipeline union(com.google.firebase.firestore.Pipeline other);
     method public com.google.firebase.firestore.Pipeline unnest(com.google.firebase.firestore.pipeline.Selectable arrayWithAlias);
     method public com.google.firebase.firestore.Pipeline unnest(com.google.firebase.firestore.pipeline.Selectable arrayWithAlias, com.google.firebase.firestore.pipeline.UnnestOptions options);
@@ -496,6 +499,14 @@ package com.google.firebase.firestore {
     method public com.google.firebase.firestore.Pipeline database();
     method public com.google.firebase.firestore.Pipeline documents(com.google.firebase.firestore.DocumentReference... documents);
     method public com.google.firebase.firestore.Pipeline documents(java.lang.String... documents);
+    method public static com.google.firebase.firestore.Pipeline subcollection(com.google.firebase.firestore.pipeline.SubcollectionSource source);
+    method public static com.google.firebase.firestore.Pipeline subcollection(String path);
+    field public static final com.google.firebase.firestore.PipelineSource.Companion Companion;
+  }
+
+  public static final class PipelineSource.Companion {
+    method public com.google.firebase.firestore.Pipeline subcollection(com.google.firebase.firestore.pipeline.SubcollectionSource source);
+    method public com.google.firebase.firestore.Pipeline subcollection(String path);
   }
 
   @java.lang.annotation.Retention(java.lang.annotation.RetentionPolicy.RUNTIME) @java.lang.annotation.Target({java.lang.annotation.ElementType.METHOD, java.lang.annotation.ElementType.FIELD}) public @interface PropertyName {
@@ -973,6 +984,7 @@ package com.google.firebase.firestore.pipeline {
     method public static final com.google.firebase.firestore.pipeline.Expression cosineDistance(String vectorFieldName, double[] vector);
     method public final com.google.firebase.firestore.pipeline.AggregateFunction count();
     method public final com.google.firebase.firestore.pipeline.AggregateFunction countDistinct();
+    method public static final com.google.firebase.firestore.pipeline.Expression currentDocument();
     method public static final com.google.firebase.firestore.pipeline.Expression currentTimestamp();
     method public final com.google.firebase.firestore.pipeline.Ordering descending();
     method public final com.google.firebase.firestore.pipeline.Expression divide(com.google.firebase.firestore.pipeline.Expression divisor);
@@ -1033,6 +1045,12 @@ package com.google.firebase.firestore.pipeline {
     method public final com.google.firebase.firestore.pipeline.Expression floor();
     method public static final com.google.firebase.firestore.pipeline.Expression floor(com.google.firebase.firestore.pipeline.Expression numericExpr);
     method public static final com.google.firebase.firestore.pipeline.Expression floor(String numericField);
+    method public final com.google.firebase.firestore.pipeline.Expression getField(com.google.firebase.firestore.pipeline.Expression keyExpression);
+    method public static final com.google.firebase.firestore.pipeline.Expression getField(com.google.firebase.firestore.pipeline.Expression expression, com.google.firebase.firestore.pipeline.Expression keyExpression);
+    method public static final com.google.firebase.firestore.pipeline.Expression getField(com.google.firebase.firestore.pipeline.Expression expression, String key);
+    method public final com.google.firebase.firestore.pipeline.Expression getField(String key);
+    method public static final com.google.firebase.firestore.pipeline.Expression getField(String fieldName, com.google.firebase.firestore.pipeline.Expression keyExpression);
+    method public static final com.google.firebase.firestore.pipeline.Expression getField(String fieldName, String key);
     method public final com.google.firebase.firestore.pipeline.BooleanExpression greaterThan(com.google.firebase.firestore.pipeline.Expression other);
     method public static final com.google.firebase.firestore.pipeline.BooleanExpression greaterThan(com.google.firebase.firestore.pipeline.Expression left, com.google.firebase.firestore.pipeline.Expression right);
     method public static final com.google.firebase.firestore.pipeline.BooleanExpression greaterThan(com.google.firebase.firestore.pipeline.Expression left, Object right);
@@ -1304,6 +1322,7 @@ package com.google.firebase.firestore.pipeline {
     method public final com.google.firebase.firestore.pipeline.Expression unixSecondsToTimestamp();
     method public static final com.google.firebase.firestore.pipeline.Expression unixSecondsToTimestamp(com.google.firebase.firestore.pipeline.Expression expr);
     method public static final com.google.firebase.firestore.pipeline.Expression unixSecondsToTimestamp(String fieldName);
+    method public static final com.google.firebase.firestore.pipeline.Expression variable(String name);
     method public static final com.google.firebase.firestore.pipeline.Expression vector(com.google.firebase.firestore.VectorValue vector);
     method public static final com.google.firebase.firestore.pipeline.Expression vector(double[] vector);
     method public final com.google.firebase.firestore.pipeline.Expression vectorLength();
@@ -1431,6 +1450,7 @@ package com.google.firebase.firestore.pipeline {
     method public com.google.firebase.firestore.pipeline.Expression cosineDistance(String vectorFieldName, com.google.firebase.firestore.pipeline.Expression vector);
     method public com.google.firebase.firestore.pipeline.Expression cosineDistance(String vectorFieldName, com.google.firebase.firestore.VectorValue vector);
     method public com.google.firebase.firestore.pipeline.Expression cosineDistance(String vectorFieldName, double[] vector);
+    method public com.google.firebase.firestore.pipeline.Expression currentDocument();
     method public com.google.firebase.firestore.pipeline.Expression currentTimestamp();
     method public com.google.firebase.firestore.pipeline.Expression divide(com.google.firebase.firestore.pipeline.Expression dividend, com.google.firebase.firestore.pipeline.Expression divisor);
     method public com.google.firebase.firestore.pipeline.Expression divide(com.google.firebase.firestore.pipeline.Expression dividend, Number divisor);
@@ -1471,6 +1491,10 @@ package com.google.firebase.firestore.pipeline {
     method public com.google.firebase.firestore.pipeline.Field field(String name);
     method public com.google.firebase.firestore.pipeline.Expression floor(com.google.firebase.firestore.pipeline.Expression numericExpr);
     method public com.google.firebase.firestore.pipeline.Expression floor(String numericField);
+    method public com.google.firebase.firestore.pipeline.Expression getField(com.google.firebase.firestore.pipeline.Expression expression, com.google.firebase.firestore.pipeline.Expression keyExpression);
+    method public com.google.firebase.firestore.pipeline.Expression getField(com.google.firebase.firestore.pipeline.Expression expression, String key);
+    method public com.google.firebase.firestore.pipeline.Expression getField(String fieldName, com.google.firebase.firestore.pipeline.Expression keyExpression);
+    method public com.google.firebase.firestore.pipeline.Expression getField(String fieldName, String key);
     method public com.google.firebase.firestore.pipeline.BooleanExpression greaterThan(com.google.firebase.firestore.pipeline.Expression left, com.google.firebase.firestore.pipeline.Expression right);
     method public com.google.firebase.firestore.pipeline.BooleanExpression greaterThan(com.google.firebase.firestore.pipeline.Expression left, Object right);
     method public com.google.firebase.firestore.pipeline.BooleanExpression greaterThan(String fieldName, com.google.firebase.firestore.pipeline.Expression expression);
@@ -1653,6 +1677,7 @@ package com.google.firebase.firestore.pipeline {
     method public com.google.firebase.firestore.pipeline.Expression unixMillisToTimestamp(String fieldName);
     method public com.google.firebase.firestore.pipeline.Expression unixSecondsToTimestamp(com.google.firebase.firestore.pipeline.Expression expr);
     method public com.google.firebase.firestore.pipeline.Expression unixSecondsToTimestamp(String fieldName);
+    method public com.google.firebase.firestore.pipeline.Expression variable(String name);
     method public com.google.firebase.firestore.pipeline.Expression vector(com.google.firebase.firestore.VectorValue vector);
     method public com.google.firebase.firestore.pipeline.Expression vector(double[] vector);
     method public com.google.firebase.firestore.pipeline.Expression vectorLength(com.google.firebase.firestore.pipeline.Expression vectorExpression);
@@ -1773,6 +1798,15 @@ package com.google.firebase.firestore.pipeline {
     method public final T withOption(String key, long value);
   }
 
+  public final class SubcollectionSource extends com.google.firebase.firestore.pipeline.Stage<com.google.firebase.firestore.pipeline.SubcollectionSource> {
+    method public static com.google.firebase.firestore.pipeline.SubcollectionSource of(String path);
+    field public static final com.google.firebase.firestore.pipeline.SubcollectionSource.Companion Companion;
+  }
+
+  public static final class SubcollectionSource.Companion {
+    method public com.google.firebase.firestore.pipeline.SubcollectionSource of(String path);
+  }
+
   public final class UnnestOptions extends com.google.firebase.firestore.pipeline.AbstractOptions<com.google.firebase.firestore.pipeline.UnnestOptions> {
     ctor public UnnestOptions();
     method public com.google.firebase.firestore.pipeline.UnnestOptions withIndexField(String indexField);

firebase-firestore/gradle.properties

@@ -1,2 +1,2 @@
-version=26.1.3
+version=26.2.3
 latestReleasedVersion=26.1.2

firebase-firestore/src/androidTest/java/com/google/firebase/firestore/PipelineTest.java

@@ -144,7 +144,7 @@ public void tearDown() {
     IntegrationTestUtil.tearDown();
   }
 
-  private final Map<String, Map<String, Object>> bookDocs =
+  static final Map<String, Map<String, Object>> bookDocs =
       mapOfEntries(
           entry(
               "book1",