google-cloud-bigquery 1.11.2 → 1.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fda568083e129056b970a84c51457de70ee1074698efcfcb1c7d2b569e3a2f4e
-  data.tar.gz: 00f0df1a1c99a772dccea807556dfb58defce2fe585d11f88dcbd94fcc75007c
+  metadata.gz: 4fb1722765075dded454afdeea337efe2c088c118f6f966c55a84ff9bb065df1
+  data.tar.gz: 2884b2a12b6a5137234dd4a3fd1fc2420ed2c05eaae223ebeae285caa1ba44b8
 SHA512:
-  metadata.gz: a100f2ad6e60402e1b4fdfc93db21e0331a68eeaff458ed633515766630bc9a985ff0a1a6847b9004b252027ffe1e8018a1da6eef16c9b02a200c3d79bb9650c
-  data.tar.gz: 68e929461695fdf232ca89b8ed9af7e21647b0c6ea93c1552319b7f3e5cc9583ddf07466edcfe753764d0ed383100aa70da9fc16ff1ad45e8296753cb0bdebbc
+  metadata.gz: 851560e73e7e1f48b58e08f99ada6f2f822f33f9dfe246e19b6d3abec4b0bfb2ef4802f402e2951ca0e40cb966be2981930fb62608f81d5a57edfa6ae5626d1f
+  data.tar.gz: b1a0dc302400edfe2a499d0299cc913cf85e4f34e29b460b8f5b3564a33b0e9a13c99d37539cc65afee07b4cbcfd7103bb07b4898866ea68dcab2187105ead1a

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Release History
 
+### 1.12.0 / 2019-07-10
+
+* Add BigQuery Model API
+  * Add Model
+  * Add StandardSql Field, DataType, StructType
+  * Add Dataset#model and Dataset#models
+* Correct Float value conversion
+  * Ensure that NaN, Infinity, and -Infinity are converted correctly.
+
 ### 1.11.2 / 2019-06-11
 
 * Update "Loading data" link

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

@@ -85,7 +85,15 @@ module Google
           elsif field.type == "INTEGER"
             Integer value[:v]
           elsif field.type == "FLOAT"
-            Float value[:v]
+            if value[:v] == "Infinity"
+              Float::INFINITY
+            elsif value[:v] == "-Infinity"
+              -Float::INFINITY
+            elsif value[:v] == "NaN"
+              Float::NAN
+            else
+              Float value[:v]
+            end
           elsif field.type == "NUMERIC"
             BigDecimal value[:v]
           elsif field.type == "BOOLEAN"
@@ -370,9 +378,19 @@ module Google
         #   is nil.
         def self.millis_to_time time_millis
           return nil unless time_millis
-          time_millis = Integer time_millis
-          time_secs = time_millis / 1000.0
-          ::Time.at time_secs
+          ::Time.at Rational(time_millis, 1000)
+        end
+
+        ##
+        # @private
+        #
+        # Converts a Ruby Time object to a primitive time value in milliseconds.
+        #
+        # @return [Integer, nil] The primitive time value in milliseconds, or
+        #   nil if the given argument is nil.
+        def self.time_to_millis time_obj
+          return nil unless time_obj
+          (time_obj.to_i * 1000) + (time_obj.nsec / 1000000)
         end
       end
 

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

@@ -17,6 +17,7 @@ require "json"
 require "google/cloud/errors"
 require "google/cloud/bigquery/service"
 require "google/cloud/bigquery/table"
+require "google/cloud/bigquery/model"
 require "google/cloud/bigquery/external"
 require "google/cloud/bigquery/dataset/list"
 require "google/cloud/bigquery/dataset/access"
@@ -668,6 +669,89 @@ module Google
           Table::List.from_gapi gapi, service, dataset_id, max
         end
 
