google-cloud-bigquery 1.17.0 → 1.18.0

data/lib/google/cloud/bigquery/query_job.rb

@@ -611,7 +611,7 @@ module Google
             )
 
             updater = QueryJob::Updater.new service, req
-            updater.params = options[:params] if options[:params]
+            updater.set_params_and_types options[:params], options[:types] if options[:params]
             updater.create = options[:create]
             updater.write = options[:write]
             updater.table = options[:table]
@@ -723,30 +723,113 @@ module Google
           ##
           # Sets the query parameters. Standard SQL only.
           #
-          # @param [Array, Hash] params Used to pass query arguments when the
-          #   `query` string contains either positional (`?`) or named
-          #   (`@myparam`) query parameters. If value passed is an array
-          #   `["foo"]`, the query must use positional query parameters. If
-          #   value passed is a hash `{ myparam: "foo" }`, the query must use
-          #   named query parameters. When set, `legacy_sql` will automatically
-          #   be set to false and `standard_sql` to true.
+          # Use {set_params_and_types} to set both params and types.
+          #
+          # @param [Array, Hash] params Standard SQL only. Used to pass query arguments when the `query` string contains
+          #   either positional (`?`) or named (`@myparam`) query parameters. If value passed is an array `["foo"]`, the
+          #   query must use positional query parameters. If value passed is a hash `{ myparam: "foo" }`, the query must
+          #   use named query parameters. When set, `legacy_sql` will automatically be set to false and `standard_sql`
+          #   to true.
+          #
+          #   Ruby types are mapped to BigQuery types as follows:
+          #
+          #   | BigQuery    | Ruby                                 | Notes                                          |
+          #   |-------------|--------------------------------------|------------------------------------------------|
+          #   | `BOOL`      | `true`/`false`                       |                                                |
+          #   | `INT64`     | `Integer`                            |                                                |
+          #   | `FLOAT64`   | `Float`                              |                                                |
+          #   | `NUMERIC`   | `BigDecimal`                         | Will be rounded to 9 decimal places            |
+          #   | `STRING`    | `String`                             |                                                |
+          #   | `DATETIME`  | `DateTime`                           | `DATETIME` does not support time zone.         |
+          #   | `DATE`      | `Date`                               |                                                |
+          #   | `TIMESTAMP` | `Time`                               |                                                |
+          #   | `TIME`      | `Google::Cloud::BigQuery::Time`      |                                                |
+          #   | `BYTES`     | `File`, `IO`, `StringIO`, or similar |                                                |
+          #   | `ARRAY`     | `Array`                              | Nested arrays, `nil` values are not supported. |
+          #   | `STRUCT`    | `Hash`                               | Hash keys may be strings or symbols.           |
+          #
+          #   See [Data Types](https://cloud.google.com/bigquery/docs/reference/standard-sql/data-types) for an overview
+          #   of each BigQuery data type, including allowed values.
           #
           # @!group Attributes
           def params= params
+            set_params_and_types params
+          end
+
+          ##
+          # Sets the query parameters. Standard SQL only.
+          #
+          # @param [Array, Hash] params Standard SQL only. Used to pass query arguments when the `query` string contains
+          #   either positional (`?`) or named (`@myparam`) query parameters. If value passed is an array `["foo"]`, the
+          #   query must use positional query parameters. If value passed is a hash `{ myparam: "foo" }`, the query must
+          #   use named query parameters. When set, `legacy_sql` will automatically be set to false and `standard_sql`
+          #   to true.
+          #
+          #   Ruby types are mapped to BigQuery types as follows:
+          #
+          #   | BigQuery    | Ruby                                 | Notes                                          |
+          #   |-------------|--------------------------------------|------------------------------------------------|
+          #   | `BOOL`      | `true`/`false`                       |                                                |
+          #   | `INT64`     | `Integer`                            |                                                |
+          #   | `FLOAT64`   | `Float`                              |                                                |
+          #   | `NUMERIC`   | `BigDecimal`                         | Will be rounded to 9 decimal places            |
+          #   | `STRING`    | `String`                             |                                                |
+          #   | `DATETIME`  | `DateTime`                           | `DATETIME` does not support time zone.         |
+          #   | `DATE`      | `Date`                               |                                                |
+          #   | `TIMESTAMP` | `Time`                               |                                                |
+          #   | `TIME`      | `Google::Cloud::BigQuery::Time`      |                                                |
+          #   | `BYTES`     | `File`, `IO`, `StringIO`, or similar |                                                |
+          #   | `ARRAY`     | `Array`                              | Nested arrays, `nil` values are not supported. |
+          #   | `STRUCT`    | `Hash`                               | Hash keys may be strings or symbols.           |
+          #
+          #   See [Data Types](https://cloud.google.com/bigquery/docs/reference/standard-sql/data-types) for an overview
+          #   of each BigQuery data type, including allowed values.
+          # @param [Array, Hash] types Standard SQL only. Types of the SQL parameters in `params`. It is not always to
+          #   infer the right SQL type from a value in `params`. In these cases, `types` must be used to specify the SQL
+          #   type for these values.
+          #
+          #   Must match the value type passed to `params`. This must be an `Array` when the query uses positional query
+          #   parameters. This must be an `Hash` when the query uses named query parameters. The values should be
+          #   BigQuery type codes from the following list:
+          #
+          #   * `:BOOL`
+          #   * `:INT64`
+          #   * `:FLOAT64`
+          #   * `:NUMERIC`
+          #   * `:STRING`
+          #   * `:DATETIME`
+          #   * `:DATE`
+          #   * `:TIMESTAMP`
+          #   * `:TIME`
+          #   * `:BYTES`
+          #   * `Array` - Lists are specified by providing the type code in an array. For example, an array of integers
+          #     are specified as `[:INT64]`.
+          #   * `Hash` - Types for STRUCT values (`Hash` objects) are specified using a `Hash` object, where the keys
+          #     match the `params` hash, and the values are the types value that matches the data.
+          #
+          #   Types are optional.
+          #
+          # @!group Attributes
+          def set_params_and_types params, types = nil
+            types ||= params.class.new
+            raise ArgumentError, "types must use the same format as params" if types.class != params.class
+
             case params
             when Array then
               @gapi.configuration.query.use_legacy_sql = false
               @gapi.configuration.query.parameter_mode = "POSITIONAL"
