Delete upsert() from Pipeline.java and tests

Author: wu-hui

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

@@ -61,7 +61,6 @@
 import com.google.cloud.firestore.pipeline.stages.Unnest;
 import com.google.cloud.firestore.pipeline.stages.UnnestOptions;
 import com.google.cloud.firestore.pipeline.stages.Update;
-import com.google.cloud.firestore.pipeline.stages.Upsert;
 import com.google.cloud.firestore.pipeline.stages.Where;
 import com.google.cloud.firestore.telemetry.MetricsUtil.MetricsContext;
 import com.google.cloud.firestore.telemetry.TelemetryConstants;
@@ -1002,105 +1001,224 @@ public Pipeline unnest(Selectable field, UnnestOptions options) {
   /**
    * Performs a delete operation on documents from previous stages.
    *
-   * @return A new {@code Pipeline} object with this stage appended to the stage list.
+   * <p>
+   * Example:
+   *
+   * <pre>{@code
+   * // Delete all documents in the "logs" collection where "status" is "archived"
+   * firestore.pipeline()
+   *     .collection("logs")
+   *     .where(field("status").equal("archived"))
+   *     .delete()
+   *     .execute()
+   *     .get();
+   * }</pre>
+   *
+   * @return A new {@code Pipeline} object with this stage appended to the stage
+   *         list.
    */
   @BetaApi
   public Pipeline delete() {
     return append(new Delete());
   }
 
   /**
-   * Performs an upsert operation using documents from previous stages.
+   * Performs an update operation using documents from previous stages.
    *
-   * @return A new {@code Pipeline} object with this stage appended to the stage list.
-   */
-  @BetaApi
-  public Pipeline upsert() {
-    return append(new Upsert());
-  }
-
-  /**
-   * Performs an upsert operation using documents from previous stages.
+   * <p>
+   * This method updates the documents in place based on the data flowing through
+   * the pipeline.
+   * To specify transformations, use {@link #update(Selectable...)}.
    *
-   * @param target The collection to upsert to.
-   * @return A new {@code Pipeline} object with this stage appended to the stage list.
-   */
-  @BetaApi
-  public Pipeline upsert(CollectionReference target) {
-    return append(new Upsert().withCollection(target));
-  }
-
-  /**
-   * Performs an upsert operation using documents from previous stages.
+   * <p>
+   * Example 1: Update a collection's schema by adding a new field and removing
+   * an old one.
    *
-   * @param upsertStage The {@code Upsert} stage to append.
-   * @return A new {@code Pipeline} object with this stage appended to the stage list.
-   */
-  @InternalApi
-  public Pipeline upsert(Upsert upsertStage) {
-    return append(upsertStage);
-  }
-
-  /**
-   * Performs an update operation using documents from previous stages.
+   * <pre>{@code
+   * firestore.pipeline()
+   *     .collection("books")
+   *     .addFields(constant("Fiction").as("genre"))
+   *     .removeFields("old_genre")
+   *     .update()
+   *     .execute()
+   *     .get();
+   * }</pre>
    *
-   * @return A new {@code Pipeline} object with this stage appended to the stage list.
+   * <p>
+   * Example 2: Update documents in place with data from literals.
+   *
+   * <pre>{@code
+   * Map<String, Object> updateData = new HashMap<>();
+   * updateData.put("__name__", firestore.collection("books").document("book1"));
+   * updateData.put("status", "Updated");
+   *
+   * firestore.pipeline()
+   *     .literals(updateData)
+   *     .update()
+   *     .execute()
+   *     .get();
+   * }</pre>
+   *
+   * @return A new {@code Pipeline} object with this stage appended to the stage
+   *         list.
    */
   @BetaApi
   public Pipeline update() {
     return append(new Update());
   }
 
   /**
-   * Performs an update operation using documents from previous stages.
+   * Performs an update operation using documents from previous stages with
+   * specified
+   * transformations.
+   *
+   * <p>
+   * Example:
+   *
+   * <pre>{@code
+   * // Update the "status" field to "Discounted" for all books where price > 50
+   * firestore.pipeline()
+   *     .collection("books")
+   *     .where(field("price").greaterThan(50))
+   *     .update(constant("Discounted").as("status"))
+   *     .execute()
+   *     .get();
+   * }</pre>
    *
    * @param transformations The transformations to apply.
-   * @return A new {@code Pipeline} object with this stage appended to the stage list.
+   * @return A new {@code Pipeline} object with this stage appended to the stage
+   *         list.
    */
   @BetaApi
   public Pipeline update(Selectable... transformations) {
     return append(new Update().withTransformations(transformations));
   }
 
   /**
-   * Performs an update operation using documents from previous stages.
+   * Performs an update operation using an {@link Update} stage.
+   *
+   * <p>
+   * This method allows you to use a pre-configured {@link Update} stage.
+   *
+   * <p>
+   * Example:
+   *
+   * <pre>{@code
+   * Update updateStage = new Update().withTransformations(constant("Updated").as("status"));
+   *
+   * firestore.pipeline()
+   *     .collection("books")
+   *     .where(field("title").equal("The Hitchhiker's Guide to the Galaxy"))
+   *     .update(updateStage)
+   *     .execute()
+   *     .get();
+   * }</pre>
    *
    * @param update The {@code Update} stage to append.
-   * @return A new {@code Pipeline} object with this stage appended to the stage list.
+   * @return A new {@code Pipeline} object with this stage appended to the stage
+   *         list.
    */
-  @InternalApi
+  @BetaApi
   public Pipeline update(Update update) {
     return append(update);
   }
 
   /**
    * Performs an insert operation using documents from previous stages.
    *
-   * @return A new {@code Pipeline} object with this stage appended to the stage list.
+   * <p>
+   * The documents must include a valid {@code __name__} field specifying the
+   * document reference to insert. If the document already exists, the operation
+   * will fail.
+   *
+   * <p>
+   * Example:
+   *
+   * <pre>{@code
+   * Map<String, Object> book = new HashMap<>();
+   * book.put("__name__", firestore.collection("books").document("newBook"));
+   * book.put("title", "New Book");
+   *
+   * firestore.pipeline()
+   *     .literals(book)
+   *     .insert()
+   *     .execute()
+   *     .get();
+   * }</pre>
+   *
+   * @return A new {@code Pipeline} object with this stage appended to the stage
+   *         list.
    */
   @BetaApi
   public Pipeline insert() {
     return append(new Insert());
   }
 
   /**
-   * Performs an insert operation using documents from previous stages.
+   * Performs an insert operation using documents from previous stages into a
+   * specified target
+   * collection.
+   *
+   * <p>
+   * If documents have an ID (or expression evaluation for ID), they will use it.
+   * Otherwise,
+   * auto-generated IDs will be used if applicable (depending on the source).
+   *
+   * <p>
+   * Example:
+   *
+   * <pre>{@code
+   * CollectionReference backupCol = firestore.collection("books_backup");
+   *
+   * Map<String, Object> book = new HashMap<>();
+   * book.put("title", "New Book");
+   *
+   * firestore.pipeline()
+   *     .literals(book)
+   *     .insert(backupCol)
+   *     .execute()
+   *     .get();
+   * }</pre>
    *
    * @param target The collection to insert to.
-   * @return A new {@code Pipeline} object with this stage appended to the stage list.
+   * @return A new {@code Pipeline} object with this stage appended to the stage
+   *         list.
    */
   @BetaApi
   public Pipeline insert(CollectionReference target) {
     return append(new Insert().withCollection(target));
   }
 
   /**
-   * Performs an insert operation using documents from previous stages.
+   * Performs an insert operation using an {@link Insert} stage.
+   *
+   * <p>
+   * This method allows you to use a pre-configured {@link Insert} stage.
+   *
+   * <p>
+   * Example: Use a pre-configured {@link Insert} stage with a target collection
+   * and ID expression, reading from literals.
+   *
+   * <pre>{@code
+   * CollectionReference targetCol = firestore.collection("books_backup");
+   * Insert insertStage = new Insert().withCollection(targetCol).withIdExpression(field("custom_id"));
+   *
+   * Map<String, Object> book = new HashMap<>();
+   * book.put("custom_id", "book1");
+   * book.put("title", "Book 1");
+   *
+   * firestore.pipeline()
+   *     .literals(book)
+   *     .insert(insertStage)
+   *     .execute()
+   *     .get();
+   * }</pre>
    *
    * @param insertStage The {@code Insert} stage to append.
-   * @return A new {@code Pipeline} object with this stage appended to the stage list.
+   * @return A new {@code Pipeline} object with this stage appended to the stage
+   *         list.
    */
-  @InternalApi
+  @BetaApi
   public Pipeline insert(Insert insertStage) {
     return append(insertStage);
   }

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

@@ -159,8 +159,21 @@ public Pipeline documents(String... docs) {
   }
 
   /**
-   * Creates a new {@link Pipeline} that operates on a static set of documents
-   * represented as Maps.
+   * Creates a new {@link Pipeline} that operates on a static set of documents represented as Maps.
+   *
+   * <p>Example:
+   *
+   * <pre>{@code
+   * Map<String, Object> doc1 = new HashMap<>();
+   * doc1.put("title", "Book 1");
+   * Map<String, Object> doc2 = new HashMap<>();
+   * doc2.put("title", "Book 2");
+   *
+   * Snapshot snapshot = firestore.pipeline()
+   *     .literals(doc1, doc2)
+   *     .execute()
+   *     .get();
+   * }</pre>
    *
    * @param data The Maps representing documents to include in the pipeline.
    * @return A new {@code Pipeline} instance with a literals source.

google-cloud-firestore/src/main/java/com/google/cloud/firestore/pipeline/stages/Delete.java

@@ -18,12 +18,8 @@
 
 import com.google.api.core.BetaApi;
 import com.google.api.core.InternalApi;
-import com.google.cloud.firestore.CollectionReference;
-import com.google.cloud.firestore.PipelineUtils;
 import com.google.firestore.v1.Value;
 import java.util.ArrayList;
-import java.util.List;
-import javax.annotation.Nullable;
 
 @InternalApi
 public final class Delete extends Stage {

google-cloud-firestore/src/main/java/com/google/cloud/firestore/pipeline/stages/Insert.java

@@ -17,15 +17,10 @@
 package com.google.cloud.firestore.pipeline.stages;
 
 import com.google.api.core.BetaApi;
-import com.google.api.core.InternalApi;
 import com.google.cloud.firestore.CollectionReference;
 import com.google.cloud.firestore.PipelineUtils;
 import com.google.cloud.firestore.pipeline.expressions.Expression;
-import com.google.cloud.firestore.pipeline.expressions.Selectable;
 import com.google.firestore.v1.Value;
-import java.util.ArrayList;
-import java.util.List;
-import javax.annotation.Nullable;
 
 @BetaApi
 public final class Insert extends Stage {

google-cloud-firestore/src/main/java/com/google/cloud/firestore/pipeline/stages/Literals.java

@@ -46,7 +46,8 @@ Iterable<Value> toStageArgs() {
   }
 
   private Value encodeLiteralMap(Map<?, ?> map) {
-    com.google.firestore.v1.MapValue.Builder mapValue = com.google.firestore.v1.MapValue.newBuilder();
+    com.google.firestore.v1.MapValue.Builder mapValue =
+        com.google.firestore.v1.MapValue.newBuilder();
     for (Map.Entry<?, ?> entry : map.entrySet()) {
       String key = String.valueOf(entry.getKey());
       Object v = entry.getValue();

google-cloud-firestore/src/main/java/com/google/cloud/firestore/pipeline/stages/Upsert.java

@@ -17,7 +17,6 @@
 package com.google.cloud.firestore.pipeline.stages;
 
 import com.google.api.core.BetaApi;
-import com.google.api.core.InternalApi;
 import com.google.cloud.firestore.CollectionReference;
 import com.google.cloud.firestore.PipelineUtils;
 import com.google.cloud.firestore.pipeline.expressions.Expression;
@@ -56,7 +55,8 @@ public Upsert withCollection(CollectionReference target) {
 
   @BetaApi
   public Upsert withIdExpression(Expression idExpr) {
-    return new Upsert(this.transformations, this.options.with("document_id", PipelineUtils.encodeValue(idExpr)));
+    return new Upsert(
+        this.transformations, this.options.with("document_id", PipelineUtils.encodeValue(idExpr)));
   }
 
   @BetaApi