google-cloud-spanner 1.6.4 → 1.7.1

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

@@ -34,7 +34,7 @@ module Google
       #
       #   db = spanner.client "my-instance", "my-database"
       #
-      #   results = db.execute "SELECT * FROM users"
+      #   results = db.execute_query "SELECT * FROM users"
       #
       #   results.rows.each do |row|
       #     puts "User #{row[:id]} is #{row[:name]}"

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

@@ -33,7 +33,7 @@ module Google
       #
       #   db = spanner.client "my-instance", "my-database"
       #
-      #   results = db.execute "SELECT * FROM users"
+      #   results = db.execute_query "SELECT * FROM users"
       #
       #   results.fields.pairs.each do |name, type|
       #     puts "Column #{name} is type #{type}"

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

@@ -52,11 +52,15 @@ module Google
         def initialize; end
 
         ##
-        # Whether the partition was created for an execute/query operation.
+        # Whether the partition was created for an execute_query/query
+        # operation.
         # @return [Boolean]
-        def execute?
+        def execute_query?
           !@execute.nil?
         end
+        alias execute? execute_query?
+        alias execute_sql? execute_query?
+        alias query? execute_query?
 
         ##
         # Whether the partition was created for a read operation.
@@ -67,7 +71,8 @@ module Google
 
         ##
         # @private
-        # Whether the partition does not have an execute or read operation.
+        # Whether the partition does not have an execute_query or read
+        # operation.
         # @return [Boolean]
         def empty?
           @execute.nil? && @read.nil?
@@ -84,7 +89,7 @@ module Google
         def to_h
           {}.tap do |h|
             h[:execute] = Base64.strict_encode64(@execute.to_proto) if @execute
-            h[:read] = Base64.strict_encode64(@read.to_proto) if @read
+            h[:read]    = Base64.strict_encode64(@read.to_proto)    if @read
           end
         end
 
@@ -163,12 +168,14 @@ module Google
         def self.load data
           data = JSON.parse data, symbolize_names: true unless data.is_a? Hash
 
-          # TODO: raise if hash[:execute].nil? && hash[:read].nil?
+          # TODO: raise if hash[:execute_query].nil? && hash[:read].nil?
           new.tap do |p|
             if data[:execute]
-              execute_grpc = Google::Spanner::V1::ExecuteSqlRequest.decode \
-                Base64.decode64(data[:execute])
-              p.instance_variable_set :@execute, execute_grpc
+              execute_sql_grpc = \
+                Google::Spanner::V1::ExecuteSqlRequest.decode(
+                  Base64.decode64(data[:execute])
+                )
+              p.instance_variable_set :@execute, execute_sql_grpc
             end
             if data[:read]
               read_grpc = Google::Spanner::V1::ReadRequest.decode \
@@ -189,7 +196,7 @@ module Google
         ##
         # @private New Partition from a Google::Spanner::V1::ExecuteSqlRequest
         # object.
-        def self.from_execute_grpc grpc
+        def self.from_execute_sql_grpc grpc
           new.tap do |p|
             p.instance_variable_set :@execute, grpc
           end

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

@@ -58,7 +58,7 @@ module Google
       #   db = spanner.client "my-instance", "my-database"
       #
       #   db.transaction do |tx|
-      #     results = tx.execute "SELECT * FROM users"
+      #     results = tx.execute_query "SELECT * FROM users"
       #
       #     results.rows.each do |row|
       #       puts "User #{row[:id]} is #{row[:name]}"
@@ -463,7 +463,7 @@ module Google
         #   db = spanner.client "my-instance", "my-database"
         #
         #   db.transaction do |tx|
-        #     results = tx.execute "SELECT * FROM users"
+        #     results = tx.execute_query "SELECT * FROM users"
         #
         #     results.rows.each do |row|
         #       puts "User #{row[:id]} is #{row[:name]}"

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

@@ -24,7 +24,7 @@ module Google
       #
       # Represents the result set from an operation returning data.
       #
-      # See {Google::Cloud::Spanner::Client#execute} and
+      # See {Google::Cloud::Spanner::Client#execute_query} and
       # {Google::Cloud::Spanner::Client#read}.
       #
       # @example
