make options and returns internal, add update stage

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

@@ -62,6 +62,8 @@
 import com.google.cloud.firestore.pipeline.stages.Union;
 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.UpdateOptions;
 import com.google.cloud.firestore.pipeline.stages.Upsert;
 import com.google.cloud.firestore.pipeline.stages.UpsertOptions;
 import com.google.cloud.firestore.pipeline.stages.Where;
@@ -1029,7 +1031,7 @@ public Pipeline delete(CollectionReference target) {
    * @param options The {@code DeleteOptions} to apply to the stage.
    * @return A new {@code Pipeline} object with this stage appended to the stage list.
    */
-  @BetaApi
+  @InternalApi
   public Pipeline delete(Delete deleteStage, DeleteOptions options) {
     return append(deleteStage.withOptions(options));
   }
@@ -1052,7 +1054,7 @@ public Pipeline upsert() {
    */
   @BetaApi
   public Pipeline upsert(CollectionReference target) {
-    return append(Upsert.withCollection(target));
+    return append(Update.withCollection(target));
   }
 
   /**
@@ -1062,11 +1064,44 @@ public Pipeline upsert(CollectionReference target) {
    * @param options The {@code UpsertOptions} to apply to the stage.
    * @return A new {@code Pipeline} object with this stage appended to the stage list.
    */
-  @BetaApi
+  @InternalApi
   public Pipeline upsert(Upsert upsertStage, UpsertOptions options) {
     return append(upsertStage.withOptions(options));
   }
 
+  /**
+   * 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 update() {
+    return append(new Update());
+  }
+
+  /**
+   * Performs an update operation using documents from previous stages.
+   *
+   * @param target The collection to upsert to.
+   * @return A new {@code Pipeline} object with this stage appended to the stage list.
+   */
+  @BetaApi
+  public Pipeline update(CollectionReference target) {
+    return append(Update.withCollection(target));
+  }
+
+  /**
+   * Performs an update operation using documents from previous stages.
+   *
+   * @param update The {@code Update} stage to append.
+   * @param options The {@code UpdateOptions} to apply to the stage.
+   * @return A new {@code Pipeline} object with this stage appended to the stage list.
+   */
+  @InternalApi
+  public Pipeline update(Update updateStage, UpdateOptions options) {
+    return append(updateStage.withOptions(options));
+  }
+
   /**
    * Performs an insert operation using documents from previous stages.
    *
@@ -1095,7 +1130,7 @@ public Pipeline insert(CollectionReference target) {
    * @param options The {@code InsertOptions} to apply to the stage.
    * @return A new {@code Pipeline} object with this stage appended to the stage list.
    */
-  @BetaApi
+  @InternalApi
   public Pipeline insert(Insert insertStage, InsertOptions options) {
     return append(insertStage.withOptions(options));
   }

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

@@ -46,12 +46,12 @@ public static Delete withCollection(CollectionReference target) {
     return new Delete(path.startsWith("/") ? path : "/" + path, InternalOptions.EMPTY);
   }
 
-  @BetaApi
+  @InternalApi
   public Delete withOptions(DeleteOptions options) {
     return new Delete(path, this.options.adding(options));
   }
 
-  @BetaApi
+  @InternalApi
   public Delete withReturns(DeleteReturn returns) {
     return new Delete(
         path, this.options.with("returns", PipelineUtils.encodeValue(returns.getValue())));

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

@@ -16,10 +16,10 @@
 
 package com.google.cloud.firestore.pipeline.stages;
 
-import com.google.api.core.BetaApi;
+import com.google.api.core.InternalApi;
 
 /** Options for a Delete pipeline stage. */
-@BetaApi
+@InternalApi
 public class DeleteOptions extends WriteOptions<DeleteOptions> {
 
   /** Creates a new, empty `DeleteOptions` object. */

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

@@ -16,7 +16,10 @@
 
 package com.google.cloud.firestore.pipeline.stages;
 
+import com.google.api.core.InternalApi;
+
 /** Defines the return value options for a Delete pipeline stage. */
+@InternalApi
 public enum DeleteReturn {
   EMPTY("EMPTY"),
   DOCUMENT_ID("DOCUMENT_ID");

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

@@ -47,12 +47,12 @@ public static Insert withCollection(CollectionReference target) {
     return new Insert(path.startsWith("/") ? path : "/" + path, InternalOptions.EMPTY);
   }
 
-  @BetaApi
+  @InternalApi
   public Insert withOptions(InsertOptions options) {
     return new Insert(path, this.options.adding(options));
   }
 
-  @BetaApi
+  @InternalApi
   public Insert withReturns(InsertReturn returns) {
     return new Insert(
         path, this.options.with("returns", PipelineUtils.encodeValue(returns.getValue())));

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

@@ -16,10 +16,10 @@
 
 package com.google.cloud.firestore.pipeline.stages;
 
-import com.google.api.core.BetaApi;
+import com.google.api.core.InternalApi;
 
 /** Options for an Insert pipeline stage. */
-@BetaApi
+@InternalApi
 public class InsertOptions extends WriteOptions<InsertOptions> {
 
   /** Creates a new, empty `InsertOptions` object. */

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

@@ -16,7 +16,10 @@
 
 package com.google.cloud.firestore.pipeline.stages;
 
+import com.google.api.core.InternalApi;
+
 /** Defines the return value options for an Insert pipeline stage. */
+@InternalApi
 public enum InsertReturn {
   EMPTY("EMPTY"),
   DOCUMENT_ID("DOCUMENT_ID");

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

@@ -0,0 +1,78 @@
+/*
+ * Copyright 2024 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *       http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+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.Selectable;
+import com.google.firestore.v1.Value;
+import java.util.ArrayList;
+import java.util.List;
+import javax.annotation.Nullable;
+
+@InternalApi
+public final class Update extends Stage {
+
+  @Nullable private final String path;
+
+  private Update(@Nullable String path, InternalOptions options) {
+    super("update", options);
+    this.path = path;
+  }
+
+  @BetaApi
+  public Update() {
+    this(null, InternalOptions.EMPTY);
+  }
+
+  @BetaApi
+  public static Update withCollection(CollectionReference target) {
+    String path = target.getPath();
+    return new Update(path.startsWith("/") ? path : "/" + path, InternalOptions.EMPTY);
+  }
+
+  @InternalApi
+  public Update withOptions(UpdateOptions options) {
+    return new Update(path, this.options.adding(options));
+  }
+
+  @InternalApi
+  public Update withReturns(UpdateReturn returns) {
+    return new Update(
+        path, this.options.with("returns", PipelineUtils.encodeValue(returns.getValue())));
+  }
+
+  @BetaApi
+  public Update withTransformations(Selectable... transformations) {
+    return new Update(
+        path,
+        this.options.with(
+            "transformations",
+            PipelineUtils.encodeValue(PipelineUtils.selectablesToMap(transformations))));
+  }
+
+  @Override
+  Iterable<Value> toStageArgs() {
+    List<Value> args = new ArrayList<>();
+    if (path != null) {
+      args.add(Value.newBuilder().setReferenceValue(path).build());
+    }
+    return args;
+  }
+}

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

@@ -0,0 +1,49 @@
+/*
+ * Copyright 2024 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *       http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.google.cloud.firestore.pipeline.stages;
+
+import com.google.api.core.BetaApi;
+
+/** Options for an Update pipeline stage. */
+@BetaApi
+public class UpdateOptions extends WriteOptions<UpdateOptions> {
+
+  /** Creates a new, empty `UpdateOptions` object. */
+  public UpdateOptions() {
+    super(InternalOptions.EMPTY);
+  }
+
+  UpdateOptions(InternalOptions options) {
+    super(options);
+  }
+
+  @Override
+  UpdateOptions self(InternalOptions options) {
+    return new UpdateOptions(options);
+  }
+
+  /**
+   * Sets the conflict resolution strategy.
+   *
+   * @param conflictResolution The conflict resolution strategy.
+   * @return A new options object with the conflict resolution set.
+   */
+  @BetaApi
+  public UpdateOptions withConflictResolution(ConflictResolution conflictResolution) {
+    return with("conflict_resolution", conflictResolution.getValue());
+  }
+}

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

@@ -0,0 +1,36 @@
+/*
+ * Copyright 2026 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *       http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.google.cloud.firestore.pipeline.stages;
+
+import com.google.api.core.InternalApi;
+
+/** Defines the return value options for an Update pipeline stage. */
+@InternalApi
+public enum UpdateReturn {
+  EMPTY("EMPTY"),
+  DOCUMENT_ID("DOCUMENT_ID");
+
+  private final String value;
+
+  UpdateReturn(String value) {
+    this.value = value;
+  }
+
+  public String getValue() {
+    return value;
+  }
+}

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

@@ -47,12 +47,12 @@ public static Upsert withCollection(CollectionReference target) {
     return new Upsert(path.startsWith("/") ? path : "/" + path, InternalOptions.EMPTY);
   }
 
-  @BetaApi
+  @InternalApi
   public Upsert withOptions(UpsertOptions options) {
     return new Upsert(path, this.options.adding(options));
   }
 
-  @BetaApi
+  @InternalApi
   public Upsert withReturns(UpsertReturn returns) {
     return new Upsert(
         path, this.options.with("returns", PipelineUtils.encodeValue(returns.getValue())));

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

@@ -16,10 +16,10 @@
 
 package com.google.cloud.firestore.pipeline.stages;
 
-import com.google.api.core.BetaApi;
+import com.google.api.core.InternalApi;
 
 /** Options for an Upsert pipeline stage. */
-@BetaApi
+@InternalApi
 public class UpsertOptions extends WriteOptions<UpsertOptions> {
 
   /** Creates a new, empty `UpsertOptions` object. */
@@ -42,7 +42,7 @@ UpsertOptions self(InternalOptions options) {
    * @param conflictResolution The conflict resolution strategy.
    * @return A new options object with the conflict resolution set.
    */
-  @BetaApi
+  @InternalApi
   public UpsertOptions withConflictResolution(ConflictResolution conflictResolution) {
     return with("conflict_resolution", conflictResolution.getValue());
   }

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

@@ -16,7 +16,10 @@
 
 package com.google.cloud.firestore.pipeline.stages;
 
+import com.google.api.core.InternalApi;
+
 /** Defines the return value options for an Upsert pipeline stage. */
+@InternalApi
 public enum UpsertReturn {
   EMPTY("EMPTY"),
   DOCUMENT_ID("DOCUMENT_ID");