google-cloud-bigquery 1.14.0 → 1.42.0

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

@@ -48,6 +48,44 @@ module Google
       #     puts job.data.first
       #   end
       #
+      # @example With multiple statements and child jobs:
+      #   require "google/cloud/bigquery"
+      #
+      #   bigquery = Google::Cloud::Bigquery.new
+      #
+      #   multi_statement_sql = <<~SQL
+      #     -- Declare a variable to hold names as an array.
+      #     DECLARE top_names ARRAY<STRING>;
+      #     -- Build an array of the top 100 names from the year 2017.
+      #     SET top_names = (
+      #     SELECT ARRAY_AGG(name ORDER BY number DESC LIMIT 100)
+      #     FROM `bigquery-public-data.usa_names.usa_1910_current`
+      #     WHERE year = 2017
+      #     );
+      #     -- Which names appear as words in Shakespeare's plays?
+      #     SELECT
+      #     name AS shakespeare_name
+      #     FROM UNNEST(top_names) AS name
+      #     WHERE name IN (
+      #     SELECT word
+      #     FROM `bigquery-public-data.samples.shakespeare`
+      #     );
+      #   SQL
+      #
+      #   job = bigquery.query_job multi_statement_sql
+      #
+      #   job.wait_until_done!
+      #
+      #   child_jobs = bigquery.jobs parent_job: job
+      #
+      #   child_jobs.each do |child_job|
+      #     script_statistics = child_job.script_statistics
+      #     puts script_statistics.evaluation_kind
+      #     script_statistics.stack_frames.each do |stack_frame|
+      #       puts stack_frame.text
+      #     end
+      #   end
+      #
       class QueryJob < Job
         ##
         # Checks if the priority for the query is `BATCH`.
@@ -56,8 +94,7 @@ module Google
         #   otherwise.
         #
         def batch?
-          val = @gapi.configuration.query.priority
-          val == "BATCH"
+          @gapi.configuration.query.priority == "BATCH"
         end
 
         ##
@@ -205,17 +242,16 @@ module Google
         #   end
         #
         def query_plan
-          return nil unless @gapi.statistics.query &&
-                            @gapi.statistics.query.query_plan
-          Array(@gapi.statistics.query.query_plan).map do |stage|
-            Stage.from_gapi stage
-          end
+          return nil unless @gapi&.statistics&.query&.query_plan
+          Array(@gapi.statistics.query.query_plan).map { |stage| Stage.from_gapi stage }
         end
 
         ##
         # The type of query statement, if valid. Possible values (new values
         # might be added in the future):
         #
+        # * "ALTER_TABLE": DDL statement, see [Using Data Definition Language
+        #   Statements](https://cloud.google.com/bigquery/docs/reference/standard-sql/data-definition-language)
         # * "CREATE_MODEL": DDL statement, see [Using Data Definition Language
         #   Statements](https://cloud.google.com/bigquery/docs/reference/standard-sql/data-definition-language)
         # * "CREATE_TABLE": DDL statement, see [Using Data Definition Language
@@ -261,8 +297,16 @@ module Google
         #   query_job.ddl? #=> true
         #
         def ddl?
-          %w[CREATE_MODEL CREATE_TABLE CREATE_TABLE_AS_SELECT CREATE_VIEW \
-             DROP_MODEL DROP_TABLE DROP_VIEW].include? statement_type
+          [
+            "ALTER_TABLE",
+            "CREATE_MODEL",
+            "CREATE_TABLE",
+            "CREATE_TABLE_AS_SELECT",
+            "CREATE_VIEW",
+            "DROP_MODEL",
+            "DROP_TABLE",
+            "DROP_VIEW"
+          ].include? statement_type
         end
 
         ##
@@ -285,7 +329,12 @@ module Google
         #   query_job.dml? #=> true
         #
         def dml?
-          %w[INSERT UPDATE MERGE DELETE].include? statement_type
+          [
+            "INSERT",
+            "UPDATE",
+            "MERGE",
+            "DELETE"
+          ].include? statement_type
         end
 
         ##
@@ -308,6 +357,22 @@ module Google
           @gapi.statistics.query.ddl_operation_performed
         end
 
+        ##
+        # The DDL target routine, in reference state. (See {Routine#reference?}.)
+        # Present only for `CREATE/DROP FUNCTION/PROCEDURE` queries. (See
+        # {#statement_type}.)
+        #
+        # @return [Google::Cloud::Bigquery::Routine, nil] The DDL target routine, in
+        #   reference state.
+        #
+        def ddl_target_routine
+          return nil unless @gapi.statistics.query
+          ensure_service!
+          routine = @gapi.statistics.query.ddl_target_routine
+          return nil unless routine
+          Google::Cloud::Bigquery::Routine.new_reference_from_gapi routine, service
+        end
+
         ##
         # The DDL target table, in reference state. (See {Table#reference?}.)
         # Present only for `CREATE/DROP TABLE/VIEW` queries. (See
