Merge branch 'tomandersen/pipelines' into tomandersen/pipelines-evaluate

# Conflicts:
#	firebase-firestore/api.txt
#	firebase-firestore/src/main/java/com/google/firebase/firestore/Pipeline.kt
#	firebase-firestore/src/main/java/com/google/firebase/firestore/model/Values.kt
#	firebase-firestore/src/main/java/com/google/firebase/firestore/pipeline/expressions.kt
#	firebase-firestore/src/main/java/com/google/firebase/firestore/pipeline/stage.kt

Author: tom-andersen

firebase-firestore/api.txt

@@ -47,7 +47,7 @@
 import com.google.firebase.firestore.pipeline.AggregateFunction;
 import com.google.firebase.firestore.pipeline.AggregateStage;
 import com.google.firebase.firestore.pipeline.Expr;
-import com.google.firebase.firestore.pipeline.Stage;
+import com.google.firebase.firestore.pipeline.RawStage;
 import com.google.firebase.firestore.testutil.IntegrationTestUtil;
 import java.util.Collections;
 import java.util.LinkedHashMap;
@@ -279,15 +279,14 @@ public void groupAndAccumulateResultsGeneric() {
         firestore
             .pipeline()
             .collection(randomCol)
-            .addStage(Stage.ofName("where").withArguments(lt(field("published"), 1984)))
-            .addStage(
-                Stage.ofName("aggregate")
+            .rawStage(RawStage.ofName("where").withArguments(lt(field("published"), 1984)))
+            .rawStage(
+                RawStage.ofName("aggregate")
                     .withArguments(
                         ImmutableMap.of("avgRating", AggregateFunction.avg("rating")),
                         ImmutableMap.of("genre", field("genre"))))
-            .addStage(Stage.ofName("where").withArguments(gt("avgRating", 4.3)))
-            .addStage(
-                Stage.ofName("sort").withArguments(field("avgRating").descending()))
+            .rawStage(RawStage.ofName("where").withArguments(gt("avgRating", 4.3)))
+            .rawStage(RawStage.ofName("sort").withArguments(field("avgRating").descending()))
             .execute();
     assertThat(waitFor(execute).getResults())
         .comparingElementsUsing(DATA_CORRESPONDENCE)

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

@@ -613,40 +613,39 @@ public void testQueriesCanUseArrayContainsAnyFilters() {
     FirebaseFirestore db = collection.firestore;
 
     // Search for "array" to contain [42, 43].
-    Pipeline pipeline = db.pipeline()
-        .convertFrom(collection.whereArrayContainsAny("array", asList(42L, 43L)));
+    Pipeline pipeline =
+        db.pipeline().convertFrom(collection.whereArrayContainsAny("array", asList(42L, 43L)));
     PipelineSnapshot snapshot = waitFor(pipeline.execute());
     assertEquals(asList(docA, docB, docD, docE), pipelineSnapshotToValues(snapshot));
 
     // With objects.
-    pipeline = db.pipeline()
-        .convertFrom(collection.whereArrayContainsAny("array", asList(map("a", 42L))));
+    pipeline =
+        db.pipeline().convertFrom(collection.whereArrayContainsAny("array", asList(map("a", 42L))));
     snapshot = waitFor(pipeline.execute());
     assertEquals(asList(docF), pipelineSnapshotToValues(snapshot));
 
     // With null.
-    pipeline = db.pipeline()
-        .convertFrom(collection.whereArrayContainsAny("array", nullList()));
+    pipeline = db.pipeline().convertFrom(collection.whereArrayContainsAny("array", nullList()));
     snapshot = waitFor(pipeline.execute());
     assertEquals(new ArrayList<>(), pipelineSnapshotToValues(snapshot));
 
     // With null and a value.
     List<Object> inputList = nullList();
     inputList.add(43L);
-    pipeline = db.pipeline()
-        .convertFrom(collection.whereArrayContainsAny("array", inputList));
+    pipeline = db.pipeline().convertFrom(collection.whereArrayContainsAny("array", inputList));
     snapshot = waitFor(pipeline.execute());
     assertEquals(asList(docE), pipelineSnapshotToValues(snapshot));
 
     // With NaN.
-    pipeline = db.pipeline()
-        .convertFrom(collection.whereArrayContainsAny("array", asList(Double.NaN)));
+    pipeline =
+        db.pipeline().convertFrom(collection.whereArrayContainsAny("array", asList(Double.NaN)));
     snapshot = waitFor(pipeline.execute());
     assertEquals(new ArrayList<>(), pipelineSnapshotToValues(snapshot));
 
     // With NaN and a value.
-    pipeline = db.pipeline()
-        .convertFrom(collection.whereArrayContainsAny("array", asList(Double.NaN, 43L)));
+    pipeline =
+        db.pipeline()
+            .convertFrom(collection.whereArrayContainsAny("array", asList(Double.NaN, 43L)));
     snapshot = waitFor(pipeline.execute());
     assertEquals(asList(docE), pipelineSnapshotToValues(snapshot));
   }

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

@@ -575,7 +575,7 @@ public static void checkQueryAndPipelineResultsMatch(Query query, String... expe
     }
     PipelineSnapshot docsFromPipeline;
     try {
-        docsFromPipeline = waitFor(query.getFirestore().pipeline().convertFrom(query).execute());
+      docsFromPipeline = waitFor(query.getFirestore().pipeline().convertFrom(query).execute());
     } catch (Exception e) {
       throw new RuntimeException("Pipeline FAILED", e);
     }

firebase-firestore/src/androidTest/java/com/google/firebase/firestore/testutil/IntegrationTestUtil.java

@@ -51,6 +51,7 @@ import com.google.firebase.firestore.pipeline.SampleStage
 import com.google.firebase.firestore.pipeline.SelectStage
 import com.google.firebase.firestore.pipeline.Selectable
 import com.google.firebase.firestore.pipeline.SortStage
+import com.google.firebase.firestore.pipeline.Stage
 import com.google.firebase.firestore.pipeline.UnionStage
 import com.google.firebase.firestore.pipeline.UnnestStage
 import com.google.firebase.firestore.pipeline.WhereStage
@@ -62,7 +63,7 @@ open class AbstractPipeline
 internal constructor(
   internal val firestore: FirebaseFirestore,
   internal val userDataReader: UserDataReader,
-  internal val stages: FluentIterable<BaseStage<*>>
+  internal val stages: FluentIterable<Stage<*>>
 ) {
   private fun toStructuredPipelineProto(options: InternalOptions?): StructuredPipeline {
     val builder = StructuredPipeline.newBuilder()
@@ -136,10 +137,10 @@ private constructor(
   internal constructor(
     firestore: FirebaseFirestore,
     userDataReader: UserDataReader,
-    stage: BaseStage<*>
+    stage: Stage<*>
   ) : this(firestore, userDataReader, FluentIterable.of(stage))
 
-  private fun append(stage: BaseStage<*>): Pipeline {
+  private fun append(stage: Stage<*>): Pipeline {
     return Pipeline(firestore, userDataReader, stages.append(stage))
   }
 
@@ -152,17 +153,17 @@ private constructor(
   }
 
   /**
-   * 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.
+   * Adds a raw 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 way to call stages that are supported by the Firestore backend but that
    * are not implemented in the SDK version being used.
    *
    * @param rawStage An [RawStage] object that specifies stage name and parameters.
    * @return A new [Pipeline] object with this stage appended to the stage list.
    */
-  fun addStage(rawStage: RawStage): Pipeline = append(rawStage)
+  fun rawStage(rawStage: RawStage): Pipeline = append(rawStage)
 
   /**
    * Adds new fields to outputs from previous stages.

firebase-firestore/src/main/java/com/google/firebase/firestore/Pipeline.kt

@@ -20,7 +20,6 @@
 import static com.google.firebase.firestore.util.Assert.hardAssert;
 
 import androidx.annotation.NonNull;
-
 import com.google.firebase.firestore.model.Document;
 import com.google.firebase.firestore.model.FieldPath;
 import com.google.firebase.firestore.model.Values;
@@ -29,7 +28,6 @@
 import com.google.firebase.firestore.pipeline.Field;
 import com.google.firebase.firestore.util.Assert;
 import com.google.firestore.v1.Value;
-
 import java.util.ArrayList;
 import java.util.Arrays;
 import java.util.Collections;
@@ -219,14 +217,16 @@ BooleanExpr toPipelineExpr() {
         return and(exists, x.arrayContainsAny(value.getArrayValue().getValuesList()));
       case IN:
         return and(exists, x.eqAny(value.getArrayValue().getValuesList()));
-      case NOT_IN: {
-        List<Value> list = value.getArrayValue().getValuesList();
-        if (hasNaN(list)) {
-          return and(exists, x.notEqAny(filterNaN(list)), ifError(x.isNotNan(), Expr.constant(true)));
-        } else {
-          return and(exists, x.notEqAny(list));
+      case NOT_IN:
+        {
+          List<Value> list = value.getArrayValue().getValuesList();
+          if (hasNaN(list)) {
+            return and(
+                exists, x.notEqAny(filterNaN(list)), ifError(x.isNotNan(), Expr.constant(true)));
+          } else {
+            return and(exists, x.notEqAny(list));
+          }
         }
-      }
       default:
         // Handle OPERATOR_UNSPECIFIED and UNRECOGNIZED cases as needed
         throw new IllegalArgumentException("Unsupported operator: " + operator);

firebase-firestore/src/main/java/com/google/firebase/firestore/core/FieldFilter.java

@@ -37,7 +37,7 @@
 import com.google.firebase.firestore.pipeline.FunctionExpr;
 import com.google.firebase.firestore.pipeline.InternalOptions;
 import com.google.firebase.firestore.pipeline.Ordering;
-import com.google.firebase.firestore.pipeline.BaseStage;
+import com.google.firebase.firestore.pipeline.Stage;
 import com.google.firebase.firestore.util.BiFunction;
 import com.google.firebase.firestore.util.Function;
 import com.google.firebase.firestore.util.IntFunction;
@@ -549,7 +549,8 @@ public Pipeline toPipeline(FirebaseFirestore firestore, UserDataReader userDataR
     if (fields.size() == 1) {
       p = p.where(fields.get(0).exists());
     } else {
-      BooleanExpr[] conditions = skipFirstToArray(fields, BooleanExpr[]::new, Expr.Companion::exists);
+      BooleanExpr[] conditions =
+          skipFirstToArray(fields, BooleanExpr[]::new, Expr.Companion::exists);
       p = p.where(and(fields.get(0).exists(), conditions));
     }
 
@@ -587,17 +588,18 @@ private static <T> T[] skipFirstToArray(List<T> list, IntFunction<T[]> generator
     int size = list.size();
     T[] result = generator.apply(size - 1);
     for (int i = 1; i < size; i++) {
-      result[i-1] = list.get(i);
+      result[i - 1] = list.get(i);
     }
     return result;
   }
 
   // Many Pipelines require first parameter to be separated out from rest.
-  private static <T, R> R[] skipFirstToArray(List<T> list, IntFunction<R[]> generator, Function<T, R> map) {
+  private static <T, R> R[] skipFirstToArray(
+      List<T> list, IntFunction<R[]> generator, Function<T, R> map) {
     int size = list.size();
     R[] result = generator.apply(size - 1);
     for (int i = 1; i < size; i++) {
-      result[i-1] = map.apply(list.get(i));
+      result[i - 1] = map.apply(list.get(i));
     }
     return result;
   }
@@ -621,7 +623,7 @@ private static BooleanExpr whereConditionsFromCursor(
   }
 
   @NonNull
-  private BaseStage<?> pipelineSource(FirebaseFirestore firestore) {
+  private Stage<?> pipelineSource(FirebaseFirestore firestore) {
     if (isDocumentQuery()) {
       return new DocumentsSource(path.canonicalString());
     } else if (isCollectionGroupQuery()) {

firebase-firestore/src/main/java/com/google/firebase/firestore/core/Query.java

@@ -679,8 +679,7 @@ internal object Values {
   fun encodeValue(timestamp: com.google.firebase.Timestamp): Value =
     encodeValue(timestamp(timestamp.seconds, timestamp.nanoseconds))
 
-  @JvmStatic
-  fun encodeValue(value: Timestamp): Value = Value.newBuilder().setTimestampValue(value).build()
+  @JvmStatic fun encodeValue(value: Timestamp): Value = Value.newBuilder().setTimestampValue(value).build()
 
   @JvmField val TRUE_VALUE: Value = Value.newBuilder().setBooleanValue(true).build()
 

firebase-firestore/src/main/java/com/google/firebase/firestore/model/Values.kt

@@ -798,8 +798,7 @@ abstract class Expr internal constructor() {
      * @param second Numeric expression to add.
      * @return A new [Expr] representing the addition operation.
      */
-    @JvmStatic
-    fun add(first: Expr, second: Expr): Expr = FunctionExpr("add", evaluateAdd, first, second)
+    @JvmStatic fun add(first: Expr, second: Expr): Expr = FunctionExpr("add", evaluateAdd, first, second)
 
     /**
      * Creates an expression that adds numeric expressions with a constant.
@@ -808,8 +807,7 @@ abstract class Expr internal constructor() {
      * @param second Constant to add.
      * @return A new [Expr] representing the addition operation.
      */
-    @JvmStatic
-    fun add(first: Expr, second: Number): Expr = FunctionExpr("add", evaluateAdd, first, second)
+    @JvmStatic fun add(first: Expr, second: Number): Expr = FunctionExpr("add", evaluateAdd, first, second)
 
     /**
      * Creates an expression that adds a numeric field with a numeric expression.
@@ -885,8 +883,7 @@ abstract class Expr internal constructor() {
      * @return A new [Expr] representing the multiplication operation.
      */
     @JvmStatic
-    fun multiply(first: Expr, second: Expr): Expr =
-      FunctionExpr("multiply", evaluateMultiply, first, second)
+    fun multiply(first: Expr, second: Expr): Expr = FunctionExpr("multiply", evaluateMultiply, first, second)
 
     /**
      * Creates an expression that multiplies numeric expressions with a constant.
@@ -896,8 +893,7 @@ abstract class Expr internal constructor() {
      * @return A new [Expr] representing the multiplication operation.
      */
     @JvmStatic
-    fun multiply(first: Expr, second: Number): Expr =
-      FunctionExpr("multiply", evaluateMultiply, first, second)
+    fun multiply(first: Expr, second: Number): Expr = FunctionExpr("multiply", evaluateMultiply, first, second)
 
     /**
      * Creates an expression that multiplies a numeric field with a numeric expression.
@@ -1858,6 +1854,28 @@ abstract class Expr internal constructor() {
     fun mapGet(fieldName: String, keyExpression: Expr): Expr =
       FunctionExpr("map_get", evaluateMapGet, fieldName, keyExpression)
 
+    /**
+     * Accesses a value from a map (object) field using the provided [keyExpression].
+     *
+     * @param mapExpression The expression representing the map.
+     * @param keyExpression The key to access in the map.
+     * @return A new [Expr] representing the value associated with the given key in the map.
+     */
+    @JvmStatic
+    fun mapGet(mapExpression: Expr, keyExpression: Expr): Expr =
+      FunctionExpr("map_get", mapExpression, keyExpression)
+
+    /**
+     * Accesses a value from a map (object) field using the provided [keyExpression].
+     *
+     * @param fieldName The field name of the map field.
+     * @param keyExpression The key to access in the map.
+     * @return A new [Expr] representing the value associated with the given key in the map.
+     */
+    @JvmStatic
+    fun mapGet(fieldName: String, keyExpression: Expr): Expr =
+      FunctionExpr("map_get", fieldName, keyExpression)
+
     /**
      * Creates an expression that merges multiple maps into a single map. If multiple maps have the
      * same key, the later value is used.
@@ -2659,6 +2677,25 @@ abstract class Expr internal constructor() {
     fun array(elements: List<Any?>): Expr =
       FunctionExpr("array", evaluateArray, elements.map(::toExprOrConstant).toTypedArray())
 
+    /**
+     * Creates an expression that creates a Firestore array value from an input array.
+     *
+     * @param elements The input array to evaluate in the expression.
+     * @return A new [Expr] representing the array function.
+     */
+    @JvmStatic
+    fun array(vararg elements: Any?): Expr =
+      FunctionExpr("array", elements.map(::toExprOrConstant).toTypedArray<Expr>())
+
+    /**
+     * Creates an expression that creates a Firestore array value from an input array.
+     *
+     * @param elements The input array to evaluate in the expression.
+     * @return A new [Expr] representing the array function.
+     */
+    @JvmStatic
+    fun array(elements: List<Any?>): Expr =
+      FunctionExpr("array", elements.map(::toExprOrConstant).toTypedArray())
     /**
      * Creates an expression that concatenates an array with other arrays.
      *