google-cloud-spanner 2.0.0 → 2.5.0

data/lib/google/cloud/spanner/session.rb

@@ -16,6 +16,7 @@
 require "google/cloud/spanner/data"
 require "google/cloud/spanner/results"
 require "google/cloud/spanner/commit"
+require "google/cloud/spanner/commit_response"
 require "google/cloud/spanner/batch_update"
 
 module Google
@@ -162,6 +163,19 @@ module Google
         #   * `:optimizer_version` (String) The version of optimizer to use.
         #     Empty to use database default. "latest" to use the latest
         #     available optimizer version.
+        # @param [Hash] call_options A hash of values to specify the custom
+        #   call options, e.g., timeout, retries, etc. Call options are
+        #   optional. The following settings can be provided:
+        #
+        #   * `:timeout` (Numeric) A numeric value of custom timeout in seconds
+        #     that overrides the default setting.
+        #   * `:retry_policy` (Hash) A hash of values that overrides the default
+        #     setting of retry policy with the following keys:
+        #     * `:initial_delay` (`Numeric`) - The initial delay in seconds.
+        #     * `:max_delay` (`Numeric`) - The max delay in seconds.
+        #     * `:multiplier` (`Numeric`) - The incremental backoff multiplier.
+        #     * `:retry_codes` (`Array<String>`) - The error codes that should
+        #       trigger a retry.
         #
         # @return [Google::Cloud::Spanner::Results] The results of the query
         #   execution.
@@ -275,8 +289,32 @@ module Google
         #     puts "User #{row[:id]} is #{row[:name]}"
         #   end
         #
+        # @example Query using custom timeout and retry policy:
+        #   require "google/cloud/spanner"
+        #
+        #   spanner = Google::Cloud::Spanner.new
+        #
+        #   db = spanner.client "my-instance", "my-database"
+        #
+        #   timeout = 30.0
+        #   retry_policy = {
+        #     initial_delay: 0.25,
+        #     max_delay:     32.0,
+        #     multiplier:    1.3,
+        #     retry_codes:   ["UNAVAILABLE"]
+        #   }
+        #   call_options = { timeout: timeout, retry_policy: retry_policy }
+        #
+        #   results = db.execute_query \
+        #     "SELECT * FROM users", call_options: call_options
+        #
+        #   results.rows.each do |row|
+        #     puts "User #{row[:id]} is #{row[:name]}"
+        #   end
+        #
         def execute_query sql, params: nil, types: nil, transaction: nil,
-                          partition_token: nil, seqno: nil, query_options: nil
+                          partition_token: nil, seqno: nil, query_options: nil,
+                          call_options: nil
           ensure_service!
           if query_options.nil?
             query_options = @query_options
@@ -289,7 +327,8 @@ module Google
                                           transaction: transaction,
                                           partition_token: partition_token,
                                           seqno: seqno,
-                                          query_options: query_options
+                                          query_options: query_options,
+                                          call_options: call_options
           @last_updated_at = Time.now
           results
         end
@@ -302,6 +341,20 @@ module Google
         #   transactions.
         # @param [Integer] seqno A per-transaction sequence number used to
         #   identify this request.
+        # @param [Hash] call_options A hash of values to specify the custom
+        #   call options, e.g., timeout, retries, etc. Call options are
+        #   optional. The following settings can be provided:
+        #
+        #   * `:timeout` (Numeric) A numeric value of custom timeout in seconds
+        #     that overrides the default setting.
+        #   * `:retry_policy` (Hash) A hash of values that overrides the default
+        #     setting of retry policy with the following keys:
+        #     * `:initial_delay` (`Numeric`) - The initial delay in seconds.
+        #     * `:max_delay` (`Numeric`) - The max delay in seconds.
+        #     * `:multiplier` (`Numeric`) - The incremental backoff multiplier.
+        #     * `:retry_codes` (`Array<String>`) - The error codes that should
+        #       trigger a retry.
+        #
         # @yield [batch_update] a batch update object
         # @yieldparam [Google::Cloud::Spanner::BatchUpdate] batch_update a batch
         #   update object accepting DML statements and optional parameters and