+        ##
+        # Retrieves an existing model by ID.
+        #
+        # @param [String] model_id The ID of a model.
+        # @param [Boolean] skip_lookup Optionally create just a local reference
+        #   object without verifying that the resource exists on the BigQuery
+        #   service. Calls made on this object will raise errors if the resource
+        #   does not exist. Default is `false`. Optional.
+        #
+        # @return [Google::Cloud::Bigquery::Model, nil] Returns `nil` if the
+        #   model does not exist.
+        #
+        # @example
+        #   require "google/cloud/bigquery"
+        #
+        #   bigquery = Google::Cloud::Bigquery.new
+        #   dataset = bigquery.dataset "my_dataset"
+        #
+        #   model = dataset.model "my_model"
+        #   puts model.model_id
+        #
+        # @example Avoid retrieving the model resource with `skip_lookup`:
+        #   require "google/cloud/bigquery"
+        #
+        #   bigquery = Google::Cloud::Bigquery.new
+        #
+        #   dataset = bigquery.dataset "my_dataset"
+        #
+        #   model = dataset.model "my_model", skip_lookup: true
+        #
+        # @!group Model
+        #
+        def model model_id, skip_lookup: nil
+          ensure_service!
+          if skip_lookup
+            return Model.new_reference project_id, dataset_id, model_id, service
+          end
+          gapi = service.get_model dataset_id, model_id
+          Model.from_gapi_json gapi, service
+        rescue Google::Cloud::NotFoundError
+          nil
+        end
+
+        ##
+        # Retrieves the list of models belonging to the dataset.
+        #
+        # @param [String] token A previously-returned page token representing
+        #   part of the larger set of results to view.
+        # @param [Integer] max Maximum number of models to return.
+        #
+        # @return [Array<Google::Cloud::Bigquery::Model>] An array of models
+        #   (See {Google::Cloud::Bigquery::Model::List})
+        #
+        # @example
+        #   require "google/cloud/bigquery"
+        #
+        #   bigquery = Google::Cloud::Bigquery.new
+        #   dataset = bigquery.dataset "my_dataset"
+        #
+        #   models = dataset.models
+        #   models.each do |model|
+        #     puts model.model_id
+        #   end
+        #
+        # @example Retrieve all models: (See {Model::List#all})
+        #   require "google/cloud/bigquery"
+        #
+        #   bigquery = Google::Cloud::Bigquery.new
+        #   dataset = bigquery.dataset "my_dataset"
+        #
+        #   models = dataset.models
+        #   models.all do |model|
+        #     puts model.model_id
+        #   end
+        #
+        # @!group Model
+        #
+        def models token: nil, max: nil
+          ensure_service!
+          gapi = service.list_models dataset_id, token: token, max: max
+          Model::List.from_gapi gapi, service, dataset_id, max
+        end
+
         ##
         # Queries data by creating a [query
         # job](https://cloud.google.com/bigquery/docs/query-overview#query_jobs).

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