@@ -34,7 +34,7 @@ module Google
       #
       #   db = spanner.client "my-instance", "my-database"
       #
-      #   results = db.execute "SELECT * FROM users"
+      #   results = db.execute_query "SELECT * FROM users"
       #
       #   results.fields.pairs.each do |name, type|
       #     puts "Column #{name} is type #{type}"
@@ -63,7 +63,7 @@ module Google
         #
         #   db = spanner.client "my-instance", "my-database"
         #
-        #   results = db.execute "SELECT * FROM users"
+        #   results = db.execute_query "SELECT * FROM users"
         #
         #   results.fields.pairs.each do |name, type|
         #     puts "Column #{name} is type #{type}"
@@ -88,7 +88,7 @@ module Google
         #
         #   db = spanner.client "my-instance", "my-database"
         #
-        #   results = db.execute "SELECT * FROM users"
+        #   results = db.execute_query "SELECT * FROM users"
         #
         #   results.rows.each do |row|
         #     puts "User #{row[:id]} is #{row[:name]}"
@@ -102,11 +102,6 @@ module Google
           end
 
           fields = @metadata.row_type.fields
-          if fields.count.zero?
-            @closed = true
-            return []
-          end
-
           values = []
           buffered_responses = []
           buffer_upper_bound = 10
@@ -130,16 +125,18 @@ module Google
                 # This can set the resume_token to nil
                 resume_token = grpc.resume_token
 
-                buffered_responses.each do |resp|
-                  if chunked_value
-                    resp.values.unshift merge(chunked_value, resp.values.shift)
-                    chunked_value = nil
-                  end
-                  to_iterate = values + Array(resp.values)
-                  chunked_value = to_iterate.pop if resp.chunked_value
-                  values = to_iterate.pop(to_iterate.count % fields.count)
-                  to_iterate.each_slice(fields.count) do |slice|
-                    yield Data.from_grpc(slice, fields)
+                if fields.count > 0
+                  buffered_responses.each do |resp|
+                    if chunked_value
+                      resp.values.unshift merge(chunked_value, resp.values.shift)
+                      chunked_value = nil
+                    end
+                    to_iterate = values + Array(resp.values)
+                    chunked_value = to_iterate.pop if resp.chunked_value
+                    values = to_iterate.pop(to_iterate.count % fields.count)
+                    to_iterate.each_slice(fields.count) do |slice|
+                      yield Data.from_grpc(slice, fields)
+                    end
                   end
                 end
 
@@ -154,10 +151,10 @@ module Google
               end
 
               # Resume the stream from the last known resume_token
-              if @execute_options
-                @enum = @service.streaming_execute_sql \
+              if @execute_query_options
+                @enum = @service.execute_streaming_sql \
                   @session_path, @sql,
-                  @execute_options.merge(resume_token: resume_token)
+                  @execute_query_options.merge(resume_token: resume_token)
               else
                 @enum = @service.streaming_read_table \
                   @session_path, @table, @columns,
@@ -174,21 +171,23 @@ module Google
           end
 
           # clear out any remaining values left over
-          buffered_responses.each do |resp|
-            if chunked_value
-              resp.values.unshift merge(chunked_value, resp.values.shift)
-              chunked_value = nil
+          if fields.count > 0
+            buffered_responses.each do |resp|
+              if chunked_value
+                resp.values.unshift merge(chunked_value, resp.values.shift)
+                chunked_value = nil
+              end
+              to_iterate = values + Array(resp.values)
+              chunked_value = to_iterate.pop if resp.chunked_value
+              values = to_iterate.pop(to_iterate.count % fields.count)
+              to_iterate.each_slice(fields.count) do |slice|
+                yield Data.from_grpc(slice, fields)
+              end
             end
-            to_iterate = values + Array(resp.values)
-            chunked_value = to_iterate.pop if resp.chunked_value
-            values = to_iterate.pop(to_iterate.count % fields.count)
-            to_iterate.each_slice(fields.count) do |slice|
+            values.each_slice(fields.count) do |slice|
               yield Data.from_grpc(slice, fields)
             end
           end
-          values.each_slice(fields.count) do |slice|
-            yield Data.from_grpc(slice, fields)
-          end
 
           # If we get this far then we can release the session
           @closed = true
