feat(Spanner): Add directed read feature (#6078)

googleapis · Jan 5, 2024 · 4beb3c4 · 4beb3c4
1 parent 53ede15
commit 4beb3c4
Show file tree

Hide file tree

Showing 21 changed files with 681 additions and 44 deletions.
diff --git a/Spanner/src/Connection/Grpc.php b/Spanner/src/Connection/Grpc.php
@@ -47,6 +47,7 @@
 use Google\Cloud\Spanner\SpannerClient as ManualSpannerClient;
 use Google\Cloud\Spanner\V1\CreateSessionRequest;
 use Google\Cloud\Spanner\V1\DeleteSessionRequest;
+use Google\Cloud\Spanner\V1\DirectedReadOptions;
 use Google\Cloud\Spanner\V1\ExecuteBatchDmlRequest\Statement;
 use Google\Cloud\Spanner\V1\ExecuteSqlRequest\QueryOptions;
 use Google\Cloud\Spanner\V1\KeySet;
@@ -941,6 +942,7 @@ public function executeStreamingSql(array $args)
             $queryOptions += ['optimizerStatisticsPackage' => $envQueryOptimizerStatisticsPackage];
         }
         $queryOptions += $this->defaultQueryOptions;
+        $this->setDirectedReadOptions($args);
 
         if ($queryOptions) {
             $args['queryOptions'] = $this->serializer->decodeMessage(
@@ -980,7 +982,7 @@ public function streamingRead(array $args)
                 $requestOptions
             );
         }
-
+        $this->setDirectedReadOptions($args);
         $args['transaction'] = $this->createTransactionSelector($args);
 
         $databaseName = $this->pluck('database', $args);
@@ -1597,4 +1599,20 @@ private function getLroResponseMapper($typeUrl)
 
         return null;
     }
+
+    /**
+     * Set DirectedReadOptions if provided.
+     *
+     * @param array $args
+     */
+    private function setDirectedReadOptions(array &$args)
+    {
+        $directedReadOptions = $this->pluck('directedReadOptions', $args, false);
+        if (!empty($directedReadOptions)) {
+            $args['directedReadOptions'] = $this->serializer->decodeMessage(
+                new DirectedReadOptions,
+                $directedReadOptions
+            );
+        }
+    }
 }
diff --git a/Spanner/src/Database.php b/Spanner/src/Database.php
@@ -177,6 +177,11 @@ class Database
      */
     private $databaseRole;
 