@@ -316,7 +369,7 @@ module Google
         # @return [Array<Integer>] A list with the exact number of rows that
         #   were modified for each DML statement.
         #
-        def batch_update transaction, seqno
+        def batch_update transaction, seqno, call_options: nil
           ensure_service!
 
           raise ArgumentError, "block is required" unless block_given?
@@ -325,7 +378,8 @@ module Google
           yield batch
 
           results = service.execute_batch_dml path, transaction,
-                                              batch.statements, seqno
+                                              batch.statements, seqno,
+                                              call_options: call_options
           @last_updated_at = Time.now
           results
         end
@@ -349,6 +403,19 @@ module Google
         # @param [Google::Cloud::Spanner::V1::TransactionSelector] transaction The
         #   transaction selector value to send. Only used for single-use
         #   transactions.
+        # @param [Hash] call_options A hash of values to specify the custom
+        #   call options, e.g., timeout, retries, etc. Call options are
+        #   optional. The following settings can be provided:
+        #
+        #   * `:timeout` (Numeric) A numeric value of custom timeout in seconds
+        #     that overrides the default setting.
+        #   * `:retry_policy` (Hash) A hash of values that overrides the default
+        #     setting of retry policy with the following keys:
+        #     * `:initial_delay` (`Numeric`) - The initial delay in seconds.
+        #     * `:max_delay` (`Numeric`) - The max delay in seconds.
+        #     * `:multiplier` (`Numeric`) - The incremental backoff multiplier.
+        #     * `:retry_codes` (`Array<String>`) - The error codes that should
+        #       trigger a retry.
         #
         # @return [Google::Cloud::Spanner::Results] The results of the read
         #   operation.
@@ -367,25 +434,28 @@ module Google
         #   end
         #
         def read table, columns, keys: nil, index: nil, limit: nil,
-                 transaction: nil, partition_token: nil
+                 transaction: nil, partition_token: nil, call_options: nil
           ensure_service!
 
           results = Results.read service, path, table, columns,
                                  keys: keys, index: index, limit: limit,
                                  transaction: transaction,
-                                 partition_token: partition_token
+                                 partition_token: partition_token,
+                                 call_options: call_options
           @last_updated_at = Time.now
           results
         end
 
         def partition_query sql, transaction, params: nil, types: nil,
-                            partition_size_bytes: nil, max_partitions: nil
+                            partition_size_bytes: nil, max_partitions: nil,
+                            call_options: nil
           ensure_service!
 
           results = service.partition_query \
             path, sql, transaction, params: params, types: types,
                                     partition_size_bytes: partition_size_bytes,
-                                    max_partitions: max_partitions
+                                    max_partitions: max_partitions,
+                                    call_options: call_options
 
           @last_updated_at = Time.now
 
@@ -394,14 +464,15 @@ module Google
 
         def partition_read table, columns, transaction, keys: nil,
                            index: nil, partition_size_bytes: nil,
-                           max_partitions: nil
+                           max_partitions: nil, call_options: nil
           ensure_service!
 
           results = service.partition_read \
             path, table, columns, transaction,
             keys: keys, index: index,
             partition_size_bytes: partition_size_bytes,
-            max_partitions: max_partitions
+            max_partitions: max_partitions,
+            call_options: call_options
 
           @last_updated_at = Time.now
 
@@ -414,10 +485,34 @@ module Google
         # @param [String] transaction_id The identifier of previously-started
         #   transaction to be used instead of starting a new transaction.
         #   Optional.
