google-cloud-spanner 2.21.0 → 2.23.0

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

@@ -18,6 +18,7 @@ require "google/cloud/spanner/results"
 require "google/cloud/spanner/commit"
 require "google/cloud/spanner/commit_response"
 require "google/cloud/spanner/batch_update"
+require "google/cloud/spanner/batch_write"
 
 module Google
   module Cloud
@@ -116,6 +117,7 @@ module Google
         #   | `BOOL`      | `true`/`false` | |
         #   | `INT64`     | `Integer`      | |
         #   | `FLOAT64`   | `Float`        | |
+        #   | `FLOAT32`   | `Float`        | |
         #   | `NUMERIC`   | `BigDecimal`   | |
         #   | `STRING`    | `String`       | |
         #   | `DATE`      | `Date`         | |
@@ -142,6 +144,7 @@ module Google
         #   * `:BYTES`
         #   * `:DATE`
         #   * `:FLOAT64`
+        #   * `:FLOAT32`
         #   * `:NUMERIC`
         #   * `:INT64`
         #   * `:STRING`
@@ -562,6 +565,9 @@ module Google
         # @param [String] transaction_id The identifier of previously-started
         #   transaction to be used instead of starting a new transaction.
         #   Optional.
+        # @param [Boolean] exclude_txn_from_change_streams If set to true,
+        #   mutations will not be recorded in change streams with DDL option
+        #   `allow_txn_exclusion=true`. Used if starting a new transaction.
         # @param [Hash] commit_options A hash of commit options.
         #   e.g., return_commit_stats. Commit options are optional.
         #   The following options can be provided:
@@ -639,13 +645,14 @@ module Google
         #   puts commit_resp.timestamp
         #   puts commit_resp.stats.mutation_count
         #
-        def commit transaction_id: nil, commit_options: nil,
-                   request_options: nil, call_options: nil
+        def commit transaction_id: nil, exclude_txn_from_change_streams: false,
+                   commit_options: nil, request_options: nil, call_options: nil
           ensure_service!
           commit = Commit.new
           yield commit
           commit_resp = service.commit path, commit.mutations,
                                        transaction_id: transaction_id,
+                                       exclude_txn_from_change_streams: exclude_txn_from_change_streams,
                                        commit_options: commit_options,
                                        request_options: request_options,
                                        call_options: call_options
@@ -654,6 +661,103 @@ module Google
           commit_options ? resp : resp.timestamp
         end
 
