google-cloud-bigquery 1.8.2 → 1.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a0a449a43a1a49603e04ea3d47e7e60a3145fc47da1637e6a995209701479f2b
-  data.tar.gz: 7f18be48f6a7dd9cb641a60dc38a20f5f0cdc6005b932a54339203c585b153bb
+  metadata.gz: 783828eac7c8335eced73772ee8d7f154daa10adfb2976c0961bca8132d449f5
+  data.tar.gz: baf70806a64f209d6fd7d5567b11df9287879ea941478054ca4806dafb8980ec
 SHA512:
-  metadata.gz: 07070a48ae7e992e29df9da0b4fe105bbfc7bdc038eef7a861ccdce4dd5269dea568df3190286f48b52a95bbf85e9b66957bc03a17180bbb84e4dbde5b0aceb5
-  data.tar.gz: ef0afe60412417e242ae1d0acfe1ddd72d6e0473535f8d1b425e451372411bd7fdac427ae6c3faa325552daca83e9f6a9614314e1b226684f783b230a79a61db
+  metadata.gz: dd35d5d59e70c1d6aa417bed8e48a5d94454353953b8a674f28f94a03ee748d8c559028ef5551a9e2c6d3ec98a67b036e48c8bbc261cf44671eb3f4d1ccd6086
+  data.tar.gz: 2bffb6a6249419fdc9745e8f829a04f53daae9bdbc67fd72c9e58e8a70741e9261df1f189139bd73b5aacfe0584acacbd438720a6d314c5410cd40c30c675063

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Release History
 
+### 1.9.0 / 2018-10-25
+
+* Add clustering fields to LoadJob, QueryJob and Table
+* Add DDL/DML support
+  * Update QueryJob#data to not return table rows for DDL/DML
+  * Add DDL/DML statistics attrs to QueryJob and Data
+* Add #numeric to Table::Updater and LoadJob::Updater (@leklund)
+
 ### 1.8.2 / 2018-09-20
 
 * Update documentation.

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

@@ -59,6 +59,10 @@ module Google
         # @private The Google API Client object in JSON Hash.
         attr_accessor :gapi_json
 
+        ##
+        # @private The query Job gapi object, or nil if from Table#data.
+        attr_accessor :job_gapi
+
         # @private
         def initialize arr = []
           @service = nil
@@ -195,6 +199,130 @@ module Google
           schema.headers
         end
 
