google-cloud-bigquery 0.29.0 → 0.30.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 58e73b43f4053457d2df061703e3314483552dbb
-  data.tar.gz: 927a49cb45ff1a1c2aac5fa319e19dc0b422af23
+SHA256:
+  metadata.gz: 8c5eccec9f2f10fd5b5637a91516d68bee4f8b7f2e7e8e58a6b213afe89e56fe
+  data.tar.gz: 55d8b9b98cd3e52bb7c6111feaa9811487c61a4b2868126c54af7f9dec5fde1b
 SHA512:
-  metadata.gz: 8d86f37859a1a6cf2b682afd8b4e3f77b178fb8333e47606673e02e0a5e6ba76e61c6ee3c9bfbd5bd8d4763eff03f9c54bc067c10f39883772a6c730c0d8b443
-  data.tar.gz: d9d5afd3aac9c23e523909d78b7ae5fc886ce783e5b3cad0068aff21a815841a564e9baf6f35b2235adf0ed743df55d41c33b570f9b99a5d5a96ea50768882d0
+  metadata.gz: 6377e7a4cef9081723669ae08913786a1cdb37d65b0ae922dfc0a930e664eec451f95802e3f95f96eefcf24a5bf2eff23b00102bdd1f449a076018b7fc4d61cc
+  data.tar.gz: 9a4e917438c795ba7baa5692c5c6b70de0593b047e575f6113f112221d5c9925348e17ed6564d9361a872d6ca9918ac12df421a217e1d6e1096e98649829e447

data/README.md

@@ -24,8 +24,8 @@ Instructions and configuration options are covered in the [Authentication Guide]
 require "google/cloud/bigquery"
 
 bigquery = Google::Cloud::Bigquery.new(
-  project: "my-todo-project",
-  keyfile: "/path/to/keyfile.json"
+  project_id: "my-todo-project",
+  credentials: "/path/to/keyfile.json"
 )
 
 # Create a new table to archive todos

data/lib/google-cloud-bigquery.rb

@@ -13,9 +13,9 @@
 # limitations under the License.
 
 ##
-# This file is here to be autorequired by bundler, so that the .bigquery and
-# #bigquery methods can be available, but the library and all dependencies won't
-# be loaded until required and used.
+# This file is here to be autorequired by bundler, so that the
+# Google::Cloud.bigquery and Google::Cloud#bigquery methods can be available,
+# but the library and all dependencies won't be loaded until required and used.
 
 
 gem "google-cloud-core"
@@ -75,10 +75,11 @@ module Google
     # For more information on connecting to Google Cloud see the [Authentication
     # Guide](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/guides/authentication).
     #
-    # @param [String] project Identifier for a BigQuery project. If not present,
-    #   the default project for the credentials is used.
-    # @param [String, Hash] keyfile Keyfile downloaded from Google Cloud. If
-    #   file path the file must be readable.
+    # @param [String] project_id Identifier for a BigQuery project. If not
+    #   present, the default project for the credentials is used.
+    # @param [String, Hash, Google::Auth::Credentials] credentials The path to
+    #   the keyfile as a String, the contents of the keyfile as a Hash, or a
+    #   Google::Auth::Credentials object. (See {Bigquery::Credentials})
     # @param [String, Array<String>] scope The OAuth 2.0 scopes controlling the
     #   set of resources and operations that the connection can access. See
     #   [Using OAuth 2.0 to Access Google
@@ -100,10 +101,11 @@ module Google
     #   dataset = bigquery.dataset "my_dataset"
     #   table = dataset.table "my_table"
     #
-    def self.bigquery project = nil, keyfile = nil, scope: nil, retries: nil,
-                      timeout: nil
+    def self.bigquery project_id = nil, credentials = nil, scope: nil,
+                      retries: nil, timeout: nil
       require "google/cloud/bigquery"
-      Google::Cloud::Bigquery.new project: project, keyfile: keyfile,
+      Google::Cloud::Bigquery.new project_id: project_id,
+                                  credentials: credentials,
                                   scope: scope, retries: retries,
                                   timeout: timeout
     end

data/lib/google/cloud/bigquery.rb

@@ -347,6 +347,45 @@ module Google
     # table.insert rows
     # ```
     #