+        ##
+        # Batches the supplied mutation groups in a collection of efficient
+        # transactions.
+        #
+        # All mutations in a group are committed atomically. However, mutations
+        # across groups can be committed non-atomically in an unspecified order
+        # and thus they must be independent of each other. Partial failure is
+        # possible, i.e., some groups may have been committed successfully,
+        # while others may have failed. The results of individual batches are
+        # streamed into the response as the batches are applied.
+        #
+        # BatchWrite requests are not replay protected, meaning that each mutation
+        # group may be applied more than once. Replays of non-idempotent mutations
+        # may have undesirable effects. For example, replays of an insert mutation
+        # may produce an already exists error or if you use generated or commit
+        # timestamp-based keys, it may result in additional rows being added to the
+        # mutation's table. We recommend structuring your mutation groups to be
+        # idempotent to avoid this issue.
+        #
+        # @param [Boolean] exclude_txn_from_change_streams If set to true,
+        #   mutations will not be recorded in change streams with DDL option
+        #   `allow_txn_exclusion=true`.
+        # @param [Hash] request_options Common request options.
+        #
+        #   * `:priority` (String) The relative priority for requests.
+        #     The priority acts as a hint to the Cloud Spanner scheduler
+        #     and does not guarantee priority or order of execution.
+        #     Valid values are `:PRIORITY_LOW`, `:PRIORITY_MEDIUM`,
+        #     `:PRIORITY_HIGH`. If priority not set then default is
+        #     `PRIORITY_UNSPECIFIED` is equivalent to `:PRIORITY_HIGH`.
+        #   * `:tag` (String) A per-request tag which can be applied to
+        #     queries or reads, used for statistics collection. Tag must be a
+        #     valid identifier of the form: `[a-zA-Z][a-zA-Z0-9_\-]` between 2
+        #     and 64 characters in length.
+        #
+        # @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_write] a batch write object
+        # @yieldparam [Google::Cloud::Spanner::BatchWrite] batch_write a batch
+        #   write object used to add mutaion groups through {MutationGroup}.
+        #
+        # @return [Google::Cloud::Spanner::BatchWriteResults] The results of
+        #   the batch write operation. This is a stream of responses, each
+        #   covering a set of the mutation groups that were either applied or
+        #   failed together.
+        #
+        # @example
+        #   require "google/cloud/spanner"
+        #
+        #   spanner = Google::Cloud::Spanner.new
+        #
+        #   db = spanner.client "my-instance", "my-database"
+        #
+        #   results = db.batch_write do |b|
+        #     # First mutation group
+        #     b.mutation_group do |mg|
+        #       mg.upsert "Singers", [{ SingerId: 16, FirstName: "Charlie", LastName: "Terry" }]
+        #     end
+        #
+        #     # Second mutation group
+        #     b.mutation_group do |mg|
+        #       mg.upsert "Singers", [{ SingerId: 17, FirstName: "Catalina", LastName: "Smith" }]
+        #       mg.update "Albums", [{ SingerId: 17, AlbumId: 1, AlbumTitle: "Go Go Go" }]
+        #     end
+        #   end
+        #
+        #   results.each do |response|
+        #     puts "groups applied: #{response.indexes}" if response.ok?
+        #   end
+        #
+        def batch_write exclude_txn_from_change_streams: false,
+                        request_options: nil,
+                        call_options: nil
+          ensure_service!
+          b = BatchWrite.new
+          yield b
+          response = service.batch_write path, b.mutation_groups_grpc,
+                                         exclude_txn_from_change_streams: exclude_txn_from_change_streams,
+                                         request_options: request_options,
+                                         call_options: call_options
+          results = BatchWriteResults.new response
+          @last_updated_at = Time.now
+          results
+        end
+
         ##
         # Inserts or updates rows in a table. If any of the rows already exist,
         # then its column values are overwritten with the ones provided. Any
@@ -672,6 +776,7 @@ module Google
         #   | `BOOL`      | `true`/`false` | |
         #   | `INT64`     | `Integer`      | |
         #   | `FLOAT64`   | `Float`        | |
+        #   | `FLOAT32`   | `Float`        | |
         #   | `NUMERIC`   | `BigDecimal`   | |
         #   | `STRING`    | `String`       | |
         #   | `DATE`      | `Date`         | |
@@ -682,6 +787,12 @@ module Google
         #   See [Data
         #   types](https://cloud.google.com/spanner/docs/data-definition-language#data_types).
         #
+        # @param [String] transaction_id The identifier of previously-started
+        #   transaction to be used instead of starting a new transaction.
+        #   Optional.
+        # @param [Boolean] exclude_txn_from_change_streams If set to true,
+        #   mutations will not be recorded in change streams with DDL option
+        #   `allow_txn_exclusion=true`. Used if starting a new transaction.
         # @param [Hash] commit_options A hash of commit options.
         #   e.g., return_commit_stats. Commit options are optional.
         #   The following options can be provided:
@@ -752,10 +863,12 @@ module Google
         #   puts commit_resp.timestamp
         #   puts commit_resp.stats.mutation_count
         #
