google-cloud-spanner 2.22.0 → 2.24.0

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

@@ -0,0 +1,288 @@
+# Copyright 2024 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+module Google
+  module Cloud
+    module Spanner
+      ##
+      # Part of the BatchWrite DSL. This object defines a group of mutations
+      # to be included in a BatchWrite operation. All writes within a mutation
+      # group will execute atomically at a single logical point in time across
+      # columns, rows, and tables in a database.
+      #
+      # All changes are accumulated in memory until the block passed to
+      # {Client#batch_write} completes.
+      #
+      # @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
+      #
+      class MutationGroup
+        # @private
+        def initialize
+          @commit = Commit.new
+        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
+        # column values not explicitly written are preserved.
+        #
+        # All changes are accumulated in memory until the block passed to
+        # {Client#batch_write} completes.
+        #
+        # @param [String] table The name of the table in the database to be
+        #   modified.
+        # @param [Array<Hash>] rows One or more hash objects with the hash keys
+        #   matching the table's columns, and the hash values matching the
+        #   table's values.
+        #
+        #   Ruby types are mapped to Spanner types as follows:
+        #
+        #   | Spanner     | Ruby           | Notes  |
+        #   |-------------|----------------|---|
+        #   | `BOOL`      | `true`/`false` | |
+        #   | `INT64`     | `Integer`      | |
+        #   | `FLOAT64`   | `Float`        | |
+        #   | `FLOAT32`   | `Float`        | |
+        #   | `NUMERIC`   | `BigDecimal`   | |
+        #   | `STRING`    | `String`       | |
+        #   | `DATE`      | `Date`         | |
+        #   | `TIMESTAMP` | `Time`, `DateTime` | |
+        #   | `BYTES`     | `File`, `IO`, `StringIO`, or similar | |
+        #   | `ARRAY`     | `Array` | Nested arrays are not supported. |
+        #
+        #   See [Data
+        #   types](https://cloud.google.com/spanner/docs/data-definition-language#data_types).
+        #
+        # @example
+        #   require "google/cloud/spanner"
+        #
+        #   spanner = Google::Cloud::Spanner.new
+        #
+        #   db = spanner.client "my-instance", "my-database"
+        #
+        #   results = db.batch_write do |b|
+        #     b.mutation_group do |mg|
+        #       mg.upsert "Singers", [{ SingerId: 16, FirstName: "Charlie", LastName: "Terry" }]
+        #     end
+        #   end
+        #
+        def upsert table, *rows
+          @commit.upsert table, rows
+        end
+        alias save upsert
+
+        ##
+        # Inserts new rows in a table. If any of the rows already exist, the
+        # write or request fails with error {Google::Cloud::AlreadyExistsError}.
+        #
+        # All changes are accumulated in memory until the block passed to
+        # {Client#batch_write} completes.
+        #
+        # @param [String] table The name of the table in the database to be
+        #   modified.
+        # @param [Array<Hash>] rows One or more hash objects with the hash keys
+        #   matching the table's columns, and the hash values matching the
+        #   table's values.
+        #
+        #   Ruby types are mapped to Spanner types as follows:
+        #
+        #   | Spanner     | Ruby           | Notes  |
+        #   |-------------|----------------|---|
+        #   | `BOOL`      | `true`/`false` | |
+        #   | `INT64`     | `Integer`      | |
+        #   | `FLOAT64`   | `Float`        | |
+        #   | `FLOAT32`   | `Float`        | |
+        #   | `NUMERIC`   | `BigDecimal`   | |
+        #   | `STRING`    | `String`       | |
+        #   | `DATE`      | `Date`         | |
+        #   | `TIMESTAMP` | `Time`, `DateTime` | |
+        #   | `BYTES`     | `File`, `IO`, `StringIO`, or similar | |
+        #   | `ARRAY`     | `Array` | Nested arrays are not supported. |
+        #
+        #   See [Data
+        #   types](https://cloud.google.com/spanner/docs/data-definition-language#data_types).
+        #
+        # @example
+        #   require "google/cloud/spanner"
+        #
+        #   spanner = Google::Cloud::Spanner.new
+        #
+        #   db = spanner.client "my-instance", "my-database"
+        #
+        #   results = db.batch_write do |b|
+        #     b.mutation_group do |mg|
+        #       mg.insert "Singers", [{ SingerId: 16, FirstName: "Charlie", LastName: "Terry" }]
+        #     end
+        #   end
+        #
+        def insert table, *rows
+          @commit.insert table, rows
+        end
+
+        ##
+        # Updates existing rows in a table. If any of the rows does not already
+        # exist, the request fails with error {Google::Cloud::NotFoundError}.
+        #
+        # All changes are accumulated in memory until the block passed to
+        # {Client#batch_write} completes.
+        #
+        # @param [String] table The name of the table in the database to be
+        #   modified.
+        # @param [Array<Hash>] rows One or more hash objects with the hash keys
+        #   matching the table's columns, and the hash values matching the
+        #   table's values.
+        #
+        #   Ruby types are mapped to Spanner types as follows:
+        #
+        #   | Spanner     | Ruby           | Notes  |
+        #   |-------------|----------------|---|
+        #   | `BOOL`      | `true`/`false` | |
+        #   | `INT64`     | `Integer`      | |
+        #   | `FLOAT64`   | `Float`        | |
+        #   | `FLOAT32`   | `Float`        | |
+        #   | `NUMERIC`   | `BigDecimal`   | |
+        #   | `STRING`    | `String`       | |
+        #   | `DATE`      | `Date`         | |
+        #   | `TIMESTAMP` | `Time`, `DateTime` | |
+        #   | `BYTES`     | `File`, `IO`, `StringIO`, or similar | |
+        #   | `ARRAY`     | `Array` | Nested arrays are not supported. |
+        #
+        #   See [Data
+        #   types](https://cloud.google.com/spanner/docs/data-definition-language#data_types).
+        #
+        # @example
+        #   require "google/cloud/spanner"
+        #
+        #   spanner = Google::Cloud::Spanner.new
+        #
+        #   db = spanner.client "my-instance", "my-database"
+        #
+        #   results = db.batch_write do |b|
+        #     b.mutation_group do |mg|
+        #       mg.update "Singers", [{ SingerId: 16, FirstName: "Charlie", LastName: "Terry" }]
+        #     end
+        #   end
+        #
+        def update table, *rows
+          @commit.update table, rows
+        end
+
+        ##
+        # Inserts or replaces rows in a table. If any of the rows already exist,
+        # it is deleted, and the column values provided are inserted instead.
+        # Unlike #upsert, this means any values not explicitly written become
+        # `NULL`.
+        #
+        # All changes are accumulated in memory until the block passed to
+        # {Client#batch_write} completes.
+        #
+        # @param [String] table The name of the table in the database to be
+        #   modified.
+        # @param [Array<Hash>] rows One or more hash objects with the hash keys
+        #   matching the table's columns, and the hash values matching the
+        #   table's values.
+        #
+        #   Ruby types are mapped to Spanner types as follows:
+        #
+        #   | Spanner     | Ruby           | Notes  |
+        #   |-------------|----------------|---|
+        #   | `BOOL`      | `true`/`false` | |
+        #   | `INT64`     | `Integer`      | |
+        #   | `FLOAT64`   | `Float`        | |
+        #   | `FLOAT32`   | `Float`        | |
+        #   | `NUMERIC`   | `BigDecimal`   | |
+        #   | `STRING`    | `String`       | |
+        #   | `DATE`      | `Date`         | |
+        #   | `TIMESTAMP` | `Time`, `DateTime` | |
+        #   | `BYTES`     | `File`, `IO`, `StringIO`, or similar | |
+        #   | `ARRAY`     | `Array` | Nested arrays are not supported. |
+        #
+        #   See [Data
+        #   types](https://cloud.google.com/spanner/docs/data-definition-language#data_types).
+        #
+        # @example
+        #   require "google/cloud/spanner"
+        #
+        #   spanner = Google::Cloud::Spanner.new
+        #
+        #   db = spanner.client "my-instance", "my-database"
+        #
+        #   results = db.batch_write do |b|
+        #     b.mutation_group do |mg|
+        #       mg.replace "Singers", [{ SingerId: 16, FirstName: "Charlie", LastName: "Terry" }]
+        #     end
+        #   end
+        #
+        def replace table, *rows
+          @commit.replace table, rows
+        end
+
+        ##
+        # Deletes rows from a table. Succeeds whether or not the specified rows
+        # were present.
+        #
+        # All changes are accumulated in memory until the block passed to
+        # {Client#batch_write} completes.
+        #
+        # @param [String] table The name of the table in the database to be
+        #   modified.
+        # @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.
+        #
+        # @example
+        #   require "google/cloud/spanner"
+        #
+        #   spanner = Google::Cloud::Spanner.new
+        #
+        #   db = spanner.client "my-instance", "my-database"
+        #
+        #   results = db.batch_write do |b|
+        #     b.mutation_group do |mg|
+        #       mg.delete "Singers", [1, 2, 3]
+        #     end
+        #   end
+        #
+        def delete table, keys = []
+          @commit.delete table, keys
+        end
+
+        ##
+        # @private
+        # All of the mutations created in the transaction block.
+        def mutations
+          @commit.mutations
+        end
+      end
+    end
+  end
+end

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