+        ##
+        # The type of query statement, if valid. Possible values (new values
+        # might be added in the future):
+        #
+        # * "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
+        #   Statements](https://cloud.google.com/bigquery/docs/reference/standard-sql/data-definition-language)
+        # * "CREATE_TABLE_AS_SELECT": DDL statement, see [Using Data Definition
+        #   Language Statements](https://cloud.google.com/bigquery/docs/reference/standard-sql/data-definition-language)
+        # * "CREATE_VIEW": DDL statement, see [Using Data Definition Language
+        #   Statements](https://cloud.google.com/bigquery/docs/reference/standard-sql/data-definition-language)
+        # * "DELETE": DML statement, see [Data Manipulation Language Syntax](https://cloud.google.com/bigquery/docs/reference/standard-sql/dml-syntax)
+        # * "DROP_MODEL": DDL statement, see [Using Data Definition Language
+        #   Statements](https://cloud.google.com/bigquery/docs/reference/standard-sql/data-definition-language)
+        # * "DROP_TABLE": DDL statement, see [Using Data Definition Language
+        #   Statements](https://cloud.google.com/bigquery/docs/reference/standard-sql/data-definition-language)
+        # * "DROP_VIEW": DDL statement, see [Using Data Definition Language
+        #   Statements](https://cloud.google.com/bigquery/docs/reference/standard-sql/data-definition-language)
+        # * "INSERT": DML statement, see [Data Manipulation Language Syntax](https://cloud.google.com/bigquery/docs/reference/standard-sql/dml-syntax)
+        # * "MERGE": DML statement, see [Data Manipulation Language Syntax](https://cloud.google.com/bigquery/docs/reference/standard-sql/dml-syntax)
+        # * "SELECT": SQL query, see [Standard SQL Query Syntax](https://cloud.google.com/bigquery/docs/reference/standard-sql/query-syntax)
+        # * "UPDATE": DML statement, see [Data Manipulation Language Syntax](https://cloud.google.com/bigquery/docs/reference/standard-sql/dml-syntax)
+        #
+        # @return [String, nil] The type of query statement.
+        #
+        def statement_type
+          return nil unless job_gapi && job_gapi.statistics.query
+          job_gapi.statistics.query.statement_type
+        end
+
+        ##
+        # Whether the query that created this data was a DDL statement.
+        #
+        # @see https://cloud.google.com/bigquery/docs/reference/standard-sql/data-definition-language
+        #   Using Data Definition Language Statements
+        #
+        # @return [Boolean]
+        #
+        # @example
+        #   require "google/cloud/bigquery"
+        #
+        #   bigquery = Google::Cloud::Bigquery.new
+        #   data = bigquery.query "CREATE TABLE my_table (x INT64)"
+        #
+        #   data.statement_type #=> "CREATE_TABLE"
+        #   data.ddl? #=> true
+        #
+        def ddl?
+          %w[CREATE_MODEL CREATE_TABLE CREATE_TABLE_AS_SELECT CREATE_VIEW \
+             DROP_MODEL DROP_TABLE DROP_VIEW].include? statement_type
+        end
+
+        ##
+        # Whether the query that created this data was a DML statement.
+        #
+        # @see https://cloud.google.com/bigquery/docs/reference/standard-sql/dml-syntax
+        #   Data Manipulation Language Syntax
+        #
+        # @return [Boolean]
+        #
+        # @example
+        #   require "google/cloud/bigquery"
+        #
+        #   bigquery = Google::Cloud::Bigquery.new
+        #   data = bigquery.query "UPDATE my_table " \
+        #                         "SET x = x + 1 " \
+        #                         "WHERE x IS NOT NULL"
+        #
+        #   data.statement_type #=> "UPDATE"
+        #   data.dml? #=> true
+        #
+        def dml?
+          %w[INSERT UPDATE MERGE DELETE].include? statement_type
+        end
+
+        ##
+        # The DDL operation performed, possibly dependent on the pre-existence
+        # of the DDL target. (See {#ddl_target_table}.) Possible values (new
+        # values might be added in the future):
+        #
+        # * "CREATE": The query created the DDL target.
+        # * "SKIP": No-op. Example cases: the query is
+        #   `CREATE TABLE IF NOT EXISTS` while the table already exists, or the
+        #   query is `DROP TABLE IF EXISTS` while the table does not exist.
+        # * "REPLACE": The query replaced the DDL target. Example case: the
+        #   query is `CREATE OR REPLACE TABLE`, and the table already exists.
+        # * "DROP": The query deleted the DDL target.
+        #
+        # @return [String, nil] The DDL operation performed.
+        #
+        def ddl_operation_performed
+          return nil unless job_gapi && job_gapi.statistics.query
+          job_gapi.statistics.query.ddl_operation_performed
+        end
+
+        ##
+        # The DDL target table, in reference state. (See {Table#reference?}.)
+        # Present only for `CREATE/DROP TABLE/VIEW` queries. (See
+        # {#statement_type}.)
+        #
+        # @return [Google::Cloud::Bigquery::Table, nil] The DDL target table, in
+        #   reference state.
+        #
+        def ddl_target_table
+          return nil unless job_gapi && job_gapi.statistics.query
+          ensure_service!
+          table = job_gapi.statistics.query.ddl_target_table
+          return nil unless table
+          Google::Cloud::Bigquery::Table.new_reference_from_gapi table, service
+        end
+
+        ##
+        # The number of rows affected by a DML statement. Present only for DML
+        # statements `INSERT`, `UPDATE` or `DELETE`. (See {#statement_type}.)
+        #
+        # @return [Integer, nil] The number of rows affected by a DML statement,
+        #   or `nil` if the query is not a DML statement.
+        #
+        def num_dml_affected_rows
+          return nil unless job_gapi && job_gapi.statistics.query
+          job_gapi.statistics.query.num_dml_affected_rows
+        end
+
         ##
         # Whether there is a next page of data.
         #
@@ -252,7 +380,7 @@ module Google
             @table_gapi.table_reference.dataset_id,
             @table_gapi.table_reference.table_id,
             token: token
-          self.class.from_gapi_json data_json, @table_gapi, @service
+          self.class.from_gapi_json data_json, @table_gapi, job_gapi, @service
         end
 
         ##
@@ -327,13 +455,16 @@ module Google
 
         ##
         # @private New Data from a response object.
-        def self.from_gapi_json gapi_json, table_gapi, service
-          formatted_rows = Convert.format_rows(gapi_json[:rows],
-                                               table_gapi.schema.fields)
+        def self.from_gapi_json gapi_json, table_gapi, job_gapi, service
+          rows = gapi_json[:rows] || []
+          unless rows.empty?
+            rows = Convert.format_rows rows, table_gapi.schema.fields
+          end
 
