google-cloud-spanner 1.14.0 → 2.0.0

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

@@ -166,6 +166,13 @@ module Google
         #   partitions to return. For example, this may be set to the number of
         #   workers available. This is only a hint and may provide different
         #   results based on the request.
+        # @param [Hash] query_options A hash of values to specify the custom
+        #   query options for executing SQL query. Query options are optional.
+        #   The following settings can be provided:
+        #
+        #   * `:optimizer_version` (String) The version of optimizer to use.
+        #     Empty to use database default. "latest" to use the latest
+        #     available optimizer version.
         #
         # @return [Array<Google::Cloud::Spanner::Partition>] The partitions
         #   created by the query partition.
@@ -188,7 +195,8 @@ module Google
         #   batch_snapshot.close
         #
         def partition_query sql, params: nil, types: nil,
-                            partition_size_bytes: nil, max_partitions: nil
+                            partition_size_bytes: nil, max_partitions: nil,
+                            query_options: nil
           ensure_session!
 
           params, types = Convert.to_input_params_and_types params, types
@@ -197,17 +205,17 @@ module Google
             sql, tx_selector, params: params, types: types,
                               partition_size_bytes: partition_size_bytes,
                               max_partitions: max_partitions
-
           results.partitions.map do |grpc|
             # Convert partition protos to execute sql request protos