+        # @param [Hash] commit_options A hash of commit options.
+        #   e.g., return_commit_stats. Commit options are optional.
+        #   The following options can be provided:
+        #
+        #   * `:return_commit_stats` (Boolean) A boolean value. If `true`,
+        #     then statistics related to the transaction will be included in
+        #     {CommitResponse}. Default value is `false`
+        #
+        # transaction. Default it is `false`.
+        # @param [Hash] call_options A hash of values to specify the custom
+        #   call options, e.g., timeout, retries, etc. Call options are
+        #   optional. The following settings can be provided:
+        #
+        #   * `:timeout` (Numeric) A numeric value of custom timeout in seconds
+        #     that overrides the default setting.
+        #   * `:retry_policy` (Hash) A hash of values that overrides the default
+        #     setting of retry policy with the following keys:
+        #     * `:initial_delay` (`Numeric`) - The initial delay in seconds.
+        #     * `:max_delay` (`Numeric`) - The max delay in seconds.
+        #     * `:multiplier` (`Numeric`) - The incremental backoff multiplier.
+        #     * `:retry_codes` (`Array<String>`) - The error codes that should
+        #       trigger a retry.
+        #
         # @yield [commit] The block for mutating the data.
         # @yieldparam [Google::Cloud::Spanner::Commit] commit The Commit object.
         #
-        # @return [Time] The timestamp at which the operation committed.
+        # @return [Time, CommitResponse] The timestamp at which the operation
+        #   committed. If commit options are set it returns {CommitResponse}.
         #
         # @example
         #   require "google/cloud/spanner"
@@ -431,14 +526,33 @@ module Google
         #     c.insert "users", [{ id: 2, name: "Harvey",  active: true }]
         #   end
         #
-        def commit transaction_id: nil
+        # @example Get commit stats
+        #   require "google/cloud/spanner"
+        #
+        #   spanner = Google::Cloud::Spanner.new
+        #
+        #   db = spanner.client "my-instance", "my-database"
+        #
+        #   commit_options = { return_commit_stats: true }
+        #   commit_resp = db.commit commit_options: commit_options do |c|
+        #     c.update "users", [{ id: 1, name: "Charlie", active: false }]
+        #     c.insert "users", [{ id: 2, name: "Harvey",  active: true }]
+        #   end
+        #
+        #   puts commit_resp.timestamp
+        #   puts commit_resp.stats.mutation_count
+        #
+        def commit transaction_id: nil, commit_options: nil, call_options: nil
           ensure_service!
           commit = Commit.new
           yield commit
           commit_resp = service.commit path, commit.mutations,
-                                       transaction_id: transaction_id
+                                       transaction_id: transaction_id,
+                                       commit_options: commit_options,
+                                       call_options: call_options
           @last_updated_at = Time.now
-          Convert.timestamp_to_time commit_resp.commit_timestamp
+          resp = CommitResponse.from_grpc commit_resp
+          commit_options ? resp : resp.timestamp
         end
 
         ##
@@ -468,7 +582,30 @@ module Google
         #   See [Data
         #   types](https://cloud.google.com/spanner/docs/data-definition-language#data_types).
         #
-        # @return [Time] The timestamp at which the operation committed.
+        # @param [Hash] commit_options A hash of commit options.
+        #   e.g., return_commit_stats. Commit options are optional.
+        #   The following options can be provided:
+        #
+        #   * `:return_commit_stats` (Boolean) A boolean value. If `true`,
+        #     then statistics related to the transaction will be included in
+        #     {CommitResponse}. Default value is `false`
+        #
+        # @param [Hash] call_options A hash of values to specify the custom
+        #   call options, e.g., timeout, retries, etc. Call options are
+        #   optional. The following settings can be provided:
+        #
+        #   * `:timeout` (Numeric) A numeric value of custom timeout in seconds
+        #     that overrides the default setting.
+        #   * `:retry_policy` (Hash) A hash of values that overrides the default
+        #     setting of retry policy with the following keys:
+        #     * `:initial_delay` (`Numeric`) - The initial delay in seconds.
+        #     * `:max_delay` (`Numeric`) - The max delay in seconds.
+        #     * `:multiplier` (`Numeric`) - The incremental backoff multiplier.
+        #     * `:retry_codes` (`Array<String>`) - The error codes that should
+        #       trigger a retry.
+        #
+        # @return [Time, CommitResponse] The timestamp at which the operation
+        #   committed. If commit options are set it returns {CommitResponse}.
         #
         # @example
         #   require "google/cloud/spanner"