@@ -106,9 +106,7 @@ module Google
         # @return [Array<Google::Cloud::Spanner::Instance>] The list of
         #   instances. (See {Google::Cloud::Spanner::Instance::List})
         #
-        # @deprecated Use
-        # {Google::Cloud::Spanner::Admin::Instance#instance_admin Client#list_instances}
-        # instead.
+        # @deprecated Use {Google::Cloud::Spanner::Admin::Instance.instance_admin}.list_instances instead.
         #
         # @example
         #   require "google/cloud/spanner"
@@ -144,9 +142,7 @@ module Google
         # @return [Google::Cloud::Spanner::Instance, nil] The instance, or `nil`
         #   if the instance does not exist.
         #
-        # @deprecated Use
-        # {Google::Cloud::Spanner::Admin::Instance#instance_admin Client#get_instance}
-        # instead.
+        # @deprecated Use {Google::Cloud::Spanner::Admin::Instance.instance_admin}.get_instance instead.
         #
         # @example
         #   require "google/cloud/spanner"
@@ -208,9 +204,7 @@ module Google
         #   asynchronous processing of an instance create operation.
         # @raise [ArgumentError] if both processing_units or nodes are specified.
         #
-        # @deprecated Use
-        # {Google::Cloud::Spanner::Admin::Instance#instance_admin Client#create_instance}
-        # instead.
+        # @deprecated Use {Google::Cloud::Spanner::Admin::Instance.instance_admin}.create_instance instead.
         #
         # @example
         #   require "google/cloud/spanner"
