google-cloud-bigquery 0.20.0

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

@@ -0,0 +1,174 @@
+# Copyright 2015 Google Inc. All rights reserved.
+#
+# 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
+#
+#     http://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 "delegate"
+
+module Google
+  module Cloud
+    module Bigquery
+      class Job
+        ##
+        # Job::List is a special case Array with additional values.
+        class List < DelegateClass(::Array)
+          ##
+          # If not empty, indicates that there are more records that match
+          # the request and this value should be passed to continue.
+          attr_accessor :token
+
+          # A hash of this page of results.
+          attr_accessor :etag
+
+          ##
+          # @private Create a new Job::List with an array of jobs.
+          def initialize arr = []
+            super arr
+          end
+
+          ##
+          # Whether there is a next page of jobs.
+          #
+          # @return [Boolean]
+          #
+          # @example
+          #   require "google/cloud"
+          #
+          #   gcloud = Google::Cloud.new
+          #   bigquery = gcloud.bigquery
+          #
+          #   jobs = bigquery.jobs
+          #   if jobs.next?
+          #     next_jobs = jobs.next
+          #   end
+          def next?
+            !token.nil?
+          end
+
+          ##
+          # Retrieve the next page of jobs.
+          #
+          # @return [Job::List]
+          #
+          # @example
+          #   require "google/cloud"
+          #
+          #   gcloud = Google::Cloud.new
+          #   bigquery = gcloud.bigquery
+          #
+          #   jobs = bigquery.jobs
+          #   if jobs.next?
+          #     next_jobs = jobs.next
+          #   end
+          def next
+            return nil unless next?
+            ensure_service!
+            options = { all: @hidden, token: token, max: @max, filter: @filter }
+            gapi = @service.list_jobs options
+            self.class.from_gapi gapi, @service, @hidden, @max, @filter
+          end
+
+          ##
+          # Retrieves all jobs by repeatedly loading {#next} until {#next?}
+          # returns `false`. Calls the given block once for each job, which is
+          # passed as the parameter.
+          #
+          # An Enumerator is returned if no block is given.
+          #
+          # This method may make several API calls until all jobs are retrieved.
+          # Be sure to use as narrow a search criteria as possible. Please use
+          # with caution.
+          #
+          # @param [Integer] request_limit The upper limit of API requests to
+          #   make to load all jobs. Default is no limit.
+          # @yield [job] The block for accessing each job.
+          # @yieldparam [Job] job The job object.
+          #
+          # @return [Enumerator]
+          #
+          # @example Iterating each job by passing a block:
+          #   require "google/cloud"
+          #
+          #   gcloud = Google::Cloud.new
+          #   bigquery = gcloud.bigquery
+          #
+          #   bigquery.jobs.all do |job|
+          #     puts job.state
+          #   end
+          #
+          # @example Using the enumerator by not passing a block:
+          #   require "google/cloud"
+          #
+          #   gcloud = Google::Cloud.new
+          #   bigquery = gcloud.bigquery
+          #
+          #   all_states = bigquery.jobs.all.map do |job|
+          #     job.state
+          #   end
+          #
+          # @example Limit the number of API calls made:
+          #   require "google/cloud"
+          #
+          #   gcloud = Google::Cloud.new
+          #   bigquery = gcloud.bigquery
+          #
+          #   bigquery.jobs.all(request_limit: 10) do |job|
+          #     puts job.state
+          #   end
+          #
+          def all request_limit: nil
+            request_limit = request_limit.to_i if request_limit
+            unless block_given?
+              return enum_for(:all, request_limit: request_limit)
+            end
+            results = self
+            loop do
+              results.each { |r| yield r }
+              if request_limit
+                request_limit -= 1
+                break if request_limit < 0
+              end
+              break unless results.next?
+              results = results.next
+            end
+          end
+
+          ##
+          # @private New Job::List from a Google API Client
+          # Google::Apis::BigqueryV2::JobList object.
+          def self.from_gapi gapi_list, service, hidden = nil, max = nil,
+                             filter = nil
+            jobs = List.new(Array(gapi_list.jobs).map do |gapi_object|
+              Job.from_gapi gapi_object, service
+            end)
+            jobs.instance_variable_set :@token,   gapi_list.next_page_token
+            jobs.instance_variable_set :@etag,    gapi_list.etag
+            jobs.instance_variable_set :@service, service
+            jobs.instance_variable_set :@hidden,  hidden
+            jobs.instance_variable_set :@max,     max
+            jobs.instance_variable_set :@filter,  filter
+            jobs
+          end
+
+          protected
+
+          ##
+          # Raise an error unless an active service is available.
+          def ensure_service!
+            fail "Must have active connection" unless @service
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,203 @@
+# Copyright 2015 Google Inc. All rights reserved.
+#
+# 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
+#
+#     http://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/bigquery/service"
+
+module Google
+  module Cloud
+    module Bigquery
+      ##
+      # # LoadJob
+      #
+      # A {Job} subclass representing a load operation that may be performed
+      # on a {Table}. A LoadJob instance is created when you call {Table#load}.
+      #
+      # @see https://cloud.google.com/bigquery/loading-data-into-bigquery
+      #   Loading Data Into BigQuery
+      # @see https://cloud.google.com/bigquery/docs/reference/v2/jobs Jobs API
+      #   reference
+      #
+      class LoadJob < Job
+        ##
+        # The URI or URIs representing the Google Cloud Storage files from which
+        # the operation loads data.
+        def sources
+          Array @gapi.configuration.load.source_uris
+        end
+
+        ##
+        # The table into which the operation loads data. This is the table on
+        # which {Table#load} was invoked. Returns a {Table} instance.
+        def destination
+          table = @gapi.configuration.load.destination_table
+          return nil unless table
+          retrieve_table table.project_id,
+                         table.dataset_id,
+                         table.table_id
+        end
+
+        ##
+        # The delimiter used between fields in the source data. The default is a
+        # comma (,).
+        def delimiter
+          @gapi.configuration.load.field_delimiter || ","
+        end
+
+        ##
+        # The number of header rows at the top of a CSV file to skip. The
+        # default value is `0`.
+        def skip_leading_rows
+          @gapi.configuration.load.skip_leading_rows || 0
+        end
+
+        ##
+        # Checks if the character encoding of the data is UTF-8. This is the
+        # default.
+        def utf8?
+          val = @gapi.configuration.load.encoding
+          return true if val.nil?
+          val == "UTF-8"
+        end
+
+        ##
+        # Checks if the character encoding of the data is ISO-8859-1.
+        def iso8859_1?
+          val = @gapi.configuration.load.encoding
+          val == "ISO-8859-1"
+        end
+
+        ##
+        # The value that is used to quote data sections in a CSV file. The
+        # default value is a double-quote (`"`). If your data does not contain
+        # quoted sections, the value should be an empty string. If your data
+        # contains quoted newline characters, {#quoted_newlines?} should return
+        # `true`.
+        def quote
+          val = @gapi.configuration.load.quote
+          val = "\"" if val.nil?
+          val
+        end
+
+        ##
+        # The maximum number of bad records that the load operation can ignore.
+        # If the number of bad records exceeds this value, an error is returned.
+        # The default value is `0`, which requires that all records be valid.
+        def max_bad_records
+          val = @gapi.configuration.load.max_bad_records
+          val = 0 if val.nil?
+          val
+        end
+
+        ##
+        # Checks if quoted data sections may contain newline characters in a CSV
+        # file. The default is `false`.
+        def quoted_newlines?
+          val = @gapi.configuration.load.allow_quoted_newlines
+          val = true if val.nil?
+          val
+        end
+
+        ##
+        # Checks if the format of the source data is [newline-delimited
+        # JSON](http://jsonlines.org/). The default is `false`.
+        def json?
+          val = @gapi.configuration.load.source_format
+          val == "NEWLINE_DELIMITED_JSON"
+        end
+
+        ##
+        # Checks if the format of the source data is CSV. The default is `true`.
+        def csv?
+          val = @gapi.configuration.load.source_format
+          return true if val.nil?
+          val == "CSV"
+        end
+
+        ##
+        # Checks if the source data is a Google Cloud Datastore backup.
+        def backup?
+          val = @gapi.configuration.load.source_format
+          val == "DATASTORE_BACKUP"
+        end
+
+        ##
+        # Checks if the load operation accepts rows that are missing trailing
+        # optional columns. The missing values are treated as nulls. If `false`,
+        # records with missing trailing columns are treated as bad records, and
+        # if there are too many bad records, an error is returned. The default
+        # value is `false`. Only applicable to CSV, ignored for other formats.
+        def allow_jagged_rows?
+          val = @gapi.configuration.load.allow_jagged_rows
+          val = false if val.nil?
+          val
+        end
+
+        ##
+        # Checks if the load operation allows extra values that are not
+        # represented in the table schema. If `true`, the extra values are
+        # ignored. If `false`, records with extra columns are treated as bad
+        # records, and if there are too many bad records, an invalid error is
+        # returned. The default is `false`.
+        def ignore_unknown_values?
+          val = @gapi.configuration.load.ignore_unknown_values
+          val = false if val.nil?
+          val
+        end
+
+        ##
+        # The schema for the data. Returns a hash. Can be empty if the table has
+        # already has the correct schema (see {Table#schema}), or if the schema
+        # can be inferred from the loaded data.
+        def schema
+          Schema.from_gapi(@gapi.configuration.load.schema).freeze
+        end
+
+        ##
+        # The number of source files.
+        def input_files
+          Integer @gapi.statistics.load.input_files
+        rescue
+          nil
+        end
+
+        ##
+        # The number of bytes of source data.
+        def input_file_bytes
+          Integer @gapi.statistics.load.input_file_bytes
+        rescue
+          nil
+        end
+
+        ##
+        # The number of rows that have been loaded into the table. While an
+        # import job is in the running state, this value may change.
+        def output_rows
+          Integer @gapi.statistics.load.output_rows
+        rescue
+          nil
+        end
+
+        ##
+        # The number of bytes that have been loaded into the table. While an
+        # import job is in the running state, this value may change.
+        def output_bytes
+          Integer @gapi.statistics.load.output_bytes
+        rescue
+          nil
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,481 @@
+# Copyright 2015 Google Inc. All rights reserved.
+#
+# 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
+#
+#     http://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/core/gce"
+require "google/cloud/errors"
+require "google/cloud/bigquery/service"
+require "google/cloud/bigquery/credentials"
+require "google/cloud/bigquery/dataset"
+require "google/cloud/bigquery/job"
+require "google/cloud/bigquery/query_data"
+
+module Google
+  module Cloud
+    module Bigquery
+      ##
+      # # Project
+      #
+      # Projects are top-level containers in Google Cloud Platform. They store
+      # information about billing and authorized users, and they contain
+      # BigQuery data. Each project has a friendly name and a unique ID.
+      #
+      # Google::Cloud::Bigquery::Project is the main object for interacting with
+      # Google BigQuery. {Google::Cloud::Bigquery::Dataset} objects are created,
+      # accessed, and deleted by Google::Cloud::Bigquery::Project.
+      #
+      # See {Google::Cloud#bigquery}
+      #
+      # @example
+      #   require "google/cloud"
+      #
+      #   gcloud = Google::Cloud.new
+      #   bigquery = gcloud.bigquery
+      #   dataset = bigquery.dataset "my_dataset"
+      #   table = dataset.table "my_table"
+      #
+      class Project
+        ##
+        # @private The Service object.
+        attr_accessor :service
+
+        ##
+        # Creates a new Service instance.
+        #
+        # See {Google::Cloud.bigquery}
+        def initialize service
+          @service = service
+        end
+
+        ##
+        # The BigQuery project connected to.
+        #
+        # @example
+        #   require "google/cloud"
+        #
+        #   gcloud = Google::Cloud.new "my-todo-project",
+        #                              "/path/to/keyfile.json"
+        #   bigquery = gcloud.bigquery
+        #
+        #   bigquery.project #=> "my-todo-project"
+        #
+        def project
+          service.project
+        end
+
+        ##
+        # @private Default project.
+        def self.default_project
+          ENV["BIGQUERY_PROJECT"] ||
+            ENV["GOOGLE_CLOUD_PROJECT"] ||
+            ENV["GCLOUD_PROJECT"] ||
+            Google::Cloud::Core::GCE.project_id
+        end
+
+        ##
+        # Queries data using the [asynchronous
+        # method](https://cloud.google.com/bigquery/querying-data).
+        #
+        # @param [String] query A query string, following the BigQuery [query
+        #   syntax](https://cloud.google.com/bigquery/query-reference), of the
+        #   query to execute. Example: "SELECT count(f1) FROM
+        #   [myProjectId:myDatasetId.myTableId]".
+        # @param [String] priority Specifies a priority for the query. Possible
+        #   values include `INTERACTIVE` and `BATCH`. The default value is
+        #   `INTERACTIVE`.
+        # @param [Boolean] cache Whether to look for the result in the query
+        #   cache. The query cache is a best-effort cache that will be flushed
+        #   whenever tables in the query are modified. The default value is
+        #   true. For more information, see [query
+        #   caching](https://developers.google.com/bigquery/querying-data).
+        # @param [Table] table The destination table where the query results
+        #   should be stored. If not present, a new table will be created to
+        #   store the results.
+        # @param [String] create Specifies whether the job is allowed to create
+        #   new tables.
+        #
+        #   The following values are supported:
+        #
+        #   * `needed` - Create the table if it does not exist.
+        #   * `never` - The table must already exist. A 'notFound' error is
+        #     raised if the table does not exist.
+        # @param [String] write Specifies the action that occurs if the
+        #   destination table already exists.
+        #
+        #   The following values are supported:
+        #
+        #   * `truncate` - BigQuery overwrites the table data.
+        #   * `append` - BigQuery appends the data to the table.
+        #   * `empty` - A 'duplicate' error is returned in the job result if the
+        #     table exists and contains data.
+        # @param [Boolean] large_results If `true`, allows the query to produce
+        #   arbitrarily large result tables at a slight cost in performance.
+        #   Requires `table` parameter to be set.
+        # @param [Boolean] flatten Flattens all nested and repeated fields in
+        #   the query results. The default value is `true`. `large_results`
+        #   parameter must be `true` if this is set to `false`.
+        # @param [Dataset, String] dataset Specifies the default dataset to use
+        #   for unqualified table names in the query.
+        #
+        # @return [Google::Cloud::Bigquery::QueryJob]
+        #
+        # @example
+        #   require "google/cloud"
+        #
+        #   gcloud = Google::Cloud.new
+        #   bigquery = gcloud.bigquery
+        #
+        #   job = bigquery.query_job "SELECT name FROM " \
+        #                            "[my_proj:my_data.my_table]"
+        #
+        #   job.wait_until_done!
+        #   if !job.failed?
+        #     job.query_results.each do |row|
+        #       puts row["name"]
+        #     end
+        #   end
+        #
+        def query_job query, priority: "INTERACTIVE", cache: true, table: nil,
+                      create: nil, write: nil, large_results: nil, flatten: nil,
+                      dataset: nil
+          ensure_service!
+          options = { priority: priority, cache: cache, table: table,
+                      create: create, write: write,
+                      large_results: large_results, flatten: flatten,
+                      dataset: dataset }
+          gapi = service.query_job query, options
+          Job.from_gapi gapi, service
+        end
+
+        ##
+        # Queries data using the [synchronous
+        # method](https://cloud.google.com/bigquery/querying-data).
+        #
+        # @param [String] query A query string, following the BigQuery [query
+        #   syntax](https://cloud.google.com/bigquery/query-reference), of the
+        #   query to execute. Example: "SELECT count(f1) FROM
+        #   [myProjectId:myDatasetId.myTableId]".
+        # @param [Integer] max The maximum number of rows of data to return per
+        #   page of results. Setting this flag to a small value such as 1000 and
+        #   then paging through results might improve reliability when the query
+        #   result set is large. In addition to this limit, responses are also
+        #   limited to 10 MB. By default, there is no maximum row count, and
+        #   only the byte limit applies.
+        # @param [Integer] timeout How long to wait for the query to complete,
+        #   in milliseconds, before the request times out and returns. Note that
+        #   this is only a timeout for the request, not the query. If the query
+        #   takes longer to run than the timeout value, the call returns without
+        #   any results and with QueryData#complete? set to false. The default
+        #   value is 10000 milliseconds (10 seconds).
+        # @param [Boolean] dryrun If set to `true`, BigQuery doesn't run the
+        #   job. Instead, if the query is valid, BigQuery returns statistics
+        #   about the job such as how many bytes would be processed. If the
+        #   query is invalid, an error returns. The default value is `false`.
+        # @param [Boolean] cache Whether to look for the result in the query
+        #   cache. The query cache is a best-effort cache that will be flushed
+        #   whenever tables in the query are modified. The default value is
+        #   true. For more information, see [query
+        #   caching](https://developers.google.com/bigquery/querying-data).
+        # @param [String] dataset Specifies the default datasetId and projectId
+        #   to assume for any unqualified table names in the query. If not set,
+        #   all table names in the query string must be qualified in the format
+        #   'datasetId.tableId'.
+        # @param [String] project Specifies the default projectId to assume for
+        #   any unqualified table names in the query. Only used if `dataset`
+        #   option is set.
+        #
+        # @return [Google::Cloud::Bigquery::QueryData]
+        #
+        # @example
+        #   require "google/cloud"
+        #
+        #   gcloud = Google::Cloud.new
+        #   bigquery = gcloud.bigquery
+        #
+        #   data = bigquery.query "SELECT name FROM [my_proj:my_data.my_table]"
+        #   data.each do |row|
+        #     puts row["name"]
+        #   end
+        #
+        # @example Retrieve all rows: (See {QueryData#all})
+        #   require "google/cloud"
+        #
+        #   gcloud = Google::Cloud.new
+        #   bigquery = gcloud.bigquery
+        #
+        #   data = bigquery.query "SELECT name FROM [my_proj:my_data.my_table]"
+        #   data.all do |row|
+        #     puts row["name"]
+        #   end
+        #
+        def query query, max: nil, timeout: 10000, dryrun: nil, cache: true,
+                  dataset: nil, project: nil
+          ensure_service!
+          options = { max: max, timeout: timeout, dryrun: dryrun, cache: cache,
+                      dataset: dataset, project: project }
+          gapi = service.query query, options
+          QueryData.from_gapi gapi, service
+        end
+
+        ##
+        # Retrieves an existing dataset by ID.
+        #
+        # @param [String] dataset_id The ID of a dataset.
+        #
+        # @return [Google::Cloud::Bigquery::Dataset, nil] Returns `nil` if the
+        #   dataset does not exist.
+        #
+        # @example
+        #   require "google/cloud"
+        #
+        #   gcloud = Google::Cloud.new
+        #   bigquery = gcloud.bigquery
+        #
+        #   dataset = bigquery.dataset "my_dataset"
+        #   puts dataset.name
+        #
+        def dataset dataset_id
+          ensure_service!
+          gapi = service.get_dataset dataset_id
+          Dataset.from_gapi gapi, service
+        rescue Google::Cloud::NotFoundError
+          nil
+        end
+
+        ##
+        # Creates a new dataset.
+        #
+        # @param [String] dataset_id A unique ID for this dataset, without the
+        #   project name. The ID must contain only letters (a-z, A-Z), numbers
+        #   (0-9), or underscores (_). The maximum length is 1,024 characters.
+        # @param [String] name A descriptive name for the dataset.
+        # @param [String] description A user-friendly description of the
+        #   dataset.
+        # @param [Integer] expiration The default lifetime of all tables in the
+        #   dataset, in milliseconds. The minimum value is 3600000 milliseconds
+        #   (one hour).
+        # @param [String] location The geographic location where the dataset
+        #   should reside. Possible values include `EU` and `US`. The default
+        #   value is `US`.
+        # @yield [access] a block for setting rules
+        # @yieldparam [Dataset::Access] access the object accepting rules
+        #
+        # @return [Google::Cloud::Bigquery::Dataset]
+        #
+        # @example
+        #   require "google/cloud"
+        #
+        #   gcloud = Google::Cloud.new
+        #   bigquery = gcloud.bigquery
+        #
+        #   dataset = bigquery.create_dataset "my_dataset"
+        #
+        # @example A name and description can be provided:
+        #   require "google/cloud"
+        #
+        #   gcloud = Google::Cloud.new
+        #   bigquery = gcloud.bigquery
+        #
+        #   dataset = bigquery.create_dataset "my_dataset",
+        #                                     name: "My Dataset",
+        #                                     description: "This is my Dataset"
+        #
+        # @example Access rules can be provided with the `access` option:
+        #   require "google/cloud"
+        #
+        #   gcloud = Google::Cloud.new
+        #   bigquery = gcloud.bigquery
+        #
+        #   dataset = bigquery.create_dataset "my_dataset",
+        #     access: [{"role"=>"WRITER", "userByEmail"=>"writers@example.com"}]
+        #
+        # @example Or, configure access with a block: (See {Dataset::Access})
+        #   require "google/cloud"
+        #
+        #   gcloud = Google::Cloud.new
+        #   bigquery = gcloud.bigquery
+        #
+        #   dataset = bigquery.create_dataset "my_dataset" do |access|
+        #     access.add_writer_user "writers@example.com"
+        #   end
+        #
+        def create_dataset dataset_id, name: nil, description: nil,
+                           expiration: nil, location: nil
+          ensure_service!
+
+          new_ds = Google::Apis::BigqueryV2::Dataset.new(
+            dataset_reference: Google::Apis::BigqueryV2::DatasetReference.new(
+              project_id: project, dataset_id: dataset_id))
+
+          # Can set location only on creation, no Dataset#location method
+          new_ds.update! location: location unless location.nil?
+
+          updater = Dataset::Updater.new(new_ds).tap do |b|
+            b.name = name unless name.nil?
+            b.description = description unless description.nil?
+            b.default_expiration = expiration unless expiration.nil?
+          end
+
+          if block_given?
+            yield updater
+            updater.check_for_mutated_access!
+          end
+
+          gapi = service.insert_dataset new_ds
+          Dataset.from_gapi gapi, service
+        end
+
+        ##
+        # Retrieves the list of datasets belonging to the project.
+        #
+        # @param [Boolean] all Whether to list all datasets, including hidden
+        #   ones. The default is `false`.
+        # @param [String] token A previously-returned page token representing
+        #   part of the larger set of results to view.
+        # @param [Integer] max Maximum number of datasets to return.
+        #
+        # @return [Array<Google::Cloud::Bigquery::Dataset>] (See
+        #   {Google::Cloud::Bigquery::Dataset::List})
+        #
+        # @example
+        #   require "google/cloud"
+        #
+        #   gcloud = Google::Cloud.new
+        #   bigquery = gcloud.bigquery
+        #
+        #   datasets = bigquery.datasets
+        #   datasets.each do |dataset|
+        #     puts dataset.name
+        #   end
+        #
+        # @example Retrieve hidden datasets with the `all` optional arg:
+        #   require "google/cloud"
+        #
+        #   gcloud = Google::Cloud.new
+        #   bigquery = gcloud.bigquery
+        #
+        #   all_datasets = bigquery.datasets all: true
+        #
+        # @example Retrieve all datasets: (See {Dataset::List#all})
+        #   require "google/cloud"
+        #
+        #   gcloud = Google::Cloud.new
+        #   bigquery = gcloud.bigquery
+        #
+        #   datasets = bigquery.datasets
+        #   datasets.all do |dataset|
+        #     puts dataset.name
+        #   end
+        #
+        def datasets all: nil, token: nil, max: nil
+          ensure_service!
+          options = { all: all, token: token, max: max }
+          gapi = service.list_datasets options
+          Dataset::List.from_gapi gapi, service, all, max
+        end
+
+        ##
+        # Retrieves an existing job by ID.
+        #
+        # @param [String] job_id The ID of a job.
+        #
+        # @return [Google::Cloud::Bigquery::Job, nil] Returns `nil` if the job
+        #   does not exist.
+        #
+        # @example
+        #   require "google/cloud"
+        #
+        #   gcloud = Google::Cloud.new
+        #   bigquery = gcloud.bigquery
+        #
+        #   job = bigquery.job "my_job"
+        #
+        def job job_id
+          ensure_service!
+          gapi = service.get_job job_id
+          Job.from_gapi gapi, service
+        rescue Google::Cloud::NotFoundError
+          nil
+        end
+
+        ##
+        # Retrieves the list of jobs belonging to the project.
+        #
+        # @param [Boolean] all Whether to display jobs owned by all users in the
+        #   project. The default is `false`.
+        # @param [String] token A previously-returned page token representing
+        #   part of the larger set of results to view.
+        # @param [Integer] max Maximum number of jobs to return.
+        # @param [String] filter A filter for job state.
+        #
+        #   Acceptable values are:
+        #
+        #   * `done` - Finished jobs
+        #   * `pending` - Pending jobs
+        #   * `running` - Running jobs
+        #
+        # @return [Array<Google::Cloud::Bigquery::Job>] (See
+        #   {Google::Cloud::Bigquery::Job::List})
+        #
+        # @example
+        #   require "google/cloud"
+        #
+        #   gcloud = Google::Cloud.new
+        #   bigquery = gcloud.bigquery
+        #
+        #   jobs = bigquery.jobs
+        #   jobs.each do |job|
+        #     # process job
+        #   end
+        #
+        # @example Retrieve only running jobs using the `filter` optional arg:
+        #   require "google/cloud"
+        #
+        #   gcloud = Google::Cloud.new
+        #   bigquery = gcloud.bigquery
+        #
+        #   running_jobs = bigquery.jobs filter: "running"
+        #   running_jobs.each do |job|
+        #     # process job
+        #   end
+        #
+        # @example Retrieve all jobs: (See {Job::List#all})
+        #   require "google/cloud"
+        #
+        #   gcloud = Google::Cloud.new
+        #   bigquery = gcloud.bigquery
+        #
+        #   jobs = bigquery.jobs
+        #   jobs.all do |job|
+        #     # process job
+        #   end
+        #
+        def jobs all: nil, token: nil, max: nil, filter: nil
+          ensure_service!
+          options = { all: all, token: token, max: max, filter: filter }
+          gapi = service.list_jobs options
+          Job::List.from_gapi gapi, service, all, max, filter
+        end
+
+        protected
+
+        ##
+        # Raise an error unless an active service is available.
+        def ensure_service!
+          fail "Must have active connection" unless service
+        end
+      end
+    end
+  end
+end