+    /**
+     * @var array
+     */
+    private $directedReadOptions;
+
     /**
      * Create an object representing a Database.
      *
@@ -222,6 +227,7 @@ public function __construct(
 
         $this->setLroProperties($lroConnection, $lroCallables, $this->name);
         $this->databaseRole = $databaseRole;
+        $this->directedReadOptions = $instance->directedReadOptions();
     }
 
     /**
@@ -706,6 +712,10 @@ public function iam()
      *           **Defaults to** `false`.
      *     @type array $sessionOptions Session configuration and request options.
      *           Session labels may be applied using the `labels` key.
+     *     @type array $directedReadOptions Directed read options.
+     *           {@see \Google\Cloud\Spanner\V1\DirectedReadOptions}
+     *           If using the `replicaSelection::type` setting, utilize the constants available in
+     *           {@see \Google\Cloud\Spanner\V1\DirectedReadOptions\ReplicaSelection\Type} to set a value.
      * }
      * @return Snapshot
      * @throws \BadMethodCallException If attempting to call this method within
@@ -723,6 +733,10 @@ public function snapshot(array $options = [])
         ];
 
         $options['transactionOptions'] = $this->configureSnapshotOptions($options);
+        $options['directedReadOptions'] = $this->configureDirectedReadOptions(
+            $options,
+            $this->directedReadOptions ?? []
+        );
 
         $session = $this->selectSession(
             SessionPoolInterface::CONTEXT_READ,
@@ -994,7 +1008,7 @@ public function runTransaction(callable $operation, array $options = [])
      *
      *     @type array $requestOptions Request options.
      *         For more information on available options, please see
-     *         [the upstream documentation](https://cloud.google.com/spanner/docs/reference/rest/v1/RequestOptions).
+     *         [RequestOptions](https://cloud.google.com/spanner/docs/reference/rest/v1/RequestOptions).
      *         Please note, if using the `priority` setting you may utilize the constants available
      *         on {@see \Google\Cloud\Spanner\V1\RequestOptions\Priority} to set a value.
      *         Please note, the `transactionTag` setting will be ignored as it is not supported for single-use
@@ -1043,7 +1057,7 @@ public function insert($table, array $data, array $options = [])
      *
      *     @type array $requestOptions Request options.
      *         For more information on available options, please see
-     *         [the upstream documentation](https://cloud.google.com/spanner/docs/reference/rest/v1/RequestOptions).
+     *         [RequestOptions](https://cloud.google.com/spanner/docs/reference/rest/v1/RequestOptions).
      *         Please note, if using the `priority` setting you may utilize the constants available
      *         on {@see \Google\Cloud\Spanner\V1\RequestOptions\Priority} to set a value.
      *         Please note, the `transactionTag` setting will be ignored as it is not supported for single-use
@@ -1089,7 +1103,7 @@ public function insertBatch($table, array $dataSet, array $options = [])
      *
      *     @type array $requestOptions Request options.
      *         For more information on available options, please see
-     *         [the upstream documentation](https://cloud.google.com/spanner/docs/reference/rest/v1/RequestOptions).
+     *         [RequestOptions](https://cloud.google.com/spanner/docs/reference/rest/v1/RequestOptions).
      *         Please note, if using the `priority` setting you may utilize the constants available
      *         on {@see \Google\Cloud\Spanner\V1\RequestOptions\Priority} to set a value.
      *         Please note, the `transactionTag` setting will be ignored as it is not supported for single-use
@@ -1135,7 +1149,7 @@ public function update($table, array $data, array $options = [])
      *
      *     @type array $requestOptions Request options.
      *         For more information on available options, please see
-     *         [the upstream documentation](https://cloud.google.com/spanner/docs/reference/rest/v1/RequestOptions).
+     *         [RequestOptions](https://cloud.google.com/spanner/docs/reference/rest/v1/RequestOptions).
      *         Please note, if using the `priority` setting you may utilize the constants available
      *         on {@see \Google\Cloud\Spanner\V1\RequestOptions\Priority} to set a value.
      *         Please note, the `transactionTag` setting will be ignored as it is not supported for single-use
@@ -1182,7 +1196,7 @@ public function updateBatch($table, array $dataSet, array $options = [])
      *
      *     @type array $requestOptions Request options.
      *         For more information on available options, please see
-     *         [the upstream documentation](https://cloud.google.com/spanner/docs/reference/rest/v1/RequestOptions).
+     *         [RequestOptions](https://cloud.google.com/spanner/docs/reference/rest/v1/RequestOptions).
      *         Please note, if using the `priority` setting you may utilize the constants available
      *         on {@see \Google\Cloud\Spanner\V1\RequestOptions\Priority} to set a value.
      *         Please note, the `transactionTag` setting will be ignored as it is not supported for single-use
@@ -1230,7 +1244,7 @@ public function insertOrUpdate($table, array $data, array $options = [])
      *
      *     @type array $requestOptions Request options.
      *         For more information on available options, please see
-     *         [the upstream documentation](https://cloud.google.com/spanner/docs/reference/rest/v1/RequestOptions).
+     *         [RequestOptions](https://cloud.google.com/spanner/docs/reference/rest/v1/RequestOptions).
      *         Please note, if using the `priority` setting you may utilize the constants available
      *         on {@see \Google\Cloud\Spanner\V1\RequestOptions\Priority} to set a value.
      *         Please note, the `transactionTag` setting will be ignored as it is not supported for single-use
@@ -1277,7 +1291,7 @@ public function insertOrUpdateBatch($table, array $dataSet, array $options = [])
      *
      *     @type array $requestOptions Request options.
      *         For more information on available options, please see
-     *         [the upstream documentation](https://cloud.google.com/spanner/docs/reference/rest/v1/RequestOptions).
+     *         [RequestOptions](https://cloud.google.com/spanner/docs/reference/rest/v1/RequestOptions).
      *         Please note, if using the `priority` setting you may utilize the constants available
      *         on {@see \Google\Cloud\Spanner\V1\RequestOptions\Priority} to set a value.
      *         Please note, the `transactionTag` setting will be ignored as it is not supported for single-use
@@ -1325,7 +1339,7 @@ public function replace($table, array $data, array $options = [])
      *
      *     @type array $requestOptions Request options.
      *         For more information on available options, please see
-     *         [the upstream documentation](https://cloud.google.com/spanner/docs/reference/rest/v1/RequestOptions).
+     *         [RequestOptions](https://cloud.google.com/spanner/docs/reference/rest/v1/RequestOptions).
      *         Please note, if using the `priority` setting you may utilize the constants available
      *         on {@see \Google\Cloud\Spanner\V1\RequestOptions\Priority} to set a value.
      *         Please note, the `transactionTag` setting will be ignored as it is not supported for single-use
@@ -1375,7 +1389,7 @@ public function replaceBatch($table, array $dataSet, array $options = [])
      *
      *     @type array $requestOptions Request options.
      *         For more information on available options, please see
-     *         [the upstream documentation](https://cloud.google.com/spanner/docs/reference/rest/v1/RequestOptions).
+     *         [RequestOptions](https://cloud.google.com/spanner/docs/reference/rest/v1/RequestOptions).
      *         Please note, if using the `priority` setting you may utilize the constants available
      *         on {@see \Google\Cloud\Spanner\V1\RequestOptions\Priority} to set a value.
      *         Please note, the `transactionTag` setting will be ignored as it is not supported for single-use
@@ -1629,12 +1643,16 @@ public function delete($table, KeySet $keySet, array $options = [])
      *           optimizer version will fail with a syntax error
      *           (`INVALID_ARGUMENT`) status.
      *     @type array $requestOptions Request options.
-     *         For more information on available options, please see
-     *         [the upstream documentation](https://cloud.google.com/spanner/docs/reference/rest/v1/RequestOptions).
-     *         Please note, if using the `priority` setting you may utilize the constants available
-     *         on {@see \Google\Cloud\Spanner\V1\RequestOptions\Priority} to set a value.
-     *         Please note, the `transactionTag` setting will be ignored as it is not supported for read-only
-     *         transactions.
+     *           For more information on available options, please see
+     *           [RequestOptions](https://cloud.google.com/spanner/docs/reference/rest/v1/RequestOptions).
+     *           Please note, if using the `priority` setting you may utilize the constants available
+     *           on {@see \Google\Cloud\Spanner\V1\RequestOptions\Priority} to set a value.
+     *           Please note, the `transactionTag` setting will be ignored as it is not supported for read-only
+     *           transactions.
+     *     @type array $directedReadOptions Directed read options.
+     *           {@see \Google\Cloud\Spanner\V1\DirectedReadOptions}
+     *           If using the `replicaSelection::type` setting, utilize the constants available in
+     *           {@see \Google\Cloud\Spanner\V1\DirectedReadOptions\ReplicaSelection\Type} to set a value.
      * }
      * @codingStandardsIgnoreEnd
      * @return Result
@@ -1653,6 +1671,11 @@ public function execute($sql, array $options = [])
             $options['transactionContext']
         ) = $this->transactionSelector($options);
 
+        $options['directedReadOptions'] = $this->configureDirectedReadOptions(
+            $options,
+            $this->directedReadOptions ?? []
+        );
+
         try {
             return $this->operation->execute($session, $sql, $options);
         } finally {
@@ -1769,11 +1792,11 @@ public function execute($sql, array $options = [])
      *           parameter types. Likewise, for structs, use
      *           {@see \Google\Cloud\Spanner\StructType}.
      *     @type array $requestOptions Request options.
-     *         For more information on available options, please see
-     *         [the upstream documentation](https://cloud.google.com/spanner/docs/reference/rest/v1/RequestOptions).
-     *         Please note, if using the `priority` setting you may utilize the constants available
-     *         on {@see \Google\Cloud\Spanner\V1\RequestOptions\Priority} to set a value.
-     *         Please note, the `transactionTag` setting will be ignored as it is not supported for partitioned DML.
+     *           For more information on available options, please see
+     *           [RequestOptions](https://cloud.google.com/spanner/docs/reference/rest/v1/RequestOptions).
+     *           Please note, if using the `priority` setting you may utilize the constants available
+     *           on {@see \Google\Cloud\Spanner\V1\RequestOptions\Priority} to set a value.
+     *           Please note, the `transactionTag` setting will be ignored as it is not supported for partitioned DML.
      * }
      * @return int The number of rows modified.
      */
