feat: add field order_by in spanner.proto

Google APIs · copybara-github · commit eeed69d446a9 · 2024-05-23T19:58:48.000-07:00
feat: add field lock_hint in spanner.proto

PiperOrigin-RevId: 636759139
diff --git a/google/spanner/v1/spanner.proto b/google/spanner/v1/spanner.proto
@@ -1043,6 +1043,71 @@ message PartitionResponse {
 // The request for [Read][google.spanner.v1.Spanner.Read] and
 // [StreamingRead][google.spanner.v1.Spanner.StreamingRead].
 message ReadRequest {
+  // An option to control the order in which rows are returned from a read.
+  enum OrderBy {
+    // Default value.
+    //
+    // ORDER_BY_UNSPECIFIED is equivalent to ORDER_BY_PRIMARY_KEY.
+    ORDER_BY_UNSPECIFIED = 0;
+
+    // Read rows are returned in primary key order.
+    //
+    // In the event that this option is used in conjunction with the
+    // `partition_token` field, the API will return an `INVALID_ARGUMENT` error.
+    ORDER_BY_PRIMARY_KEY = 1;
+
+    // Read rows are returned in any order.
+    ORDER_BY_NO_ORDER = 2;
+  }
+
+  // A lock hint mechanism for reads done within a transaction.
+  enum LockHint {
+    // Default value.
+    //
+    // LOCK_HINT_UNSPECIFIED is equivalent to LOCK_HINT_SHARED.
+    LOCK_HINT_UNSPECIFIED = 0;
+
+    // Acquire shared locks.
+    //
+    // By default when you perform a read as part of a read-write transaction,
+    // Spanner acquires shared read locks, which allows other reads to still
+    // access the data until your transaction is ready to commit. When your
+    // transaction is committing and writes are being applied, the transaction
+    // attempts to upgrade to an exclusive lock for any data you are writing.
+    // For more information about locks, see [Lock
+    // modes](https://cloud.google.com/spanner/docs/introspection/lock-statistics#explain-lock-modes).
+    LOCK_HINT_SHARED = 1;
+
+    // Acquire exclusive locks.
+    //
+    // Requesting exclusive locks is beneficial if you observe high write
+    // contention, which means you notice that multiple transactions are
+    // concurrently trying to read and write to the same data, resulting in a
+    // large number of aborts. This problem occurs when two transactions
+    // initially acquire shared locks and then both try to upgrade to exclusive
+    // locks at the same time. In this situation both transactions are waiting
+    // for the other to give up their lock, resulting in a deadlocked situation.
+    // Spanner is able to detect this occurring and force one of the
+    // transactions to abort. However, this is a slow and expensive operation
+    // and results in lower performance. In this case it makes sense to acquire
+    // exclusive locks at the start of the transaction because then when
+    // multiple transactions try to act on the same data, they automatically get
+    // serialized. Each transaction waits its turn to acquire the lock and
+    // avoids getting into deadlock situations.
+    //
+    // Because the exclusive lock hint is just a hint, it should not be
+    // considered equivalent to a mutex. In other words, you should not use
+    // Spanner exclusive locks as a mutual exclusion mechanism for the execution
+    // of code outside of Spanner.
+    //
+    // **Note:** Request exclusive locks judiciously because they block others
+    // from reading that data for the entire transaction, rather than just when
+    // the writes are being performed. Unless you observe high write contention,
+    // you should use the default of shared read locks so you don't prematurely
+    // block other clients from reading the data that you're writing to.
+    LOCK_HINT_EXCLUSIVE = 2;
+  }
+
   // Required. The session in which the read should be performed.
   string session = 1 [
     (google.api.field_behavior) = REQUIRED,
@@ -1117,6 +1182,19 @@ message ReadRequest {
   // If the field is set to `true` but the request does not set
   // `partition_token`, the API returns an `INVALID_ARGUMENT` error.
   bool data_boost_enabled = 15;
+
+  // Optional. Order for the returned rows.
+  //
+  // By default, Spanner will return result rows in primary key order except for
+  // PartitionRead requests. For applications that do not require rows to be
+  // returned in primary key (`ORDER_BY_PRIMARY_KEY`) order, setting
+  // `ORDER_BY_NO_ORDER` option allows Spanner to optimize row retrieval,
+  // resulting in lower latencies in certain cases (e.g. bulk point lookups).
+  OrderBy order_by = 16 [(google.api.field_behavior) = OPTIONAL];
+
+  // Optional. Lock Hint for the request, it can only be used with read-write
+  // transactions.
+  LockHint lock_hint = 17 [(google.api.field_behavior) = OPTIONAL];
 }
 
 // The request for