@@ -336,17 +401,57 @@ module Google
           @gapi.statistics.query.num_dml_affected_rows
         end
 
+        ##
+        # The number of deleted rows. Present only for DML statements `DELETE`,
+        # `MERGE` and `TRUNCATE`. (See {#statement_type}.)
+        #
+        # @return [Integer, nil] The number of deleted rows, or `nil` if not
+        #   applicable.
+        #
+        def deleted_row_count
+          @gapi.statistics.query&.dml_stats&.deleted_row_count
+        end
+
+        ##
+        # The number of inserted rows. Present only for DML statements `INSERT`
+        # and `MERGE`. (See {#statement_type}.)
+        #
+        # @return [Integer, nil] The number of inserted rows, or `nil` if not
+        #   applicable.
+        #
+        def inserted_row_count
+          @gapi.statistics.query&.dml_stats&.inserted_row_count
+        end
+
+        ##
+        # The number of updated rows. Present only for DML statements `UPDATE`
+        # and `MERGE`. (See {#statement_type}.)
+        #
+        # @return [Integer, nil] The number of updated rows, or `nil` if not
+        #   applicable.
+        #
+        def updated_row_count
+          @gapi.statistics.query&.dml_stats&.updated_row_count
+        end
+
         ##
         # The table in which the query results are stored.
         #
+        # @param [String] view Specifies the view that determines which table information is returned.
+        #   By default, basic table information and storage statistics (STORAGE_STATS) are returned.
+        #   Accepted values include `:unspecified`, `:basic`, `:storage`, and
+        #   `:full`. For more information, see [BigQuery Classes](@todo: Update the link).
+        #   The default value is the `:unspecified` view type.
+        #
         # @return [Table] A table instance.
         #
-        def destination
+        def destination view: nil
           table = @gapi.configuration.query.destination_table
           return nil unless table
           retrieve_table table.project_id,
                          table.dataset_id,
-                         table.table_id
+                         table.table_id,
+                         metadata_view: view
         end
 
         ##
@@ -383,9 +488,7 @@ module Google
         def udfs
           udfs_gapi = @gapi.configuration.query.user_defined_function_resources
           return nil unless udfs_gapi
-          Array(udfs_gapi).map do |udf|
-            udf.inline_code || udf.resource_uri
-          end
+          Array(udfs_gapi).map { |udf| udf.inline_code || udf.resource_uri }
         end
 
         ##
@@ -396,16 +499,77 @@ module Google
         #
         # @!group Attributes
         def encryption
-          EncryptionConfiguration.from_gapi(
-            @gapi.configuration.query.destination_encryption_configuration
-          )
+          EncryptionConfiguration.from_gapi @gapi.configuration.query.destination_encryption_configuration
+        end
+
+        ###
+        # Checks if the destination table will be range partitioned. See [Creating and using integer range partitioned
+        # tables](https://cloud.google.com/bigquery/docs/creating-integer-range-partitions).
+        #
+        # @return [Boolean] `true` when the table is range partitioned, or `false` otherwise.
+        #
+        # @!group Attributes
+        #
+        def range_partitioning?
+          !@gapi.configuration.query.range_partitioning.nil?
+        end
+
+        ###
+        # The field on which the destination table will be range partitioned, if any. The field must be a
+        # top-level `NULLABLE/REQUIRED` field. The only supported type is `INTEGER/INT64`. See
+        # [Creating and using integer range partitioned
+        # tables](https://cloud.google.com/bigquery/docs/creating-integer-range-partitions).
+        #
+        # @return [String, nil] The partition field, if a field was configured, or `nil` if not range partitioned.
+        #
+        # @!group Attributes
+        #
+        def range_partitioning_field
+          @gapi.configuration.query.range_partitioning.field if range_partitioning?
+        end
+
+        ###
+        # The start of range partitioning, inclusive. See [Creating and using integer range partitioned
+        # tables](https://cloud.google.com/bigquery/docs/creating-integer-range-partitions).
+        #
+        # @return [Integer, nil] The start of range partitioning, inclusive, or `nil` if not range partitioned.
+        #
+        # @!group Attributes
+        #
+        def range_partitioning_start
+          @gapi.configuration.query.range_partitioning.range.start if range_partitioning?
+        end
+
+        ###
+        # The width of each interval. See [Creating and using integer range partitioned
+        # tables](https://cloud.google.com/bigquery/docs/creating-integer-range-partitions).
+        #
+        # @return [Integer, nil] The width of each interval, for data in range partitions, or `nil` if not range
+        #   partitioned.
+        #
+        # @!group Attributes
+        #
+        def range_partitioning_interval
+          @gapi.configuration.query.range_partitioning.range.interval if range_partitioning?
+        end
+
+        ###
+        # The end of range partitioning, exclusive. See [Creating and using integer range partitioned
+        # tables](https://cloud.google.com/bigquery/docs/creating-integer-range-partitions).
+        #
+        # @return [Integer, nil] The end of range partitioning, exclusive, or `nil` if not range partitioned.
+        #
+        # @!group Attributes
+        #
+        def range_partitioning_end
+          @gapi.configuration.query.range_partitioning.range.end if range_partitioning?
         end
 
         ###
         # Checks if the destination table will be time-partitioned. See
         # [Partitioned Tables](https://cloud.google.com/bigquery/docs/partitioned-tables).
         #
