google-cloud-bigquery 1.17.0 → 1.18.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 35c396da998783ed10060a16abd258256f2b14fd9f1a2bae8842a01db2edcd61
-  data.tar.gz: c942df4f34c23a7403344d532b62ad740c0073604d184f2851f4278310558250
+  metadata.gz: a73d3045289c56feffa2def6b2f46764fa271e617629253b01e43bd689017f43
+  data.tar.gz: ac4730e78ce2a9734bcfc9c8adc5bc87576e2cbd9171e59c970cf54972c7c93f
 SHA512:
-  metadata.gz: d8b5a6f8dbec478cbb582f756ce27297e9e284a3146f644bc60a585ac952d7558235603d7a7a53a026cc9f2237bc6bf19890357b39b9559dcf1e4da671e19b7f
-  data.tar.gz: 86cbd63bffb1956b4d5685c79662befc444a6e15337f3da58118cc3cac6f3d7609b06f7be5ee836667f501dc7887b0acd5790fa9ec4f7f954606ab7780aa358a
+  metadata.gz: 3b792a52259418fd31e3507723702b3d5934289e34bdc326b844f85b5495b57d6af208ccf4043f70c3ec3e5492691e03aa7ffadc92c223035b2a82dc2730b5ae
+  data.tar.gz: 83eaa86026274ea0d0da3ee86770e0f10883510520fc35f3058bb37b5df09eb4f31f13db4fd5908f2056999128204bc4ab75606d4e4bffc1acd30dff7e334506

data/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Release History
 
+### 1.18.0 / 2019-11-06
+
+#### Features
+
+* Add optional query parameter types
+  * Allow query parameters to be nil/NULL when providing an optional
+  * Add types argument to the following methods:
+    * Project#query
+    * Project#query_job
+    * Dataset#query
+    * Dataset#query_job
+* Add param types helper methods
+  * Return the BigQuery field type code, using the same format as the
+  * Add Schema::Field#param_type
+  * Add Schema#param_types
+  * Add Data#param_types
+  * Add Table#param_types
+  * Add External::CvsSource#param_types
+  * Add External::JsonSource#param_types
+* Add support for all_users special role in Dataset access
+
 ### 1.17.0 / 2019-10-29
 
 This release requires Ruby 2.4 or later.

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

@@ -75,11 +75,7 @@ module Google
           elsif Array === value[:v]
             value[:v].map { |v| format_value v, field }
           elsif Hash === value[:v]
-            if value[:v].empty?
-              nil
-            else
-              format_row value[:v], field.fields
-            end
+            format_row value[:v], field.fields
           elsif field.type == "STRING"
             String value[:v]
           elsif field.type == "INTEGER"
@@ -115,99 +111,106 @@ module Google
 
         ##
         # @private
