feat: add RPC Priority request options

PiperOrigin-RevId: 364449524

Source-Author: Google APIs <[email protected]>
Source-Date: Mon Mar 22 17:39:37 2021 -0700
Source-Repo: googleapis/googleapis
Source-Sha: 6598bb829c9e9a534be674649ffd1b4671a821f9
Source-Link: googleapis/googleapis@6598bb8

Author: yoshi-automation

google/cloud/spanner_v1/proto/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].

google/cloud/spanner_v1/types/__init__.py

@@ -50,6 +50,7 @@
     PartitionReadRequest,
     PartitionResponse,
     ReadRequest,
+    RequestOptions,
     RollbackRequest,
     Session,
 )
@@ -93,6 +94,7 @@
     "PartitionReadRequest",
     "PartitionResponse",
     "ReadRequest",
+    "RequestOptions",
     "RollbackRequest",
     "Session",
     "Transaction",

google/cloud/spanner_v1/types/spanner.py

@@ -39,6 +39,7 @@
         "ListSessionsRequest",
         "ListSessionsResponse",
         "DeleteSessionRequest",
+        "RequestOptions",
         "ExecuteSqlRequest",
         "ExecuteBatchDmlRequest",
         "ExecuteBatchDmlResponse",
@@ -240,6 +241,41 @@ class DeleteSessionRequest(proto.Message):
     name = proto.Field(proto.STRING, number=1)
 
 
+class RequestOptions(proto.Message):
+    r"""Common request options for various APIs.
+
+    Attributes:
+        priority (google.cloud.spanner_v1.types.RequestOptions.Priority):
+            Priority for the request.
+    """
+
+    class Priority(proto.Enum):
+        r"""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.
+        """
+        PRIORITY_UNSPECIFIED = 0
+        PRIORITY_LOW = 1
+        PRIORITY_MEDIUM = 2
+        PRIORITY_HIGH = 3
+
+    priority = proto.Field(proto.ENUM, number=1, enum=Priority,)
+
+
 class ExecuteSqlRequest(proto.Message):
     r"""The request for [ExecuteSql][google.spanner.v1.Spanner.ExecuteSql]
     and
@@ -335,6 +371,8 @@ class ExecuteSqlRequest(proto.Message):
         query_options (google.cloud.spanner_v1.types.ExecuteSqlRequest.QueryOptions):
             Query optimizer configuration to use for the
             given query.
+        request_options (google.cloud.spanner_v1.types.RequestOptions):
+            Common options for this request.
     """
 
     class QueryMode(proto.Enum):
@@ -428,6 +466,8 @@ class QueryOptions(proto.Message):
 
     query_options = proto.Field(proto.MESSAGE, number=10, message=QueryOptions,)
 
+    request_options = proto.Field(proto.MESSAGE, number=11, message="RequestOptions",)
+
 
 class ExecuteBatchDmlRequest(proto.Message):
     r"""The request for
@@ -466,6 +506,8 @@ class ExecuteBatchDmlRequest(proto.Message):
             sequence number, the transaction may be aborted.
             Replays of previously handled requests will
             yield the same response as the first execution.
+        request_options (google.cloud.spanner_v1.types.RequestOptions):
+            Common options for this request.
     """
 
     class Statement(proto.Message):
@@ -523,6 +565,8 @@ class Statement(proto.Message):
 
     seqno = proto.Field(proto.INT64, number=4)
 
+    request_options = proto.Field(proto.MESSAGE, number=5, message="RequestOptions",)
+
 
 class ExecuteBatchDmlResponse(proto.Message):
     r"""The response for
@@ -867,6 +911,8 @@ class ReadRequest(proto.Message):
             must be an exact match for the values of fields common to
             this message and the PartitionReadRequest message used to
             create this partition_token.
+        request_options (google.cloud.spanner_v1.types.RequestOptions):
+            Common options for this request.
     """
 
     session = proto.Field(proto.STRING, number=1)
@@ -889,6 +935,8 @@ class ReadRequest(proto.Message):
 
     partition_token = proto.Field(proto.BYTES, number=10)
 
+    request_options = proto.Field(proto.MESSAGE, number=11, message="RequestOptions",)
+
 
 class BeginTransactionRequest(proto.Message):
     r"""The request for
@@ -900,6 +948,12 @@ class BeginTransactionRequest(proto.Message):
             transaction runs.
         options (google.cloud.spanner_v1.types.TransactionOptions):
             Required. Options for the new transaction.
+        request_options (google.cloud.spanner_v1.types.RequestOptions):
+            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.
     """
 
     session = proto.Field(proto.STRING, number=1)