-          data = new formatted_rows
+          data = new rows
           data.table_gapi = table_gapi
           data.gapi_json = gapi_json
+          data.job_gapi = job_gapi
           data.service = service
           data
         end

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

@@ -874,6 +874,32 @@ module Google
         #     end
         #   end
         #
+        # @example Execute a DDL statement:
+        #   require "google/cloud/bigquery"
+        #
+        #   bigquery = Google::Cloud::Bigquery.new
+        #
+        #   job = bigquery.query_job "CREATE TABLE my_table (x INT64)"
+        #
+        #   job.wait_until_done!
+        #   if !job.failed?
+        #     table_ref = job.ddl_target_table
+        #   end
+        #
+        # @example Execute a DML statement:
+        #   require "google/cloud/bigquery"
+        #
+        #   bigquery = Google::Cloud::Bigquery.new
+        #
+        #   job = bigquery.query_job "UPDATE my_table " \
+        #                            "SET x = x + 1 " \
+        #                            "WHERE x IS NOT NULL"
+        #
+        #   job.wait_until_done!
+        #   if !job.failed?
+        #     puts job.num_dml_affected_rows
+        #   end
+        #
         # @example Query using external data source, set destination:
         #   require "google/cloud/bigquery"
         #
@@ -930,7 +956,8 @@ module Google
         # Queries data and waits for the results. In this method, a {QueryJob}
         # is created and its results are saved to a temporary table, then read
         # from the table. Timeouts and transient errors are generally handled
-        # as needed to complete the query.
+        # as needed to complete the query. When used for executing DDL/DML
+        # statements, this method does not return row data.
         #
         # Sets the current dataset as the default dataset in the query. Useful
         # for using unqualified table names.
@@ -1066,6 +1093,26 @@ module Google
         #     puts row[:name]
         #   end
         #
+        # @example Execute a DDL statement:
+        #   require "google/cloud/bigquery"
+        #
+        #   bigquery = Google::Cloud::Bigquery.new
+        #
+        #   data = bigquery.query "CREATE TABLE my_table (x INT64)"
+        #
+        #   table_ref = data.ddl_target_table
+        #
+        # @example Execute a DML statement:
+        #   require "google/cloud/bigquery"
+        #
+        #   bigquery = Google::Cloud::Bigquery.new
+        #
+        #   data = bigquery.query "UPDATE my_table " \
+        #                         "SET x = x + 1 " \
+        #                         "WHERE x IS NOT NULL"
+        #
+        #   puts data.num_dml_affected_rows
+        #
         # @example Query using external data source, set destination:
         #   require "google/cloud/bigquery"
         #
@@ -1798,7 +1845,7 @@ module Google
         ##
         # @private New lazy Dataset object without making an HTTP request.
         def self.new_reference project_id, dataset_id, service