@@ -197,6 +196,33 @@ module Google
 
         # rubocop:enable all
 
+        ##
+        # @private
+        # Get row count from stats. This will be the exact row count for DML
+        # statements, and the lower bound row count for PDML statements.
+        def row_count
+          return @stats.row_count_lower_bound if row_count_lower_bound?
+          return @stats.row_count_exact       if row_count_exact?
+          nil
+        end
+
+        ##
+        # @private
+        # Whether the row count is the lower bound row count for PDML
+        # statements.
+        def row_count_lower_bound?
+          return nil if @stats.nil?
+          @stats.row_count == :row_count_lower_bound
+        end
+
+        ##
+        # @private
+        # Whether the row count is the exact row count for DML statements.
+        def row_count_exact?
+          return nil if @stats.nil?
+          @stats.row_count == :row_count_exact
+        end
+
         # @private
         def self.from_enum enum, service
           grpc = enum.peek
@@ -211,16 +237,21 @@ module Google
         end
 
         # @private
-        def self.execute service, session_path, sql, params: nil, types: nil,
-                         transaction: nil, partition_token: nil
-          execute_options = { transaction: transaction, params: params,
-                              types: types, partition_token: partition_token }
-          enum = service.streaming_execute_sql session_path, sql,
-                                               execute_options
+
+        def self.execute_query service, session_path, sql, params: nil,
+                               types: nil, transaction: nil,
+                               partition_token: nil, seqno: nil
+          execute_query_options = {
+            transaction: transaction, params: params, types: types,
+            partition_token: partition_token, seqno: seqno
+          }
+          enum = service.execute_streaming_sql session_path, sql,
+                                               execute_query_options
           from_enum(enum, service).tap do |results|
-            results.instance_variable_set :@session_path,    session_path
-            results.instance_variable_set :@sql,             sql
-            results.instance_variable_set :@execute_options, execute_options
+            results.instance_variable_set :@session_path, session_path
+            results.instance_variable_set :@sql,          sql
+            results.instance_variable_set :@execute_query_options,
+                                          execute_query_options
           end
         end
 

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

@@ -257,16 +257,19 @@ module Google
           end
         end
 
-        def streaming_execute_sql session_name, sql, transaction: nil,
+        def execute_streaming_sql session_name, sql, transaction: nil,
                                   params: nil, types: nil, resume_token: nil,
-                                  partition_token: nil
+                                  partition_token: nil, seqno: nil
           opts = default_options_from_session session_name
           execute do
             service.execute_streaming_sql \
-              session_name, sql, transaction: transaction, params: params,
+              session_name, sql, transaction: transaction,
+                                 params: params,
                                  param_types: types,
                                  resume_token: resume_token,
-                                 partition_token: partition_token, options: opts
+                                 partition_token: partition_token,
+                                 seqno: seqno,
+                                 options: opts
           end
         end
 
@@ -367,6 +370,17 @@ module Google
           end
         end
 
+        def create_pdml session_name
+          tx_opts = Google::Spanner::V1::TransactionOptions.new(
+            partitioned_dml: \
+              Google::Spanner::V1::TransactionOptions::PartitionedDml.new
+          )
+          opts = default_options_from_session session_name
+          execute do
+            service.begin_transaction session_name, tx_opts, options: opts
+          end
+        end
+
         def inspect
           "#{self.class}(#{@project})"
         end

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

@@ -151,6 +151,8 @@ module Google
         # @param [Google::Spanner::V1::TransactionSelector] transaction The
         #   transaction selector value to send. Only used for single-use
         #   transactions.
+        # @param [Integer] seqno A per-transaction sequence number used to
+        #   identify this request.
         #
         # @return [Google::Cloud::Spanner::Results] The results of the query
         #   execution.
@@ -162,7 +164,7 @@ module Google
         #
         #   db = spanner.client "my-instance", "my-database"
         #
-        #   results = db.execute "SELECT * FROM users"
+        #   results = db.execute_query "SELECT * FROM users"
         #
         #   results.rows.each do |row|
         #     puts "User #{row[:id]} is #{row[:name]}"
@@ -175,8 +177,10 @@ module Google
         #
         #   db = spanner.client "my-instance", "my-database"
         #