@@ -0,0 +1,665 @@
+# Copyright 2019 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+require "google/cloud/errors"
+require "google/cloud/bigquery/service"
+require "google/cloud/bigquery/model/list"
+require "google/cloud/bigquery/standard_sql"
+require "google/cloud/bigquery/convert"
+require "google/apis/bigquery_v2"
+
+module Google
+  module Cloud
+    module Bigquery
+      ##
+      # # Model
+      #
+      # A model in BigQuery ML represents what an ML system has learned from the
+      # training data.
+      #
+      # The following types of models are supported by BigQuery ML:
+      #
+      # * Linear regression for forecasting; for example, the sales of an item
+      #   on a given day. Labels are real-valued (they cannot be +/- infinity or
+      #   NaN).
+      # * Binary logistic regression for classification; for example,
+      #   determining whether a customer will make a purchase. Labels must only
+      #   have two possible values.
+      # * Multiclass logistic regression for classification. These models can be
+      #   used to predict multiple possible values such as whether an input is
+      #   "low-value," "medium-value," or "high-value." Labels can have up to 50
+      #   unique values. In BigQuery ML, multiclass logistic regression training
+      #   uses a multinomial classifier with a cross entropy loss function.
+      # * K-means clustering for data segmentation (beta); for example,
+      #   identifying customer segments. K-means is an unsupervised learning
+      #   technique, so model training does not require labels nor split data
+      #   for training or evaluation.
+      #
+      # In BigQuery ML, a model can be used with data from multiple BigQuery
+      # datasets for training and for prediction.
+      #
+      # @see https://cloud.google.com/bigquery-ml/docs/bigqueryml-intro
+      #   Introduction to BigQuery ML
+      # @see https://cloud.google.com/bigquery-ml/docs/getting-model-metadata
+      #   Getting model metadata
+      #
+      # @example
+      #   require "google/cloud/bigquery"
+      #
+      #   bigquery = Google::Cloud::Bigquery.new
+      #   dataset = bigquery.dataset "my_dataset"
+      #
+      #   model = dataset.model "my_model"
+      #
+      class Model
+        ##
+        # @private The Service object.
+        attr_accessor :service
+
+        ##
+        # @private The Google API Client JSON Hash.
+        attr_accessor :gapi_json
+
+        ##
+        # @private A Google API Client Model Reference object.
+        attr_reader :reference
+
+        ##
+        # @private Create an empty Model object.
+        def initialize
+          @service = nil
+          @gapi_json = nil
+          @reference = nil
+        end
+
+        ##
+        # A unique ID for this model.
+        #
+        # @return [String] The ID must contain only letters (a-z, A-Z), numbers
+        #   (0-9), or underscores (_). The maximum length is 1,024 characters.
+        #
+        # @!group Attributes
+        #
+        def model_id
+          return @reference.model_id if reference?
+          @gapi_json[:modelReference][:modelId]
+        end
+
+        ##
+        # The ID of the `Dataset` containing this model.
+        #
+        # @return [String] The ID must contain only letters (a-z, A-Z), numbers
+        #   (0-9), or underscores (_). The maximum length is 1,024 characters.
+        #
+        # @!group Attributes
+        #
+        def dataset_id
+          return @reference.dataset_id if reference?
+          @gapi_json[:modelReference][:datasetId]
+        end
+
+        ##
+        # The ID of the `Project` containing this model.
+        #
+        # @return [String] The project ID.
+        #
+        # @!group Attributes
+        #
+        def project_id
+          return @reference.project_id if reference?
+          @gapi_json[:modelReference][:projectId]
+        end
+
+        ##
+        # @private The gapi_json fragment containing the Project ID, Dataset ID,
+        # and Model ID.
+        #
+        # @return [Google::Apis::BigqueryV2::ModelReference]
+        #
+        def model_ref
+          return @reference if reference?
+          Google::Apis::BigqueryV2::ModelReference.new(
+            project_id: project_id,
+            dataset_id: dataset_id,
+            model_id:   model_id
+          )
+        end
+
+        ##
+        # Type of the model resource. Expected to be one of the following:
+        #
+        # * LINEAR_REGRESSION - Linear regression model.
+        # * LOGISTIC_REGRESSION - Logistic regression based classification
+        #   model.
+        # * KMEANS - K-means clustering model (beta).
+        # * TENSORFLOW - An imported TensorFlow model (beta).
+        #
+        # @return [String, nil] The model type, or `nil` if the object is a
+        #   reference (see {#reference?}).
+        #
+        # @!group Attributes
+        #
+        def model_type
+          return nil if reference?
+          @gapi_json[:modelType]
+        end
+
+        ##
+        # The name of the model.
+        #
+        # @return [String, nil] The friendly name, or `nil` if the object is a
+        #   reference (see {#reference?}).
+        #
+        # @!group Attributes
+        #
+        def name
+          return nil if reference?
+          ensure_full_data!
+          @gapi_json[:friendlyName]
+        end
+
+        ##
+        # Updates the name of the model.
+        #
+        # If the model 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] new_name The new friendly name.
+        #
+        # @!group Attributes
+        #
+        def name= new_name
+          ensure_full_data!
+          patch_gapi! friendlyName: new_name
+        end
+
+        ##
+        # The ETag hash of the model.
+        #
+        # @return [String, nil] The ETag hash, or `nil` if the object is a
+        #   reference (see {#reference?}).
+        #
+        # @!group Attributes
+        #
+        def etag
+          return nil if reference?
+          ensure_full_data!
+          @gapi_json[:etag]
+        end
+
+        ##
+        # A user-friendly description of the model.
+        #
+        # @return [String, nil] The description, or `nil` if the object is a
+        #   reference (see {#reference?}).
+        #
+        # @!group Attributes
+        #
+        def description
+          return nil if reference?
+          ensure_full_data!
+          @gapi_json[:description]
+        end
+
+        ##
+        # Updates the user-friendly description of the model.
+        #
+        # If the model 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] new_description The new user-friendly description.
+        #
+        # @!group Attributes
+        #
+        def description= new_description
+          ensure_full_data!
+          patch_gapi! description: new_description
+        end
+
+        ##
+        # The time when this model was created.
+        #
+        # @return [Time, nil] The creation time, or `nil` if the object is a
+        #   reference (see {#reference?}).
+        #
+        # @!group Attributes
+        #
+        def created_at
+          return nil if reference?
+          Convert.millis_to_time @gapi_json[:creationTime]
+        end
+
+        ##
+        # The date when this model was last modified.
+        #
+        # @return [Time, nil] The last modified time, or `nil` if not present or
+        #   the object is a reference (see {#reference?}).
+        #
+        # @!group Attributes
+        #
+        def modified_at
+          return nil if reference?
+          Convert.millis_to_time @gapi_json[:lastModifiedTime]
+        end
+
+        ##
+        # The time when this model expires.
+        # If not present, the model will persist indefinitely.
+        # Expired models will be deleted and their storage reclaimed.
+        #
+        # @return [Time, nil] The expiration time, or `nil` if not present or
+        #   the object is a reference (see {#reference?}).
+        #
+        # @!group Attributes
+        #
+        def expires_at
+          return nil if reference?
+          ensure_full_data!
+          Convert.millis_to_time @gapi_json[:expirationTime]
+        end
+
+        ##
+        # Updates time when this model expires.
+        #
+        # If the model 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 [Integer] new_expires_at The new time when this model expires.
+        #
+        # @!group Attributes
+        #
+        def expires_at= new_expires_at
+          ensure_full_data!
+          new_expires_millis = Convert.time_to_millis new_expires_at
+          patch_gapi! expirationTime: new_expires_millis
+        end
+
+        ##
+        # The geographic location where the model should reside. Possible
+        # values include `EU` and `US`. The default value is `US`.
+        #
+        # @return [String, nil] The location code.
+        #
+        # @!group Attributes
+        #
+        def location
+          return nil if reference?
+          ensure_full_data!
+          @gapi_json[:location]
+        end
+
+        ##
+        # A hash of user-provided labels associated with this model. Labels
+        # are used to organize and group models. See [Using
+        # Labels](https://cloud.google.com/bigquery/docs/labels).
+        #
+        # The returned hash is frozen and changes are not allowed. Use
+        # {#labels=} to replace the entire hash.
+        #
+        # @return [Hash<String, String>, nil] A hash containing key/value pairs.
+        #
+        # @example
+        #   require "google/cloud/bigquery"
+        #
+        #   bigquery = Google::Cloud::Bigquery.new
+        #   dataset = bigquery.dataset "my_dataset"
+        #   model = dataset.model "my_model"
+        #
+        #   labels = model.labels
+        #
+        # @!group Attributes
+        #
+        def labels
+          return nil if reference?
+          m = @gapi_json[:labels]
+          m = m.to_h if m.respond_to? :to_h
+          m.dup.freeze
+        end
+
+        ##
+        # Updates the hash of user-provided labels associated with this model.
+        # Labels are used to organize and group models. See [Using
+        # Labels](https://cloud.google.com/bigquery/docs/labels).
+        #
+        # If the model 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 [Hash<String, String>] new_labels A hash containing key/value
+        #   pairs.
+        #
+        #   * Label keys and values can be no longer than 63 characters.
+        #   * Label keys and values can contain only lowercase letters, numbers,
+        #     underscores, hyphens, and international characters.
+        #   * Label keys and values cannot exceed 128 bytes in size.
+        #   * Label keys must begin with a letter.
+        #   * Label keys must be unique within a model.
+        #
+        # @example
+        #   require "google/cloud/bigquery"
+        #
+        #   bigquery = Google::Cloud::Bigquery.new
+        #   dataset = bigquery.dataset "my_dataset"
+        #   model = dataset.model "my_model"
+        #
+        #   model.labels = { "env" => "production" }
+        #
+        # @!group Attributes
+        #
+        def labels= new_labels
+          ensure_full_data!
+          patch_gapi! labels: new_labels
+        end
+
+        ##
+        # The input feature columns that were used to train this model.
+        #
+        # @return [Array<StandardSql::Field>]
+        #
+        # @!group Attributes
+        #
+        def feature_columns
+          ensure_full_data!
+          Array(@gapi_json[:featureColumns]).map do |field_gapi_json|
+            StandardSql::Field.from_gapi_json field_gapi_json
+          end
+        end
+
+        ##
+        # The label columns that were used to train this model. The output of
+        # the model will have a "predicted_" prefix to these columns.
+        #
+        # @return [Array<StandardSql::Field>]
+        #
+        # @!group Attributes
+        #
+        def label_columns
+          ensure_full_data!
+          Array(@gapi_json[:labelColumns]).map do |field_gapi_json|
+            StandardSql::Field.from_gapi_json field_gapi_json
+          end
+        end
+
+        ##
+        # Information for all training runs in increasing order of startTime.
+        #
+        # @return [Array<Google::Cloud::Bigquery::Model::TrainingRun>]
+        #
+        # @!group Attributes
+        #
+        def training_runs
+          ensure_full_data!
+          Array @gapi_json[:trainingRuns]
+        end
+
+        ##
+        # Permanently deletes the model.
+        #
+        # @return [Boolean] Returns `true` if the model was deleted.
+        #
+        # @example
+        #   require "google/cloud/bigquery"
+        #
+        #   bigquery = Google::Cloud::Bigquery.new
+        #   dataset = bigquery.dataset "my_dataset"
+        #   model = dataset.model "my_model"
+        #
+        #   model.delete
+        #
+        # @!group Lifecycle
+        #
+        def delete
+          ensure_service!
+          service.delete_model dataset_id, model_id
+          # Set flag for #exists?
+          @exists = false
+          true
+        end
+
+        ##
+        # Reloads the model with current data from the BigQuery service.
+        #
+        # @return [Google::Cloud::Bigquery::Model] Returns the reloaded
+        #   model.
+        #
+        # @example Skip retrieving the model from the service, then load it:
+        #   require "google/cloud/bigquery"
+        #
+        #   bigquery = Google::Cloud::Bigquery.new
+        #
+        #   dataset = bigquery.dataset "my_dataset"
+        #   model = dataset.model "my_model", skip_lookup: true
+        #
+        #   model.reference? #=> true
+        #   model.reload!
+        #   model.resource? #=> true
+        #
+        # @!group Lifecycle
+        #
+        def reload!
+          ensure_service!
+          @gapi_json = service.get_model dataset_id, model_id
+          @reference = nil
+          @exists = nil
+          self
+        end
+        alias refresh! reload!
+
+        ##
+        # Determines whether the model exists in the BigQuery service. The
+        # result is cached locally. To refresh state, set `force` to `true`.
+        #
+        # @param [Boolean] force Force the latest resource representation to be
+        #   retrieved from the BigQuery service when `true`. Otherwise the
+        #   return value of this method will be memoized to reduce the number of
+        #   API calls made to the BigQuery service. The default is `false`.
+        #
+        # @return [Boolean] `true` when the model exists in the BigQuery
+        #   service, `false` otherwise.
+        #
+        # @example
+        #   require "google/cloud/bigquery"
+        #
+        #   bigquery = Google::Cloud::Bigquery.new
+        #
+        #   dataset = bigquery.dataset "my_dataset"
+        #   model = dataset.model "my_model", skip_lookup: true
+        #   model.exists? #=> true
+        #
+        def exists? force: nil
+          return resource_exists? if force
+          # If we have a value, return it
+          return @exists unless @exists.nil?
+          # Always true if we have a gapi_json object
+          return true if resource?
+          resource_exists?
+        end
+
+        ##
+        # Whether the model was created without retrieving the resource
+        # representation from the BigQuery service.
+        #
+        # @return [Boolean] `true` when the model is just a local reference
+        #   object, `false` otherwise.
+        #
+        # @example
+        #   require "google/cloud/bigquery"
+        #
+        #   bigquery = Google::Cloud::Bigquery.new
+        #
+        #   dataset = bigquery.dataset "my_dataset"
+        #   model = dataset.model "my_model", skip_lookup: true
+        #
+        #   model.reference? #=> true
+        #   model.reload!
+        #   model.reference? #=> false
+        #
+        def reference?
+          @gapi_json.nil?
+        end
+
+        ##
+        # Whether the model was created with a resource representation from
+        # the BigQuery service.
+        #
+        # @return [Boolean] `true` when the model was created with a resource
+        #   representation, `false` otherwise.
+        #
+        # @example
+        #   require "google/cloud/bigquery"
+        #
+        #   bigquery = Google::Cloud::Bigquery.new
+        #
+        #   dataset = bigquery.dataset "my_dataset"
+        #   model = dataset.model "my_model", skip_lookup: true
+        #
+        #   model.resource? #=> false
+        #   model.reload!
+        #   model.resource? #=> true
+        #
+        def resource?
+          !@gapi_json.nil?
+        end
+
+        ##
+        # Whether the model was created with a partial resource representation
+        # from the BigQuery service by retrieval through {Dataset#models}.
+        # See [Models: list
+        # response](https://cloud.google.com/bigquery/docs/reference/rest/v2/models/list#response)
+        # for the contents of the partial representation. Accessing any
+        # attribute outside of the partial representation will result in loading
+        # the full representation.
+        #
+        # @return [Boolean] `true` when the model was created with a partial
+        #   resource representation, `false` otherwise.
+        #
+        # @example
+        #   require "google/cloud/bigquery"
+        #
+        #   bigquery = Google::Cloud::Bigquery.new
+        #
+        #   dataset = bigquery.dataset "my_dataset"
+        #   model = dataset.models.first
+        #
+        #   model.resource_partial? #=> true
+        #   model.description # Loads the full resource.
+        #   model.resource_partial? #=> false
+        #
+        def resource_partial?
+          resource? && !resource_full?
+        end
+
+        ##
+        # Whether the model was created with a full resource representation
+        # from the BigQuery service.
+        #
+        # @return [Boolean] `true` when the model was created with a full
+        #   resource representation, `false` otherwise.
+        #
+        # @example
+        #   require "google/cloud/bigquery"
+        #
+        #   bigquery = Google::Cloud::Bigquery.new
+        #
+        #   dataset = bigquery.dataset "my_dataset"
+        #   model = dataset.model "my_model"
+        #
+        #   model.resource_full? #=> true
+        #
+        def resource_full?
+          resource? && @gapi_json.key?(:friendlyName)
+        end
+
+        ##
+        # @private New Model from a Google API Client object.
+        def self.from_gapi_json gapi_json, service
+          new.tap do |m|
+            m.instance_variable_set :@gapi_json, gapi_json
+            m.instance_variable_set :@service, service
+          end
+        end
+
+        ##
+        # @private New lazy Model object without making an HTTP request.
+        def self.new_reference project_id, dataset_id, model_id, service
+          raise ArgumentError, "project_id is required" unless project_id
+          raise ArgumentError, "dataset_id is required" unless dataset_id
+          raise ArgumentError, "model_id is required" unless model_id
+          raise ArgumentError, "service is required" unless service
+
+          new.tap do |m|
+            reference_gapi_json = Google::Apis::BigqueryV2::ModelReference.new(
+              project_id: project_id,
+              dataset_id: dataset_id,
+              model_id:   model_id
+            )
+            m.instance_variable_set :@reference, reference_gapi_json
+            m.instance_variable_set :@service, service
+          end
+        end
+
+        protected
+
+        ##
+        # Raise an error unless an active service is available.
+        def ensure_service!
+          raise "Must have active connection" unless service
+        end
+
+        ##
+        # Ensures the Google::Apis::BigqueryV2::Model object has been loaded
+        # from the service.
+        def ensure_gapi_json!
+          ensure_service!
+          return unless reference?
+          reload!
+        end
+
+        ##
+        # Fetch gapi_json and memoize whether resource exists.
+        def resource_exists?
+          reload!
+          @exists = true
+        rescue Google::Cloud::NotFoundError
+          @exists = false
+        end
+
+        def patch_gapi! **changes
+          return if changes.empty?
+          ensure_service!
+          patch_gapi = Google::Apis::BigqueryV2::Model.from_json changes.to_json
+          patch_gapi.model_reference = model_ref
+          @gapi_json = service.patch_model \
+            dataset_id, model_id, patch_gapi, etag
+          @reference = nil
+
+          # TODO: restore original impl after acceptance test indicates that
+          # service etag bug is fixed
+          reload!
+        end
+
+        ##
+        # Load the complete representation of the model if it has been
+        # only partially loaded by a request to the API list method.
+        def ensure_full_data!
+          reload! unless resource_full?
+        end
+      end
+    end
+  end
+end