-          # TODO: raise if dataset_id is nil?
+          raise ArgumentError, "dataset_id is required" unless dataset_id
           new.tap do |b|
             reference_gapi = Google::Apis::BigqueryV2::DatasetReference.new(
               project_id: project_id,

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

@@ -424,6 +424,45 @@ module Google
           tp.require_partition_filter
         end
 
+        ###
+        # Checks if the destination table will be clustered.
+        #
+        # @see https://cloud.google.com/bigquery/docs/clustered-tables
+        #   Introduction to Clustered Tables
+        #
+        # @return [Boolean, nil] `true` when the table will be clustered,
+        #   or `false` otherwise.
+        #
+        # @!group Attributes
+        #
+        def clustering?
+          !@gapi.configuration.load.clustering.nil?
+        end
+
+        ###
+        # 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. The order of the
+        # returned fields determines the sort order of the data.
+        #
+        # See {LoadJob::Updater#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
+        # @see https://cloud.google.com/bigquery/docs/creating-clustered-tables
+        #   Creating and Using Clustered Tables
+        #
+        # @return [Array<String>, nil] The clustering fields, or `nil` if the
+        #   destination table will not be clustered.
+        #
+        # @!group Attributes
+        #
+        def clustering_fields
+          @gapi.configuration.load.clustering.fields if clustering?
+        end
+
         ##
         # Yielded to a block to accumulate changes for a patch request.
         class Updater < LoadJob
@@ -599,6 +638,36 @@ module Google
             schema.float name, description: description, mode: mode
           end
 
+          ##
+          # Adds a numeric number field to the schema. Numeric is a
+          # fixed-precision numeric type with 38 decimal digits, 9 that follow
+          # the decimal point.
+          #
+          # See {Schema#numeric}
+          #
+          # @param [String] name The field name. The name must contain only
+          #   letters (a-z, A-Z), numbers (0-9), or underscores (_), and must
+          #   start with a letter or underscore. The maximum length is 128
+          #   characters.
+          # @param [String] description A description of the field.
+          # @param [Symbol] mode The field's mode. The possible values are
+          #   `:nullable`, `:required`, and `:repeated`. The default value is
+          #   `:nullable`.
+          #
+          # @example
+          #   require "google/cloud/bigquery"
+          #
+          #   bigquery = Google::Cloud::Bigquery.new
+          #   dataset = bigquery.dataset "my_dataset"
+          #   job = dataset.load_job "my_table", "gs://abc/file" do |schema|
+          #     schema.numeric "total_cost", mode: :required
+          #   end
+          #
+          # @!group Schema
+          def numeric name, description: nil, mode: :nullable
+            schema.numeric name, description: description, mode: mode
+          end
+
           ##
           # Adds a boolean field to the schema.
           #
@@ -1320,6 +1389,57 @@ module Google
               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.
+          #
+          # 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 {LoadJob#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
+          # @see https://cloud.google.com/bigquery/docs/creating-clustered-tables
+          #   Creating and Using Clustered Tables
+          #
+          # @param [Array<String>] fields The clustering fields. Only top-level,
+          #   non-repeated, simple-type fields are supported.
+          #
+          # @example
+          #   require "google/cloud/bigquery"
+          #
+          #   bigquery = Google::Cloud::Bigquery.new
+          #   dataset = bigquery.dataset "my_dataset"
+          #
+          #   gs_url = "gs://my-bucket/file-name.csv"
+          #   load_job = dataset.load_job "my_new_table", gs_url do |job|
+          #     job.time_partitioning_type  = "DAY"
+          #     job.time_partitioning_field = "dob"
+          #     job.schema do |schema|
+          #       schema.timestamp "dob", mode: :required
+          #       schema.string "first_name", mode: :required
+          #       schema.string "last_name", mode: :required
+          #     end
+          #     job.clustering_fields = ["last_name", "first_name"]
+          #   end
+          #
+          #   load_job.wait_until_done!
+          #   load_job.done? #=> true
+          #
+          # @!group Attributes
+          #
+          def clustering_fields= fields
+            @gapi.configuration.load.clustering ||= \
+              Google::Apis::BigqueryV2::Clustering.new
+            @gapi.configuration.load.clustering.fields = fields
+          end
+
           ##
           # @private Returns the Google API client library version of this job.
           #

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

@@ -302,6 +302,35 @@ module Google
         #     end
         #   end
         #
+        # @example Execute a DDL statement:
+        #   require "google/cloud/bigquery"
+        #
+        #   bigquery = Google::Cloud::Bigquery.new
+        #
+        #   job = bigquery.query_job "CREATE TABLE " \
+        #                            "`my_dataset.my_table` " \
+        #                            "(x INT64)"
+        #
+        #   job.wait_until_done!
+        #   if !job.failed?
+        #     table_ref = job.ddl_target_table
+        #   end
+        #
+        # @example Execute a DML statement:
+        #   require "google/cloud/bigquery"
+        #
+        #   bigquery = Google::Cloud::Bigquery.new
+        #
+        #   job = bigquery.query_job "UPDATE " \
+        #                            "`my_dataset.my_table` " \
+        #                            "SET x = x + 1 " \
+        #                            "WHERE x IS NOT NULL"
+        #
+        #   job.wait_until_done!
+        #   if !job.failed?
+        #     puts job.num_dml_affected_rows
+        #   end
+        #
         # @example Query using external data source, set destination:
         #   require "google/cloud/bigquery"
         #
@@ -356,7 +385,8 @@ module Google
         # Queries data and waits for the results. In this method, a {QueryJob}
         # is created and its results are saved to a temporary table, then read
         # from the table. Timeouts and transient errors are generally handled
-        # as needed to complete the query.
+        # as needed to complete the query. When used for executing DDL/DML
+        # statements, this method does not return row data.
         #
         # When using standard SQL and passing arguments using `params`, Ruby
         # types are mapped to BigQuery types as follows:
@@ -505,6 +535,26 @@ module Google
         #     puts row[:name]
         #   end
         #
+        # @example Execute a DDL statement:
+        #   require "google/cloud/bigquery"
+        #
+        #   bigquery = Google::Cloud::Bigquery.new
+        #
+        #   data = bigquery.query "CREATE TABLE `my_dataset.my_table` (x INT64)"
+        #
+        #   table_ref = data.ddl_target_table
+        #
+        # @example Execute a DML statement:
+        #   require "google/cloud/bigquery"
+        #
+        #   bigquery = Google::Cloud::Bigquery.new
+        #
+        #   data = bigquery.query "UPDATE `my_dataset.my_table` " \
+        #                         "SET x = x + 1 " \
+        #                         "WHERE x IS NOT NULL"
+        #
+        #   puts data.num_dml_affected_rows
+        #
         # @example Query using external data source, set destination:
         #   require "google/cloud/bigquery"
         #

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

@@ -200,15 +200,25 @@ module Google
         # The type of query statement, if valid. Possible values (new values
         # might be added in the future):
         #
-        # * "SELECT": `SELECT` query.
-        # * "INSERT": `INSERT` query; see https://cloud.google.com/bigquery/docs/reference/standard-sql/data-manipulation-language
-        # * "UPDATE": `UPDATE` query; see https://cloud.google.com/bigquery/docs/reference/standard-sql/data-manipulation-language
-        # * "DELETE": `DELETE` query; see https://cloud.google.com/bigquery/docs/reference/standard-sql/data-manipulation-language
-        # * "CREATE_TABLE": `CREATE [OR REPLACE] TABLE` without `AS SELECT`.
-        # * "CREATE_TABLE_AS_SELECT": `CREATE [OR REPLACE] TABLE ... AS SELECT`.
-        # * "DROP_TABLE": `DROP TABLE` query.
-        # * "CREATE_VIEW": `CREATE [OR REPLACE] VIEW ... AS SELECT ...`.
-        # * "DROP_VIEW": `DROP VIEW` query.
+        # * "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
+        #   Statements](https://cloud.google.com/bigquery/docs/reference/standard-sql/data-definition-language)
+        # * "CREATE_TABLE_AS_SELECT": DDL statement, see [Using Data Definition
+        #   Language Statements](https://cloud.google.com/bigquery/docs/reference/standard-sql/data-definition-language)
+        # * "CREATE_VIEW": DDL statement, see [Using Data Definition Language
+        #   Statements](https://cloud.google.com/bigquery/docs/reference/standard-sql/data-definition-language)
+        # * "DELETE": DML statement, see [Data Manipulation Language Syntax](https://cloud.google.com/bigquery/docs/reference/standard-sql/dml-syntax)
+        # * "DROP_MODEL": DDL statement, see [Using Data Definition Language
+        #   Statements](https://cloud.google.com/bigquery/docs/reference/standard-sql/data-definition-language)
+        # * "DROP_TABLE": DDL statement, see [Using Data Definition Language
+        #   Statements](https://cloud.google.com/bigquery/docs/reference/standard-sql/data-definition-language)
+        # * "DROP_VIEW": DDL statement, see [Using Data Definition Language
+        #   Statements](https://cloud.google.com/bigquery/docs/reference/standard-sql/data-definition-language)
+        # * "INSERT": DML statement, see [Data Manipulation Language Syntax](https://cloud.google.com/bigquery/docs/reference/standard-sql/dml-syntax)
+        # * "MERGE": DML statement, see [Data Manipulation Language Syntax](https://cloud.google.com/bigquery/docs/reference/standard-sql/dml-syntax)
+        # * "SELECT": SQL query, see [Standard SQL Query Syntax](https://cloud.google.com/bigquery/docs/reference/standard-sql/query-syntax)
+        # * "UPDATE": DML statement, see [Data Manipulation Language Syntax](https://cloud.google.com/bigquery/docs/reference/standard-sql/dml-syntax)
         #
         # @return [String, nil] The type of query statement.
         #
@@ -217,6 +227,51 @@ module Google
           @gapi.statistics.query.statement_type
         end
 
+        ##
+        # Whether the query is a DDL statement.
+        #
+        # @see https://cloud.google.com/bigquery/docs/reference/standard-sql/data-definition-language
+        #   Using Data Definition Language Statements
+        #
+        # @return [Boolean]
+        #
+        # @example
+        #   require "google/cloud/bigquery"
+        #
+        #   bigquery = Google::Cloud::Bigquery.new
+        #   query_job = bigquery.query_job "CREATE TABLE my_table (x INT64)"
+        #
+        #   query_job.statement_type #=> "CREATE_TABLE"
+        #   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
+        end
+
+        ##
+        # Whether the query is a DML statement.
+        #
+        # @see https://cloud.google.com/bigquery/docs/reference/standard-sql/dml-syntax
+        #   Data Manipulation Language Syntax
+        #
+        # @return [Boolean]
+        #
+        # @example
+        #   require "google/cloud/bigquery"
+        #
+        #   bigquery = Google::Cloud::Bigquery.new
+        #   query_job = bigquery.query_job "UPDATE my_table " \
+        #                                  "SET x = x + 1 " \
+        #                                  "WHERE x IS NOT NULL"
+        #
+        #   query_job.statement_type #=> "UPDATE"
+        #   query_job.dml? #=> true
+        #
+        def dml?
+          %w[INSERT UPDATE MERGE DELETE].include? statement_type
+        end
+
         ##
         # The DDL operation performed, possibly dependent on the pre-existence
         # of the DDL target. (See {#ddl_target_table}.) Possible values (new
@@ -253,6 +308,18 @@ module Google
           Google::Cloud::Bigquery::Table.new_reference_from_gapi table, service
         end
 
+        ##
+        # The number of rows affected by a DML statement. Present only for DML
+        # statements `INSERT`, `UPDATE` or `DELETE`. (See {#statement_type}.)
+        #
+        # @return [Integer, nil] The number of rows affected by a DML statement,
+        #   or `nil` if the query is not a DML statement.
+        #
+        def num_dml_affected_rows
+          return nil unless @gapi.statistics.query
+          @gapi.statistics.query.num_dml_affected_rows
+        end
+
         ##
         # The table in which the query results are stored.
         #
@@ -393,6 +460,45 @@ module Google
           tp.require_partition_filter
         end
 
+        ###
+        # Checks if the destination table will be clustered.
+        #
+        # @see https://cloud.google.com/bigquery/docs/clustered-tables
+        #   Introduction to Clustered Tables
+        #
+        # @return [Boolean, nil] `true` when the table will be clustered,
+        #   or `false` otherwise.
+        #
+        # @!group Attributes
+        #
+        def clustering?
+          !@gapi.configuration.query.clustering.nil?
+        end
+
+        ###
+        # 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. The order of the
+        # returned fields determines the sort order of the data.
+        #
+        # See {QueryJob::Updater#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
+        # @see https://cloud.google.com/bigquery/docs/creating-clustered-tables
+        #   Creating and Using Clustered Tables
+        #
+        # @return [Array<String>, nil] The clustering fields, or `nil` if the
+        #   destination table will not be clustered.
+        #
+        # @!group Attributes
+        #
+        def clustering_fields
+          @gapi.configuration.query.clustering.fields if clustering?
+        end
+
         ##
         # Refreshes the job until the job is `DONE`.
         # The delay between refreshes will incrementally increase.
@@ -451,7 +557,10 @@ module Google
         #
         def data token: nil, max: nil, start: nil
           return nil unless done?
-
+          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 }
@@ -459,7 +568,7 @@ module Google
             destination_table_dataset_id,
             destination_table_table_id,
             options