+    # To avoid making RPCs (network requests) to retrieve the dataset and table
+    # resources when streaming records, pass the `skip_lookup` option. This
+    # creates local objects without verifying that the resources exist on the
+    # BigQuery service.
+    #
+    # ```ruby
+    # require "google/cloud/bigquery"
+    #
+    # bigquery = Google::Cloud::Bigquery.new
+    # dataset = bigquery.dataset "my_dataset", skip_lookup: true
+    # table = dataset.table "people", skip_lookup: true
+    #
+    # rows = [
+    #     {
+    #         "first_name" => "Anna",
+    #         "cities_lived" => [
+    #             {
+    #                 "place" => "Stockholm",
+    #                 "number_of_years" => 2
+    #             }
+    #         ]
+    #     },
+    #     {
+    #         "first_name" => "Bob",
+    #         "cities_lived" => [
+    #             {
+    #                 "place" => "Seattle",
+    #                 "number_of_years" => 5
+    #             },
+    #             {
+    #                 "place" => "Austin",
+    #                 "number_of_years" => 6
+    #             }
+    #         ]
+    #     }
+    # ]
+    # table.insert rows
+    # ```
+    #
     # There are some trade-offs involved with streaming, so be sure to read the
     # discussion of data consistency in [Streaming Data Into
     # BigQuery](https://cloud.google.com/bigquery/streaming-data-into-bigquery).
@@ -455,10 +494,11 @@ module Google
       # [Authentication
       # Guide](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/guides/authentication).
       #
-      # @param [String] project Identifier for a BigQuery project. If not
+      # @param [String] project_id Identifier for a BigQuery project. If not
       #   present, the default project for the credentials is used.
-      # @param [String, Hash] keyfile Keyfile downloaded from Google Cloud. If
-      #   file path the file must be readable.
+      # @param [String, Hash, Google::Auth::Credentials] credentials The path to
+      #   the keyfile as a String, the contents of the keyfile as a Hash, or a
+      #   Google::Auth::Credentials object. (See {Bigquery::Credentials})
       # @param [String, Array<String>] scope The OAuth 2.0 scopes controlling
       #   the set of resources and operations that the connection can access.
       #   See # [Using OAuth 2.0 to Access Google #
@@ -470,6 +510,9 @@ module Google
       # @param [Integer] retries Number of times to retry requests on server
       #   error. The default value is `5`. Optional.
       # @param [Integer] timeout Default timeout to use in requests. Optional.
+      # @param [String] project Alias for the `project_id` argument. Deprecated.
+      # @param [String] keyfile Alias for the `credentials` argument.
+      #   Deprecated.
       #
       # @return [Google::Cloud::Bigquery::Project]
       #
@@ -480,23 +523,20 @@ module Google
       #   dataset = bigquery.dataset "my_dataset"
       #   table = dataset.table "my_table"
       #
-      def self.new project: nil, keyfile: nil, scope: nil, retries: nil,
-                   timeout: nil
-        project ||= Google::Cloud::Bigquery::Project.default_project
-        project = project.to_s # Always cast to a string
-        fail ArgumentError, "project is missing" if project.empty?
+      def self.new project_id: nil, credentials: nil, scope: nil, retries: nil,
+                   timeout: nil, project: nil, keyfile: nil
+        project_id ||= (project || Bigquery::Project.default_project_id)
+        project_id = project_id.to_s # Always cast to a string
+        fail ArgumentError, "project_id is missing" if project_id.empty?
 
-        if keyfile.nil?
-          credentials = Google::Cloud::Bigquery::Credentials.default(
-            scope: scope)
-        else
-          credentials = Google::Cloud::Bigquery::Credentials.new(
-            keyfile, scope: scope)
+        credentials ||= (keyfile || Bigquery::Credentials.default(scope: scope))
+        unless credentials.is_a? Google::Auth::Credentials
+          credentials = Bigquery::Credentials.new credentials, scope: scope
         end
 
-        Google::Cloud::Bigquery::Project.new(
-          Google::Cloud::Bigquery::Service.new(
-            project, credentials, retries: retries, timeout: timeout))
+        Bigquery::Project.new(
+          Bigquery::Service.new(
+            project_id, credentials, retries: retries, timeout: timeout))
       end
     end
   end

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

@@ -13,18 +13,44 @@
 # limitations under the License.
 
 
-require "google/cloud/credentials"
+require "googleauth"
 
 module Google
   module Cloud
     module Bigquery
       ##