-            execute_sql_grpc = Google::Spanner::V1::ExecuteSqlRequest.new(
+            execute_sql_grpc = V1::ExecuteSqlRequest.new(
               {
                 session: session.path,
                 sql: sql,
                 params: params,
                 param_types: types,
                 transaction: tx_selector,
-                partition_token: grpc.partition_token
+                partition_token: grpc.partition_token,
+                query_options: query_options
               }.delete_if { |_, v| v.nil? }
             )
             Partition.from_execute_sql_grpc execute_sql_grpc
@@ -274,7 +282,7 @@ module Google
 
           results.partitions.map do |grpc|
             # Convert partition protos to read request protos
-            read_grpc = Google::Spanner::V1::ReadRequest.new(
+            read_grpc = V1::ReadRequest.new(
               {
                 session: session.path,
                 table: table,
@@ -415,6 +423,14 @@ module Google
         #     specified using a {Fields} object.
         #
         #   Types are optional.
+        # @param [Hash] query_options A hash of values to specify the custom
+        #   query options for executing SQL query. Query options are optional.
+        #   The following settings can be provided:
+        #
+        #   * `:optimizer_version` (String) The version of optimizer to use.
+        #     Empty to use database default. "latest" to use the latest
+        #     available optimizer version.
+        #
         # @return [Google::Cloud::Spanner::Results] The results of the query
         #   execution.
         #
@@ -518,13 +534,29 @@ module Google
         #     puts "User #{row[:id]} is #{row[:name]}"
         #   end
         #
-        def execute_query sql, params: nil, types: nil
+        # @example Query using query options:
+        #   require "google/cloud/spanner"
+        #
+        #   spanner = Google::Cloud::Spanner.new
+        #   batch_client = spanner.batch_client "my-instance", "my-database"
+        #   batch_snapshot = batch_client.batch_snapshot
+        #
+        #   results = batch_snapshot.execute_query \
+        #      "SELECT * FROM users",
+        #      query_options: { optimizer_version: "1" }
+        #
+        #   results.rows.each do |row|
+        #     puts "User #{row[:id]} is #{row[:name]}"
+        #   end
+        #
+        def execute_query sql, params: nil, types: nil, query_options: nil
           ensure_session!
 
           params, types = Convert.to_input_params_and_types params, types
 
           session.execute_query sql, params: params, types: types,
-                                     transaction: tx_selector
+                                transaction: tx_selector,
+                                query_options: query_options
         end
         alias execute execute_query
         alias query execute_query
@@ -628,20 +660,18 @@ module Google
         ##
         # @private Loads the serialized batch snapshot. See
         # {BatchClient#load_batch_snapshot}.
-        def self.load data, service: nil
+        def self.load data, service: nil, query_options: nil
           data = JSON.parse data, symbolize_names: true unless data.is_a? Hash
 
-          session_grpc = Google::Spanner::V1::Session.decode \
-            Base64.decode64(data[:session])
-          transaction_grpc = Google::Spanner::V1::Transaction.decode \
-            Base64.decode64(data[:transaction])
+          session_grpc = V1::Session.decode Base64.decode64(data[:session])
+          transaction_grpc = V1::Transaction.decode Base64.decode64(data[:transaction])
 
-          from_grpc transaction_grpc, Session.from_grpc(session_grpc, service)
+          from_grpc transaction_grpc, Session.from_grpc(session_grpc, service, query_options: query_options)
         end
 
         ##
         # @private Creates a new BatchSnapshot instance from a
-        # Google::Spanner::V1::Transaction.
+        # `Google::Cloud::Spanner::V1::Transaction`.
         def self.from_grpc grpc, session
           new grpc, session
         end
@@ -650,7 +680,7 @@ module Google
 
         # The TransactionSelector to be used for queries
         def tx_selector
-          Google::Spanner::V1::TransactionSelector.new id: transaction_id
+          V1::TransactionSelector.new id: transaction_id
         end
 
         ##
@@ -661,12 +691,15 @@ module Google
         end
 
         def execute_partition_query partition
+          query_options = partition.execute.query_options
+          query_options = query_options.to_h unless query_options.nil?
           session.execute_query \
             partition.execute.sql,
             params: partition.execute.params,
             types: partition.execute.param_types.to_h,
             transaction: partition.execute.transaction,
-            partition_token: partition.execute.partition_token
+            partition_token: partition.execute.partition_token,
+            query_options: query_options
         end
 
         def execute_partition_read partition

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

@@ -155,7 +155,7 @@ module Google
               Convert.to_input_params_and_types params, types
             # param_types is a grpc map field, can't be nil
             converted_types ||= {}
-            Google::Spanner::V1::ExecuteBatchDmlRequest::Statement.new(
+            V1::ExecuteBatchDmlRequest::Statement.new(
               sql: sql,
               params: converted_params,
               param_types: converted_types

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

@@ -53,12 +53,13 @@ module Google
         ##
         # @private Creates a new Spanner Client instance.
         def initialize project, instance_id, database_id, session_labels: nil,
-                       pool_opts: {}
+                       pool_opts: {}, query_options: nil
           @project = project
           @instance_id = instance_id
           @database_id = database_id
           @session_labels = session_labels
           @pool = Pool.new self, pool_opts
+          @query_options = query_options
         end
 
         # The unique identifier for the project.
@@ -97,6 +98,13 @@ module Google
           @project.database instance_id, database_id
         end
 
+        # A hash of values to specify the custom query options for executing
+        # SQL query.
+        # @return [Hash]
+        def query_options
+          @query_options
+        end
+
         ##
         # Executes a SQL query.
         #
@@ -207,6 +215,13 @@ module Google
         #       Useful for reading the freshest data available at a nearby
         #       replica, while bounding the possible staleness if the local
         #       replica has fallen behind.
+        # @param [Hash] query_options A hash of values to specify the custom
+        #   query options for executing SQL query. Query options are optional.
+        #   The following settings can be provided:
+        #
+        #   * `:optimizer_version` (String) The version of optimizer to use.
+        #     Empty to use database default. "latest" to use the latest
+        #     available optimizer version.
         #
         # @return [Google::Cloud::Spanner::Results] The results of the query
         #   execution.
@@ -306,7 +321,22 @@ module Google
         #     puts "User #{row[:id]} is #{row[:name]}"
         #   end
         #
-        def execute_query sql, params: nil, types: nil, single_use: nil
+        # @example Query using query options:
+        #   require "google/cloud/spanner"
+        #
+        #   spanner = Google::Cloud::Spanner.new
+        #
+        #   db = spanner.client "my-instance", "my-database"
+        #
+        #   results = db.execute_query \
+        #     "SELECT * FROM users", query_options: { optimizer_version: "1" }
+        #
+        #   results.rows.each do |row|
+        #     puts "User #{row[:id]} is #{row[:name]}"
+        #   end
+        #
+        def execute_query sql, params: nil, types: nil, single_use: nil,
+                          query_options: nil
           validate_single_use_args! single_use
           ensure_service!
 
@@ -316,7 +346,8 @@ module Google
           results = nil
           @pool.with_session do |session|
             results = session.execute_query \
-              sql, params: params, types: types, transaction: single_use_tx
+              sql, params: params, types: types, transaction: single_use_tx,
+              query_options: query_options
           end
           results
         end
@@ -443,6 +474,14 @@ module Google
         #   value in `params`. In these cases, the `types` hash can be used to
         #   specify the exact SQL type for some or all of the SQL query
         #   parameters.
+        # @param [Hash] query_options A hash of values to specify the custom
+        #   query options for executing SQL query. Query options are optional.
+        #   The following settings can be provided:
+        #
+        #   * `:optimizer_version` (String) The version of optimizer to use.
+        #     Empty to use database default. "latest" to use the latest
+        #     available optimizer version.
+        #
         #
         #   The keys of the hash should be query string parameter placeholders,
         #   minus the "@". The values of the hash should be Cloud Spanner type
@@ -481,16 +520,26 @@ module Google
         #    "UPDATE users SET friends = NULL WHERE active = @active",
         #    params: { active: false }
         #
-        def execute_partition_update sql, params: nil, types: nil
+        # @example Query using query options:
+        #   require "google/cloud/spanner"
+        #
+        #   spanner = Google::Cloud::Spanner.new
+        #   db = spanner.client "my-instance", "my-database"
+        #
+        #   row_count = db.execute_partition_update \
+        #    "UPDATE users SET friends = NULL WHERE active = false",
+        #    query_options: { optimizer_version: "1" }
+        def execute_partition_update sql, params: nil, types: nil,
+                                     query_options: nil
           ensure_service!
 
           params, types = Convert.to_input_params_and_types params, types
-
           results = nil
           @pool.with_session do |session|
             results = session.execute_query \
               sql, params: params, types: types,
-                   transaction: pdml_transaction(session)
+              transaction: pdml_transaction(session),
+              query_options: query_options
           end
           # Stream all PartialResultSet to get ResultSetStats
           results.rows.to_a
@@ -1287,11 +1336,11 @@ module Google
         def create_new_session
           ensure_service!
           grpc = @project.service.create_session \
-            Admin::Database::V1::DatabaseAdminClient.database_path(
-              project_id, instance_id, database_id
+            Admin::Database::V1::DatabaseAdmin::Paths.database_path(
+              project: project_id, instance: instance_id, database: database_id
             ),
             labels: @session_labels
-          Session.from_grpc grpc, @project.service
+          Session.from_grpc grpc, @project.service, query_options: @query_options
         end
 
         ##
@@ -1315,12 +1364,12 @@ module Google
         def batch_create_sessions session_count
           ensure_service!
           resp = @project.service.batch_create_sessions \
-            Admin::Database::V1::DatabaseAdminClient.database_path(
-              project_id, instance_id, database_id
+            Admin::Database::V1::DatabaseAdmin::Paths.database_path(
+              project: project_id, instance: instance_id, database: database_id
             ),
             session_count,
             labels: @session_labels
-          resp.session.map { |grpc| Session.from_grpc grpc, @project.service }
+          resp.session.map { |grpc| Session.from_grpc grpc, @project.service, query_options: @query_options }
         end
 
         # @private
@@ -1372,9 +1421,9 @@ module Google
           bounded_staleness = Convert.number_to_duration \
             opts[:bounded_staleness] || opts[:max_staleness]
 
-          Google::Spanner::V1::TransactionSelector.new(single_use:
-            Google::Spanner::V1::TransactionOptions.new(read_only:
-              Google::Spanner::V1::TransactionOptions::ReadOnly.new({
+          V1::TransactionSelector.new(single_use:
+            V1::TransactionOptions.new(read_only:
+              V1::TransactionOptions::ReadOnly.new({
                 strong: opts[:strong],
                 read_timestamp: exact_timestamp,
                 exact_staleness: exact_staleness,
@@ -1386,7 +1435,7 @@ module Google
 
         def pdml_transaction session
           pdml_tx_grpc = @project.service.create_pdml session.path
-          Google::Spanner::V1::TransactionSelector.new id: pdml_tx_grpc.id
+          V1::TransactionSelector.new id: pdml_tx_grpc.id
         end
 
         ##

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

@@ -96,8 +96,8 @@ module Google
           rows.delete_if(&:nil?)
           rows.delete_if(&:empty?)
           @mutations += rows.map do |row|
-            Google::Spanner::V1::Mutation.new(
-              insert_or_update: Google::Spanner::V1::Mutation::Write.new(
+            V1::Mutation.new(
+              insert_or_update: V1::Mutation::Write.new(
                 table: table, columns: row.keys.map(&:to_s),
                 values: [Convert.object_to_grpc_value(row.values).list_value]
               )
@@ -154,8 +154,8 @@ module Google
           rows.delete_if(&:nil?)
           rows.delete_if(&:empty?)
           @mutations += rows.map do |row|
-            Google::Spanner::V1::Mutation.new(
-              insert: Google::Spanner::V1::Mutation::Write.new(
+            V1::Mutation.new(
+              insert: V1::Mutation::Write.new(
                 table: table, columns: row.keys.map(&:to_s),
                 values: [Convert.object_to_grpc_value(row.values).list_value]
               )
@@ -211,8 +211,8 @@ module Google
           rows.delete_if(&:nil?)
           rows.delete_if(&:empty?)
           @mutations += rows.map do |row|
-            Google::Spanner::V1::Mutation.new(
-              update: Google::Spanner::V1::Mutation::Write.new(
+            V1::Mutation.new(
+              update: V1::Mutation::Write.new(
                 table: table, columns: row.keys.map(&:to_s),
                 values: [Convert.object_to_grpc_value(row.values).list_value]
               )
@@ -270,8 +270,8 @@ module Google
           rows.delete_if(&:nil?)
           rows.delete_if(&:empty?)
           @mutations += rows.map do |row|
-            Google::Spanner::V1::Mutation.new(
-              replace: Google::Spanner::V1::Mutation::Write.new(
+            V1::Mutation.new(
+              replace: V1::Mutation::Write.new(
                 table: table, columns: row.keys.map(&:to_s),
                 values: [Convert.object_to_grpc_value(row.values).list_value]
               )
@@ -306,8 +306,8 @@ module Google
         #
         def delete table, keys = []
           @mutations += [
-            Google::Spanner::V1::Mutation.new(
-              delete: Google::Spanner::V1::Mutation::Delete.new(
+            V1::Mutation.new(
+              delete: V1::Mutation::Delete.new(
                 table: table, key_set: key_set(keys)
               )
             )
@@ -323,20 +323,20 @@ module Google
         protected
 
         def key_set keys
-          return Google::Spanner::V1::KeySet.new all: true if keys.nil?
+          return V1::KeySet.new all: true if keys.nil?
           keys = [keys] unless keys.is_a? Array
-          return Google::Spanner::V1::KeySet.new all: true if keys.empty?
+          return V1::KeySet.new all: true if keys.empty?
           if keys_are_ranges? keys
             key_ranges = keys.map do |r|
               Convert.to_key_range r
             end
-            return Google::Spanner::V1::KeySet.new ranges: key_ranges
+            return V1::KeySet.new ranges: key_ranges
           end
           key_list = keys.map do |key|
             key = [key] unless key.is_a? Array
             Convert.object_to_grpc_value(key).list_value
           end
-          Google::Spanner::V1::KeySet.new keys: key_list
+          V1::KeySet.new keys: key_list
         end
 
         def keys_are_ranges? keys

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

@@ -169,12 +169,12 @@ module Google
             return field.to_grpc_type if field.respond_to? :to_grpc_type
 
             if Array === field
-              Google::Spanner::V1::Type.new(
+              V1::Type.new(
                 code: :ARRAY,
                 array_element_type: grpc_type_for_field(field.first)
               )
             else
-              Google::Spanner::V1::Type.new(code: field)
+              V1::Type.new(code: field)
             end
           end
 
@@ -274,24 +274,24 @@ module Google
               range_opts.delete :end_closed
             end
 
-            Google::Spanner::V1::KeyRange.new range_opts
+            V1::KeyRange.new range_opts
           end
 
           def to_key_set keys
-            return Google::Spanner::V1::KeySet.new(all: true) if keys.nil?
+            return V1::KeySet.new(all: true) if keys.nil?
             keys = [keys] unless keys.is_a? Array
-            return Google::Spanner::V1::KeySet.new(all: true) if keys.empty?
+            return V1::KeySet.new(all: true) if keys.empty?
 
             if keys_are_ranges? keys
               key_ranges = keys.map { |r| to_key_range(r) }
-              return Google::Spanner::V1::KeySet.new(ranges: key_ranges)
+              return V1::KeySet.new(ranges: key_ranges)
             end
 
             key_list = keys.map do |key|
               key = [key] unless key.is_a? Array
               object_to_grpc_value(key).list_value
             end
-            Google::Spanner::V1::KeySet.new keys: key_list
+            V1::KeySet.new keys: key_list
           end
 
           def keys_are_ranges? keys