-          Data.from_gapi_json data_hash, destination_table_gapi, service
+          Data.from_gapi_json data_hash, destination_table_gapi, @gapi, service
         end
         alias query_results data
 
@@ -800,9 +909,9 @@ module Google
           #
           #   key_name = "projects/a/locations/b/keyRings/c/cryptoKeys/d"
           #   encrypt_config = bigquery.encryption kms_key: key_name
-          #   job = bigquery.query_job "SELECT 1;" do |query|
-          #     query.table = dataset.table "my_table", skip_lookup: true
-          #     query.encryption = encrypt_config
+          #   job = bigquery.query_job "SELECT 1;" do |job|
+          #     job.table = dataset.table "my_table", skip_lookup: true
+          #     job.encryption = encrypt_config
           #   end
           #
           # @!group Attributes
@@ -828,12 +937,15 @@ module Google
           #
           #   bigquery = Google::Cloud::Bigquery.new
           #   dataset = bigquery.dataset "my_dataset"
+          #   destination_table = dataset.table "my_destination_table",
+          #                                     skip_lookup: true
           #
           #   job = dataset.query_job "SELECT * FROM UNNEST(" \
           #                           "GENERATE_TIMESTAMP_ARRAY(" \
           #                           "'2018-10-01 00:00:00', " \
           #                           "'2018-10-10 00:00:00', " \
           #                           "INTERVAL 1 DAY)) AS dob" do |job|
