1. Add code samples to comments

2. Updated Null/Nan semantics for online execution
3. Validate for duplicated aliases
4. Add new functions

Author: wu-hui

firebase-firestore/api.txt

@@ -400,12 +400,8 @@ public void testCannotPerformMoreThanMaxAggregations() {
 
     assertThat(e, instanceOf(FirebaseFirestoreException.class));
     FirebaseFirestoreException firestoreException = (FirebaseFirestoreException) e;
-    if (isRunningAgainstEmulator()) {
-      assertEquals(FirebaseFirestoreException.Code.UNKNOWN, firestoreException.getCode());
-    } else {
-      assertEquals(FirebaseFirestoreException.Code.INVALID_ARGUMENT, firestoreException.getCode());
-      assertTrue(firestoreException.getMessage().contains("maximum number of aggregations"));
-    }
+    assertEquals(FirebaseFirestoreException.Code.INVALID_ARGUMENT, firestoreException.getCode());
+    assertTrue(firestoreException.getMessage().contains("maximum number of aggregations"));
   }
 
   @Test

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

@@ -38,8 +38,8 @@
 import com.google.firebase.firestore.FirebaseFirestoreSettings;
 import com.google.firebase.firestore.ListenerRegistration;
 import com.google.firebase.firestore.MetadataChanges;
+import com.google.firebase.firestore.Pipeline;
 import com.google.firebase.firestore.PipelineResult;
-import com.google.firebase.firestore.PipelineSnapshot;
 import com.google.firebase.firestore.Query;
 import com.google.firebase.firestore.QuerySnapshot;
 import com.google.firebase.firestore.Source;
@@ -468,7 +468,7 @@ public static List<Map<String, Object>> querySnapshotToValues(QuerySnapshot quer
   }
 
   public static List<Map<String, Object>> pipelineSnapshotToValues(
-      PipelineSnapshot pipelineSnapshot) {
+      Pipeline.Snapshot pipelineSnapshot) {
     List<Map<String, Object>> res = new ArrayList<>();
     for (PipelineResult result : pipelineSnapshot) {
       res.add(result.getData());
@@ -484,7 +484,7 @@ public static List<String> querySnapshotToIds(QuerySnapshot querySnapshot) {
     return res;
   }
 
-  public static List<String> pipelineSnapshotToIds(PipelineSnapshot pipelineResults) {
+  public static List<String> pipelineSnapshotToIds(Pipeline.Snapshot pipelineResults) {
     List<String> res = new ArrayList<>();
     for (PipelineResult result : pipelineResults) {
       DocumentReference ref = result.getRef();
@@ -597,7 +597,7 @@ public static void checkQueryAndPipelineResultsMatch(Query query, String... expe
     } catch (Exception e) {
       throw new RuntimeException("Classic Query FAILED", e);
     }
-    PipelineSnapshot docsFromPipeline;
+    Pipeline.Snapshot docsFromPipeline;
     try {
       docsFromPipeline = waitFor(query.getFirestore().pipeline().createFrom(query).execute());
     } catch (Exception e) {

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

@@ -14,7 +14,7 @@
 
 package com.google.firebase.firestore;
 
-import static com.google.firebase.firestore.pipeline.Expr.field;
+import static com.google.firebase.firestore.pipeline.Expression.field;
 
 import androidx.annotation.NonNull;
 import androidx.annotation.Nullable;
@@ -232,7 +232,7 @@ private AverageAggregateField(@NonNull FieldPath fieldPath) {
     @NonNull
     @Override
     AliasedAggregate toPipeline() {
-      return field(getFieldPath()).avg().alias(getAlias());
+      return field(getFieldPath()).average().alias(getAlias());
     }
   }
 }

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

@@ -885,13 +885,33 @@ static void setClientLanguage(@NonNull String languageToken) {
   }
 
   /**
-   * Builds a new Pipeline from this Firestore instance.
-   *
-   * NOTE: Pipeline does not have realtime updates support and SDK cache access, it completely relies
-   * on the connection to the server for the results, and does not augment the results with the SDK
-   * cache. To get realtime updates and SDK cache access use {@code realTimePipeline()} instead.
-   *
-   * @return {@code PipelineSource} for this Firestore instance.
+   * Creates a new {@link PipelineSource} to build and execute a data pipeline.
+   *
+   * <p>A pipeline is composed of a sequence of stages. Each stage processes the
+   * output from the previous one, and the final stage's output is the result of the
+   * pipeline's execution.
+   *
+   * <p><b>Example usage:</b>
+   * <pre>{@code
+   * Pipeline pipeline = firestore.pipeline()
+   * .collection("books")
+   * .where(Field("rating").isGreaterThan(4.5))
+   * .sort(Field("rating").descending())
+   * .limit(2);
+   * }</pre>
+   *
+   * <p><b>Note on Execution:</b> The stages are conceptual. The Firestore backend may
+   * optimize execution (e.g., reordering or merging stages) as long as the
+   * final result remains the same.
+   *
+   * <p><b>Important Limitations:</b>
+   * <ul>
+   * <li>Pipelines operate on a <b>request/response basis only</b>.
+   * <li>They do <b>not</b> utilize or update the local SDK cache.
+   * <li>They do <b>not</b> support realtime snapshot listeners.
+   * </ul>
+   *
+   * @return A {@code PipelineSource} to begin defining the pipeline's stages.
    */
   @NonNull
   public PipelineSource pipeline() {