@@ -480,8 +617,29 @@ module Google
         #   db.upsert "users", [{ id: 1, name: "Charlie", active: false },
         #                       { id: 2, name: "Harvey",  active: true }]
         #
-        def upsert table, *rows, transaction_id: nil
-          commit transaction_id: transaction_id do |c|
+        # @example Get commit stats
+        #   require "google/cloud/spanner"
+        #
+        #   spanner = Google::Cloud::Spanner.new
+        #
+        #   db = spanner.client "my-instance", "my-database"
+        #
+        #   records = [{ id: 1, name: "Charlie", active: false },
+        #             { id: 2, name: "Harvey",  active: true }]
+        #   commit_options = { return_commit_stats: true }
+        #   commit_resp = db.upsert "users", records, commit_options: commit_options
+        #
+        #   puts commit_resp.timestamp
+        #   puts commit_resp.stats.mutation_count
+        #
+        def upsert table, *rows, transaction_id: nil, commit_options: nil,
+                   call_options: nil
+          opts = {
+            transaction_id: transaction_id,
+            commit_options: commit_options,
+            call_options: call_options
+          }
+          commit(**opts) do |c|
             c.upsert table, rows
           end
         end
@@ -513,7 +671,30 @@ module Google
         #   See [Data
         #   types](https://cloud.google.com/spanner/docs/data-definition-language#data_types).
         #
-        # @return [Time] The timestamp at which the operation committed.
+        # @param [Hash] commit_options A hash of commit options.
+        #   e.g., return_commit_stats. Commit options are optional.
+        #   The following options can be provided:
+        #
+        #   * `:return_commit_stats` (Boolean) A boolean value. If `true`,
+        #     then statistics related to the transaction will be included in
+        #     {CommitResponse}. Default value is `false`
+        #
+        # @param [Hash] call_options A hash of values to specify the custom
+        #   call options, e.g., timeout, retries, etc. Call options are
+        #   optional. The following settings can be provided:
+        #
+        #   * `:timeout` (Numeric) A numeric value of custom timeout in seconds
+        #     that overrides the default setting.
+        #   * `:retry_policy` (Hash) A hash of values that overrides the default
+        #     setting of retry policy with the following keys:
+        #     * `:initial_delay` (`Numeric`) - The initial delay in seconds.
+        #     * `:max_delay` (`Numeric`) - The max delay in seconds.
+        #     * `:multiplier` (`Numeric`) - The incremental backoff multiplier.
+        #     * `:retry_codes` (`Array<String>`) - The error codes that should
+        #       trigger a retry.
+        #
+        # @return [Time, CommitResponse] The timestamp at which the operation
+        #   committed. If commit options are set it returns {CommitResponse}.
         #
         # @example
         #   require "google/cloud/spanner"
@@ -525,8 +706,29 @@ module Google
         #   db.insert "users", [{ id: 1, name: "Charlie", active: false },
         #                       { id: 2, name: "Harvey",  active: true }]
         #
-        def insert table, *rows, transaction_id: nil
-          commit transaction_id: transaction_id do |c|
+        # @example Get commit stats
+        #   require "google/cloud/spanner"
+        #
+        #   spanner = Google::Cloud::Spanner.new
+        #
+        #   db = spanner.client "my-instance", "my-database"
+        #
+        #   records = [{ id: 1, name: "Charlie", active: false },
+        #              { id: 2, name: "Harvey",  active: true }]
+        #   commit_options = { return_commit_stats: true }
+        #   commit_resp = db.insert "users", records, commit_options: commit_options
+        #
+        #   puts commit_resp.timestamp
+        #   puts commit_resp.stats.mutation_count
+        #
+        def insert table, *rows, transaction_id: nil, commit_options: nil,
+                   call_options: nil
+          opts = {
+            transaction_id: transaction_id,
+            commit_options: commit_options,
+            call_options: call_options
+          }
+          commit(**opts) do |c|
             c.insert table, rows
           end
         end