+          #     job.table = destination_table
           #     job.time_partitioning_type = "DAY"
           #   end
           #
@@ -871,12 +983,15 @@ module Google
           #
           #   bigquery = Google::Cloud::Bigquery.new
           #   dataset = bigquery.dataset "my_dataset"
+          #   destination_table = dataset.table "my_destination_table",
+          #                                     skip_lookup: true
           #
           #   job = dataset.query_job "SELECT * FROM UNNEST(" \
           #                           "GENERATE_TIMESTAMP_ARRAY(" \
           #                           "'2018-10-01 00:00:00', " \
           #                           "'2018-10-10 00:00:00', " \
           #                           "INTERVAL 1 DAY)) AS dob" do |job|
+          #     job.table = destination_table
           #     job.time_partitioning_type  = "DAY"
           #     job.time_partitioning_field = "dob"
           #   end
@@ -908,12 +1023,15 @@ module Google
           #
           #   bigquery = Google::Cloud::Bigquery.new
           #   dataset = bigquery.dataset "my_dataset"
+          #   destination_table = dataset.table "my_destination_table",
+          #                                     skip_lookup: true
           #
           #   job = dataset.query_job "SELECT * FROM UNNEST(" \
           #                           "GENERATE_TIMESTAMP_ARRAY(" \
           #                           "'2018-10-01 00:00:00', " \
           #                           "'2018-10-10 00:00:00', " \
           #                           "INTERVAL 1 DAY)) AS dob" do |job|