-        def self.to_query_param value
-          if TrueClass === value
-            return Google::Apis::BigqueryV2::QueryParameter.new(
-              parameter_type:  Google::Apis::BigqueryV2::QueryParameterType.new(type: "BOOL"),
-              parameter_value: Google::Apis::BigqueryV2::QueryParameterValue.new(value: true)
-            )
-          elsif FalseClass === value
-            return Google::Apis::BigqueryV2::QueryParameter.new(
-              parameter_type:  Google::Apis::BigqueryV2::QueryParameterType.new(type: "BOOL"),
-              parameter_value: Google::Apis::BigqueryV2::QueryParameterValue.new(value: false)
-            )
-          elsif Integer === value
-            return Google::Apis::BigqueryV2::QueryParameter.new(
-              parameter_type:  Google::Apis::BigqueryV2::QueryParameterType.new(type: "INT64"),
-              parameter_value: Google::Apis::BigqueryV2::QueryParameterValue.new(value: value)
-            )
-          elsif Float === value
-            return Google::Apis::BigqueryV2::QueryParameter.new(
-              parameter_type:  Google::Apis::BigqueryV2::QueryParameterType.new(type: "FLOAT64"),
-              parameter_value: Google::Apis::BigqueryV2::QueryParameterValue.new(value: value)
-            )
-          elsif BigDecimal === value
-            # Round to precision of 9
-            value_str = value.finite? ? value.round(9).to_s("F") : value.to_s
-            return Google::Apis::BigqueryV2::QueryParameter.new(
-              parameter_type:  Google::Apis::BigqueryV2::QueryParameterType.new(type: "NUMERIC"),
-              parameter_value: Google::Apis::BigqueryV2::QueryParameterValue.new(value: value_str)
-            )
-          elsif String === value
-            return Google::Apis::BigqueryV2::QueryParameter.new(
-              parameter_type:  Google::Apis::BigqueryV2::QueryParameterType.new(type: "STRING"),
-              parameter_value: Google::Apis::BigqueryV2::QueryParameterValue.new(value: value)
-            )
-          elsif DateTime === value
-            return Google::Apis::BigqueryV2::QueryParameter.new(
-              parameter_type:  Google::Apis::BigqueryV2::QueryParameterType.new(type: "DATETIME"),
-              parameter_value: Google::Apis::BigqueryV2::QueryParameterValue.new(value: value.strftime("%Y-%m-%d %H:%M:%S.%6N"))
-            )
-          elsif Date === value
-            return Google::Apis::BigqueryV2::QueryParameter.new(
-              parameter_type:  Google::Apis::BigqueryV2::QueryParameterType.new(type: "DATE"),
-              parameter_value: Google::Apis::BigqueryV2::QueryParameterValue.new(value: value.to_s)
-            )
-          elsif ::Time === value
-            return Google::Apis::BigqueryV2::QueryParameter.new(
-              parameter_type:  Google::Apis::BigqueryV2::QueryParameterType.new(type: "TIMESTAMP"),
-              parameter_value: Google::Apis::BigqueryV2::QueryParameterValue.new(
-                value: value.strftime("%Y-%m-%d %H:%M:%S.%6N%:z"))
-            )
-          elsif Bigquery::Time === value
-            return Google::Apis::BigqueryV2::QueryParameter.new(
-              parameter_type:  Google::Apis::BigqueryV2::QueryParameterType.new(type: "TIME"),
-              parameter_value: Google::Apis::BigqueryV2::QueryParameterValue.new(value: value.value)
-            )
-          elsif value.respond_to?(:read) && value.respond_to?(:rewind)
-            value.rewind
-            return Google::Apis::BigqueryV2::QueryParameter.new(
-              parameter_type:  Google::Apis::BigqueryV2::QueryParameterType.new(type: "BYTES"),
-              parameter_value: Google::Apis::BigqueryV2::QueryParameterValue.new(value: Base64.strict_encode64(
-                  value.read.force_encoding("ASCII-8BIT")))
+        def self.to_query_param param, type = nil
+          type ||= default_query_param_type_for param
+
+          Google::Apis::BigqueryV2::QueryParameter.new(
+            parameter_type:  to_query_param_type(type),
+            parameter_value: to_query_param_value(param)
+          )
+        end
+
+        ##
+        # @private
+        def self.to_query_param_value value
+          return Google::Apis::BigqueryV2::QueryParameterValue.new value: nil if value.nil?
+
+          json_value = to_json_value value
+
+          if Array === json_value
+            array_values = json_value.map { |v| to_query_param_value v }
+            Google::Apis::BigqueryV2::QueryParameterValue.new array_values: array_values
+          elsif Hash === json_value
+            struct_pairs = json_value.map do |key, value|
+              [String(key), to_query_param_value(value)]
+            end
+            struct_values = Hash[struct_pairs]
+            Google::Apis::BigqueryV2::QueryParameterValue.new struct_values: struct_values
+          else
+            # Everything else is converted to a string, per the API expectations.
+            Google::Apis::BigqueryV2::QueryParameterValue.new value: json_value.to_s
+          end
+        end
+
+        def self.to_query_param_type type
+          if Array === type
+            Google::Apis::BigqueryV2::QueryParameterType.new(
+              type: "ARRAY".freeze,
+              array_type: to_query_param_type(type.first)
             )
-          elsif Array === value
-            array_params = value.map { |param| Convert.to_query_param param }
-            return Google::Apis::BigqueryV2::QueryParameter.new(
-              parameter_type: Google::Apis::BigqueryV2::QueryParameterType.new(
-                type: "ARRAY",
-                array_type: array_params.first.parameter_type
-              ),
-              parameter_value: Google::Apis::BigqueryV2::QueryParameterValue.new(
-                array_values: array_params.map(&:parameter_value)
-              )
+          elsif Hash === type
+            Google::Apis::BigqueryV2::QueryParameterType.new(
+              type: "STRUCT".freeze,
+              struct_types: type.map do |key, val|
+                Google::Apis::BigqueryV2::QueryParameterType::StructType.new(
+                  name: String(key),
+                  type: to_query_param_type(val)
+                )
+              end
             )
-          elsif Hash === value
-            struct_pairs = value.map do |name, param|
-              struct_param = Convert.to_query_param param
-              [Google::Apis::BigqueryV2::QueryParameterType::StructType.new(
-                name: String(name),
-                type: struct_param.parameter_type
-              ), struct_param.parameter_value]
+          else
+            Google::Apis::BigqueryV2::QueryParameterType.new(type: type.to_s.freeze)
+          end
+        end
+
+        def self.default_query_param_type_for param
+          raise ArgumentError, "nil params are not supported, must assign optional type" if param.nil?
+
+          case param
+          when String
+            :STRING
+          when Symbol
+            :STRING
+          when TrueClass
+            :BOOL
+          when FalseClass
+            :BOOL
+          when Integer
+            :INT64
+          when BigDecimal
+            :NUMERIC
+          when Numeric
+            :FLOAT64
+          when ::Time
+            :TIMESTAMP
+          when Bigquery::Time
+            :TIME
+          when DateTime
+            :DATETIME
+          when Date
+            :DATE
+          when Array
+            if param.empty?
+              raise ArgumentError, "Cannot determine type for empty array values"
             end
-            struct_values = Hash[struct_pairs.map do |type, value|
-              [type.name.to_sym, value]
+            non_nil_values = param.compact.map { |p| default_query_param_type_for p }.compact
+            if non_nil_values.empty?
+              raise ArgumentError, "Cannot determine type for array of nil values"
+            end
+            if non_nil_values.uniq.count > 1
+              raise ArgumentError, "Cannot determine type for array of different types of values"
+            end
+            [non_nil_values.first]
+          when Hash
+            Hash[param.map do |key, value|
+              [key, default_query_param_type_for(value)]
             end]
-
-            return Google::Apis::BigqueryV2::QueryParameter.new(
-              parameter_type: Google::Apis::BigqueryV2::QueryParameterType.new(
-                type: "STRUCT",
-                struct_types: struct_pairs.map(&:first)
-              ),
-              parameter_value: Google::Apis::BigqueryV2::QueryParameterValue.new(struct_values: struct_values)
-            )
           else
-            raise "A query parameter of type #{value.class} is not supported."
+            if param.respond_to?(:read) && param.respond_to?(:rewind)
+              :BYTES
+            else
+              raise "A query parameter of type #{param.class} is not supported"
+            end
           end
         end
 
@@ -222,6 +225,9 @@ module Google
             value.strftime "%Y-%m-%d %H:%M:%S.%6N%:z"
           elsif Bigquery::Time === value
             value.value
+          elsif BigDecimal === value
+            # Round to precision of 9
+            value.finite? ? value.round(9).to_s("F") : value.to_s
           elsif value.respond_to?(:read) && value.respond_to?(:rewind)
             value.rewind
             Base64.strict_encode64(value.read.force_encoding("ASCII-8BIT"))

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

@@ -200,6 +200,28 @@ module Google
           schema.headers
         end
 
+        ##
+        # The types of the fields in the data, obtained from the schema of the
+        # table from which the data was read. 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"
+        #
+        #   data = table.data
+        #
+        #   data.param_types
+        #
+        def param_types
+          schema.param_types
+        end
+
         ##
         # The type of query statement, if valid. Possible values (new values
         # might be added in the future):

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

@@ -824,27 +824,6 @@ module Google
         # Sets the current dataset as the default dataset in the query. Useful
         # for using unqualified table names.
         #
-        # When using standard SQL and passing arguments using `params`, 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.
-        #
         # The geographic location for the job ("US", "EU", etc.) can be set via
         # {QueryJob::Updater#location=} in a block passed to this method. If the
         # dataset is a full resource representation (see {#resource_full?}), the
@@ -855,13 +834,55 @@ module Google
         #   syntax](https://cloud.google.com/bigquery/query-reference), of the
         #   query to execute. Example: "SELECT count(f1) FROM
         #   [myProjectId:myDatasetId.myTableId]".
-        # @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.
+        # @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.
         # @param [Hash<String|Symbol, External::DataSource>] external A Hash
         #   that represents the mapping of the external tables to the table
         #   names used in the SQL query. The hash keys are the table names, and
@@ -1025,6 +1046,24 @@ module Google
         #     end
         #   end
         #
+        # @example Query using named query parameters with types:
+        #   require "google/cloud/bigquery"
+        #
+        #   bigquery = Google::Cloud::Bigquery.new
+        #   dataset = bigquery.dataset "my_dataset"
+        #
+        #   job = dataset.query_job "SELECT name FROM my_table " \
+        #                           "WHERE id IN UNNEST(@ids)",
+        #                           params: { ids: [] },
+        #                           types: { ids: [:INT64] }
+        #
+        #   job.wait_until_done!
+        #   if !job.failed?
+        #     job.data.each do |row|
+        #       puts row[:name]
+        #     end
+        #   end
+        #
         # @example Execute a DDL statement:
         #   require "google/cloud/bigquery"
         #
@@ -1077,16 +1116,16 @@ module Google
         #
         # @!group Data
         #
-        def query_job query, params: nil, external: nil, priority: "INTERACTIVE", cache: true, table: nil, create: nil,
-                      write: nil, dryrun: nil, standard_sql: nil, legacy_sql: nil, large_results: nil, flatten: nil,
-                      maximum_billing_tier: nil, maximum_bytes_billed: nil, job_id: nil, prefix: nil, labels: nil,
-                      udfs: nil
+        def query_job query, params: nil, types: nil, external: nil, priority: "INTERACTIVE", cache: true, table: nil,
+                      create: nil, write: nil, dryrun: nil, standard_sql: nil, legacy_sql: nil, large_results: nil,
+                      flatten: nil, maximum_billing_tier: nil, maximum_bytes_billed: nil, job_id: nil, prefix: nil,
+                      labels: nil, udfs: nil
           ensure_service!
-          options = { priority: priority, cache: cache, table: table, create: create, write: write, dryrun: dryrun,
-                      large_results: large_results, flatten: flatten, legacy_sql: legacy_sql,
-                      standard_sql: standard_sql, maximum_billing_tier: maximum_billing_tier,
-                      maximum_bytes_billed: maximum_bytes_billed, job_id: job_id, prefix: prefix, params: params,
-                      external: external, labels: labels, udfs: udfs }
+          options = { params: params, types: types, external: external, priority: priority, cache: cache, table: table,
+                      create: create, write: write, dryrun: dryrun, standard_sql: standard_sql, legacy_sql: legacy_sql,
+                      large_results: large_results, flatten: flatten, maximum_billing_tier: maximum_billing_tier,
+                      maximum_bytes_billed: maximum_bytes_billed, job_id: job_id, prefix: prefix, labels: labels,
+                      udfs: udfs }
 
           updater = QueryJob::Updater.from_options service, query, options
           updater.dataset = self
@@ -1108,27 +1147,6 @@ module Google
         # Sets the current dataset as the default dataset in the query. Useful
         # for using unqualified table names.
         #
-        # When using standard SQL and passing arguments using `params`, 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.
-        #
         # The geographic location for the job ("US", "EU", etc.) can be set via
         # {QueryJob::Updater#location=} in a block passed to this method. If the
         # dataset is a full resource representation (see {#resource_full?}), the
@@ -1141,13 +1159,55 @@ module Google
         #   syntax](https://cloud.google.com/bigquery/query-reference), of the
         #   query to execute. Example: "SELECT count(f1) FROM
         #   [myProjectId:myDatasetId.myTableId]".
-        # @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.
+        # @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.
         # @param [Hash<String|Symbol, External::DataSource>] external A Hash
         #   that represents the mapping of the external tables to the table
         #   names used in the SQL query. The hash keys are the table names, and
@@ -1239,6 +1299,21 @@ module Google
         #     puts row[:name]
         #   end
         #
+        # @example Query using named query parameters with types:
+        #   require "google/cloud/bigquery"
+        #
+        #   bigquery = Google::Cloud::Bigquery.new
+        #   dataset = bigquery.dataset "my_dataset"
+        #
+        #   data = dataset.query "SELECT name FROM my_table " \
+        #                        "WHERE id IN UNNEST(@ids)",
+        #                        params: { ids: [] },
+        #                        types: { ids: [:INT64] }
+        #
+        #   data.each do |row|
+        #     puts row[:name]
+        #   end
+        #
         # @example Execute a DDL statement:
         #   require "google/cloud/bigquery"
         #
@@ -1282,9 +1357,10 @@ module Google
         #
         # @!group Data
         #
-        def query query, params: nil, external: nil, max: nil, cache: true, standard_sql: nil, legacy_sql: nil, &block
-          job = query_job query, params: params, external: external, cache: cache, standard_sql: standard_sql,
-                                 legacy_sql: legacy_sql, &block
+        def query query, params: nil, types: nil, external: nil, max: nil, cache: true,
+                  standard_sql: nil, legacy_sql: nil, &block
+          job = query_job query, params: params, types: types, external: external, cache: cache,
+                                 standard_sql: standard_sql, legacy_sql: legacy_sql, &block
           job.wait_until_done!
           ensure_job_succeeded! job