Skip to content
This repository was archived by the owner on May 8, 2026. It is now read-only.

Commit f1bba01

Browse files
wu-huiwu-hui
committed
Delete upsert() from Pipeline.java and tests
1 parent e162660 commit f1bba01

8 files changed

Lines changed: 310 additions & 195 deletions

File tree

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

Lines changed: 130 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -61,7 +61,6 @@
6161
import com.google.cloud.firestore.pipeline.stages.Unnest;
6262
import com.google.cloud.firestore.pipeline.stages.UnnestOptions;
6363
import com.google.cloud.firestore.pipeline.stages.Update;
64-
import com.google.cloud.firestore.pipeline.stages.Upsert;
6564
import com.google.cloud.firestore.pipeline.stages.Where;
6665
import com.google.cloud.firestore.telemetry.MetricsUtil.MetricsContext;
6766
import com.google.cloud.firestore.telemetry.TelemetryConstants;
@@ -1002,6 +1001,18 @@ public Pipeline unnest(Selectable field, UnnestOptions options) {
10021001
/**
10031002
* Performs a delete operation on documents from previous stages.
10041003
*
1004+
* <p>Example:
1005+
*
1006+
* <pre>{@code
1007+
* // Delete all documents in the "logs" collection where "status" is "archived"
1008+
* firestore.pipeline()
1009+
* .collection("logs")
1010+
* .where(field("status").equal("archived"))
1011+
* .delete()
1012+
* .execute()
1013+
* .get();
1014+
* }</pre>
1015+
*
10051016
* @return A new {@code Pipeline} object with this stage appended to the stage list.
10061017
*/
10071018
@BetaApi
@@ -1010,39 +1021,36 @@ public Pipeline delete() {
10101021
}
10111022

10121023
/**
1013-
* Performs an upsert operation using documents from previous stages.
1024+
* Performs an update operation using documents from previous stages.
10141025
*
1015-
* @return A new {@code Pipeline} object with this stage appended to the stage list.
1016-
*/
1017-
@BetaApi
1018-
public Pipeline upsert() {
1019-
return append(new Upsert());
1020-
}
1021-
1022-
/**
1023-
* Performs an upsert operation using documents from previous stages.
1026+
* <p>This method updates the documents in place based on the data flowing through the pipeline.
1027+
* To specify transformations, use {@link #update(Selectable...)}.
10241028
*
1025-
* @param target The collection to upsert to.
1026-
* @return A new {@code Pipeline} object with this stage appended to the stage list.
1027-
*/
1028-
@BetaApi
1029-
public Pipeline upsert(CollectionReference target) {
1030-
return append(new Upsert().withCollection(target));
1031-
}
1032-
1033-
/**
1034-
* Performs an upsert operation using documents from previous stages.
1029+
* <p>Example 1: Update a collection's schema by adding a new field and removing an old one.
10351030
*
1036-
* @param upsertStage The {@code Upsert} stage to append.
1037-
* @return A new {@code Pipeline} object with this stage appended to the stage list.
1038-
*/
1039-
@InternalApi
1040-
public Pipeline upsert(Upsert upsertStage) {
1041-
return append(upsertStage);
1042-
}
1043-
1044-
/**
1045-
* Performs an update operation using documents from previous stages.
1031+
* <pre>{@code
1032+
* firestore.pipeline()
1033+
* .collection("books")
1034+
* .addFields(constant("Fiction").as("genre"))
1035+
* .removeFields("old_genre")
1036+
* .update()
1037+
* .execute()
1038+
* .get();
1039+
* }</pre>
1040+
*
1041+
* <p>Example 2: Update documents in place with data from literals.
1042+
*
1043+
* <pre>{@code
1044+
* Map<String, Object> updateData = new HashMap<>();
1045+
* updateData.put("__name__", firestore.collection("books").document("book1"));
1046+
* updateData.put("status", "Updated");
1047+
*
1048+
* firestore.pipeline()
1049+
* .literals(updateData)
1050+
* .update()
1051+
* .execute()
1052+
* .get();
1053+
* }</pre>
10461054
*
10471055
* @return A new {@code Pipeline} object with this stage appended to the stage list.
10481056
*/
@@ -1052,7 +1060,20 @@ public Pipeline update() {
10521060
}
10531061

10541062
/**
1055-
* Performs an update operation using documents from previous stages.
1063+
* Performs an update operation using documents from previous stages with specified
1064+
* transformations.
1065+
*
1066+
* <p>Example:
1067+
*
1068+
* <pre>{@code
1069+
* // Update the "status" field to "Discounted" for all books where price > 50
1070+
* firestore.pipeline()
1071+
* .collection("books")
1072+
* .where(field("price").greaterThan(50))
1073+
* .update(constant("Discounted").as("status"))
1074+
* .execute()
1075+
* .get();
1076+
* }</pre>
10561077
*
10571078
* @param transformations The transformations to apply.
10581079
* @return A new {@code Pipeline} object with this stage appended to the stage list.
@@ -1063,19 +1084,51 @@ public Pipeline update(Selectable... transformations) {
10631084
}
10641085

10651086
/**
1066-
* Performs an update operation using documents from previous stages.
1087+
* Performs an update operation using an {@link Update} stage.
1088+
*
1089+
* <p>This method allows you to use a pre-configured {@link Update} stage.
1090+
*
1091+
* <p>Example:
1092+
*
1093+
* <pre>{@code
1094+
* Update updateStage = new Update().withTransformations(constant("Updated").as("status"));
1095+
*
1096+
* firestore.pipeline()
1097+
* .collection("books")
1098+
* .where(field("title").equal("The Hitchhiker's Guide to the Galaxy"))
1099+
* .update(updateStage)
1100+
* .execute()
1101+
* .get();
1102+
* }</pre>
10671103
*
10681104
* @param update The {@code Update} stage to append.
10691105
* @return A new {@code Pipeline} object with this stage appended to the stage list.
10701106
*/
1071-
@InternalApi
1107+
@BetaApi
10721108
public Pipeline update(Update update) {
10731109
return append(update);
10741110
}
10751111

10761112
/**
10771113
* Performs an insert operation using documents from previous stages.
10781114
*
1115+
* <p>The documents must include a valid {@code __name__} field specifying the document reference
1116+
* to insert. If the document already exists, the operation will fail.
1117+
*
1118+
* <p>Example:
1119+
*
1120+
* <pre>{@code
1121+
* Map<String, Object> book = new HashMap<>();
1122+
* book.put("__name__", firestore.collection("books").document("newBook"));
1123+
* book.put("title", "New Book");
1124+
*
1125+
* firestore.pipeline()
1126+
* .literals(book)
1127+
* .insert()
1128+
* .execute()
1129+
* .get();
1130+
* }</pre>
1131+
*
10791132
* @return A new {@code Pipeline} object with this stage appended to the stage list.
10801133
*/
10811134
@BetaApi
@@ -1084,7 +1137,26 @@ public Pipeline insert() {
10841137
}
10851138

10861139
/**
1087-
* Performs an insert operation using documents from previous stages.
1140+
* Performs an insert operation using documents from previous stages into a specified target
1141+
* collection.
1142+
*
1143+
* <p>If documents have an ID (or expression evaluation for ID), they will use it. Otherwise,
1144+
* auto-generated IDs will be used if applicable (depending on the source).
1145+
*
1146+
* <p>Example:
1147+
*
1148+
* <pre>{@code
1149+
* CollectionReference backupCol = firestore.collection("books_backup");
1150+
*
1151+
* Map<String, Object> book = new HashMap<>();
1152+
* book.put("title", "New Book");
1153+
*
1154+
* firestore.pipeline()
1155+
* .literals(book)
1156+
* .insert(backupCol)
1157+
* .execute()
1158+
* .get();
1159+
* }</pre>
10881160
*
10891161
* @param target The collection to insert to.
10901162
* @return A new {@code Pipeline} object with this stage appended to the stage list.
@@ -1095,12 +1167,32 @@ public Pipeline insert(CollectionReference target) {
10951167
}
10961168

10971169
/**
1098-
* Performs an insert operation using documents from previous stages.
1170+
* Performs an insert operation using an {@link Insert} stage.
1171+
*
1172+
* <p>This method allows you to use a pre-configured {@link Insert} stage.
1173+
*
1174+
* <p>Example: Use a pre-configured {@link Insert} stage with a target collection and ID
1175+
* expression, reading from literals.
1176+
*
1177+
* <pre>{@code
1178+
* CollectionReference targetCol = firestore.collection("books_backup");
1179+
* Insert insertStage = new Insert().withCollection(targetCol).withIdExpression(field("custom_id"));
1180+
*
1181+
* Map<String, Object> book = new HashMap<>();
1182+
* book.put("custom_id", "book1");
1183+
* book.put("title", "Book 1");
1184+
*
1185+
* firestore.pipeline()
1186+
* .literals(book)
1187+
* .insert(insertStage)
1188+
* .execute()
1189+
* .get();
1190+
* }</pre>
10991191
*
11001192
* @param insertStage The {@code Insert} stage to append.
11011193
* @return A new {@code Pipeline} object with this stage appended to the stage list.
11021194
*/
1103-
@InternalApi
1195+
@BetaApi
11041196
public Pipeline insert(Insert insertStage) {
11051197
return append(insertStage);
11061198
}
@@ -1446,7 +1538,7 @@ public void onComplete() {
14461538
}
14471539
};
14481540