-        # @return [Boolean, nil] `true` when the table will be time-partitioned,
+        # @return [Boolean] `true` when the table will be time-partitioned,
         #   or `false` otherwise.
         #
         # @!group Attributes
@@ -418,8 +582,9 @@ module Google
         # The period for which the destination table will be partitioned, if
         # any. See [Partitioned Tables](https://cloud.google.com/bigquery/docs/partitioned-tables).
         #
-        # @return [String, nil] The partition type. Currently the only supported
-        #   value is "DAY", or `nil` if not present.
+        # @return [String, nil] The partition type. The supported types are `DAY`,
+        #   `HOUR`, `MONTH`, and `YEAR`, which will generate one partition per day,
+        #   hour, month, and year, respectively; or `nil` if not present.
         #
         # @!group Attributes
         #
@@ -479,10 +644,15 @@ module Google
         ###
         # Checks if the destination table will be clustered.
         #
+        # See {QueryJob::Updater#clustering_fields=}, {Table#clustering_fields} and
+        # {Table#clustering_fields=}.
+        #
         # @see https://cloud.google.com/bigquery/docs/clustered-tables
-        #   Introduction to Clustered Tables
+        #   Introduction to clustered tables
+        # @see https://cloud.google.com/bigquery/docs/creating-clustered-tables
+        #   Creating and using clustered tables
         #
-        # @return [Boolean, nil] `true` when the table will be clustered,
+        # @return [Boolean] `true` when the table will be clustered,
         #   or `false` otherwise.
         #
         # @!group Attributes
@@ -497,14 +667,16 @@ module Google
         # be first partitioned and subsequently clustered. The order of the
         # returned fields determines the sort order of the data.
         #
-        # See {QueryJob::Updater#clustering_fields=}.
+        # BigQuery supports clustering for both partitioned and non-partitioned
+        # tables.
+        #
+        # See {QueryJob::Updater#clustering_fields=}, {Table#clustering_fields} and
+        # {Table#clustering_fields=}.
         #
-        # @see https://cloud.google.com/bigquery/docs/partitioned-tables
-        #   Partitioned Tables
         # @see https://cloud.google.com/bigquery/docs/clustered-tables
-        #   Introduction to Clustered Tables
+        #   Introduction to clustered tables
         # @see https://cloud.google.com/bigquery/docs/creating-clustered-tables
-        #   Creating and Using Clustered Tables
+        #   Creating and using clustered tables
         #
         # @return [Array<String>, nil] The clustering fields, or `nil` if the
         #   destination table will not be clustered.
@@ -535,8 +707,7 @@ module Google
 
           ensure_service!
           loop do
-            query_results_gapi = service.job_query_results \
-              job_id, location: location, max: 0
+            query_results_gapi = service.job_query_results job_id, location: location, max: 0
             if query_results_gapi.job_complete
               @destination_schema_gapi = query_results_gapi.schema
               break
@@ -566,27 +737,28 @@ module Google
         #
         #   job.wait_until_done!
         #   data = job.data
+        #
+        #   # Iterate over the first page of results
         #   data.each do |row|
         #     puts row[:word]
         #   end
+        #   # Retrieve the next page of results
         #   data = data.next if data.next?
         #
         def data token: nil, max: nil, start: nil
           return nil unless done?
-          if dryrun?
-            return Data.from_gapi_json({ rows: [] }, nil, @gapi, service)
-          end
+          return Data.from_gapi_json({ rows: [] }, nil, @gapi, service) if dryrun?
           if ddl? || dml?
             data_hash = { totalRows: nil, rows: [] }
             return Data.from_gapi_json data_hash, nil, @gapi, service
           end
           ensure_schema!
 
-          options = { token: token, max: max, start: start }
-          data_hash = service.list_tabledata \
-            destination_table_dataset_id,
-            destination_table_table_id,
-            options
+          data_hash = service.list_tabledata destination_table_dataset_id,
+                                             destination_table_table_id,
+                                             token: token,
+                                             max: max,
+                                             start: start
           Data.from_gapi_json data_hash, destination_table_gapi, @gapi, service
         end
         alias query_results data
@@ -597,12 +769,11 @@ module Google
           ##
           # @private Create an Updater object.
           def initialize service, gapi
+            super()
             @service = service
             @gapi = gapi
           end
 
-          # rubocop:disable all
-
           ##
           # @private Create an Updater from an options hash.
           #