@@ -1901,11 +1924,15 @@ public function executePartitionedUpdate($statement, array $options = [])
      *     @type array $sessionOptions Session configuration and request options.
      *           Session labels may be applied using the `labels` key.
      *     @type array $requestOptions Request options.
-     *         For more information on available options, please see
-     *         [the upstream documentation](https://cloud.google.com/spanner/docs/reference/rest/v1/RequestOptions).
-     *         Please note, if using the `priority` setting you may utilize the constants available
-     *         on {@see \Google\Cloud\Spanner\V1\RequestOptions\Priority} to set a value.
-     *         Please note, the `transactionTag` setting will be ignored as it is not supported for read-only transactions.
+     *           For more information on available options, please see
+     *           [RequestOptions](https://cloud.google.com/spanner/docs/reference/rest/v1/RequestOptions).
+     *           Please note, if using the `priority` setting you may utilize the constants available
+     *           on {@see \Google\Cloud\Spanner\V1\RequestOptions\Priority} to set a value.
+     *           Please note, the `transactionTag` setting will be ignored as it is not supported for read-only transactions.
+     *     @type array $directedReadOptions Directed read options.
+     *           {@see \Google\Cloud\Spanner\V1\DirectedReadOptions}
+     *           If using the `replicaSelection::type` setting, utilize the constants available in
+     *           {@see \Google\Cloud\Spanner\V1\DirectedReadOptions\ReplicaSelection\Type} to set a value.
      * }
      * @codingStandardsIgnoreEnd
      * @return Result
@@ -1922,6 +1949,11 @@ public function read($table, KeySet $keySet, array $columns, array $options = []
         $options['transaction'] = $transactionOptions;
         $options['transactionContext'] = $context;
 
+        $options['directedReadOptions'] = $this->configureDirectedReadOptions(
+            $options,
+            $this->directedReadOptions ?? []
+        );
+
         try {
             return $this->operation->read($session, $table, $keySet, $columns, $options);
         } finally {
@@ -2100,7 +2132,7 @@ private function selectSession($context = SessionPoolInterface::CONTEXT_READ, ar
      *
      *     @type array $requestOptions Request options.
      *         For more information on available options, please see
-     *         [the upstream documentation](https://cloud.google.com/spanner/docs/reference/rest/v1/RequestOptions).
+     *         [RequestOptions](https://cloud.google.com/spanner/docs/reference/rest/v1/RequestOptions).
      *         Please note, if using the `priority` setting you may utilize the constants available
      *         on {@see \Google\Cloud\Spanner\V1\RequestOptions\Priority} to set a value.
      *         Please note, the `transactionTag` setting will be ignored as it is not supported for single-use transactions.

diff --git a/Spanner/src/Instance.php b/Spanner/src/Instance.php
@@ -122,6 +122,11 @@ class Instance
      */
     private $iam;
 
+    /**
+     * @var array
+     */
+    private $directedReadOptions;
+
     /**
      * Create an object representing a Cloud Spanner instance.
      *
@@ -137,6 +142,14 @@ class Instance
      *        returned as a {@see \Google\Cloud\Core\Int64} object for 32 bit platform
      *        compatibility. **Defaults to** false.
      * @param array $info [optional] A representation of the instance object.
+     * @param array $options [optional]{
+     *     Instance options
+     *
+     *     @type array $directedReadOptions Directed read options.
+     *           {@see \Google\Cloud\Spanner\V1\DirectedReadOptions}
+     *           If using the `replicaSelection::type` setting, utilize the constants available in
+     *           {@see \Google\Cloud\Spanner\V1\DirectedReadOptions\ReplicaSelection\Type} to set a value.
+     * }
      */
     public function __construct(
         ConnectionInterface $connection,
@@ -145,7 +158,8 @@ public function __construct(
         $projectId,
         $name,
         $returnInt64AsObject = false,
-        array $info = []
+        array $info = [],
+        array $options = []
     ) {
         $this->connection = $connection;
         $this->projectId = $projectId;
@@ -154,6 +168,7 @@ public function __construct(
         $this->info = $info;
 
         $this->setLroProperties($lroConnection, $lroCallables, $this->name);
+        $this->directedReadOptions = $options['directedReadOptions'] ?? [];
     }
 
     /**
@@ -794,4 +809,19 @@ public function __debugInfo()
             'info' => $this->info
         ];
     }
+
+    /**
+     * Return the directed read options.
+     *
+     * Example:
+     * ```
+     * $name = $instance->directedReadOptions();
+     * ```
+     *
+     * @return array
+     */
+    public function directedReadOptions()
+    {
+        return $this->directedReadOptions;
+    }
 }