add documentation and overload for getField()

Author: cherylEnkidu

google-cloud-firestore/src/main/java/com/google/cloud/firestore/Pipeline.java

@@ -275,13 +275,32 @@ public static Pipeline subcollection(String path) {
   }
 
   /**
-   * Adds new fields or redefines existing fields in the output documents by
-   * evaluating given expressions.
+   * Defines one or more variables in the pipeline's scope. `define` is used to
+   * bind a value to a
+   * variable for internal reuse within the pipeline body (accessed via the {@link
+   * Expression#variable(String)} function).
    *
    * <p>
-   * This stage is useful for binding a value to a variable for internal reuse
-   * within the pipeline
-   * body (accessed via the {@link Expression#variable(String)} function).
+   * This stage is useful for declaring reusable values or intermediate
+   * calculations that can be
+   * referenced multiple times in later parts of the pipeline, improving
+   * readability and maintainability.
+   *
+   * <p>
+   * Each variable is defined using an {@link AliasedExpression}, which pairs an
+   * expression with a name (alias).
+   *
+   * <p>
+   * Example:
+   *
+   * <pre>{@code
+   * firestore.pipeline().collection("products")
+   *     .define(
+   *         multiply(field("price"), 0.9).as("discountedPrice"),
+   *         add(field("stock"), 10).as("newStock"))
+   *     .where(lessThan(variable("discountedPrice"), 100))
+   *     .select(field("name"), variable("newStock"));
+   * }</pre>
    *
    * @param expression            The expression to define using
    *                              {@link AliasedExpression}.
@@ -312,7 +331,110 @@ public Expression toArrayExpression() {
   }
 
   /**
-   * Converts the pipeline into a scalar expression.
+   * Converts this Pipeline into an expression that evaluates to a single scalar
+   * result. Used for
+   * 1:1 lookups or Aggregations when the subquery is expected to return a single
+   * value or object.
+   *
+   * <p>
+   * <b>Runtime Validation:</b> The runtime will validate that the result set
+   * contains exactly
+   * one item. It throws a runtime error if the result has more than one item, and
+   * evaluates to
+   * {@code null} if the pipeline has zero results.
+   *
+   * <p>
+   * <b>Result Unwrapping:</b> For simpler access, scalar subqueries producing a
+   * single field
+   * automatically unwrap that value to the top level, ignoring the inner alias.
+   * If the subquery
+   * returns multiple fields, they are preserved as a map.
+   *
+   * <p>
+   * <b>Example 1: Single field unwrapping</b>
+   * 
+   * <pre>{@code
+   * // Calculate average rating for each restaurant using a subquery
+   * db.pipeline().collection("restaurants")
+   *     .define(field("id").as("rid"))
+   *     .addFields(
+   *         db.pipeline().collection("reviews")
+   *             .where(field("restaurant_id").equal(variable("rid")))
+   *             // Inner aggregation returns a single document
+   *             .aggregate(AggregateFunction.average("rating").as("value"))
+   *             // Convert Pipeline -> Scalar Expression (validates result is 1 item)
+   *             .toScalarExpression()
+   *             .as("average_rating"))
+   * }</pre>
+   *
+   * <p>
+   * <i>The result set is unwrapped twice: from {@code "average_rating": [{
+   * "value": 4.5 }]}
+   * to {@code "average_rating": { "value": 4.5 }}, and finally to
+   * {@code "average_rating": 4.5}.</i>
+   *
+   * <pre>{@code
+   * // Output Document:
+   * [
+   *   {
+   *     "id": "123",
+   *     "name": "The Burger Joint",
+   *     "cuisine": "American",
+   *     "average_rating": 4.5
+   *   },
+   *   {
+   *     "id": "456",
+   *     "name": "Sushi World",
+   *     "cuisine": "Japanese",
+   *     "average_rating": 4.8
+   *   }
+   * ]
+   * }</pre>
+   *
+   * <p>
+   * <b>Example 2: Multiple fields (Map)</b>
+   * 
+   * <pre>{@code
+   * // For each restaurant, calculate review statistics (average rating AND total
+   * // count)
+   * db.pipeline().collection("restaurants")
+   *     .define(field("id").as("rid"))
+   *     .addFields(
+   *         db.pipeline().collection("reviews")
+   *             .where(field("restaurant_id").equal(variable("rid")))
+   *             .aggregate(
+   *                 AggregateFunction.average("rating").as("avg_score"),
+   *                 AggregateFunction.countAll().as("review_count"))
+   *             .toScalarExpression()
+   *             .as("stats"))
+   * }</pre>
+   *
+   * <p>
+   * <i>When the subquery produces multiple fields, they are wrapped in a map:</i>
+   *
+   * <pre>{@code
+   * // Output Document:
+   * [
+   *   {
+   *     "id": "123",
+   *     "name": "The Burger Joint",
+   *     "cuisine": "American",
+   *     "stats": {
+   *       "avg_score": 4.0,
+   *       "review_count": 3
+   *     }
+   *   },
+   *   {
+   *     "id": "456",
+   *     "name": "Sushi World",
+   *     "cuisine": "Japanese",
+   *     "stats": {
+   *       "avg_score": 4.8,
+   *       "review_count": 120
+   *     }
+   *   }
+   * ]
+   * }</pre>
    *
    * @return A new {@link Expression} representing the pipeline as a scalar.
    */