+          #     job.table = destination_table
           #     job.time_partitioning_type = "DAY"
           #     job.time_partitioning_expiration = 86_400
           #   end
@@ -948,6 +1066,54 @@ module Google
               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.
+          #
+          # 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}.
+          #
+          # @see https://cloud.google.com/bigquery/docs/partitioned-tables
+          #   Partitioned Tables
+          # @see https://cloud.google.com/bigquery/docs/clustered-tables
+          #   Introduction to Clustered Tables
+          # @see https://cloud.google.com/bigquery/docs/creating-clustered-tables
+          #   Creating and Using Clustered Tables
+          #
+          # @param [Array<String>] fields The clustering fields. Only top-level,
+          #   non-repeated, simple-type fields are supported.
+          #
+          # @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 = dataset.query_job "SELECT * FROM my_table" do |job|
+          #     job.table = destination_table
+          #     job.time_partitioning_type = "DAY"
+          #     job.time_partitioning_field = "dob"
+          #     job.clustering_fields = ["last_name", "first_name"]
+          #   end
+          #
+          #   job.wait_until_done!
+          #   job.done? #=> true
+          #
+          # @!group Attributes
+          #
+          def clustering_fields= fields
+            @gapi.configuration.query.clustering ||= \
+              Google::Apis::BigqueryV2::Clustering.new
+            @gapi.configuration.query.clustering.fields = fields
+          end
+
           ##
           # @private Returns the Google API client library version of this job.
           #

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

@@ -192,10 +192,6 @@ module Google
         # the example below. BigQuery does not allow you to change partitioning
         # on an existing table.
         #
-        # If the table is not a full resource representation (see
-        # {#resource_full?}), the full representation will be retrieved before
-        # the update to comply with ETag-based optimistic concurrency control.
-        #
         # @param [String] type The partition type. Currently the only
         #   supported value is "DAY".
         #
@@ -249,10 +245,6 @@ module Google
         # the example below. BigQuery does not allow you to change partitioning
         # on an existing table.
         #
-        # If the table is not a full resource representation (see
-        # {#resource_full?}), the full representation will be retrieved before
-        # the update to comply with ETag-based optimistic concurrency control.
-        #
         # @param [String] field The partition field. The field must be a
         #   top-level TIMESTAMP or DATE field. Its mode must be NULLABLE or
         #   REQUIRED.
@@ -332,6 +324,50 @@ module Google
           patch_gapi! :time_partitioning
         end
 
+        ###
+        # Checks if the table is clustered.
+        #
+        # @see https://cloud.google.com/bigquery/docs/clustered-tables
+        #   Introduction to Clustered Tables
+        #
+        # @return [Boolean, nil] `true` when the table is clustered, or
+        #   `false` otherwise, if the object is a resource (see {#resource?});
+        #   `nil` if the object is a reference (see {#reference?}).
+        #
+        # @!group Attributes
+        #
+        def clustering?
+          return nil if reference?
+          !@gapi.clustering.nil?
+        end
+
+        ###
+        # One or more fields on which data should be clustered. Must be
+        # specified with time-based partitioning, data in the table will be
+        # first partitioned and subsequently clustered. The order of the
+        # returned fields determines the sort order of the data.
+        #
+        # See {Table::Updater#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
+        # @see https://cloud.google.com/bigquery/docs/creating-clustered-tables
+        #   Creating and Using Clustered Tables
+        #
+        # @return [Array<String>, nil] The clustering fields, or `nil` if the
+        #   table is not clustered or if the table is a reference (see
+        #   {#reference?}).
+        #
+        # @!group Attributes
+        #
+        def clustering_fields
+          return nil if reference?
+          ensure_full_data!
+          @gapi.clustering.fields if clustering?
+        end
+
         ##
         # The combined Project ID, Dataset ID, and Table ID for this table, in
         # the format specified by the [Legacy SQL Query