@@ -278,9 +272,7 @@ module Google
         #   instance configurations. (See
         #   {Google::Cloud::Spanner::Instance::Config::List})
         #
-        # @deprecated Use
-        # {Google::Cloud::Spanner::Admin::Instance#instance_admin Client#list_instance_configs}
-        # instead.
+        # @deprecated Use {Google::Cloud::Spanner::Admin::Instance.instance_admin}.list_instance_configs instead.
         #
         # @example
         #   require "google/cloud/spanner"
@@ -319,9 +311,7 @@ module Google
         #   configuration, or `nil` if the instance configuration does not
         #   exist.
         #
-        # @deprecated Use
-        # {Google::Cloud::Spanner::Admin::Instance#instance_admin Client#get_instance_config}
-        # instead.
+        # @deprecated Use {Google::Cloud::Spanner::Admin::Instance.instance_admin}.get_instance_config instead.
         #
         # @example
         #   require "google/cloud/spanner"
@@ -355,9 +345,7 @@ module Google
         # @return [Array<Google::Cloud::Spanner::Database>] The list of
         #   databases. (See {Google::Cloud::Spanner::Database::List})
         #
-        # @deprecated Use
-        # {Google::Cloud::Spanner::Admin::Database#database_admin Client#list_databases}
-        # instead.
+        # @deprecated Use {Google::Cloud::Spanner::Admin::Database.database_admin}.list_databases instead.
         #
         # @example
         #   require "google/cloud/spanner"