-      # @private Represents the Oauth2 signing logic for Bigquery.
-      class Credentials < Google::Cloud::Credentials
+      # # Credentials
+      #
+      # Represents the authentication and authorization used to connect to the
+      # BigQuery API.
+      #
+      # @example
+      #   require "google/cloud/bigquery"
+      #
+      #   keyfile = "/path/to/keyfile.json"
+      #   creds = Google::Cloud::Bigquery::Credentials.new keyfile
+      #
+      #   bigquery = Google::Cloud::Bigquery.new(
+      #     project_id: "my-project",
+      #     credentials: creds
+      #   )
+      #
+      #   bigquery.project_id #=> "my-project"
+      #
+      class Credentials < Google::Auth::Credentials
         SCOPE = ["https://www.googleapis.com/auth/bigquery"]
-        PATH_ENV_VARS = %w(BIGQUERY_KEYFILE GOOGLE_CLOUD_KEYFILE GCLOUD_KEYFILE)
-        JSON_ENV_VARS = %w(BIGQUERY_KEYFILE_JSON GOOGLE_CLOUD_KEYFILE_JSON
+        PATH_ENV_VARS = %w(BIGQUERY_CREDENTIALS
+                           GOOGLE_CLOUD_CREDENTIALS
+                           BIGQUERY_KEYFILE
+                           GOOGLE_CLOUD_KEYFILE
+                           GCLOUD_KEYFILE)
+        JSON_ENV_VARS = %w(BIGQUERY_CREDENTIALS_JSON
+                           GOOGLE_CLOUD_CREDENTIALS_JSON
+                           BIGQUERY_KEYFILE_JSON
+                           GOOGLE_CLOUD_KEYFILE_JSON
                            GCLOUD_KEYFILE_JSON)
+        DEFAULT_PATHS = \
+          ["~/.config/gcloud/application_default_credentials.json"]
       end
     end
   end

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

@@ -49,14 +49,14 @@ module Google
         attr_accessor :table_gapi
 
         ##
-        # @private The Google API Client object.
-        attr_accessor :gapi
+        # @private The Google API Client object in JSON Hash.
+        attr_accessor :gapi_json
 
         # @private
         def initialize arr = []
           @service = nil
           @table_gapi = nil
-          @gapi = nil
+          @gapi_json = nil
           super arr
         end
 
@@ -66,7 +66,7 @@ module Google
         # @return [String] The resource type.
         #
         def kind
-          @gapi.kind
+          @gapi_json[:kind]
         end
 
         ##
@@ -75,7 +75,7 @@ module Google
         # @return [String] The ETag hash.
         #
         def etag
-          @gapi.etag
+          @gapi_json[:etag]
         end
 
         ##
@@ -85,7 +85,7 @@ module Google
         # @return [String] The pagination token.
         #
         def token
-          @gapi.page_token
+          @gapi_json[:pageToken]
         end
 
         ##
@@ -107,7 +107,7 @@ module Google
         #   end
         #
         def total
-          Integer @gapi.total_rows
+          Integer @gapi_json[:totalRows]
         rescue
           nil
         end
@@ -224,11 +224,11 @@ module Google
         def next
           return nil unless next?
           ensure_service!
-          data_gapi = service.list_tabledata \
+          data_json = service.list_tabledata \
             @table_gapi.table_reference.dataset_id,
             @table_gapi.table_reference.table_id,
             token: token
-          self.class.from_gapi data_gapi, @table_gapi, @service
+          self.class.from_gapi_json data_json, @table_gapi, @service
         end
 
         ##
@@ -302,13 +302,13 @@ module Google
 
         ##
         # @private New Data from a response object.
-        def self.from_gapi gapi, table_gapi, service
-          formatted_rows = Convert.format_rows(gapi.rows,
+        def self.from_gapi_json gapi_json, table_gapi, service
+          formatted_rows = Convert.format_rows(gapi_json[:rows],
                                                table_gapi.schema.fields)
 
           data = new formatted_rows
           data.table_gapi = table_gapi
-          data.gapi = gapi
+          data.gapi_json = gapi_json
           data.service = service
           data
         end

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

@@ -51,11 +51,16 @@ module Google
         # @private The Google API Client object.
         attr_accessor :gapi
 
+        ##
+        # @private A Google API Client Dataset Reference object.
+        attr_reader :reference
+
         ##
         # @private Create an empty Dataset object.
         def initialize
           @service = nil
-          @gapi = {}
+          @gapi = nil
+          @reference = nil
         end
 
         ##
@@ -67,6 +72,7 @@ module Google
         # @!group Attributes
         #
         def dataset_id
+          return reference.dataset_id if reference?
           @gapi.dataset_reference.dataset_id
         end
 
@@ -78,6 +84,7 @@ module Google
         # @!group Attributes
         #
         def project_id
+          return reference.project_id if reference?
           @gapi.dataset_reference.project_id
         end
 
@@ -86,7 +93,7 @@ module Google
         # The gapi fragment containing the Project ID and Dataset ID as a
         # camel-cased hash.
         def dataset_ref
-          dataset_ref = @gapi.dataset_reference
+          dataset_ref = reference? ? reference : @gapi.dataset_reference
           dataset_ref = dataset_ref.to_h if dataset_ref.respond_to? :to_h
           dataset_ref
         end
@@ -94,22 +101,30 @@ module Google
         ##
         # A descriptive name for the dataset.
         #
-        # @return [String] The friendly name.
+        # @return [String, nil] The friendly name, or `nil` if the object is
+        #   a reference (see {#reference?}).
         #
         # @!group Attributes
         #
         def name
+          return nil if reference?
           @gapi.friendly_name
         end
 
         ##
         # Updates the descriptive name for the dataset.
         #
-        # @param [String] new_name The new friendly name.
+        # If the dataset 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, or `nil` if the object
+        #   is a reference (see {#reference?}).
         #
         # @!group Attributes
         #
         def name= new_name
+          reload! unless resource_full?
           @gapi.update! friendly_name: new_name
           patch_gapi! :friendly_name
         end
@@ -117,11 +132,13 @@ module Google
         ##
         # The ETag hash of the dataset.
         #
-        # @return [String] The ETag hash.
+        # @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.etag
         end
@@ -129,11 +146,13 @@ module Google
         ##
         # A URL that can be used to access the dataset using the REST API.
         #
-        # @return [String] A REST URL for the resource.
+        # @return [String, nil] A REST URL for the resource, or `nil` if the
+        #   object is a reference (see {#reference?}).
         #
         # @!group Attributes
         #
         def api_url
+          return nil if reference?
           ensure_full_data!
           @gapi.self_link
         end
@@ -141,11 +160,13 @@ module Google
         ##
         # A user-friendly description of the dataset.
         #
-        # @return [String] The description.
+        # @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.description
         end
@@ -153,11 +174,16 @@ module Google
         ##
         # Updates the user-friendly description of the dataset.
         #
+        # If the dataset 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 description for the dataset.
         #
         # @!group Attributes
         #
         def description= new_description
+          reload! unless resource_full?
           @gapi.update! description: new_description
           patch_gapi! :description
         end
@@ -165,11 +191,14 @@ module Google
         ##
         # The default lifetime of all tables in the dataset, in milliseconds.
         #
-        # @return [Integer] The default table expiration in milliseconds.
+        # @return [Integer, nil] The default table expiration in milliseconds,
+        #   or `nil` if not present or the object is a reference (see
+        #   {#reference?}).
         #
         # @!group Attributes
         #
         def default_expiration
+          return nil if reference?
           ensure_full_data!
           begin
             Integer @gapi.default_table_expiration_ms
@@ -182,12 +211,17 @@ module Google
         # Updates the default lifetime of all tables in the dataset, in
         # milliseconds.
         #
+        # If the dataset 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_default_expiration The new default table
         #   expiration in milliseconds.
         #
         # @!group Attributes
         #
         def default_expiration= new_default_expiration
+          reload! unless resource_full?
           @gapi.update! default_table_expiration_ms: new_default_expiration
           patch_gapi! :default_table_expiration_ms
         end
@@ -195,11 +229,13 @@ module Google
         ##
         # The time when this dataset was created.
         #
-        # @return [Time, nil] The creation time.
+        # @return [Time, nil] The creation time, or `nil` if not present or the
+        #   object is a reference (see {#reference?}).
         #
         # @!group Attributes
         #
         def created_at
+          return nil if reference?
           ensure_full_data!
           begin
             ::Time.at(Integer(@gapi.creation_time) / 1000.0)
@@ -211,11 +247,13 @@ module Google
         ##
         # The date when this dataset or any of its tables was last modified.
         #
-        # @return [Time, nil] The last modified time.
+        # @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?
           ensure_full_data!
           begin
             ::Time.at(Integer(@gapi.last_modified_time) / 1000.0)
@@ -228,11 +266,13 @@ module Google
         # The geographic location where the dataset should reside. Possible
         # values include `EU` and `US`. The default value is `US`.
         #
-        # @return [String] The location code.
+        # @return [String, nil] The location code, or `nil` if the object is a
+        #   reference (see {#reference?}).
         #
         # @!group Attributes
         #
         def location
+          return nil if reference?
           ensure_full_data!
           @gapi.location
         end
@@ -245,7 +285,8 @@ module Google
         # The returned hash is frozen and changes are not allowed. Use
         # {#labels=} to replace the entire hash.
         #
-        # @return [Hash<String, String>] A hash containing key/value pairs.
+        # @return [Hash<String, String>, nil] A hash containing key/value pairs,
+        #   or `nil` if the object is a reference (see {#reference?}).
         #
         # @example
         #   require "google/cloud/bigquery"
@@ -259,6 +300,7 @@ module Google
         # @!group Attributes
         #
         def labels
+          return nil if reference?
           m = @gapi.labels
           m = m.to_h if m.respond_to? :to_h
           m.dup.freeze
@@ -269,6 +311,10 @@ module Google
         # Labels are used to organize and group datasets. See [Using
         # Labels](https://cloud.google.com/bigquery/docs/labels).
         #
+        # If the dataset 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>] labels A hash containing key/value
         #   pairs.
         #
@@ -290,6 +336,7 @@ module Google
         # @!group Attributes
         #
         def labels= labels
+          reload! unless resource_full?
           @gapi.labels = labels
           patch_gapi! :labels
         end
@@ -299,6 +346,10 @@ module Google
         # when passing a block, see {Dataset::Access} for all the methods
         # available.
         #
+        # If the dataset 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.
+        #
         # @see https://cloud.google.com/bigquery/access-control BigQuery Access
         #   Control
         #
@@ -332,6 +383,7 @@ module Google
         #
         def access
           ensure_full_data!
+          reload! unless resource_full?
           access_builder = Access.from_gapi @gapi
           if block_given?
             yield access_builder
@@ -455,7 +507,14 @@ module Google
         end
 
         ##
-        # Creates a new view table from the given query.
+        # Creates a new [view](https://cloud.google.com/bigquery/docs/views)
+        # table, which is a virtual table defined by the given SQL query.
+        #
+        # BigQuery's views are logical views, not materialized views, which
+        # means that the query that defines the view is re-executed every time
+        # the view is queried. Queries are billed according to the total amount
+        # of data in all table fields referenced directly or indirectly by the
+        # top-level query. (See {Table#view?} and {Table#query}.)
         #
         # @param [String] table_id The ID of the view table. The ID must contain
         #   only letters (a-z, A-Z), numbers (0-9), or underscores (_). The
@@ -480,7 +539,7 @@ module Google
         #   containing the same code. See [User-Defined
         #   Functions](https://cloud.google.com/bigquery/docs/reference/standard-sql/user-defined-functions).
         #
-        # @return [Google::Cloud::Bigquery::View] A new view object.
+        # @return [Google::Cloud::Bigquery::Table] A new table object.
         #
         # @example
         #   require "google/cloud/bigquery"
@@ -528,10 +587,13 @@ module Google
         # Retrieves an existing table by ID.
         #
         # @param [String] table_id The ID of a table.
+        # @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::Table,
-        #   Google::Cloud::Bigquery::View, nil] Returns `nil` if the table does
-        #   not exist
+        # @return [Google::Cloud::Bigquery::Table, nil] Returns `nil` if the
+        #   table does not exist.
         #
         # @example
         #   require "google/cloud/bigquery"
@@ -542,10 +604,22 @@ module Google
         #   table = dataset.table "my_table"
         #   puts table.name
         #
+        # @example Avoid retrieving the table resource with `skip_lookup`:
+        #   require "google/cloud/bigquery"
+        #
+        #   bigquery = Google::Cloud::Bigquery.new
+        #
+        #   dataset = bigquery.dataset "my_dataset"
+        #
+        #   table = dataset.table "my_table", skip_lookup: true
+        #
         # @!group Table
         #
-        def table table_id
+        def table table_id, skip_lookup: nil
           ensure_service!
+          if skip_lookup
+            return Table.new_reference project_id, dataset_id, table_id, service
+          end
           gapi = service.get_table dataset_id, table_id
           Table.from_gapi gapi, service
         rescue Google::Cloud::NotFoundError
@@ -559,9 +633,8 @@ module Google
         #   part of the larger set of results to view.
         # @param [Integer] max Maximum number of tables to return.
         #
-        # @return [Array<Google::Cloud::Bigquery::Table>,
-        #   Array<Google::Cloud::Bigquery::View>] An array of tables and/or
-        #   views(See {Google::Cloud::Bigquery::Table::List})
+        # @return [Array<Google::Cloud::Bigquery::Table>] An array of tables
+        #   (See {Google::Cloud::Bigquery::Table::List})
         #
         # @example
         #   require "google/cloud/bigquery"
@@ -1507,6 +1580,146 @@ module Google
           true
         end
 
+        ##
+        # Reloads the dataset with current data from the BigQuery service.
+        #
+        # @return [Google::Cloud::Bigquery::Dataset] Returns the reloaded
+        #   dataset.
+        #
+        # @example Skip retrieving the dataset from the service, then load it:
+        #   require "google/cloud/bigquery"
+        #
+        #   bigquery = Google::Cloud::Bigquery.new
+        #
+        #   dataset = bigquery.dataset "my_dataset", skip_lookup: true
+        #   dataset.reload!
+        #
+        def reload!
+          ensure_service!
+          reloaded_gapi = service.get_dataset dataset_id
+          @reference = nil
+          @gapi = reloaded_gapi
+          self
+        end
+        alias_method :refresh!, :reload!
+
+        ##
+        # Determines whether the dataset exists in the BigQuery service. The
+        # result is cached locally.
+        #
+        # @return [Boolean] `true` when the dataset exists in the BigQuery
+        #   service, `false` otherwise.
+        #
+        # @example
+        #   require "google/cloud/bigquery"
+        #
+        #   bigquery = Google::Cloud::Bigquery.new
+        #
+        #   dataset = bigquery.dataset "my_dataset", skip_lookup: true
+        #   dataset.exists? # true
+        #
+        def exists?
+          # Always true if we have a gapi object
+          return true unless reference?
+          # If we have a value, return it
+          return @exists unless @exists.nil?
+          ensure_gapi!
+          @exists = true
+        rescue Google::Cloud::NotFoundError
+          @exists = false
+        end
+
+        ##
+        # Whether the dataset was created without retrieving the resource
+        # representation from the BigQuery service.
+        #
+        # @return [Boolean] `true` when the dataset is just a local reference
+        #   object, `false` otherwise.
+        #
+        # @example
+        #   require "google/cloud/bigquery"
+        #
+        #   bigquery = Google::Cloud::Bigquery.new
+        #
+        #   dataset = bigquery.dataset "my_dataset", skip_lookup: true
+        #
+        #   dataset.reference? # true
+        #   dataset.reload!
+        #   dataset.reference? # false
+        #
+        def reference?
+          @gapi.nil?
+        end
+
+        ##
+        # Whether the dataset was created with a resource representation from
+        # the BigQuery service.
+        #
+        # @return [Boolean] `true` when the dataset was created with a resource
+        #   representation, `false` otherwise.
+        #
+        # @example
+        #   require "google/cloud/bigquery"
+        #
+        #   bigquery = Google::Cloud::Bigquery.new
+        #
+        #   dataset = bigquery.dataset "my_dataset", skip_lookup: true
+        #
+        #   dataset.resource? # false
+        #   dataset.reload!
+        #   dataset.resource? # true
+        #
+        def resource?
+          !@gapi.nil?
+        end
+
+        ##
+        # Whether the dataset was created with a partial resource representation
+        # from the BigQuery service by retrieval through {Project#datasets}.
+        # See [Datasets: list
+        # response](https://cloud.google.com/bigquery/docs/reference/rest/v2/datasets/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 dataset was created with a partial
+        #   resource representation, `false` otherwise.
+        #
+        # @example
+        #   require "google/cloud/bigquery"
+        #
+        #   bigquery = Google::Cloud::Bigquery.new
+        #
+        #   dataset = bigquery.datasets.first
+        #
+        #   dataset.resource_partial? # true
+        #   dataset.description # Loads the full resource.
+        #   dataset.resource_partial? # false
+        #
+        def resource_partial?
+          @gapi.is_a? Google::Apis::BigqueryV2::DatasetList::Dataset
+        end
+
+        ##
+        # Whether the dataset was created with a full resource representation
+        # from the BigQuery service.
+        #
+        # @return [Boolean] `true` when the dataset was created with a full
+        #   resource representation, `false` otherwise.
+        #
+        # @example
+        #   require "google/cloud/bigquery"
+        #
+        #   bigquery = Google::Cloud::Bigquery.new
+        #
+        #   dataset = bigquery.dataset "my_dataset"
+        #
+        #   dataset.resource_full? # true
+        #
+        def resource_full?
+          @gapi.is_a? Google::Apis::BigqueryV2::Dataset
+        end
+
         ##
         # @private New Dataset from a Google API Client object.
         def self.from_gapi gapi, conn
@@ -1516,6 +1729,20 @@ module Google
           end
         end
 
+        ##
+        # @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?
+          new.tap do |b|
+            reference_gapi = Google::Apis::BigqueryV2::DatasetReference.new(
+              project_id: project_id,
+              dataset_id: dataset_id
+            )
+            b.service = service
+            b.instance_variable_set :@reference, reference_gapi
+          end
+        end
+
         ##
         # Inserts data into the given table for near-immediate querying, without
         # the need to complete a load operation before the data can appear in
@@ -1552,6 +1779,19 @@ module Google
         #   ]
         #   dataset.insert "my_table", rows
         #
+        # @example Avoid retrieving the dataset with `skip_lookup`:
+        #   require "google/cloud/bigquery"
+        #
+        #   bigquery = Google::Cloud::Bigquery.new
+        #
+        #   dataset = bigquery.dataset "my_dataset", skip_lookup: true
+        #
+        #   rows = [
+        #     { "first_name" => "Alice", "age" => 21 },
+        #     { "first_name" => "Bob", "age" => 22 }
+        #   ]
+        #   dataset.insert "my_table", rows
+        #
         # @example Using `autocreate` to create a new table if none exists.
         #   require "google/cloud/bigquery"
         #
@@ -1598,7 +1838,7 @@ module Google
         end
 
         ##
-        # Create an asynchonous inserter object used to insert rows in batches.
+        # Create an asynchronous inserter object used to insert rows in batches.
         #
         # @param [String] table_id The ID of the table to insert rows into.
         # @param [Boolean] skip_invalid Insert all valid rows of a request, even
@@ -1617,8 +1857,8 @@ module Google
         # @attr_reader [Numeric] threads The number of threads used to insert
         #   batches of rows. Default is 4.
         # @yield [response] the callback for when a batch of rows is inserted
-        # @yieldparam [InsertResponse] response the result of the asynchonous
-        #   insert
+        # @yieldparam [Table::AsyncInserter::Result] result the result of the
+        #   asynchronous insert
         #
         # @return [Table::AsyncInserter] Returns an inserter object.
         #
@@ -1628,9 +1868,13 @@ module Google
         #   bigquery = Google::Cloud::Bigquery.new
         #   dataset = bigquery.dataset "my_dataset"
         #   table = dataset.table "my_table"
-        #   inserter = table.insert_async do |response|
-        #     log_insert "inserted #{response.insert_count} rows " \
-        #       "with #{response.error_count} errors"
+        #   inserter = table.insert_async do |result|
+        #     if result.error?
+        #       log_error result.error
+        #     else
+        #       log_insert "inserted #{result.insert_count} rows " \
+        #         "with #{result.error_count} errors"
+        #     end
         #   end
         #
         #   rows = [
@@ -1674,6 +1918,15 @@ module Google
           fail "Must have active connection" unless service
         end
 
+        ##
+        # Ensures the Google::Apis::BigqueryV2::Dataset object has been loaded
+        # from the service.
+        def ensure_gapi!
+          ensure_service!
+          return unless reference?
+          reload!
+        end
+
         def patch_gapi! *attributes
           return if attributes.empty?
           ensure_service!
@@ -1689,17 +1942,7 @@ module Google
         # Load the complete representation of the dataset if it has been
         # only partially loaded by a request to the API list method.
         def ensure_full_data!
-          reload_gapi! unless data_complete?
-        end
-
-        def reload_gapi!
-          ensure_service!
-          gapi = service.get_dataset dataset_id
-          @gapi = gapi
-        end
-
-        def data_complete?
-          @gapi.is_a? Google::Apis::BigqueryV2::Dataset
+          reload! if resource_partial?
         end
 
         def load_storage table_id, url, options = {}