1449-
logger.log(Level.WARNING, "Sending pipeline request: " + request.getStructuredPipeline());
1541+
logger.log(Level.FINEST, "Sending pipeline request: " + request.getStructuredPipeline());
14501542

14511543
rpcContext.streamRequest(request, observer, rpcContext.getClient().executePipelineCallable());
14521544
}

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

Lines changed: 15 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -159,8 +159,21 @@ public Pipeline documents(String... docs) {
159159
}
160160

161161
/**
162-
* Creates a new {@link Pipeline} that operates on a static set of documents
163-
* represented as Maps.
162+
* Creates a new {@link Pipeline} that operates on a static set of documents represented as Maps.
163+
*
164+
* <p>Example:
165+
*
166+
* <pre>{@code
167+
* Map<String, Object> doc1 = new HashMap<>();
168+
* doc1.put("title", "Book 1");
169+
* Map<String, Object> doc2 = new HashMap<>();
170+
* doc2.put("title", "Book 2");
171+
*
172+
* Snapshot snapshot = firestore.pipeline()
173+
* .literals(doc1, doc2)
174+
* .execute()
175+
* .get();
176+
* }</pre>
164177
*
165178
* @param data The Maps representing documents to include in the pipeline.
166179
* @return A new {@code Pipeline} instance with a literals source.

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

Lines changed: 1 addition & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
/*
2-
* Copyright 2024 Google LLC
2+
* Copyright 2026 Google LLC
33
*
44
* Licensed under the Apache License, Version 2.0 (the "License");
55
* you may not use this file except in compliance with the License.
@@ -18,12 +18,8 @@
1818

1919
import com.google.api.core.BetaApi;
2020
import com.google.api.core.InternalApi;
21-
import com.google.cloud.firestore.CollectionReference;
22-
import com.google.cloud.firestore.PipelineUtils;
2321
import com.google.firestore.v1.Value;
2422
import java.util.ArrayList;
25-
import java.util.List;
26-
import javax.annotation.Nullable;
2723

2824
@InternalApi
2925
public final class Delete extends Stage {

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

Lines changed: 1 addition & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
/*
2-
* Copyright 2024 Google LLC
2+
* Copyright 2026 Google LLC
33
*
44
* Licensed under the Apache License, Version 2.0 (the "License");
55
* you may not use this file except in compliance with the License.
@@ -17,15 +17,10 @@
1717
package com.google.cloud.firestore.pipeline.stages;
1818

1919
import com.google.api.core.BetaApi;
20-
import com.google.api.core.InternalApi;
2120
import com.google.cloud.firestore.CollectionReference;
2221
import com.google.cloud.firestore.PipelineUtils;
2322
import com.google.cloud.firestore.pipeline.expressions.Expression;
24-
import com.google.cloud.firestore.pipeline.expressions.Selectable;
2523
import com.google.firestore.v1.Value;
26-
import java.util.ArrayList;
27-
import java.util.List;
28-
import javax.annotation.Nullable;
2924

3025
@BetaApi
3126
public final class Insert extends Stage {

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

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -46,7 +46,8 @@ Iterable<Value> toStageArgs() {
4646
}
4747

4848
private Value encodeLiteralMap(Map<?, ?> map) {
49-
com.google.firestore.v1.MapValue.Builder mapValue = com.google.firestore.v1.MapValue.newBuilder();
49+
com.google.firestore.v1.MapValue.Builder mapValue =
50+
com.google.firestore.v1.MapValue.newBuilder();
5051
for (Map.Entry<?, ?> entry : map.entrySet()) {
5152
String key = String.valueOf(entry.getKey());
5253
Object v = entry.getValue();

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
/*
2-
* Copyright 2024 Google LLC
2+
* Copyright 2026 Google LLC
33
*
44
* Licensed under the Apache License, Version 2.0 (the "License");
55
* you may not use this file except in compliance with the License.

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

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,6 @@
1717
package com.google.cloud.firestore.pipeline.stages;
1818

1919
import com.google.api.core.BetaApi;
20-
import com.google.api.core.InternalApi;
2120
import com.google.cloud.firestore.CollectionReference;
2221
import com.google.cloud.firestore.PipelineUtils;
2322
import com.google.cloud.firestore.pipeline.expressions.Expression;
@@ -56,7 +55,8 @@ public Upsert withCollection(CollectionReference target) {
5655

5756
@BetaApi
5857
public Upsert withIdExpression(Expression idExpr) {
59-
return new Upsert(this.transformations, this.options.with("document_id", PipelineUtils.encodeValue(idExpr)));
58+
return new Upsert(
59+
this.transformations, this.options.with("document_id", PipelineUtils.encodeValue(idExpr)));
6060
}
6161

6262
@BetaApi

0 commit comments

Comments
 (0)