@@ -394,9 +382,7 @@ module Google
         # @return [Google::Cloud::Spanner::Database, nil] The database, or `nil`
         #   if the database does not exist.
         #
-        # @deprecated Use
-        # {Google::Cloud::Spanner::Admin::Database#database_admin Client#get_database}
-        # instead.
+        # @deprecated Use {Google::Cloud::Spanner::Admin::Database.database_admin}.get_database instead.
         #
         # @example
         #   require "google/cloud/spanner"
@@ -445,9 +431,7 @@ module Google
         # @return [Database::Job] The job representing the long-running,
         #   asynchronous processing of a database create operation.
         #
-        # @deprecated Use
-        # {Google::Cloud::Spanner::Admin::Database#database_admin Client#create_database}
-        # instead.
+        # @deprecated Use {Google::Cloud::Spanner::Admin::Database.database_admin}.create_database instead.
         #
         # @example
         #   require "google/cloud/spanner"
@@ -688,9 +672,7 @@ module Google
           raise "Must have active connection to service" unless service
         end
 
-        # @deprecated Use
-        # {Google::Cloud::Spanner::Admin::Database#database_admin Client#database_path}
-        # instead.
+        # @deprecated Use {Google::Cloud::Spanner::Admin::Database.database_admin}.database_path instead.
         def database_path instance_id, database_id
           Admin::Database::V1::DatabaseAdminClient.database_path(
             project, instance_id, database_id

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

@@ -435,13 +435,15 @@ module Google
           service.partition_query request, opts
         end
 
-        def commit session_name, mutations = [], transaction_id: nil,
+        def commit session_name, mutations = [],
+                   transaction_id: nil, exclude_txn_from_change_streams: false,
                    commit_options: nil, request_options: nil, call_options: nil
           route_to_leader = LARHeaders.commit
           tx_opts = nil
           if transaction_id.nil?
             tx_opts = 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
           opts = default_options session_name: session_name,
@@ -482,11 +484,14 @@ module Google
           service.rollback request, opts
         end
 
-        def begin_transaction session_name, request_options: nil,
+        def begin_transaction session_name,
+                              exclude_txn_from_change_streams: false,
+                              request_options: nil,
                               call_options: nil,
                               route_to_leader: nil
           tx_opts = 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
           )
           opts = default_options session_name: session_name,
                                  call_options: call_options,
@@ -499,6 +504,24 @@ module Google
           service.begin_transaction request, opts
         end
 
+        def batch_write session_name,
+                        mutation_groups,
+                        exclude_txn_from_change_streams: false,
+                        request_options: nil,
+                        call_options: nil
+          route_to_leader = LARHeaders.batch_write
+          opts = default_options session_name: session_name,
+                                 call_options: call_options,
+                                 route_to_leader: route_to_leader
+          request = {
+            session: session_name,
+            request_options: request_options,
+            mutation_groups: mutation_groups,
+            exclude_txn_from_change_streams: exclude_txn_from_change_streams
+          }
+          service.batch_write request, opts
+        end
+
         def create_snapshot session_name, strong: nil, timestamp: nil,
                             staleness: nil, call_options: nil
           tx_opts = V1::TransactionOptions.new(
@@ -517,9 +540,12 @@ module Google
           service.begin_transaction request, opts
         end
 
-        def create_pdml session_name, call_options: nil
+        def create_pdml session_name,
+                        exclude_txn_from_change_streams: false,
+                        call_options: nil
           tx_opts = V1::TransactionOptions.new(
-            partitioned_dml: V1::TransactionOptions::PartitionedDml.new
+            partitioned_dml: V1::TransactionOptions::PartitionedDml.new,
+            exclude_txn_from_change_streams: exclude_txn_from_change_streams
           )
           route_to_leader = LARHeaders.begin_transaction true
           opts = default_options session_name: session_name,