@@ -557,7 +759,30 @@ module Google
         #   See [Data
         #   types](https://cloud.google.com/spanner/docs/data-definition-language#data_types).
         #
-        # @return [Time] The timestamp at which the operation committed.
+        # @param [Hash] commit_options A hash of commit options.
+        #   e.g., return_commit_stats. Commit options are optional.
+        #   The following options can be provided:
+        #
+        #   * `:return_commit_stats` (Boolean) A boolean value. If `true`,
+        #     then statistics related to the transaction will be included in
+        #     {CommitResponse}. Default value is `false`
+        #
+        # @param [Hash] call_options A hash of values to specify the custom
+        #   call options, e.g., timeout, retries, etc. Call options are
+        #   optional. The following settings can be provided:
+        #
+        #   * `:timeout` (Numeric) A numeric value of custom timeout in seconds
+        #     that overrides the default setting.
+        #   * `:retry_policy` (Hash) A hash of values that overrides the default
+        #     setting of retry policy with the following keys:
+        #     * `:initial_delay` (`Numeric`) - The initial delay in seconds.
+        #     * `:max_delay` (`Numeric`) - The max delay in seconds.
+        #     * `:multiplier` (`Numeric`) - The incremental backoff multiplier.
+        #     * `:retry_codes` (`Array<String>`) - The error codes that should
+        #       trigger a retry.
+        #
+        # @return [Time, CommitResponse] The timestamp at which the operation
+        #   committed. If commit options are set it returns {CommitResponse}.
         #
         # @example
         #   require "google/cloud/spanner"
@@ -569,8 +794,29 @@ module Google
         #   db.update "users", [{ id: 1, name: "Charlie", active: false },
         #                       { id: 2, name: "Harvey",  active: true }]
         #
-        def update table, *rows, transaction_id: nil
-          commit transaction_id: transaction_id do |c|
+        # @example Get commit stats
+        #   require "google/cloud/spanner"
+        #
+        #   spanner = Google::Cloud::Spanner.new
+        #
+        #   db = spanner.client "my-instance", "my-database"
+        #
+        #   records = [{ id: 1, name: "Charlie", active: false },
+        #              { id: 2, name: "Harvey",  active: true }]
+        #   commit_options = { return_commit_stats: true  }
+        #   commit_resp = db.update "users", records, commit_options: commit_options
+        #
+        #   puts commit_resp.timestamp
+        #   puts commit_resp.stats.mutation_count
+        #
+        def update table, *rows, transaction_id: nil, commit_options: nil,
+                   call_options: nil
+          opts = {
+            transaction_id: transaction_id,
+            commit_options: commit_options,
+            call_options: call_options
+          }
+          commit(**opts) do |c|
             c.update table, rows
           end
         end
@@ -603,7 +849,30 @@ module Google
         #   See [Data
         #   types](https://cloud.google.com/spanner/docs/data-definition-language#data_types).
         #
-        # @return [Time] The timestamp at which the operation committed.
+        # @param [Hash] commit_options A hash of commit options.
+        #   e.g., return_commit_stats. Commit options are optional.
+        #   The following options can be provided:
+        #
+        #   * `:return_commit_stats` (Boolean) A boolean value. If `true`,
+        #     then statistics related to the transaction will be included in
+        #     {CommitResponse}. Default value is `false`.
+        #
+        # @param [Hash] call_options A hash of values to specify the custom
+        #   call options, e.g., timeout, retries, etc. Call options are
+        #   optional. The following settings can be provided:
+        #
+        #   * `:timeout` (Numeric) A numeric value of custom timeout in seconds
+        #     that overrides the default setting.
+        #   * `:retry_policy` (Hash) A hash of values that overrides the default
+        #     setting of retry policy with the following keys:
+        #     * `:initial_delay` (`Numeric`) - The initial delay in seconds.
+        #     * `:max_delay` (`Numeric`) - The max delay in seconds.
+        #     * `:multiplier` (`Numeric`) - The incremental backoff multiplier.
+        #     * `:retry_codes` (`Array<String>`) - The error codes that should
+        #       trigger a retry.
+        #
+        # @return [Time, CommitResponse] The timestamp at which the operation
+        #   committed. If commit options are set it returns {CommitResponse}.
         #
         # @example
         #   require "google/cloud/spanner"