@@ -624,15 +795,16 @@ 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.create_session = options[:create_session]
+            updater.session_id = options[:session_id] if options[:session_id]
             updater.write = options[:write]
             updater.table = options[:table]
             updater.dryrun = options[:dryrun]
             updater.maximum_bytes_billed = options[:maximum_bytes_billed]
             updater.labels = options[:labels] if options[:labels]
-            updater.legacy_sql = Convert.resolve_legacy_sql(
-              options[:standard_sql], options[:legacy_sql])
+            updater.legacy_sql = Convert.resolve_legacy_sql options[:standard_sql], options[:legacy_sql]
             updater.external = options[:external] if options[:external]
             updater.priority = options[:priority]
             updater.cache = options[:cache]
@@ -642,8 +814,6 @@ module Google
             updater
           end
 
-          # rubocop:enable all
-
           ##
           # Sets the geographic location where the job should run. Required
           # except for US and EU.
@@ -731,41 +901,127 @@ module Google
           #
           # @!group Attributes
           def dataset= value
-            @gapi.configuration.query.default_dataset =
-              @service.dataset_ref_from value
+            @gapi.configuration.query.default_dataset = @service.dataset_ref_from value
           end
 
           ##
           # 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.
+          #
+          #   BigQuery types are converted from Ruby types as follows:
+          #
+          #   | BigQuery     | Ruby                                 | Notes                                            |
+          #   |--------------|--------------------------------------|--------------------------------------------------|
+          #   | `BOOL`       | `true`/`false`                       |                                                  |
+          #   | `INT64`      | `Integer`                            |                                                  |
+          #   | `FLOAT64`    | `Float`                              |                                                  |
+          #   | `NUMERIC`    | `BigDecimal`                         | `BigDecimal` values will be rounded to scale 9.  |
+          #   | `BIGNUMERIC` | `BigDecimal`                         | NOT AUTOMATIC: Must be mapped using `types`.     |
+          #   | `STRING`     | `String`                             |                                                  |
+          #   | `DATETIME`   | `DateTime`                           | `DATETIME` does not support time zone.           |
+          #   | `DATE`       | `Date`                               |                                                  |
+          #   | `GEOGRAPHY`  | `String` (WKT or GeoJSON)            | NOT AUTOMATIC: Must be mapped using `types`.     |
+          #   | `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. For the `GEOGRAPHY` type, see [Working with BigQuery
+          #   GIS data](https://cloud.google.com/bigquery/docs/gis-data).
           #
           # @!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.
+          #
+          #   BigQuery types are converted from Ruby types as follows:
+          #
+          #   | BigQuery     | Ruby                                 | Notes                                            |
+          #   |--------------|--------------------------------------|--------------------------------------------------|
+          #   | `BOOL`       | `true`/`false`                       |                                                  |
+          #   | `INT64`      | `Integer`                            |                                                  |
+          #   | `FLOAT64`    | `Float`                              |                                                  |
+          #   | `NUMERIC`    | `BigDecimal`                         | `BigDecimal` values will be rounded to scale 9.  |
+          #   | `BIGNUMERIC` | `BigDecimal`                         | NOT AUTOMATIC: Must be mapped using `types`.     |
+          #   | `STRING`     | `String`                             |                                                  |
+          #   | `DATETIME`   | `DateTime`                           | `DATETIME` does not support time zone.           |
+          #   | `DATE`       | `Date`                               |                                                  |
+          #   | `GEOGRAPHY`  | `String` (WKT or GeoJSON)            | NOT AUTOMATIC: Must be mapped using `types`.     |
+          #   | `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. For the `GEOGRAPHY` type, see [Working with BigQuery
+          #   GIS data](https://cloud.google.com/bigquery/docs/gis-data).
+          # @param [Array, Hash] types Standard SQL only. Types of the SQL parameters in `params`. It is not always
+          #   possible 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.
+          #
+          #   Arguments 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`
+          #   * `:BIGNUMERIC`
+          #   * `:STRING`
+          #   * `:DATETIME`
+          #   * `:DATE`
+          #   * `:GEOGRAPHY`
+          #   * `: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
+            when Array
               @gapi.configuration.query.use_legacy_sql = false
               @gapi.configuration.query.parameter_mode = "POSITIONAL"
-              @gapi.configuration.query.query_parameters = params.map do |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
+            when Hash
               @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 do |named_param|
-                    named_param.name = String name
-                  end
-                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
 
@@ -783,8 +1039,38 @@ module Google
           #
           # @!group Attributes
           def create= value