-              @gapi.configuration.query.query_parameters = params.map { |param| Convert.to_query_param param }
+              @gapi.configuration.query.query_parameters = params.zip(types).map do |param, type|
+                Convert.to_query_param param, type
+              end
             when Hash then
               @gapi.configuration.query.use_legacy_sql = false
               @gapi.configuration.query.parameter_mode = "NAMED"
-              @gapi.configuration.query.query_parameters =
-                params.map do |name, param|
-                  Convert.to_query_param(param).tap { |named_param| named_param.name = String name }
-                end
+              @gapi.configuration.query.query_parameters = params.map do |name, param|
+                type = types[name]
+                Convert.to_query_param(param, type).tap { |named_param| named_param.name = String name }
+              end
             else
-              raise "Query parameters must be an Array or a Hash."
+              raise ArgumentError, "params must be an Array or a Hash"
             end
           end
 

data/lib/google/cloud/bigquery/schema.rb

@@ -154,6 +154,27 @@ module Google
           fields.map(&:name).map(&:to_sym)
         end
 
+        ##
+        # The types of the fields, using the same format as the optional query
+        # parameter types.
+        #
+        # @return [Hash] A hash with column names as keys, and types as values.
+        #
+        # @example
+        #   require "google/cloud/bigquery"
+        #
+        #   bigquery = Google::Cloud::Bigquery.new
+        #   dataset = bigquery.dataset "my_dataset"
+        #   table = dataset.create_table "my_table"
+        #
+        #   schema = table.schema
+        #
+        #   schema.param_types
+        #
+        def param_types
+          Hash[fields.map { |field| [field.name.to_sym, field.param_type] }]
+        end
+
         ##
         # Retrieve a field by name.
         #

data/lib/google/cloud/bigquery/schema/field.rb

@@ -261,6 +261,7 @@ module Google
           def record?
             type == "RECORD" || type == "STRUCT"
           end
+          alias struct? record?
 
           ##
           # The nested fields if the type property is set to `RECORD`. Will be
@@ -288,6 +289,36 @@ module Google
             fields.map(&:name).map(&:to_sym)
           end
 
+          ##
+          # The types of the field, using the same format as the optional query
+          # parameter types.
+          #
+          # The parameter types are one of the following BigQuery type codes:
+          #
+          # * `:BOOL`
+          # * `:INT64`
+          # * `:FLOAT64`
+          # * `:NUMERIC`
+          # * `:STRING`
+          # * `:DATETIME`
+          # * `:DATE`
+          # * `:TIMESTAMP`
+          # * `:TIME`
+          # * `:BYTES`
+          # * `Array` - Lists are specified by providing the type code in an array. For example, an array of integers
+          #   are specified as `[:INT64]`.
+          # * `Hash` - Types for STRUCT values (`Hash` objects) are specified using a `Hash` object, where the keys
+          #   are the nested field names, and the values are the the nested field types.
+          #
+          # @return [Symbol, Array, Hash] The type.
+          #
+          def param_type
+            param_type = type.to_sym
+            param_type = Hash[fields.map { |field| [field.name.to_sym, field.param_type] }] if record?
+            param_type = [param_type] if repeated?
+            param_type
+          end
+
           ##
           # Retrieve a nested field by name, if the type property is
           # set to `RECORD`. Will return `nil` otherwise.

data/lib/google/cloud/bigquery/table.rb

@@ -870,6 +870,26 @@ module Google
           schema.headers
         end
 
+        ##
+        # The types of the fields in the table, obtained from its schema.
+        # Types use the same format as the optional query parameter types.
+        #
+        # @return [Hash] A hash with field names as keys, and types as values.
+        #
+        # @example
+        #   require "google/cloud/bigquery"
+        #
+        #   bigquery = Google::Cloud::Bigquery.new
+        #   dataset = bigquery.dataset "my_dataset"
+        #   table = dataset.table "my_table"
+        #
+        #   table.param_types
+        #
+        def param_types
+          return nil if reference?
+          schema.param_types
+        end
+
         ##
         # The {EncryptionConfiguration} object that represents the custom
         # encryption method used to protect the table. If not set,

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

@@ -16,7 +16,7 @@
 module Google
   module Cloud
     module Bigquery
-      VERSION = "1.17.0".freeze
+      VERSION = "1.18.0".freeze
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: google-cloud-bigquery
 version: !ruby/object:Gem::Version
-  version: 1.17.0
+  version: 1.18.0
 platform: ruby
 authors:
 - Mike Moore
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-10-30 00:00:00.000000000 Z
+date: 2019-11-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby