feat: add RPC Priority request options

Google APIs · copybara-github · commit 6598bb829c9e · 2021-03-22T17:40:03.000-07:00
PiperOrigin-RevId: 364449524
diff --git a/google/spanner/v1/spanner.proto b/google/spanner/v1/spanner.proto
@@ -425,6 +425,42 @@ message DeleteSessionRequest {
   ];
 }
 
+// Common request options for various APIs.
+message RequestOptions {
+  // The relative priority for requests. Note that priority is not applicable
+  // for [BeginTransaction][google.spanner.v1.Spanner.BeginTransaction].
+  //
+  // The priority acts as a hint to the Cloud Spanner scheduler and does not
+  // guarantee priority or order of execution. For example:
+  //
+  // * Some parts of a write operation always execute at `PRIORITY_HIGH`,
+  //   regardless of the specified priority. This may cause you to see an
+  //   increase in high priority workload even when executing a low priority
+  //   request. This can also potentially cause a priority inversion where a
+  //   lower priority request will be fulfilled ahead of a higher priority
+  //   request.
+  // * If a transaction contains multiple operations with different priorities,
+  //   Cloud Spanner does not guarantee to process the higher priority
+  //   operations first. There may be other constraints to satisfy, such as
+  //   order of operations.
+  enum Priority {
+    // `PRIORITY_UNSPECIFIED` is equivalent to `PRIORITY_HIGH`.
+    PRIORITY_UNSPECIFIED = 0;
+
+    // This specifies that the request is low priority.
+    PRIORITY_LOW = 1;
+
+    // This specifies that the request is medium priority.
+    PRIORITY_MEDIUM = 2;
+
+    // This specifies that the request is high priority.
+    PRIORITY_HIGH = 3;
+  }
+
+  // Priority for the request.
+  Priority priority = 1;
+}
+
 // The request for [ExecuteSql][google.spanner.v1.Spanner.ExecuteSql] and
 // [ExecuteStreamingSql][google.spanner.v1.Spanner.ExecuteStreamingSql].
 message ExecuteSqlRequest {
@@ -576,6 +612,9 @@ message ExecuteSqlRequest {
 
   // Query optimizer configuration to use for the given query.
   QueryOptions query_options = 10;
+
+  // Common options for this request.
+  RequestOptions request_options = 11;
 }
 
 // The request for [ExecuteBatchDml][google.spanner.v1.Spanner.ExecuteBatchDml].
@@ -642,6 +681,9 @@ message ExecuteBatchDmlRequest {
   // sequence number, the transaction may be aborted. Replays of previously
   // handled requests will yield the same response as the first execution.
   int64 seqno = 4 [(google.api.field_behavior) = REQUIRED];
+
+  // Common options for this request.
+  RequestOptions request_options = 5;
 }
 
 // The response for [ExecuteBatchDml][google.spanner.v1.Spanner.ExecuteBatchDml]. Contains a list
@@ -876,6 +918,9 @@ message ReadRequest {
   // match for the values of fields common to this message and the
   // PartitionReadRequest message used to create this partition_token.
   bytes partition_token = 10;
+
+  // Common options for this request.
+  RequestOptions request_options = 11;
 }
 
 // The request for [BeginTransaction][google.spanner.v1.Spanner.BeginTransaction].
@@ -890,6 +935,13 @@ message BeginTransactionRequest {
 
   // Required. Options for the new transaction.
   TransactionOptions options = 2 [(google.api.field_behavior) = REQUIRED];
+
+  // Common options for this request.
+  // Priority is ignored for this request. Setting the priority in this
+  // request_options struct will not do anything. To set the priority for a
+  // transaction, set it on the reads and writes that are part of this
+  // transaction instead.
+  RequestOptions request_options = 3;
 }
 
 // The request for [Commit][google.spanner.v1.Spanner.Commit].
@@ -928,6 +980,9 @@ message CommitRequest {
   // the [CommitResponse][google.spanner.v1.CommitResponse.commit_stats]. Default value is
   // `false`.
   bool return_commit_stats = 5;
+
+  // Common options for this request.
+  RequestOptions request_options = 6;
 }
 
 // The response for [Commit][google.spanner.v1.Spanner.Commit].
