feat: add option for returning Spanner commit stats (#817)

PiperOrigin-RevId: 353145174

Source-Author: Google APIs <noreply@google.com>
Source-Date: Thu Jan 21 18:06:01 2021 -0800
Source-Repo: googleapis/googleapis
Source-Sha: 8fa381b7138f1d72966ff20563efae1b2194d359
Source-Link: googleapis/googleapis@8fa381b

google-cloud-spanner/src/main/java/com/google/cloud/spanner/v1/SpannerClient.java

@@ -724,6 +724,11 @@ public final UnaryCallable<BeginTransactionRequest, Transaction> beginTransactio
    * reasons. If `Commit` returns `ABORTED`, the caller should re-attempt the transaction from the
    * beginning, re-using the same session.
    *
+   * <p>On very rare occasions, `Commit` might return `UNKNOWN`. This can happen, for example, if
+   * the client job experiences a 1+ hour networking failure. At that point, Cloud Spanner has lost
+   * track of the transaction outcome and we recommend that you perform another read from the
+   * database to see the state of things as they are now.
+   *
    * @param session Required. The session in which the transaction to be committed is running.
    * @param transactionId Commit a previously-started transaction.
    * @param mutations The mutations to be executed when this transaction commits. All mutations are
@@ -751,6 +756,11 @@ public final CommitResponse commit(
    * reasons. If `Commit` returns `ABORTED`, the caller should re-attempt the transaction from the
    * beginning, re-using the same session.
    *
+   * <p>On very rare occasions, `Commit` might return `UNKNOWN`. This can happen, for example, if
+   * the client job experiences a 1+ hour networking failure. At that point, Cloud Spanner has lost
+   * track of the transaction outcome and we recommend that you perform another read from the
+   * database to see the state of things as they are now.
+   *
    * @param session Required. The session in which the transaction to be committed is running.
    * @param singleUseTransaction Execute mutations in a temporary transaction. Note that unlike
    *     commit of a previously-started transaction, commit with a temporary transaction is
@@ -784,6 +794,11 @@ public final CommitResponse commit(
    * reasons. If `Commit` returns `ABORTED`, the caller should re-attempt the transaction from the
    * beginning, re-using the same session.
    *
+   * <p>On very rare occasions, `Commit` might return `UNKNOWN`. This can happen, for example, if
+   * the client job experiences a 1+ hour networking failure. At that point, Cloud Spanner has lost
+   * track of the transaction outcome and we recommend that you perform another read from the
+   * database to see the state of things as they are now.
+   *
    * @param session Required. The session in which the transaction to be committed is running.
    * @param transactionId Commit a previously-started transaction.
    * @param mutations The mutations to be executed when this transaction commits. All mutations are
@@ -811,6 +826,11 @@ public final CommitResponse commit(
    * reasons. If `Commit` returns `ABORTED`, the caller should re-attempt the transaction from the
    * beginning, re-using the same session.
    *
+   * <p>On very rare occasions, `Commit` might return `UNKNOWN`. This can happen, for example, if
+   * the client job experiences a 1+ hour networking failure. At that point, Cloud Spanner has lost
+   * track of the transaction outcome and we recommend that you perform another read from the
+   * database to see the state of things as they are now.
+   *
    * @param session Required. The session in which the transaction to be committed is running.
    * @param singleUseTransaction Execute mutations in a temporary transaction. Note that unlike
    *     commit of a previously-started transaction, commit with a temporary transaction is
@@ -844,6 +864,11 @@ public final CommitResponse commit(
    * reasons. If `Commit` returns `ABORTED`, the caller should re-attempt the transaction from the
    * beginning, re-using the same session.
    *
+   * <p>On very rare occasions, `Commit` might return `UNKNOWN`. This can happen, for example, if
+   * the client job experiences a 1+ hour networking failure. At that point, Cloud Spanner has lost
+   * track of the transaction outcome and we recommend that you perform another read from the
+   * database to see the state of things as they are now.
+   *
    * @param request The request object containing all of the parameters for the API call.
    * @throws com.google.api.gax.rpc.ApiException if the remote call fails
    */
@@ -861,6 +886,11 @@ public final CommitResponse commit(CommitRequest request) {
    * reasons. If `Commit` returns `ABORTED`, the caller should re-attempt the transaction from the
    * beginning, re-using the same session.
    *
+   * <p>On very rare occasions, `Commit` might return `UNKNOWN`. This can happen, for example, if
+   * the client job experiences a 1+ hour networking failure. At that point, Cloud Spanner has lost
+   * track of the transaction outcome and we recommend that you perform another read from the
+   * database to see the state of things as they are now.
+   *
    * <p>Sample code:
    */
   public final UnaryCallable<CommitRequest, CommitResponse> commitCallable() {

google-cloud-spanner/src/test/java/com/google/cloud/spanner/v1/SpannerClientTest.java

@@ -954,7 +954,10 @@ public void beginTransactionExceptionTest2() throws Exception {
   @Test
   public void commitTest() throws Exception {
     CommitResponse expectedResponse =
-        CommitResponse.newBuilder().setCommitTimestamp(Timestamp.newBuilder().build()).build();
+        CommitResponse.newBuilder()
+            .setCommitTimestamp(Timestamp.newBuilder().build())
+            .setCommitStats(CommitResponse.CommitStats.newBuilder().build())
+            .build();
     mockSpanner.addResponse(expectedResponse);
 
     SessionName session = SessionName.of("[PROJECT]", "[INSTANCE]", "[DATABASE]", "[SESSION]");
@@ -996,7 +999,10 @@ public void commitExceptionTest() throws Exception {
   @Test
   public void commitTest2() throws Exception {
     CommitResponse expectedResponse =
-        CommitResponse.newBuilder().setCommitTimestamp(Timestamp.newBuilder().build()).build();
+        CommitResponse.newBuilder()
+            .setCommitTimestamp(Timestamp.newBuilder().build())
+            .setCommitStats(CommitResponse.CommitStats.newBuilder().build())
+            .build();
     mockSpanner.addResponse(expectedResponse);
 
     SessionName session = SessionName.of("[PROJECT]", "[INSTANCE]", "[DATABASE]", "[SESSION]");
@@ -1038,7 +1044,10 @@ public void commitExceptionTest2() throws Exception {
   @Test
   public void commitTest3() throws Exception {
     CommitResponse expectedResponse =
-        CommitResponse.newBuilder().setCommitTimestamp(Timestamp.newBuilder().build()).build();
+        CommitResponse.newBuilder()
+            .setCommitTimestamp(Timestamp.newBuilder().build())
+            .setCommitStats(CommitResponse.CommitStats.newBuilder().build())
+            .build();
     mockSpanner.addResponse(expectedResponse);
 
     String session = "session1984987798";
@@ -1080,7 +1089,10 @@ public void commitExceptionTest3() throws Exception {
   @Test
   public void commitTest4() throws Exception {
     CommitResponse expectedResponse =
-        CommitResponse.newBuilder().setCommitTimestamp(Timestamp.newBuilder().build()).build();
+        CommitResponse.newBuilder()
+            .setCommitTimestamp(Timestamp.newBuilder().build())
+            .setCommitStats(CommitResponse.CommitStats.newBuilder().build())
+            .build();
     mockSpanner.addResponse(expectedResponse);
 
     String session = "session1984987798";

grpc-google-cloud-spanner-v1/src/main/java/com/google/spanner/v1/SpannerGrpc.java

@@ -924,6 +924,11 @@ public void beginTransaction(
      * transactions. However, it can also happen for a variety of other
      * reasons. If `Commit` returns `ABORTED`, the caller should re-attempt
      * the transaction from the beginning, re-using the same session.
+     * On very rare occasions, `Commit` might return `UNKNOWN`. This can happen,
+     * for example, if the client job experiences a 1+ hour networking failure.
+     * At that point, Cloud Spanner has lost track of the transaction outcome and
+     * we recommend that you perform another read from the database to see the
+     * state of things as they are now.
      * </pre>
      */
     public void commit(
@@ -1357,6 +1362,11 @@ public void beginTransaction(
      * transactions. However, it can also happen for a variety of other
      * reasons. If `Commit` returns `ABORTED`, the caller should re-attempt
      * the transaction from the beginning, re-using the same session.
+     * On very rare occasions, `Commit` might return `UNKNOWN`. This can happen,
+     * for example, if the client job experiences a 1+ hour networking failure.
+     * At that point, Cloud Spanner has lost track of the transaction outcome and
+     * we recommend that you perform another read from the database to see the
+     * state of things as they are now.
      * </pre>
      */
     public void commit(
@@ -1663,6 +1673,11 @@ public com.google.spanner.v1.Transaction beginTransaction(
      * transactions. However, it can also happen for a variety of other
      * reasons. If `Commit` returns `ABORTED`, the caller should re-attempt
      * the transaction from the beginning, re-using the same session.
+     * On very rare occasions, `Commit` might return `UNKNOWN`. This can happen,
+     * for example, if the client job experiences a 1+ hour networking failure.
+     * At that point, Cloud Spanner has lost track of the transaction outcome and
+     * we recommend that you perform another read from the database to see the
+     * state of things as they are now.
      * </pre>
      */
     public com.google.spanner.v1.CommitResponse commit(
@@ -1932,6 +1947,11 @@ public com.google.common.util.concurrent.ListenableFuture<com.google.spanner.v1.
      * transactions. However, it can also happen for a variety of other
      * reasons. If `Commit` returns `ABORTED`, the caller should re-attempt
      * the transaction from the beginning, re-using the same session.
+     * On very rare occasions, `Commit` might return `UNKNOWN`. This can happen,
+     * for example, if the client job experiences a 1+ hour networking failure.
+     * At that point, Cloud Spanner has lost track of the transaction outcome and
+     * we recommend that you perform another read from the database to see the
+     * state of things as they are now.
      * </pre>
      */
     public com.google.common.util.concurrent.ListenableFuture<com.google.spanner.v1.CommitResponse>

proto-google-cloud-spanner-v1/src/main/java/com/google/spanner/v1/CommitRequest.java

@@ -111,6 +111,11 @@ private CommitRequest(
                   input.readMessage(com.google.spanner.v1.Mutation.parser(), extensionRegistry));
               break;
             }
+          case 40:
+            {
+              returnCommitStats_ = input.readBool();
+              break;
+            }
           default:
             {
               if (!parseUnknownField(input, unknownFields, extensionRegistry, tag)) {
@@ -422,6 +427,26 @@ public com.google.spanner.v1.MutationOrBuilder getMutationsOrBuilder(int index)
     return mutations_.get(index);
   }
 
+  public static final int RETURN_COMMIT_STATS_FIELD_NUMBER = 5;
+  private boolean returnCommitStats_;
+  /**
+   *
+   *
+   * <pre>
+   * If `true`, then statistics related to the transaction will be included in
+   * the [CommitResponse][google.spanner.v1.CommitResponse.commit_stats]. Default value is
+   * `false`.
+   * </pre>
+   *
+   * <code>bool return_commit_stats = 5;</code>
+   *
+   * @return The returnCommitStats.
+   */
+  @java.lang.Override
+  public boolean getReturnCommitStats() {
+    return returnCommitStats_;
+  }
+
   private byte memoizedIsInitialized = -1;
 
   @java.lang.Override
@@ -448,6 +473,9 @@ public void writeTo(com.google.protobuf.CodedOutputStream output) throws java.io
     for (int i = 0; i < mutations_.size(); i++) {
       output.writeMessage(4, mutations_.get(i));
     }
+    if (returnCommitStats_ != false) {
+      output.writeBool(5, returnCommitStats_);
+    }
     unknownFields.writeTo(output);
   }
 
@@ -473,6 +501,9 @@ public int getSerializedSize() {
     for (int i = 0; i < mutations_.size(); i++) {
       size += com.google.protobuf.CodedOutputStream.computeMessageSize(4, mutations_.get(i));
     }
+    if (returnCommitStats_ != false) {
+      size += com.google.protobuf.CodedOutputStream.computeBoolSize(5, returnCommitStats_);
+    }
     size += unknownFields.getSerializedSize();
     memoizedSize = size;
     return size;
@@ -490,6 +521,7 @@ public boolean equals(final java.lang.Object obj) {
 
     if (!getSession().equals(other.getSession())) return false;
     if (!getMutationsList().equals(other.getMutationsList())) return false;
+    if (getReturnCommitStats() != other.getReturnCommitStats()) return false;
     if (!getTransactionCase().equals(other.getTransactionCase())) return false;
     switch (transactionCase_) {
       case 2:
@@ -518,6 +550,8 @@ public int hashCode() {
       hash = (37 * hash) + MUTATIONS_FIELD_NUMBER;
       hash = (53 * hash) + getMutationsList().hashCode();
     }
+    hash = (37 * hash) + RETURN_COMMIT_STATS_FIELD_NUMBER;
+    hash = (53 * hash) + com.google.protobuf.Internal.hashBoolean(getReturnCommitStats());
     switch (transactionCase_) {
       case 2:
         hash = (37 * hash) + TRANSACTION_ID_FIELD_NUMBER;
@@ -684,6 +718,8 @@ public Builder clear() {
       } else {
         mutationsBuilder_.clear();
       }
+      returnCommitStats_ = false;
+
       transactionCase_ = 0;
       transaction_ = null;
       return this;
@@ -733,6 +769,7 @@ public com.google.spanner.v1.CommitRequest buildPartial() {
       } else {
         result.mutations_ = mutationsBuilder_.build();
       }
+      result.returnCommitStats_ = returnCommitStats_;
       result.transactionCase_ = transactionCase_;
       onBuilt();
       return result;
@@ -814,6 +851,9 @@ public Builder mergeFrom(com.google.spanner.v1.CommitRequest other) {
           }
         }
       }
+      if (other.getReturnCommitStats() != false) {
+        setReturnCommitStats(other.getReturnCommitStats());
+      }
       switch (other.getTransactionCase()) {
         case TRANSACTION_ID:
           {
@@ -1712,6 +1752,64 @@ public java.util.List<com.google.spanner.v1.Mutation.Builder> getMutationsBuilde
       return mutationsBuilder_;
     }
 
+    private boolean returnCommitStats_;
+    /**
+     *
+     *
+     * <pre>
+     * If `true`, then statistics related to the transaction will be included in
+     * the [CommitResponse][google.spanner.v1.CommitResponse.commit_stats]. Default value is
+     * `false`.
+     * </pre>
+     *
+     * <code>bool return_commit_stats = 5;</code>
+     *
+     * @return The returnCommitStats.
+     */
+    @java.lang.Override
+    public boolean getReturnCommitStats() {
+      return returnCommitStats_;
+    }
+    /**
+     *
+     *
+     * <pre>
+     * If `true`, then statistics related to the transaction will be included in
+     * the [CommitResponse][google.spanner.v1.CommitResponse.commit_stats]. Default value is
+     * `false`.
+     * </pre>
+     *
+     * <code>bool return_commit_stats = 5;</code>
+     *
+     * @param value The returnCommitStats to set.
+     * @return This builder for chaining.
+     */
+    public Builder setReturnCommitStats(boolean value) {
+
+      returnCommitStats_ = value;
+      onChanged();
+      return this;
+    }
+    /**
+     *
+     *
+     * <pre>
+     * If `true`, then statistics related to the transaction will be included in
+     * the [CommitResponse][google.spanner.v1.CommitResponse.commit_stats]. Default value is
+     * `false`.
+     * </pre>
+     *
+     * <code>bool return_commit_stats = 5;</code>
+     *
+     * @return This builder for chaining.
+     */
+    public Builder clearReturnCommitStats() {
+
+      returnCommitStats_ = false;
+      onChanged();
+      return this;
+    }
+
     @java.lang.Override
     public final Builder setUnknownFields(final com.google.protobuf.UnknownFieldSet unknownFields) {
       return super.setUnknownFields(unknownFields);

proto-google-cloud-spanner-v1/src/main/java/com/google/spanner/v1/CommitRequestOrBuilder.java

@@ -185,5 +185,20 @@ public interface CommitRequestOrBuilder
    */
   com.google.spanner.v1.MutationOrBuilder getMutationsOrBuilder(int index);
 
+  /**
+   *
+   *
+   * <pre>
+   * If `true`, then statistics related to the transaction will be included in
+   * the [CommitResponse][google.spanner.v1.CommitResponse.commit_stats]. Default value is
+   * `false`.
+   * </pre>
+   *
+   * <code>bool return_commit_stats = 5;</code>
+   *
+   * @return The returnCommitStats.
+   */
+  boolean getReturnCommitStats();
+
   public com.google.spanner.v1.CommitRequest.TransactionCase getTransactionCase();
 }