@@ -615,8 +884,29 @@ module Google
         #   db.replace "users", [{ id: 1, name: "Charlie", active: false },
         #                        { id: 2, name: "Harvey",  active: true }]
         #
-        def replace table, *rows, transaction_id: nil
-          commit transaction_id: transaction_id do |c|
+        # @example Get commit stats
+        #   require "google/cloud/spanner"
+        #
+        #   spanner = Google::Cloud::Spanner.new
+        #
+        #   db = spanner.client "my-instance", "my-database"
+        #
+        #   records = [{ id: 1, name: "Charlie", active: false },
+        #              { id: 2, name: "Harvey",  active: true }]
+        #   commit_options = { return_commit_stats: true  }
+        #   commit_resp = db.replace "users", records, commit_options: commit_options
+        #
+        #   puts commit_resp.timestamp
+        #   puts commit_resp.stats.mutation_count
+        #
+        def replace table, *rows, transaction_id: nil, commit_options: nil,
+                    call_options: nil
+          opts = {
+            transaction_id: transaction_id,
+            commit_options: commit_options,
+            call_options: call_options
+          }
+          commit(**opts) do |c|
             c.replace table, rows
           end
         end
@@ -630,8 +920,30 @@ module Google
         # @param [Object, Array<Object>] keys A single, or list of keys or key
         #   ranges to match returned data to. Values should have exactly as many
         #   elements as there are columns in the primary key.
-        #
-        # @return [Time] The timestamp at which the operation committed.
+        # @param [Hash] commit_options A hash of commit options.
+        #   e.g., return_commit_stats. Commit options are optional.
+        #   The following options can be provided:
+        #
+        #   * `:return_commit_stats` (Boolean) A boolean value. If `true`,
+        #     then statistics related to the transaction will be included in
+        #     {CommitResponse}. Default value is `false`
+        #
+        # @param [Hash] call_options A hash of values to specify the custom
+        #   call options, e.g., timeout, retries, etc. Call options are
+        #   optional. The following settings can be provided:
+        #
+        #   * `:timeout` (Numeric) A numeric value of custom timeout in seconds
+        #     that overrides the default setting.
+        #   * `:retry_policy` (Hash) A hash of values that overrides the default
+        #     setting of retry policy with the following keys:
+        #     * `:initial_delay` (`Numeric`) - The initial delay in seconds.
+        #     * `:max_delay` (`Numeric`) - The max delay in seconds.
+        #     * `:multiplier` (`Numeric`) - The incremental backoff multiplier.
+        #     * `:retry_codes` (`Array<String>`) - The error codes that should
+        #       trigger a retry.
+        #
+        # @return [Time, CommitResponse] The timestamp at which the operation
+        #   committed. If commit options are set it returns {CommitResponse}.
         #
         # @example
         #   require "google/cloud/spanner"
@@ -642,8 +954,27 @@ module Google
         #
         #   db.delete "users", [1, 2, 3]
         #
-        def delete table, keys = [], transaction_id: nil
-          commit transaction_id: transaction_id do |c|
+        # @example Get commit stats
+        #   require "google/cloud/spanner"
+        #
+        #   spanner = Google::Cloud::Spanner.new
+        #
+        #   db = spanner.client "my-instance", "my-database"
+        #
+        #   commit_options = { return_commit_stats: true }
+        #   commit_resp = db.delete "users", [1,2,3], commit_options: commit_options
+        #
+        #   puts commit_resp.timestamp
+        #   puts commit_resp.stats.mutation_count
+        #
+        def delete table, keys = [], transaction_id: nil, commit_options: nil,
+                   call_options: nil
+          opts = {
+            transaction_id: transaction_id,
+            commit_options: commit_options,
+            call_options: call_options
+          }
+          commit(**opts) do |c|
             c.delete table, keys
           end
         end