@@ -1137,7 +1173,7 @@ module Google
           options = { token: token, max: max, start: start }
           data_json = service.list_tabledata \
             dataset_id, table_id, options
-          Data.from_gapi_json data_json, gapi, service
+          Data.from_gapi_json data_json, gapi, nil, service
         end
 
         ##
@@ -2184,7 +2220,8 @@ module Google
         ##
         # @private New lazy Table object without making an HTTP request.
         def self.new_reference project_id, dataset_id, table_id, service
-          # TODO: raise if dataset_id or table_id is nil?
+          raise ArgumentError, "dataset_id is required" unless dataset_id
+          raise ArgumentError, "table_id is required" unless table_id
           new.tap do |b|
             reference_gapi = Google::Apis::BigqueryV2::TableReference.new(
               project_id: project_id,
@@ -2447,6 +2484,56 @@ module Google
             @schema = nil
           end
 
+          ##
+          # Sets one or more fields on which data should be clustered. Must be
+          # specified with time-based partitioning, data in the table will be
+          # first partitioned and subsequently 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.
+          #
+          # You can only set the clustering fields while creating a table as in
+          # the example below. BigQuery does not allow you to change clustering
+          # on an existing table.
+          #
+          # See {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
+          # @see https://cloud.google.com/bigquery/docs/creating-clustered-tables
+          #   Creating and Using Clustered Tables
+          #
+          # @param [Array<String>] fields The clustering fields. Only top-level,
+          #   non-repeated, simple-type fields are supported.
+          #
+          # @example
+          #   require "google/cloud/bigquery"
+          #
+          #   bigquery = Google::Cloud::Bigquery.new
+          #   dataset = bigquery.dataset "my_dataset"
+          #   table = dataset.create_table "my_table" do |table|
+          #     table.time_partitioning_type  = "DAY"
+          #     table.time_partitioning_field = "dob"
+          #     table.schema do |schema|
+          #       schema.timestamp "dob", mode: :required
+          #       schema.string "first_name", mode: :required
+          #       schema.string "last_name", mode: :required
+          #     end
+          #     table.clustering_fields = ["last_name", "first_name"]
+          #   end
+          #
+          # @!group Attributes
+          #
+          def clustering_fields= fields
+            @gapi.clustering ||= Google::Apis::BigqueryV2::Clustering.new
+            @gapi.clustering.fields = fields
+            patch_gapi! :clustering
+          end
+
           ##
           # Returns the table's schema. This method can also be used to set,
           # replace, or add to the schema by passing a block. See {Schema} for
@@ -2596,6 +2683,36 @@ module Google
             schema.float name, description: description, mode: mode
           end
 
+          ##
+          # Adds a numeric number field to the schema. Numeric is a
+          # fixed-precision numeric type with 38 decimal digits, 9 that follow
+          # the decimal point.
+          #
+          # See {Schema#numeric}
+          #
+          # @param [String] name The field name. The name must contain only
+          #   letters (a-z, A-Z), numbers (0-9), or underscores (_), and must
+          #   start with a letter or underscore. The maximum length is 128
+          #   characters.
+          # @param [String] description A description of the field.
+          # @param [Symbol] mode The field's mode. The possible values are
+          #   `:nullable`, `:required`, and `:repeated`. The default value is
+          #   `:nullable`.
+          #
+          # @example
+          #   require "google/cloud/bigquery"
+          #
+          #   bigquery = Google::Cloud::Bigquery.new
+          #   dataset = bigquery.dataset "my_dataset"
+          #   table = dataset.create_table "my_table" do |schema|
+          #     schema.numeric "total_cost", mode: :required
+          #   end
+          #
+          # @!group Schema
+          def numeric name, description: nil, mode: :nullable
+            schema.numeric name, description: description, mode: mode
+          end
+
           ##
           # Adds a boolean field to the schema.
           #

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

@@ -16,7 +16,7 @@
 module Google
   module Cloud
     module Bigquery
-      VERSION = "1.8.2".freeze
+      VERSION = "1.9.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.8.2
+  version: 1.9.0
 platform: ruby
 authors:
 - Mike Moore
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-09-20 00:00:00.000000000 Z
+date: 2018-10-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: google-cloud-core
@@ -157,14 +157,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.50.0
+        version: 0.59.2
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.50.0
+        version: 0.59.2
 - !ruby/object:Gem::Dependency
   name: simplecov
   requirement: !ruby/object:Gem::Requirement