-            @gapi.configuration.query.create_disposition =
-              Convert.create_disposition value
+            @gapi.configuration.query.create_disposition = Convert.create_disposition value
+          end
+
+          ##
+          # Sets the create_session property. If true, creates a new session,
+          # where session id will be a server generated random id. If false,
+          # runs query with an existing {#session_id=}, otherwise runs query in
+          # non-session mode. The default value is `false`.
+          #
+          # @param [Boolean] value The create_session property. The default
+          # value is `false`.
+          #
+          # @!group Attributes
+          def create_session= value
+            @gapi.configuration.query.create_session = value
+          end
+
+          ##
+          # Sets the session ID for a query run in session mode. See {#create_session=}.
+          #
+          # @param [String] value The session ID. The default value is `nil`.
+          #
+          # @!group Attributes
+          def session_id= value
+            @gapi.configuration.query.connection_properties ||= []
+            prop = @gapi.configuration.query.connection_properties.find { |cp| cp.key == "session_id" }
+            if prop
+              prop.value = value
+            else
+              prop = Google::Apis::BigqueryV2::ConnectionProperty.new key: "session_id", value: value
+              @gapi.configuration.query.connection_properties << prop
+            end
           end
 
           ##
@@ -802,8 +1088,7 @@ module Google
           #
           # @!group Attributes
           def write= value
-            @gapi.configuration.query.write_disposition =
-              Convert.write_disposition value
+            @gapi.configuration.query.write_disposition = Convert.write_disposition value
           end
 
           ##
@@ -849,12 +1134,21 @@ module Google
           # Sets the labels to use for the job.
           #
           # @param [Hash] value A hash of user-provided labels associated with
-          #   the job. You can use these to organize and group your jobs. Label
-          #   keys and values can be no longer than 63 characters, can only
-          #   contain lowercase letters, numeric characters, underscores and
-          #   dashes. International characters are allowed. Label values are
-          #   optional. Label keys must start with a letter and each label in
-          #   the list must have a different key.
+          #   the job. You can use these to organize and group your jobs.
+          #
+          #   The labels applied to a resource must meet the following requirements:
+          #
+          #   * Each resource can have multiple labels, up to a maximum of 64.
+          #   * Each label must be a key-value pair.
+          #   * Keys have a minimum length of 1 character and a maximum length of
+          #     63 characters, and cannot be empty. Values can be empty, and have
+          #     a maximum length of 63 characters.
+          #   * Keys and values can contain only lowercase letters, numeric characters,
+          #     underscores, and dashes. All characters must use UTF-8 encoding, and
+          #     international characters are allowed.
+          #   * The key portion of a label must be unique. However, you can use the
+          #     same key with multiple resources.
+          #   * Keys must start with a lowercase letter or international character.
           #
           # @!group Attributes
           #
@@ -905,10 +1199,8 @@ module Google
           # @!group Attributes
           #
           def external= value
-            external_table_pairs = value.map do |name, obj|
-              [String(name), obj.to_gapi]
-            end
-            external_table_hash = Hash[external_table_pairs]
+            external_table_pairs = value.map { |name, obj| [String(name), obj.to_gapi] }
+            external_table_hash = external_table_pairs.to_h
             @gapi.configuration.query.table_definitions = external_table_hash
           end
 
@@ -925,8 +1217,7 @@ module Google
           #
           # @!group Attributes
           def udfs= value
-            @gapi.configuration.query.user_defined_function_resources =
-              udfs_gapi_from value
+            @gapi.configuration.query.user_defined_function_resources = udfs_gapi_from value
           end
 
           ##
@@ -950,21 +1241,180 @@ module Google
           #
           # @!group Attributes
           def encryption= val