@@ -908,6 +962,8 @@ class BeginTransactionRequest(proto.Message):
         proto.MESSAGE, number=2, message=gs_transaction.TransactionOptions,
     )
 
+    request_options = proto.Field(proto.MESSAGE, number=3, message="RequestOptions",)
+
 
 class CommitRequest(proto.Message):
     r"""The request for [Commit][google.spanner.v1.Spanner.Commit].
@@ -938,6 +994,8 @@ class CommitRequest(proto.Message):
             be included in the
             [CommitResponse][google.spanner.v1.CommitResponse.commit_stats].
             Default value is ``false``.
+        request_options (google.cloud.spanner_v1.types.RequestOptions):
+            Common options for this request.
     """
 
     session = proto.Field(proto.STRING, number=1)
@@ -955,6 +1013,8 @@ class CommitRequest(proto.Message):
 
     return_commit_stats = proto.Field(proto.BOOL, number=5)
 
+    request_options = proto.Field(proto.MESSAGE, number=6, message="RequestOptions",)
+
 
 class CommitResponse(proto.Message):
     r"""The response for [Commit][google.spanner.v1.Spanner.Commit].

scripts/fixup_spanner_v1_keywords.py

@@ -42,20 +42,20 @@ class spannerCallTransformer(cst.CSTTransformer):
     CTRL_PARAMS: Tuple[str] = ('retry', 'timeout', 'metadata')
     METHOD_TO_PARAMS: Dict[str, Tuple[str]] = {
     'batch_create_sessions': ('database', 'session_count', 'session_template', ),
-    'begin_transaction': ('session', 'options', ),
-    'commit': ('session', 'transaction_id', 'single_use_transaction', 'mutations', 'return_commit_stats', ),
+    'begin_transaction': ('session', 'options', 'request_options', ),
+    'commit': ('session', 'transaction_id', 'single_use_transaction', 'mutations', 'return_commit_stats', 'request_options', ),
     'create_session': ('database', 'session', ),
     'delete_session': ('name', ),
-    'execute_batch_dml': ('session', 'transaction', 'statements', 'seqno', ),
-    'execute_sql': ('session', 'sql', 'transaction', 'params', 'param_types', 'resume_token', 'query_mode', 'partition_token', 'seqno', 'query_options', ),
-    'execute_streaming_sql': ('session', 'sql', 'transaction', 'params', 'param_types', 'resume_token', 'query_mode', 'partition_token', 'seqno', 'query_options', ),
+    'execute_batch_dml': ('session', 'transaction', 'statements', 'seqno', 'request_options', ),
+    'execute_sql': ('session', 'sql', 'transaction', 'params', 'param_types', 'resume_token', 'query_mode', 'partition_token', 'seqno', 'query_options', 'request_options', ),
+    'execute_streaming_sql': ('session', 'sql', 'transaction', 'params', 'param_types', 'resume_token', 'query_mode', 'partition_token', 'seqno', 'query_options', 'request_options', ),
     'get_session': ('name', ),
     'list_sessions': ('database', 'page_size', 'page_token', 'filter', ),
     'partition_query': ('session', 'sql', 'transaction', 'params', 'param_types', 'partition_options', ),
     'partition_read': ('session', 'table', 'key_set', 'transaction', 'index', 'columns', 'partition_options', ),
-    'read': ('session', 'table', 'columns', 'key_set', 'transaction', 'index', 'limit', 'resume_token', 'partition_token', ),
+    'read': ('session', 'table', 'columns', 'key_set', 'transaction', 'index', 'limit', 'resume_token', 'partition_token', 'request_options', ),
     'rollback': ('session', 'transaction_id', ),
-    'streaming_read': ('session', 'table', 'columns', 'key_set', 'transaction', 'index', 'limit', 'resume_token', 'partition_token', ),
+    'streaming_read': ('session', 'table', 'columns', 'key_set', 'transaction', 'index', 'limit', 'resume_token', 'partition_token', 'request_options', ),
 
     }
 

synth.metadata

@@ -11,8 +11,8 @@
       "git": {
         "name": "googleapis",
         "remote": "https://github.com/googleapis/googleapis.git",
-        "sha": "149a3a84c29c9b8189576c7442ccb6dcf6a8f95b",
-        "internalRef": "364411656"
+        "sha": "6598bb829c9e9a534be674649ffd1b4671a821f9",
+        "internalRef": "364449524"
       }
     },
     {