-        #   results = db.execute "SELECT * FROM users WHERE active = @active",
-        #                        params: { active: true }
+        #   results = db.execute_query(
+        #     "SELECT * FROM users WHERE active = @active",
+        #     params: { active: true }
+        #   )
         #
         #   results.rows.each do |row|
         #     puts "User #{row[:id]} is #{row[:name]}"
@@ -191,11 +195,13 @@ module Google
         #
         #   user_hash = { id: 1, name: "Charlie", active: false }
         #
-        #   results = db.execute "SELECT * FROM users WHERE " \
-        #                        "ID = @user_struct.id " \
-        #                        "AND name = @user_struct.name " \
-        #                        "AND active = @user_struct.active",
-        #                        params: { user_struct: user_hash }
+        #   results = db.execute_query(
+        #     "SELECT * FROM users WHERE " \
+        #     "ID = @user_struct.id " \
+        #     "AND name = @user_struct.name " \
+        #     "AND active = @user_struct.active",
+        #     params: { user_struct: user_hash }
+        #   )
         #
         #   results.rows.each do |row|
         #     puts "User #{row[:id]} is #{row[:name]}"
@@ -211,12 +217,14 @@ module Google
         #   user_type = db.fields id: :INT64, name: :STRING, active: :BOOL
         #   user_hash = { id: 1, name: nil, active: false }
         #
-        #   results = db.execute "SELECT * FROM users WHERE " \
-        #                        "ID = @user_struct.id " \
-        #                        "AND name = @user_struct.name " \
-        #                        "AND active = @user_struct.active",
-        #                        params: { user_struct: user_hash },
-        #                        types: { user_struct: user_type }
+        #   results = db.execute_query(
+        #     "SELECT * FROM users WHERE " \
+        #     "ID = @user_struct.id " \
+        #     "AND name = @user_struct.name " \
+        #     "AND active = @user_struct.active",
+        #     params: { user_struct: user_hash },
+        #     types: { user_struct: user_type }
+        #   )
         #
         #   results.rows.each do |row|
         #     puts "User #{row[:id]} is #{row[:name]}"
@@ -232,31 +240,35 @@ module Google
         #   user_type = db.fields id: :INT64, name: :STRING, active: :BOOL
         #   user_data = user_type.struct id: 1, name: nil, active: false
         #
-        #   results = db.execute "SELECT * FROM users WHERE " \
-        #                        "ID = @user_struct.id " \
-        #                        "AND name = @user_struct.name " \
-        #                        "AND active = @user_struct.active",
-        #                        params: { user_struct: user_struct }
+        #   results = db.execute_query(
+        #     "SELECT * FROM users WHERE " \
+        #     "ID = @user_struct.id " \
+        #     "AND name = @user_struct.name " \
+        #     "AND active = @user_struct.active",
+        #     params: { user_struct: user_struct }
+        #   )
         #
         #   results.rows.each do |row|
         #     puts "User #{row[:id]} is #{row[:name]}"
         #   end
         #
-        def execute sql, params: nil, types: nil, transaction: nil,
-                    partition_token: nil
+        def execute_query sql, params: nil, types: nil, transaction: nil,
+                          partition_token: nil, seqno: nil
           ensure_service!
 
-          results = Results.execute service, path, sql,
-                                    params: params, types: types,
-                                    transaction: transaction,
-                                    partition_token: partition_token
+          results = Results.execute_query service, path, sql,
+                                          params: params,
+                                          types: types,
+                                          transaction: transaction,
+                                          partition_token: partition_token,
+                                          seqno: seqno
           @last_updated_at = Time.now
           results
         end
 
         ##
         # Read rows from a database table, as a simple alternative to
-        # {#execute}.
+        # {#execute_query}.
         #
         # @param [String] table The name of the table in the database to be
         #   read.
@@ -612,7 +624,7 @@ module Google
         # Keeps the session alive by executing `"SELECT 1"`.
         def keepalive!
           ensure_service!
-          execute "SELECT 1"
+          execute_query "SELECT 1"
           return true
         rescue Google::Cloud::NotFoundError
           labels = @grpc.labels.to_h unless @grpc.labels.to_h.empty?