-            @gapi.configuration.query.update!(
-              destination_encryption_configuration: val.to_gapi
+            @gapi.configuration.query.update! destination_encryption_configuration: val.to_gapi
+          end
+
+          ##
+          # Sets the field on which to range partition the table. See [Creating and using integer range partitioned
+          # tables](https://cloud.google.com/bigquery/docs/creating-integer-range-partitions).
+          #
+          # See {#range_partitioning_start=}, {#range_partitioning_interval=} and {#range_partitioning_end=}.
+          #
+          # You can only set range partitioning when creating a table. BigQuery does not allow you to change
+          # partitioning on an existing table.
+          #
+          # @param [String] field The range partition field. the destination table is partitioned by this
+          #   field. The field must be a top-level `NULLABLE/REQUIRED` field. The only supported
+          #   type is `INTEGER/INT64`.
+          #
+          # @example
+          #   require "google/cloud/bigquery"
+          #
+          #   bigquery = Google::Cloud::Bigquery.new
+          #   dataset = bigquery.dataset "my_dataset"
+          #   destination_table = dataset.table "my_destination_table",
+          #                                     skip_lookup: true
+          #
+          #   job = bigquery.query_job "SELECT num FROM UNNEST(GENERATE_ARRAY(0, 99)) AS num" do |job|
+          #     job.table = destination_table
+          #     job.range_partitioning_field = "num"
+          #     job.range_partitioning_start = 0
+          #     job.range_partitioning_interval = 10
+          #     job.range_partitioning_end = 100
+          #   end
+          #
+          #   job.wait_until_done!
+          #   job.done? #=> true
+          #
+          # @!group Attributes
+          #
+          def range_partitioning_field= field
+            @gapi.configuration.query.range_partitioning ||= Google::Apis::BigqueryV2::RangePartitioning.new(
+              range: Google::Apis::BigqueryV2::RangePartitioning::Range.new
+            )
+            @gapi.configuration.query.range_partitioning.field = field
+          end
+
+          ##
+          # Sets the start of range partitioning, inclusive, for the destination table. See [Creating and using integer
+          # range partitioned tables](https://cloud.google.com/bigquery/docs/creating-integer-range-partitions).
+          #
+          # You can only set range partitioning when creating a table. BigQuery does not allow you to change
+          # partitioning on an existing table.
+          #
+          # See {#range_partitioning_field=}, {#range_partitioning_interval=} and {#range_partitioning_end=}.
+          #
+          # @param [Integer] range_start The start of range partitioning, inclusive.
+          #
+          # @example
+          #   require "google/cloud/bigquery"
+          #
+          #   bigquery = Google::Cloud::Bigquery.new
+          #   dataset = bigquery.dataset "my_dataset"
+          #   destination_table = dataset.table "my_destination_table",
+          #                                     skip_lookup: true
+          #
+          #   job = bigquery.query_job "SELECT num FROM UNNEST(GENERATE_ARRAY(0, 99)) AS num" do |job|
+          #     job.table = destination_table
+          #     job.range_partitioning_field = "num"
+          #     job.range_partitioning_start = 0
+          #     job.range_partitioning_interval = 10
+          #     job.range_partitioning_end = 100
+          #   end
+          #
+          #   job.wait_until_done!
+          #   job.done? #=> true
+          #
+          # @!group Attributes
+          #
+          def range_partitioning_start= range_start
+            @gapi.configuration.query.range_partitioning ||= Google::Apis::BigqueryV2::RangePartitioning.new(
+              range: Google::Apis::BigqueryV2::RangePartitioning::Range.new
+            )
+            @gapi.configuration.query.range_partitioning.range.start = range_start
+          end
+
+          ##
+          # Sets width of each interval for data in range partitions. See [Creating and using integer range partitioned
+          # tables](https://cloud.google.com/bigquery/docs/creating-integer-range-partitions).
+          #
+          # You can only set range partitioning when creating a table. BigQuery does not allow you to change
+          # partitioning on an existing table.
+          #
+          # See {#range_partitioning_field=}, {#range_partitioning_start=} and {#range_partitioning_end=}.
+          #
+          # @param [Integer] range_interval The width of each interval, for data in partitions.
+          #
+          # @example
+          #   require "google/cloud/bigquery"
+          #
+          #   bigquery = Google::Cloud::Bigquery.new
+          #   dataset = bigquery.dataset "my_dataset"
+          #   destination_table = dataset.table "my_destination_table",
+          #                                     skip_lookup: true
+          #
+          #   job = bigquery.query_job "SELECT num FROM UNNEST(GENERATE_ARRAY(0, 99)) AS num" do |job|
+          #     job.table = destination_table
+          #     job.range_partitioning_field = "num"
+          #     job.range_partitioning_start = 0
+          #     job.range_partitioning_interval = 10
+          #     job.range_partitioning_end = 100
+          #   end
+          #
+          #   job.wait_until_done!
+          #   job.done? #=> true
+          #
+          # @!group Attributes
+          #
+          def range_partitioning_interval= range_interval
+            @gapi.configuration.query.range_partitioning ||= Google::Apis::BigqueryV2::RangePartitioning.new(
+              range: Google::Apis::BigqueryV2::RangePartitioning::Range.new
             )
+            @gapi.configuration.query.range_partitioning.range.interval = range_interval
+          end
+
+          ##
+          # Sets the end of range partitioning, exclusive, for the destination table. See [Creating and using integer
+          # range partitioned tables](https://cloud.google.com/bigquery/docs/creating-integer-range-partitions).
+          #
+          # You can only set range partitioning when creating a table. BigQuery does not allow you to change
+          # partitioning on an existing table.
+          #
+          # See {#range_partitioning_start=}, {#range_partitioning_interval=} and {#range_partitioning_field=}.
+          #
+          # @param [Integer] range_end The end of range partitioning, exclusive.
+          #
+          # @example
+          #   require "google/cloud/bigquery"
+          #
+          #   bigquery = Google::Cloud::Bigquery.new
+          #   dataset = bigquery.dataset "my_dataset"
+          #   destination_table = dataset.table "my_destination_table",
+          #                                     skip_lookup: true
+          #
+          #   job = bigquery.query_job "SELECT num FROM UNNEST(GENERATE_ARRAY(0, 99)) AS num" do |job|
+          #     job.table = destination_table
+          #     job.range_partitioning_field = "num"
+          #     job.range_partitioning_start = 0
+          #     job.range_partitioning_interval = 10
+          #     job.range_partitioning_end = 100
+          #   end
+          #
+          #   job.wait_until_done!
+          #   job.done? #=> true
+          #
+          # @!group Attributes
+          #
+          def range_partitioning_end= range_end
+            @gapi.configuration.query.range_partitioning ||= Google::Apis::BigqueryV2::RangePartitioning.new(
+              range: Google::Apis::BigqueryV2::RangePartitioning::Range.new
+            )
+            @gapi.configuration.query.range_partitioning.range.end = range_end
           end
 
           ##
           # Sets the partitioning for the destination table. See [Partitioned
           # Tables](https://cloud.google.com/bigquery/docs/partitioned-tables).
+          # The supported types are `DAY`, `HOUR`, `MONTH`, and `YEAR`, which will
+          # generate one partition per day, hour, month, and year, respectively.
           #
           # You can only set the partitioning field while creating a table.
           # BigQuery does not allow you to change partitioning on an existing
           # table.
           #
-          # @param [String] type The partition type. Currently the only
-          #   supported value is "DAY".
+          # @param [String] type The partition type. The supported types are `DAY`,
+          #   `HOUR`, `MONTH`, and `YEAR`, which will generate one partition per day,
+          #   hour, month, and year, respectively.
           #
           # @example
           #   require "google/cloud/bigquery"
@@ -989,8 +1439,7 @@ module Google
           # @!group Attributes
           #
           def time_partitioning_type= type
-            @gapi.configuration.query.time_partitioning ||= \
-              Google::Apis::BigqueryV2::TimePartitioning.new
+            @gapi.configuration.query.time_partitioning ||= Google::Apis::BigqueryV2::TimePartitioning.new
             @gapi.configuration.query.time_partitioning.update! type: type
           end
 
@@ -1036,8 +1485,7 @@ module Google
           # @!group Attributes
           #
           def time_partitioning_field= field
-            @gapi.configuration.query.time_partitioning ||= \
-              Google::Apis::BigqueryV2::TimePartitioning.new
+            @gapi.configuration.query.time_partitioning ||= Google::Apis::BigqueryV2::TimePartitioning.new
             @gapi.configuration.query.time_partitioning.update! field: field
           end
 
@@ -1076,10 +1524,8 @@ module Google
           # @!group Attributes
           #
           def time_partitioning_expiration= expiration
-            @gapi.configuration.query.time_partitioning ||= \
-              Google::Apis::BigqueryV2::TimePartitioning.new
-            @gapi.configuration.query.time_partitioning.update! \
-              expiration_ms: expiration * 1000
+            @gapi.configuration.query.time_partitioning ||= Google::Apis::BigqueryV2::TimePartitioning.new
+            @gapi.configuration.query.time_partitioning.update! expiration_ms: expiration * 1000
           end
 
           ##
@@ -1094,30 +1540,28 @@ module Google
           # @!group Attributes
           #
           def time_partitioning_require_filter= val
-            @gapi.configuration.query.time_partitioning ||= \
-              Google::Apis::BigqueryV2::TimePartitioning.new
-            @gapi.configuration.query.time_partitioning.update! \
-              require_partition_filter: val
+            @gapi.configuration.query.time_partitioning ||= Google::Apis::BigqueryV2::TimePartitioning.new
+            @gapi.configuration.query.time_partitioning.update! require_partition_filter: val
           end
 
           ##
-          # Sets one or more fields on which the destination table should be
-          # clustered. Must be specified with time-based partitioning, data in
-          # the table will be first partitioned and subsequently clustered.
+          # Sets the list of fields on which data should be clustered.
           #
           # Only top-level, non-repeated, simple-type fields are supported. When
           # you cluster a table using multiple columns, the order of columns you
           # specify is important. The order of the specified columns determines
           # the sort order of the data.
           #
-          # See {QueryJob#clustering_fields}.
+          # BigQuery supports clustering for both partitioned and non-partitioned
+          # tables.
+          #
+          # See {QueryJob#clustering_fields}, {Table#clustering_fields} and
+          # {Table#clustering_fields=}.
           #
-          # @see https://cloud.google.com/bigquery/docs/partitioned-tables
-          #   Partitioned Tables
           # @see https://cloud.google.com/bigquery/docs/clustered-tables
-          #   Introduction to Clustered Tables
+          #   Introduction to clustered tables
           # @see https://cloud.google.com/bigquery/docs/creating-clustered-tables
-          #   Creating and Using Clustered Tables
+          #   Creating and using clustered tables
           #
           # @param [Array<String>] fields The clustering fields. Only top-level,
           #   non-repeated, simple-type fields are supported.
@@ -1143,11 +1587,27 @@ module Google
           # @!group Attributes
           #
           def clustering_fields= fields
-            @gapi.configuration.query.clustering ||= \
-              Google::Apis::BigqueryV2::Clustering.new
+            @gapi.configuration.query.clustering ||= Google::Apis::BigqueryV2::Clustering.new
             @gapi.configuration.query.clustering.fields = fields
           end
 
+          def cancel
+            raise "not implemented in #{self.class}"
+          end
+
+          def rerun!
+            raise "not implemented in #{self.class}"
+          end
+
+          def reload!
+            raise "not implemented in #{self.class}"
+          end
+          alias refresh! reload!
+
+          def wait_until_done!
+            raise "not implemented in #{self.class}"
+          end
+
           ##
           # @private Returns the Google API client library version of this job.
           #
@@ -1170,14 +1630,12 @@ module Google
           end
 
           def priority_value str
-            { "batch"       => "BATCH",
-              "interactive" => "INTERACTIVE" }[str.to_s.downcase]
+            { "batch" => "BATCH", "interactive" => "INTERACTIVE" }[str.to_s.downcase]
           end
 
           def udfs_gapi_from array_or_str
             Array(array_or_str).map do |uri_or_code|
-              resource =
-                Google::Apis::BigqueryV2::UserDefinedFunctionResource.new
+              resource = Google::Apis::BigqueryV2::UserDefinedFunctionResource.new
               if uri_or_code.start_with? "gs://"
                 resource.resource_uri = uri_or_code
               else
@@ -1237,17 +1695,26 @@ module Google
         #   end
         #
         class Stage
-          attr_reader :compute_ratio_avg, :compute_ratio_max, :id, :name,
-                      :read_ratio_avg, :read_ratio_max, :records_read,
-                      :records_written, :status, :steps, :wait_ratio_avg,
-                      :wait_ratio_max, :write_ratio_avg, :write_ratio_max
+          attr_reader :compute_ratio_avg
+          attr_reader :compute_ratio_max
+          attr_reader :id
+          attr_reader :name
+          attr_reader :read_ratio_avg
+          attr_reader :read_ratio_max
+          attr_reader :records_read
+          attr_reader :records_written
+          attr_reader :status
+          attr_reader :steps
+          attr_reader :wait_ratio_avg
+          attr_reader :wait_ratio_max
+          attr_reader :write_ratio_avg
+          attr_reader :write_ratio_max
 
           ##
           # @private Creates a new Stage instance.
-          def initialize compute_ratio_avg, compute_ratio_max, id, name,
-                         read_ratio_avg, read_ratio_max, records_read,
-                         records_written, status, steps, wait_ratio_avg,
-                         wait_ratio_max, write_ratio_avg, write_ratio_max
+          def initialize compute_ratio_avg, compute_ratio_max, id, name, read_ratio_avg, read_ratio_max, records_read,
+                         records_written, status, steps, wait_ratio_avg, wait_ratio_max, write_ratio_avg,
+                         write_ratio_max
             @compute_ratio_avg = compute_ratio_avg
             @compute_ratio_max = compute_ratio_max
             @id                = id
@@ -1268,11 +1735,9 @@ module Google
           # @private New Stage from a statistics.query.queryPlan element.
           def self.from_gapi gapi
             steps = Array(gapi.steps).map { |g| Step.from_gapi g }
-            new gapi.compute_ratio_avg, gapi.compute_ratio_max, gapi.id,
-                gapi.name, gapi.read_ratio_avg, gapi.read_ratio_max,
-                gapi.records_read, gapi.records_written, gapi.status, steps,
-                gapi.wait_ratio_avg, gapi.wait_ratio_max, gapi.write_ratio_avg,
-                gapi.write_ratio_max
+            new gapi.compute_ratio_avg, gapi.compute_ratio_max, gapi.id, gapi.name, gapi.read_ratio_avg,
+                gapi.read_ratio_max, gapi.records_read, gapi.records_written, gapi.status, steps, gapi.wait_ratio_avg,
+                gapi.wait_ratio_max, gapi.write_ratio_avg, gapi.write_ratio_max
           end
         end
 
@@ -1306,7 +1771,8 @@ module Google
         #   end
         #
         class Step
-          attr_reader :kind, :substeps
+          attr_reader :kind
+          attr_reader :substeps
 
           ##
           # @private Creates a new Stage instance.
@@ -1327,8 +1793,7 @@ module Google
         def ensure_schema!
           return unless destination_schema.nil?
 
-          query_results_gapi = service.job_query_results \
-            job_id, location: location, max: 0
+          query_results_gapi = service.job_query_results job_id, location: location, max: 0
           # raise "unable to retrieve schema" if query_results_gapi.schema.nil?
           @destination_schema_gapi = query_results_gapi.schema
         end
@@ -1346,9 +1811,10 @@ module Google
         end
 
         def destination_table_gapi
-          Google::Apis::BigqueryV2::Table.new \
+          Google::Apis::BigqueryV2::Table.new(
             table_reference: @gapi.configuration.query.destination_table,
             schema:          destination_schema
+          )
         end
       end
     end