google-cloud-spanner 1.14.0 → 1.15.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,7 +205,6 @@ 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(
@@ -207,7 +214,8 @@ module Google
                 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
@@ -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,7 +660,7 @@ 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 \
@@ -636,7 +668,7 @@ module Google
           transaction_grpc = Google::Spanner::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
 
         ##
@@ -661,12 +693,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/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
@@ -1291,7 +1340,7 @@ module Google
               project_id, instance_id, database_id
             ),
             labels: @session_labels
-          Session.from_grpc grpc, @project.service
+          Session.from_grpc grpc, @project.service, query_options: @query_options
         end
 
         ##
@@ -1320,7 +1369,7 @@ module Google
             ),
             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

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

@@ -68,12 +68,13 @@ module Google
       class Project
         ##
         # @private The Service object.
-        attr_accessor :service
+        attr_accessor :service, :query_options
 
         ##
         # @private Creates a new Spanner Project instance.
-        def initialize service
+        def initialize service, query_options: nil
           @service = service
+          @query_options = query_options
         end
 
         ##
@@ -452,6 +453,13 @@ module Google
         #   * Label values must be between 0 and 63 characters long and must
         #     conform to the regular expression `([a-z]([-a-z0-9]*[a-z0-9])?)?`.
         #   * No more than 64 labels can be associated with a given resource.
+        # @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 [Client] The newly created client.
         #
@@ -470,12 +478,20 @@ module Google
         #     end
         #   end
         #
-        def client instance_id, database_id, pool: {}, labels: nil
+        def client instance_id, database_id, pool: {}, labels: nil,
+                   query_options: nil
           # Convert from possible Google::Protobuf::Map
           labels = Hash[labels.map { |k, v| [String(k), String(v)] }] if labels
+          # Configs set by environment variables take over client-level configs.
+          if query_options.nil?
+            query_options = @query_options
+          else
+            query_options = query_options.merge @query_options unless @query_options.nil?
+          end
           Client.new self, instance_id, database_id,
                      session_labels: labels,
-                     pool_opts: valid_session_pool_options(pool)
+                     pool_opts: valid_session_pool_options(pool),
+                     query_options: query_options
         end
 
         ##
@@ -501,6 +517,13 @@ module Google
         #   * Label values must be between 0 and 63 characters long and must
         #     conform to the regular expression `([a-z]([-a-z0-9]*[a-z0-9])?)?`.
         #   * No more than 64 labels can be associated with a given resource.
+        # @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 [Client] The newly created client.
         #
@@ -529,10 +552,12 @@ module Google
         #   results = new_batch_snapshot.execute_partition \
         #     new_partition
         #
-        def batch_client instance_id, database_id, labels: nil
+        def batch_client instance_id, database_id, labels: nil,
+                         query_options: nil
           # Convert from possible Google::Protobuf::Map
           labels = Hash[labels.map { |k, v| [String(k), String(v)] }] if labels
-          BatchClient.new self, instance_id, database_id, session_labels: labels
+          BatchClient.new self, instance_id, database_id, session_labels: labels,
+                          query_options: query_options
         end
 
         protected

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

@@ -242,10 +242,12 @@ module Google
 
         def self.execute_query service, session_path, sql, params: nil,
                                types: nil, transaction: nil,
-                               partition_token: nil, seqno: nil
+                               partition_token: nil, seqno: nil,
+                               query_options: nil
           execute_query_options = {
             transaction: transaction, params: params, types: types,
-            partition_token: partition_token, seqno: seqno
+            partition_token: partition_token, seqno: seqno,
+            query_options: query_options
           }
           enum = service.execute_streaming_sql session_path, sql,
                                                execute_query_options

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

@@ -303,7 +303,8 @@ module Google
 
         def execute_streaming_sql session_name, sql, transaction: nil,
                                   params: nil, types: nil, resume_token: nil,
-                                  partition_token: nil, seqno: nil
+                                  partition_token: nil, seqno: nil,
+                                  query_options: nil
           opts = default_options_from_session session_name
           execute do
             service.execute_streaming_sql \
@@ -313,6 +314,7 @@ module Google
                                  resume_token: resume_token,
                                  partition_token: partition_token,
                                  seqno: seqno,
+                                 query_options: query_options,
                                  options: opts
           end
         end

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

@@ -49,10 +49,15 @@ module Google
         # @private The gRPC Service object.
         attr_accessor :service
 
+        ##
+        # @private The hash of query options.
+        attr_accessor :query_options
+
         # @private Creates a new Session instance.
-        def initialize grpc, service
+        def initialize grpc, service, query_options: nil
           @grpc = grpc
           @service = service
+          @query_options = query_options
         end
 
         # The unique identifier for the project.
@@ -150,6 +155,13 @@ module Google
         #   transactions.
         # @param [Integer] seqno A per-transaction sequence number used to
         #   identify this 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 [Google::Cloud::Spanner::Results] The results of the query
         #   execution.
@@ -249,16 +261,35 @@ module Google
         #     puts "User #{row[:id]} is #{row[:name]}"
         #   end
         #
+        # @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, transaction: nil,
-                          partition_token: nil, seqno: nil
+                          partition_token: nil, seqno: nil, query_options: nil
           ensure_service!
-
+          if query_options.nil?
+            query_options = @query_options
+          else
+            query_options = @query_options.merge query_options unless @query_options.nil?
+          end
           results = Results.execute_query service, path, sql,
                                           params: params,
                                           types: types,
                                           transaction: transaction,
                                           partition_token: partition_token,
-                                          seqno: seqno
+                                          seqno: seqno,
+                                          query_options: query_options
           @last_updated_at = Time.now
           results
         end
@@ -688,8 +719,8 @@ module Google
         ##
         # @private Creates a new Session instance from a
         # Google::Spanner::V1::Session.
-        def self.from_grpc grpc, service
-          new grpc, service
+        def self.from_grpc grpc, service, query_options: nil
+          new grpc, service, query_options: query_options
         end
 
         ##