-        def upsert table, *rows, transaction_id: nil, commit_options: nil,
-                   request_options: nil, call_options: nil
+        def upsert table, *rows,
+                   transaction_id: nil, exclude_txn_from_change_streams: false,
+                   commit_options: nil, request_options: nil, call_options: nil
           opts = {
             transaction_id: transaction_id,
+            exclude_txn_from_change_streams: exclude_txn_from_change_streams,
             commit_options: commit_options,
             request_options: request_options,
             call_options: call_options
@@ -783,6 +896,7 @@ module Google
         #   | `BOOL`      | `true`/`false` | |
         #   | `INT64`     | `Integer`      | |
         #   | `FLOAT64`   | `Float`        | |
+        #   | `FLOAT32`   | `Float`        | |
         #   | `NUMERIC`   | `BigDecimal`   | |
         #   | `STRING`    | `String`       | |
         #   | `DATE`      | `Date`         | |
@@ -793,6 +907,12 @@ module Google
         #   See [Data
         #   types](https://cloud.google.com/spanner/docs/data-definition-language#data_types).
         #
+        # @param [String] transaction_id The identifier of previously-started
+        #   transaction to be used instead of starting a new transaction.
+        #   Optional.
+        # @param [Boolean] exclude_txn_from_change_streams If set to true,
+        #   mutations will not be recorded in change streams with DDL option
+        #   `allow_txn_exclusion=true`. Used if starting a new transaction.
         # @param [Hash] commit_options A hash of commit options.
         #   e.g., return_commit_stats. Commit options are optional.
         #   The following options can be provided:
@@ -863,10 +983,12 @@ module Google
         #   puts commit_resp.timestamp
         #   puts commit_resp.stats.mutation_count
         #
-        def insert table, *rows, transaction_id: nil, commit_options: nil,
-                   request_options: nil, call_options: nil
+        def insert table, *rows,
+                   transaction_id: nil, exclude_txn_from_change_streams: false,
+                   commit_options: nil, request_options: nil, call_options: nil
           opts = {
             transaction_id: transaction_id,
+            exclude_txn_from_change_streams: exclude_txn_from_change_streams,
             commit_options: commit_options,
             request_options: request_options,
             call_options: call_options
@@ -893,6 +1015,7 @@ module Google
         #   | `BOOL`      | `true`/`false` | |
         #   | `INT64`     | `Integer`      | |
         #   | `FLOAT64`   | `Float`        | |
+        #   | `FLOAT32`   | `Float`        | |
         #   | `NUMERIC`   | `BigDecimal`   | |
         #   | `STRING`    | `String`       | |
         #   | `DATE`      | `Date`         | |
@@ -903,6 +1026,12 @@ module Google
         #   See [Data
         #   types](https://cloud.google.com/spanner/docs/data-definition-language#data_types).
         #
+        # @param [String] transaction_id The identifier of previously-started
+        #   transaction to be used instead of starting a new transaction.
+        #   Optional.
+        # @param [Boolean] exclude_txn_from_change_streams If set to true,
+        #   mutations will not be recorded in change streams with DDL option
+        #   `allow_txn_exclusion=true`. Used if starting a new transaction.
         # @param [Hash] commit_options A hash of commit options.
         #   e.g., return_commit_stats. Commit options are optional.
         #   The following options can be provided:
@@ -973,10 +1102,12 @@ module Google
         #   puts commit_resp.timestamp
         #   puts commit_resp.stats.mutation_count
         #
-        def update table, *rows, transaction_id: nil, commit_options: nil,
-                   request_options: nil, call_options: nil
+        def update table, *rows,
+                   transaction_id: nil, exclude_txn_from_change_streams: false,
+                   commit_options: nil, request_options: nil, call_options: nil
           opts = {
             transaction_id: transaction_id,
+            exclude_txn_from_change_streams: exclude_txn_from_change_streams,
             commit_options: commit_options,
             request_options: request_options,
             call_options: call_options
@@ -1005,6 +1136,7 @@ module Google
         #   | `BOOL`      | `true`/`false` | |
         #   | `INT64`     | `Integer`      | |
         #   | `FLOAT64`   | `Float`        | |
+        #   | `FLOAT32`   | `Float`        | |
         #   | `NUMERIC`   | `BigDecimal`   | |
         #   | `STRING`    | `String`       | |
         #   | `DATE`      | `Date`         | |
@@ -1015,6 +1147,12 @@ module Google
         #   See [Data
         #   types](https://cloud.google.com/spanner/docs/data-definition-language#data_types).
         #
+        # @param [String] transaction_id The identifier of previously-started
+        #   transaction to be used instead of starting a new transaction.
+        #   Optional.
+        # @param [Boolean] exclude_txn_from_change_streams If set to true,
+        #   mutations will not be recorded in change streams with DDL option
+        #   `allow_txn_exclusion=true`. Used if starting a new transaction.
         # @param [Hash] commit_options A hash of commit options.
         #   e.g., return_commit_stats. Commit options are optional.
         #   The following options can be provided:
@@ -1086,10 +1224,12 @@ module Google
         #   puts commit_resp.timestamp
         #   puts commit_resp.stats.mutation_count
         #
-        def replace table, *rows, transaction_id: nil, commit_options: nil,
-                    request_options: nil, call_options: nil
+        def replace table, *rows,
+                    transaction_id: nil, exclude_txn_from_change_streams: false,
+                    commit_options: nil, request_options: nil, call_options: nil
           opts = {
             transaction_id: transaction_id,
+            exclude_txn_from_change_streams: exclude_txn_from_change_streams,
             commit_options: commit_options,
             request_options: request_options,
             call_options: call_options
@@ -1108,6 +1248,12 @@ 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.
+        # @param [String] transaction_id The identifier of previously-started
+        #   transaction to be used instead of starting a new transaction.
+        #   Optional.
+        # @param [Boolean] exclude_txn_from_change_streams If set to true,
+        #   mutations will not be recorded in change streams with DDL option
+        #   `allow_txn_exclusion=true`. Used if starting a new transaction.
         # @param [Hash] commit_options A hash of commit options.
         #   e.g., return_commit_stats. Commit options are optional.
         #   The following options can be provided:
@@ -1175,10 +1321,12 @@ module Google
         #   puts commit_resp.timestamp
         #   puts commit_resp.stats.mutation_count
         #
-        def delete table, keys = [], transaction_id: nil, commit_options: nil,
-                   request_options: nil, call_options: nil
+        def delete table, keys = [],
+                   transaction_id: nil, exclude_txn_from_change_streams: false,
+                   commit_options: nil, request_options: nil, call_options: nil
           opts = {
             transaction_id: transaction_id,
+            exclude_txn_from_change_streams: exclude_txn_from_change_streams,
             commit_options: commit_options,
             request_options: request_options,
             call_options: call_options
@@ -1199,18 +1347,20 @@ module Google
         ##
         # @private
         # Creates a new transaction object every time.
-        def create_transaction
+        def create_transaction exclude_txn_from_change_streams: false
           route_to_leader = LARHeaders.begin_transaction true
-          tx_grpc = service.begin_transaction path, route_to_leader: route_to_leader
-          Transaction.from_grpc tx_grpc, self
+          tx_grpc = service.begin_transaction path,
+                                              route_to_leader: route_to_leader,
+                                              exclude_txn_from_change_streams: exclude_txn_from_change_streams
+          Transaction.from_grpc tx_grpc, self, exclude_txn_from_change_streams: exclude_txn_from_change_streams
         end
 
         ##
         # @private
         # Creates a new transaction object without the grpc object
         # within it. Use it for inline-begin of a transaction.
-        def create_empty_transaction
-          Transaction.from_grpc nil, self
+        def create_empty_transaction exclude_txn_from_change_streams: false
+          Transaction.from_grpc nil, self, exclude_txn_from_change_streams: exclude_txn_from_change_streams
         end
 
         ##

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

@@ -83,6 +83,7 @@ module Google
         #   | `BOOL`      | `true`/`false` | |
         #   | `INT64`     | `Integer`      | |
         #   | `FLOAT64`   | `Float`        | |
+        #   | `FLOAT32`   | `Float`        | |
         #   | `NUMERIC`   | `BigDecimal`   | |
         #   | `STRING`    | `String`       | |
         #   | `DATE`      | `Date`         | |
@@ -109,6 +110,7 @@ module Google
         #   * `:BYTES`
         #   * `:DATE`
         #   * `:FLOAT64`
+        #   * `:FLOAT32`
         #   * `:NUMERIC`
         #   * `:INT64`
         #   * `:STRING`
@@ -310,7 +312,7 @@ module Google
                                      transaction: tx_selector,
                                      query_options: query_options,
                                      call_options: call_options,
-                                     directed_read_options: (directed_read_options || @directed_read_options)
+                                     directed_read_options: directed_read_options || @directed_read_options
         end
         alias execute execute_query
         alias query execute_query
@@ -387,7 +389,7 @@ module Google
           session.read table, columns, keys: keys, index: index, limit: limit,
                                        transaction: tx_selector,
                                        call_options: call_options,
-                                       directed_read_options: (directed_read_options || @directed_read_options)
+                                       directed_read_options: directed_read_options || @directed_read_options
         end
 
         ##
@@ -416,6 +418,7 @@ module Google
         #   * `:BYTES`
         #   * `:DATE`
         #   * `:FLOAT64`
+        #   * `:FLOAT32`
         #   * `:NUMERIC`
         #   * `:INT64`
         #   * `:STRING`

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

@@ -85,9 +85,13 @@ module Google
         # @private Transaction tag for statistics collection.
         attr_accessor :transaction_tag
 
+        # @private Whether to exclude from change streams.
+        attr_accessor :exclude_txn_from_change_streams
+
         def initialize
           @commit = Commit.new
           @seqno = 0
+          @exclude_txn_from_change_streams = false
 
           # Mutex to enfore thread safety for transaction creation and query executions.
           #
@@ -139,6 +143,7 @@ module Google
         #   | `BOOL`      | `true`/`false` | |
         #   | `INT64`     | `Integer`      | |
         #   | `FLOAT64`   | `Float`        | |
+        #   | `FLOAT32`   | `Float`        | |
         #   | `NUMERIC`   | `BigDecimal`   | |
         #   | `STRING`    | `String`       | |
         #   | `DATE`      | `Date`         | |
@@ -165,6 +170,7 @@ module Google
         #   * `:BYTES`
         #   * `:DATE`
         #   * `:FLOAT64`
+        #   * `:FLOAT32`
         #   * `:NUMERIC`
         #   * `:INT64`
         #   * `:STRING`
@@ -402,6 +408,7 @@ module Google
         #   | `BOOL`      | `true`/`false` | |
         #   | `INT64`     | `Integer`      | |
         #   | `FLOAT64`   | `Float`        | |
+        #   | `FLOAT32`   | `Float`        | |
         #   | `NUMERIC`   | `BigDecimal`   | |
         #   | `STRING`    | `String`       | |
         #   | `DATE`      | `Date`         | |
@@ -429,6 +436,7 @@ module Google
         #   * `:BYTES`
         #   * `:DATE`
         #   * `:FLOAT64`
+        #   * `:FLOAT32`
         #   * `:NUMERIC`
         #   * `:INT64`
         #   * `:STRING`
@@ -752,6 +760,7 @@ module Google
         #   | `BOOL`      | `true`/`false` | |
         #   | `INT64`     | `Integer`      | |
         #   | `FLOAT64`   | `Float`        | |
+        #   | `FLOAT32`   | `Float`        | |
         #   | `NUMERIC`   | `BigDecimal`   | |
         #   | `STRING`    | `String`       | |
         #   | `DATE`      | `Date`         | |
@@ -799,6 +808,7 @@ module Google
         #   | `BOOL`      | `true`/`false` | |
         #   | `INT64`     | `Integer`      | |
         #   | `FLOAT64`   | `Float`        | |
+        #   | `FLOAT32`   | `Float`        | |
         #   | `NUMERIC`   | `BigDecimal`   | |
         #   | `STRING`    | `String`       | |
         #   | `DATE`      | `Date`         | |
@@ -845,6 +855,7 @@ module Google
         #   | `BOOL`      | `true`/`false` | |
         #   | `INT64`     | `Integer`      | |
         #   | `FLOAT64`   | `Float`        | |
+        #   | `FLOAT32`   | `Float`        | |
         #   | `NUMERIC`   | `BigDecimal`   | |
         #   | `STRING`    | `String`       | |
         #   | `DATE`      | `Date`         | |
@@ -893,6 +904,7 @@ module Google
         #   | `BOOL`      | `true`/`false` | |
         #   | `INT64`     | `Integer`      | |
         #   | `FLOAT64`   | `Float`        | |
+        #   | `FLOAT32`   | `Float`        | |
         #   | `NUMERIC`   | `BigDecimal`   | |
         #   | `STRING`    | `String`       | |
         #   | `DATE`      | `Date`         | |
@@ -995,6 +1007,7 @@ module Google
         #   * `:BYTES`
         #   * `:DATE`
         #   * `:FLOAT64`
+        #   * `:FLOAT32`
         #   * `:NUMERIC`
         #   * `:INT64`
         #   * `:STRING`
@@ -1143,10 +1156,11 @@ module Google
         ##
         # @private Creates a new Transaction instance from a
         # `Google::Cloud::Spanner::V1::Transaction`.
-        def self.from_grpc grpc, session
+        def self.from_grpc grpc, session, exclude_txn_from_change_streams: false
           new.tap do |s|
             s.instance_variable_set :@grpc,    grpc
             s.instance_variable_set :@session, session
+            s.exclude_txn_from_change_streams = exclude_txn_from_change_streams
           end
         end
 
@@ -1207,11 +1221,12 @@ module Google
         #
         #   This method is expected to be called from within `safe_execute()` method's block,
         #   since it provides synchronization and gurantees thread safety.
-        def tx_selector
+        def tx_selector exclude_txn_from_change_streams: false
           return V1::TransactionSelector.new id: transaction_id if existing_transaction?
           V1::TransactionSelector.new(
             begin: V1::TransactionOptions.new(
-              read_write: V1::TransactionOptions::ReadWrite.new
+              read_write: V1::TransactionOptions::ReadWrite.new,
+              exclude_txn_from_change_streams: exclude_txn_from_change_streams
             )
           )
         end

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

@@ -16,7 +16,7 @@
 module Google
   module Cloud
     module Spanner
-      VERSION = "2.21.0".freeze
+      VERSION = "2.23.0".freeze
     end
   end
 end

data/lib/google-cloud-spanner.rb

@@ -74,8 +74,9 @@ module Google
     #   spanner = gcloud.spanner scope: platform_scope
     #
     def spanner scope: nil, timeout: nil, lib_name: nil, lib_version: nil
+      timeout ||= @timeout
       Google::Cloud.spanner @project, @keyfile, scope: scope,
-                                                timeout: (timeout || @timeout),
+                                                timeout: timeout,
                                                 lib_name: lib_name,
                                                 lib_version: lib_version
     end
@@ -130,8 +131,10 @@ module Google
       require "google/cloud/spanner"
       Google::Cloud::Spanner.new project_id: project_id,
                                  credentials: credentials,
-                                 scope: scope, timeout: timeout,
-                                 lib_name: lib_name, lib_version: lib_version
+                                 scope: scope,
+                                 timeout: timeout,
+                                 lib_name: lib_name,
+                                 lib_version: lib_version
     end
   end
 end