@@ -1396,8 +1518,7 @@ public void onComplete() {
           }
         };
 
-    // logger.log(Level.FINEST, "Sending pipeline request: " +
-    // request.getStructuredPipeline());
+    logger.log(Level.FINEST, "Sending pipeline request: " + request.getStructuredPipeline());
 
     rpcContext.streamRequest(request, observer, rpcContext.getClient().executePipelineCallable());
   }

google-cloud-firestore/src/main/java/com/google/cloud/firestore/pipeline/expressions/Expression.java

@@ -218,6 +218,7 @@ public static Field field(FieldPath fieldPath) {
     return Field.ofUserPath(fieldPath.toString());
   }
 
+
   /**
    * Creates an expression that returns the current timestamp.
    *
@@ -4810,8 +4811,8 @@ public static Expression currentDocument() {
   }
 
   /**
-   * Creates an expression that retrieves the value of a variable bound via
-   * pipeline definitions.
+   * Creates an expression that retrieves the value of a variable bound via {@link
+   * Pipeline#define(AliasedExpression, AliasedExpression...)}.
    *
    * @param name The name of the variable to retrieve.
    * @return An {@link Expression} representing the variable's value.
@@ -4821,28 +4822,91 @@ public static Expression variable(String name) {
     return new Variable(name);
   }
 
+  /**
+   * Creates an expression that evaluates to the provided pipeline.
+   *
+   * @param pipeline The pipeline to use as an expression.
+   * @return A new {@link Expression} representing the pipeline value.
+   */
+  @InternalApi
+  public static Expression pipeline(Pipeline pipeline) {
+    return new PipelineValueExpression(pipeline);
+  }
+
   /**
    * Accesses a field/property of the expression (useful when the expression
-   * evaluates to a Map or Document).
+   * evaluates to a Map or
+   * Document).
    *
-   * @param expression The expression evaluating to a map/document.
-   * @param key        The key of the field to access.
+   * @param key The key of the field to access.
    * @return An {@link Expression} representing the value of the field.
    */
   @BetaApi
-  public static Expression field(Expression expression, String key) {
-    return new FunctionExpression("field", ImmutableList.of(expression, constant(key)));
+  public Expression getField(String key) {
+    return new FunctionExpression("field", ImmutableList.of(this, constant(key)));
   }
 
   /**
-   * Creates an expression that evaluates to the provided pipeline.
+   * Retrieves the value of a specific field from the document evaluated by this
+   * expression.
    *
-   * @param pipeline The pipeline to use as an expression.
-   * @return A new {@link Expression} representing the pipeline value.
+   * @param keyExpression The expression evaluating to the key to access.
+   * @return A new {@link Expression} representing the field value.
    */
-  @InternalApi
-  public static Expression pipeline(Pipeline pipeline) {
-    return new PipelineValueExpression(pipeline);
+  @BetaApi
+  public Expression getField(Expression keyExpression) {
+    return new FunctionExpression("field", ImmutableList.of(this, keyExpression));
+  }
+
+  /**
+   * Accesses a field/property of a document field using the provided {@code key}.
+   *
+   * @param fieldName The field name of the map or document field.
+   * @param key       The key of the field to access.
+   * @return An {@link Expression} representing the value of the field.
+   */
+  @BetaApi
+  public static Expression getField(String fieldName, String key) {
+    return field(fieldName).getField(key);
+  }
+
+  /**
+   * Accesses a field/property of the expression using the provided
+   * {@code keyExpression}.
+   *
+   * @param expression    The expression evaluating to a Map or Document.
+   * @param keyExpression The expression evaluating to the key.
+   * @return A new {@link Expression} representing the value of the field.
+   */
+  @BetaApi
+  public static Expression getField(Expression expression, Expression keyExpression) {
+    return expression.getField(keyExpression);
+  }
+
+  /**
+   * Accesses a field/property of a document field using the provided
+   * {@code keyExpression}.
+   *
+   * @param fieldName     The field name of the map or document field.
+   * @param keyExpression The expression evaluating to the key.
+   * @return A new {@link Expression} representing the value of the field.
+   */
+  @BetaApi
+  public static Expression getField(String fieldName, Expression keyExpression) {
+    return field(fieldName).getField(keyExpression);
+  }
+
+  /**
+   * Accesses a field/property of the expression (useful when the expression
+   * evaluates to a Map or Document).
+   *
+   * @param expression The expression evaluating to a map/document.
+   * @param key        The key of the field to access.
+   * @return An {@link Expression} representing the value of the field.
+   */
+  @BetaApi
+  public static Expression getField(Expression expression, String key) {
+    return new FunctionExpression("field", ImmutableList.of(expression, constant(key)));
   }
 
   /**

google-cloud-firestore/src/test/java/com/google/cloud/firestore/it/ITPipelineTest.java

@@ -2888,7 +2888,7 @@ public void testSubqueryWithCorrelatedField() throws Exception {
       Pipeline sub = firestore.pipeline().collection(
               collection.document("doc1").collection("some_subcollection").getPath())
               // Using field access on a variable simulating a correlated query
-              .select(com.google.cloud.firestore.pipeline.expressions.Expression.field(
+              .select(com.google.cloud.firestore.pipeline.expressions.Expression.getField(
                       com.google.cloud.firestore.pipeline.expressions.Expression.variable("p"), "a").as("parent_a"));
 
       List<PipelineResult> results = firestore