google-cloud-bigquery 0.24.0 → 0.25.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e8cba429d574299afb4e2a230f071e13417c954c
-  data.tar.gz: ca363404d3ec1d319ca4aa3738170a924c3f20fb
+  metadata.gz: 97f13393ce0c9406234614341b3cea2d23c0f6c9
+  data.tar.gz: 47ea3b9d8fad528f8049e9c2bef6c71a3711cb72
 SHA512:
-  metadata.gz: c4aa08940ba60adcc8058e4c1787227d0b40314db0c92e1c40a01dada7a5a4d973311430591d3e786dced51ce7ae65bb554220041ef6c36a5cfc27e930b866b4
-  data.tar.gz: 8ce5bc5f122cb1b90f617ed6c334df9ad7eade436e7727771ff4bad4687e4d712a97c0d4f64db4cafcb55a93e0ee72bc869f58387ac846816968e06f37a09b4b
+  metadata.gz: da73e061c5e4192f36852a5d2c27debd5404d60f3d5da5bec250f45a045ca6ea16ac7f985ef9f0de68ba1d208a1e67e2b6e138fd88a467bec304e6b2d82c7f1c
+  data.tar.gz: 9bfc2e1f267473e8ca57656bedd76875d326dc9b588191566c87d586aba406fd790d9abfbbad2a6d28459499771605bee6ccc13684205acc9a868b1a5effbc0d

data/README.md

@@ -2,7 +2,7 @@
 
 [Google BigQuery](https://cloud.google.com/bigquery/) ([docs](https://cloud.google.com/bigquery/docs)) enables super-fast, SQL-like queries against append-only tables, using the processing power of Google's infrastructure. Simply move your data into BigQuery and let it handle the hard work. You can control access to both the project and your data based on your business needs, such as giving others the ability to view or query your data.
 
-- [google-cloud-bigquery API documentation](http://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud-bigquery/master/google/cloud/bigquery)
+- [google-cloud-bigquery API documentation](http://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud-bigquery/latest)
 - [google-cloud-bigquery on RubyGems](https://rubygems.org/gems/google-cloud-bigquery)
 - [Google BigQuery documentation](https://cloud.google.com/bigquery/docs)
 

data/lib/google/cloud/bigquery.rb

@@ -43,9 +43,10 @@ module Google
     #
     # ## Listing Datasets and Tables
     #
-    # A BigQuery project holds datasets, which in turn hold tables. Assuming
-    # that you have not yet created datasets or tables in your own project,
-    # let's connect to Google's `publicdata` project, and see what you find.
+    # A BigQuery project contains datasets, which in turn contain tables.
+    # Assuming that you have not yet created datasets or tables in your own
+    # project, let's connect to Google's `publicdata` project, and see what we
+    # find.
     #
     # ```ruby
     # require "google/cloud/bigquery"
@@ -62,10 +63,10 @@ module Google
     # tables.map &:table_id #=> [..., "shakespeare", "trigrams", "wikipedia"]
     # ```
     #
-    # In addition listing all datasets and tables in the project, you can also
-    # retrieve individual datasets and tables by ID. Let's look at the structure
-    # of the `shakespeare` table, which contains an entry for every word in
-    # every play written by Shakespeare.
+    # In addition to listing all datasets and tables in the project, you can
+    # also retrieve individual datasets and tables by ID. Let's look at the
+    # structure of the `shakespeare` table, which contains an entry for every
+    # word in every play written by Shakespeare.
     #
     # ```ruby
     # require "google/cloud/bigquery"
@@ -79,15 +80,15 @@ module Google
     # table.rows_count #=> 164656
     # ```
     #
-    # Now that you know the column names for the Shakespeare table, you can
-    # write and run a query.
+    # Now that you know the column names for the Shakespeare table, let's
+    # write and run a few queries against it.
     #
     # ## Running queries
     #
     # BigQuery supports two SQL dialects: [standard
     # SQL](https://cloud.google.com/bigquery/docs/reference/standard-sql/)
-    # and the older [legacy
-    # SQL](https://cloud.google.com/bigquery/docs/reference/legacy-sql),
+    # and the older [legacy SQl (BigQuery
+    # SQL)](https://cloud.google.com/bigquery/docs/reference/legacy-sql),
     # as discussed in the guide [Migrating from legacy
     # SQL](https://cloud.google.com/bigquery/docs/reference/standard-sql/migrating-from-legacy-sql).
     #
@@ -100,7 +101,7 @@ module Google
     # Standard SQL is the preferred SQL dialect for querying data stored in
     # BigQuery. It is compliant with the SQL 2011 standard, and has extensions
     # that support querying nested and repeated data. This is the default
-    # syntax. It has several advantages over Legacy SQL, including:
+    # syntax. It has several advantages over legacy SQL, including:
     #
     # * Composability using `WITH` clauses and SQL functions
     # * Subqueries in the `SELECT` list and `WHERE` clause
@@ -115,7 +116,7 @@ module Google
     # For examples that demonstrate some of these features, see [Standard SQL
     # highlights](https://cloud.google.com/bigquery/docs/reference/standard-sql/migrating-from-legacy-sql#standard_sql_highlights).
     #
-    # Standard SQL is the default.
+    # As shown in this example, standard SQL is the library default:
     #
     # ```ruby
     # require "google/cloud/bigquery"
@@ -136,10 +137,10 @@ module Google
     # Before version 2.0, BigQuery executed queries using a non-standard SQL
     # dialect known as BigQuery SQL. This variant is optional, and can be
     # enabled by passing the flag `legacy_sql: true` with your query. (If you
-    # get an SQL syntax error with a query that may be written in standard SQL,
+    # get an SQL syntax error with a query that may be written in legacy SQL,
     # be sure that you are passing this option.)
     #
-    # To use legacy SQL, pass the option `legacy_sql: true` with your query.
+    # To use legacy SQL, pass the option `legacy_sql: true` with your query:
     #
     # ```ruby
     # require "google/cloud/bigquery"
@@ -201,35 +202,35 @@ module Google
     # ### Synchronous queries
     #
     # Let's start with the simpler synchronous approach. Notice that this time
-    # you are connecting using your own default project. This is necessary for
-    # running a query, since queries need to be able to create tables to hold
-    # results.
+    # you are connecting using your own default project. It is necessary to have
+    # write access to the project for running a query, since queries need to
+    # create tables to hold results.
     #
     # ```ruby
     # require "google/cloud/bigquery"
     #
     # bigquery = Google::Cloud::Bigquery.new
     #
-    # sql = "SELECT TOP(word, 50) as word, COUNT(*) as count " \
-    #       "FROM publicdata:samples.shakespeare"
+    # sql = "SELECT APPROX_TOP_COUNT(corpus, 10) as title, " \
+    #       "COUNT(*) as unique_words " \
+    #       "FROM publicdata.samples.shakespeare"
     # data = bigquery.query sql
     #
-    # data.count #=> 50
     # data.next? #=> false
-    # data.first #=> {"word"=>"you", "count"=>42}
+    # data.first #=> {:title=>[{:value=>"hamlet", :count=>5318}, ...}
     # ```
     #
-    # The `TOP` function shown above is just one of a variety of functions
-    # offered by BigQuery. See the [Query
-    # Reference](https://cloud.google.com/bigquery/query-reference) for a full
-    # listing.
+    # The `APPROX_TOP_COUNT` function shown above is just one of a variety of
+    # functions offered by BigQuery. See the [Query Reference (standard
+    # SQL)](https://cloud.google.com/bigquery/docs/reference/standard-sql/functions-and-operators)
+    # for a full listing.
     #
     # ### Asynchronous queries
     #
-    # Because you probably should not block for most BigQuery operations,
-    # including querying as well as importing, exporting, and copying data, the
-    # BigQuery API enables you to manage longer-running jobs. In the
-    # asynchronous approach to running a query, an instance of
+    # It is usually best not to block for most BigQuery operations, including
+    # querying as well as importing, exporting, and copying data. Therefore, the
+    # BigQuery API provides facilities for managing longer-running jobs. With
+    # the asynchronous approach to running a query, an instance of
     # {Google::Cloud::Bigquery::QueryJob} is returned, rather than an instance
     # of {Google::Cloud::Bigquery::QueryData}.
     #
@@ -238,24 +239,24 @@ module Google
     #
     # bigquery = Google::Cloud::Bigquery.new
     #
-    # sql = "SELECT TOP(word, 50) as word, COUNT(*) as count " \
-    #       "FROM publicdata:samples.shakespeare"
+    # sql = "SELECT APPROX_TOP_COUNT(corpus, 10) as title, " \
+    #       "COUNT(*) as unique_words " \
+    #       "FROM publicdata.samples.shakespeare"
     # job = bigquery.query_job sql
     #
     # job.wait_until_done!
     # if !job.failed?
-    #   job.query_results.each do |row|
-    #     puts row[:word]
-    #   end
+    #   job.query_results.first
+    #   #=> {:title=>[{:value=>"hamlet", :count=>5318}, ...}
     # end
     # ```
     #
     # Once you have determined that the job is done and has not failed, you can
     # obtain an instance of {Google::Cloud::Bigquery::QueryData} by calling
-    # {Google::Cloud::Bigquery::QueryJob#query_results}. The query results for
-    # both of the above examples are stored in temporary tables with a lifetime
-    # of about 24 hours. See the final example below for a demonstration of how
-    # to store query results in a permanent table.
+    # `query_results` on the job instance. The query results for both of the
+    # above examples are stored in temporary tables with a lifetime of about 24
+    # hours. See the final example below for a demonstration of how to store
+    # query results in a permanent table.
     #
     # ## Creating Datasets and Tables
     #
@@ -276,7 +277,7 @@ module Google
     # example below shows a schema with a repeated record field named
     # `cities_lived`. (For more information about nested and repeated fields,
     # see [Preparing Data for
-    # BigQuery](https://cloud.google.com/bigquery/preparing-data-for-bigquery).)
+    # Loading](https://cloud.google.com/bigquery/preparing-data-for-loading).)
     #
     # ```ruby
     # require "google/cloud/bigquery"
@@ -298,14 +299,14 @@ module Google
     #
     # ## Loading records
     #
+    # To follow along with these examples, you will need to set up billing on
+    # the [Google Developers Console](https://console.developers.google.com).
+    #
     # In addition to CSV, data can be imported from files that are formatted as
     # [Newline-delimited JSON](http://jsonlines.org/) or
     # [Avro](http://avro.apache.org/), or from a Google Cloud Datastore backup.
     # It can also be "streamed" into BigQuery.
     #
-    # To follow along with these examples, you will need to set up billing on
-    # the [Google Developers Console](https://console.developers.google.com).
-    #
     # ### Streaming records
     #
     # For situations in which you want new data to be available for querying as
@@ -355,8 +356,7 @@ module Google
     # To follow along with this example, please download the
     # [names.zip](http://www.ssa.gov/OACT/babynames/names.zip) archive from the
     # U.S. Social Security Administration. Inside the archive you will find over
-    # 100 files containing baby name records since the year 1880. A PDF file
-    # also contained in the archive specifies the schema used below.
+    # 100 files containing baby name records since the year 1880.
     #
     # ```ruby
     # require "google/cloud/bigquery"
@@ -365,8 +365,8 @@ module Google
     # dataset = bigquery.dataset "my_dataset"
     # table = dataset.create_table "baby_names" do |schema|
     #   schema.string "name", mode: :required
-    #   schema.string "sex", mode: :required
-    #   schema.integer "number", mode: :required
+    #   schema.string "gender", mode: :required
+    #   schema.integer "count", mode: :required
     # end
     #
     # file = File.open "names/yob2014.txt"
@@ -395,37 +395,35 @@ module Google
     # source_table = dataset.table "baby_names"
     # result_table = dataset.create_table "baby_names_results"
     #
-    # sql = "SELECT name, number as count " \
+    # sql = "SELECT name, count " \
     #       "FROM baby_names " \
-    #       "WHERE name CONTAINS 'Sam' " \
-    #       "ORDER BY count DESC"
+    #       "WHERE gender = 'M' " \
+    #       "ORDER BY count ASC LIMIT 5"
     # query_job = dataset.query_job sql, table: result_table
     #
     # query_job.wait_until_done!
     #
     # if !query_job.failed?
-    #
-    #   require "google/cloud/bigquery"
+    #   require "google/cloud/storage"
     #
     #   storage = Google::Cloud::Storage.new
     #   bucket_id = "bigquery-exports-#{SecureRandom.uuid}"
     #   bucket = storage.create_bucket bucket_id
-    #   extract_url = "gs://#{bucket.id}/baby-names-sam.csv"
+    #   extract_url = "gs://#{bucket.id}/baby-names.csv"
     #
     #   extract_job = result_table.extract extract_url
     #
     #   extract_job.wait_until_done!
     #
     #   # Download to local filesystem
-    #   bucket.files.first.download "baby-names-sam.csv"
-    #
+    #   bucket.files.first.download "baby-names.csv"
     # end
     # ```
     #
     # If a table you wish to export contains a large amount of data, you can
     # pass a wildcard URI to export to multiple files (for sharding), or an
-    # array of URIs (for partitioning), or both. See [Exporting Data From
-    # BigQuery](https://cloud.google.com/bigquery/exporting-data-from-bigquery)
+    # array of URIs (for partitioning), or both. See [Exporting
+    # Data](https://cloud.google.com/bigquery/docs/exporting-data)
     # for details.
     #
     # ## Configuring retries and timeout

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

@@ -279,8 +279,8 @@ module Google
         #   require "google/cloud/bigquery"
         #
         #   bigquery = Google::Cloud::Bigquery.new
-        #
         #   dataset = bigquery.dataset "my_dataset"
+        #
         #   dataset.delete
         #
         # @!group Lifecycle
@@ -312,6 +312,7 @@ module Google
         #
         #   bigquery = Google::Cloud::Bigquery.new
         #   dataset = bigquery.dataset "my_dataset"
+        #
         #   table = dataset.create_table "my_table"
         #
         # @example You can also pass name and description options.
@@ -319,6 +320,7 @@ module Google
         #
         #   bigquery = Google::Cloud::Bigquery.new
         #   dataset = bigquery.dataset "my_dataset"
+        #
         #   table = dataset.create_table "my_table",
         #                                name: "My Table",
         #                                description: "A description of table."
@@ -342,6 +344,7 @@ module Google
         #
         #   bigquery = Google::Cloud::Bigquery.new
         #   dataset = bigquery.dataset "my_dataset"
+        #
         #   table = dataset.create_table "my_table" do |t|
         #     t.name = "My Table",
         #     t.description = "A description of my table."
@@ -399,6 +402,7 @@ module Google
         #
         #   bigquery = Google::Cloud::Bigquery.new
         #   dataset = bigquery.dataset "my_dataset"
+        #
         #   view = dataset.create_view "my_view",
         #             "SELECT name, age FROM proj.dataset.users"
         #
@@ -407,6 +411,7 @@ module Google
         #
         #   bigquery = Google::Cloud::Bigquery.new
         #   dataset = bigquery.dataset "my_dataset"
+        #
         #   view = dataset.create_view "my_view",
         #             "SELECT name, age FROM proj.dataset.users",
         #             name: "My View", description: "This is my view"
@@ -447,6 +452,7 @@ module Google
         #
         #   bigquery = Google::Cloud::Bigquery.new
         #   dataset = bigquery.dataset "my_dataset"
+        #
         #   table = dataset.table "my_table"
         #   puts table.name
         #
@@ -476,6 +482,7 @@ module Google
         #
         #   bigquery = Google::Cloud::Bigquery.new
         #   dataset = bigquery.dataset "my_dataset"
+        #
         #   tables = dataset.tables
         #   tables.each do |table|
         #     puts table.name
@@ -486,6 +493,7 @@ module Google
         #
         #   bigquery = Google::Cloud::Bigquery.new
         #   dataset = bigquery.dataset "my_dataset"
+        #
         #   tables = dataset.tables
         #   tables.all do |table|
         #     puts table.name
@@ -550,7 +558,7 @@ module Google
         #   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.
+        #   new tables. The default value is `needed`.
         #
         #   The following values are supported:
         #
@@ -558,7 +566,7 @@ module Google
         #   * `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.
+        #   destination table already exists. The default value is `empty`.
         #
         #   The following values are supported:
         #
@@ -591,12 +599,13 @@ module Google
         #
         # @return [Google::Cloud::Bigquery::QueryJob]
         #
-        # @example
+        # @example Query using standard SQL:
         #   require "google/cloud/bigquery"
         #
         #   bigquery = Google::Cloud::Bigquery.new
+        #   dataset = bigquery.dataset "my_dataset"
         #
-        #   job = bigquery.query_job "SELECT name FROM my_table"
+        #   job = dataset.query_job "SELECT name FROM my_table"
         #
         #   job.wait_until_done!
         #   if !job.failed?
@@ -609,9 +618,10 @@ module Google
         #   require "google/cloud/bigquery"
         #
         #   bigquery = Google::Cloud::Bigquery.new
+        #   dataset = bigquery.dataset "my_dataset"
         #
-        #   job = bigquery.query_job "SELECT name FROM my_table",
-        #                            legacy_sql: true
+        #   job = dataset.query_job "SELECT name FROM my_table",
+        #                           legacy_sql: true
         #
         #   job.wait_until_done!
         #   if !job.failed?
@@ -624,9 +634,10 @@ module Google
         #   require "google/cloud/bigquery"
         #
         #   bigquery = Google::Cloud::Bigquery.new
+        #   dataset = bigquery.dataset "my_dataset"
         #
-        #   job = bigquery.query_job "SELECT name FROM my_table WHERE id = ?",
-        #                            params: [1]
+        #   job = dataset.query_job "SELECT name FROM my_table WHERE id = ?",
+        #                           params: [1]
         #
         #   job.wait_until_done!
         #   if !job.failed?
@@ -639,9 +650,10 @@ module Google
         #   require "google/cloud/bigquery"
         #
         #   bigquery = Google::Cloud::Bigquery.new
+        #   dataset = bigquery.dataset "my_dataset"
         #
-        #   job = bigquery.query_job "SELECT name FROM my_table WHERE id = @id",
-        #                            params: { id: 1 }
+        #   job = dataset.query_job "SELECT name FROM my_table WHERE id = @id",
+        #                           params: { id: 1 }
         #
         #   job.wait_until_done!
         #   if !job.failed?
@@ -747,12 +759,13 @@ module Google
         #
         # @return [Google::Cloud::Bigquery::QueryData]
         #
-        # @example
+        # @example Query using standard SQL:
         #   require "google/cloud/bigquery"
         #
         #   bigquery = Google::Cloud::Bigquery.new
+        #   dataset = bigquery.dataset "my_dataset"
         #
-        #   data = bigquery.query "SELECT name FROM my_table"
+        #   data = dataset.query "SELECT name FROM my_table"
         #
         #   data.each do |row|
         #     puts row["name"]
@@ -762,9 +775,10 @@ module Google
         #   require "google/cloud/bigquery"
         #
         #   bigquery = Google::Cloud::Bigquery.new
+        #   dataset = bigquery.dataset "my_dataset"
         #
-        #   data = bigquery.query "SELECT name FROM my_table",
-        #                         legacy_sql: true
+        #   data = dataset.query "SELECT name FROM my_table",
+        #                        legacy_sql: true
         #
         #   data.each do |row|
         #     puts row["name"]
@@ -774,9 +788,10 @@ module Google
         #   require "google/cloud/bigquery"
         #
         #   bigquery = Google::Cloud::Bigquery.new
+        #   dataset = bigquery.dataset "my_dataset"
         #
-        #   data = bigquery.query "SELECT name FROM my_table WHERE id = ?",
-        #                         params: [1]
+        #   data = dataset.query "SELECT name FROM my_table WHERE id = ?",
+        #                        params: [1]
         #
         #   data.each do |row|
         #     puts row["name"]
@@ -786,9 +801,10 @@ module Google
         #   require "google/cloud/bigquery"
         #
         #   bigquery = Google::Cloud::Bigquery.new
+        #   dataset = bigquery.dataset "my_dataset"
         #
-        #   data = bigquery.query "SELECT name FROM my_table WHERE id = @id",
-        #                         params: { id: 1 }
+        #   data = dataset.query "SELECT name FROM my_table WHERE id = @id",
+        #                        params: { id: 1 }
         #
         #   data.each do |row|
         #     puts row["name"]

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

@@ -36,7 +36,6 @@ module Google
         #     access.add_writer_user "writer@example.com"
         #     access.remove_writer_user "readers@example.com"
         #     access.add_reader_special :all
-        #     access.add_reader_view other_dataset_view_object
         #   end
         #
         class Access

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

@@ -77,15 +77,15 @@ module Google
           end
 
           ##
-          # Retrieves all datasets by repeatedly loading {#next} until {#next?}
-          # returns `false`. Calls the given block once for each dataset, which
-          # is passed as the parameter.
+          # Retrieves remaining results by repeatedly invoking {#next} until
+          # {#next?} returns `false`. Calls the given block once for each
+          # result, which is passed as the argument to the block.
           #
           # An Enumerator is returned if no block is given.
           #
-          # This method may make several API calls until all datasets are
-          # retrieved. Be sure to use as narrow a search criteria as possible.
-          # Please use with caution.
+          # This method will make repeated API calls until all remaining results
+          # are retrieved. (Unlike `#each`, for example, which merely iterates
+          # over the results returned by a single API call.) Use with caution.
           #
           # @param [Integer] request_limit The upper limit of API requests to
           #   make to load all datasets. Default is no limit.

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

@@ -44,8 +44,8 @@ module Google
       #
       #   bigquery = Google::Cloud::Bigquery.new
       #
-      #   q = "SELECT COUNT(word) as count FROM publicdata:samples.shakespeare"
-      #   job = bigquery.query_job q
+      #   job = bigquery.query_job "SELECT COUNT(word) as count FROM " \
+      #                            "publicdata.samples.shakespeare"
       #
       #   job.wait_until_done!
       #
@@ -205,6 +205,15 @@ module Google
           Array(@gapi.status.errors).map { |e| JSON.parse e.to_json }
         end
 
+        ##
+        # Cancels the job.
+        def cancel
+          ensure_service!
+          resp = service.cancel_job job_id
+          @gapi = resp.job
+          true
+        end
+
         ##
         # Created a new job with the current configuration.
         def rerun!

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

@@ -77,15 +77,15 @@ module Google
           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.
+          # Retrieves remaining results by repeatedly invoking {#next} until
+          # {#next?} returns `false`. Calls the given block once for each
+          # result, which is passed as the argument to the block.
           #
           # 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.
+          # This method will make repeated API calls until all remaining results
+          # are retrieved. (Unlike `#each`, for example, which merely iterates
+          # over the results returned by a single API call.) Use with caution.
           #
           # @param [Integer] request_limit The upper limit of API requests to
           #   make to load all jobs. Default is no limit.

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

@@ -13,7 +13,7 @@
 # limitations under the License.
 
 
-require "google/cloud/core/environment"
+require "google/cloud/env"
 require "google/cloud/errors"
 require "google/cloud/bigquery/service"
 require "google/cloud/bigquery/credentials"
@@ -89,7 +89,7 @@ module Google
           ENV["BIGQUERY_PROJECT"] ||
             ENV["GOOGLE_CLOUD_PROJECT"] ||
             ENV["GCLOUD_PROJECT"] ||
-            Google::Cloud::Core::Environment.project_id
+            Google::Cloud.env.project_id
         end
 
         ##
@@ -139,7 +139,7 @@ module Google
         #   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.
+        #   new tables. The default value is `needed`.
         #
         #   The following values are supported:
         #
@@ -147,7 +147,7 @@ module Google
         #   * `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.
+        #   destination table already exists. The default value is `empty`.
         #
         #   The following values are supported:
         #
@@ -183,13 +183,13 @@ module Google
         #
         # @return [Google::Cloud::Bigquery::QueryJob]
         #
-        # @example
+        # @example Query using standard SQL:
         #   require "google/cloud/bigquery"
         #
         #   bigquery = Google::Cloud::Bigquery.new
         #
         #   job = bigquery.query_job "SELECT name FROM " \
-        #                            "[my_proj:my_data.my_table]"
+        #                            "`my_project.my_dataset.my_table`"
         #
         #   job.wait_until_done!
         #   if !job.failed?
@@ -204,7 +204,7 @@ module Google
         #   bigquery = Google::Cloud::Bigquery.new
         #
         #   job = bigquery.query_job "SELECT name FROM " \
-        #                            "`my_proj.my_data.my_table`",
+        #                            "[my_project:my_dataset.my_table]",
         #                            legacy_sql: true
         #
         #   job.wait_until_done!
@@ -220,7 +220,7 @@ module Google
         #   bigquery = Google::Cloud::Bigquery.new
         #
         #   job = bigquery.query_job "SELECT name FROM " \
-        #                            "`my_proj.my_data.my_table`" \
+        #                            "`my_dataset.my_table`" \
         #                            " WHERE id = ?",
         #                            params: [1]
         #
@@ -237,7 +237,7 @@ module Google
         #   bigquery = Google::Cloud::Bigquery.new
         #
         #   job = bigquery.query_job "SELECT name FROM " \
-        #                            "`my_proj.my_data.my_table`" \
+        #                            "`my_dataset.my_table`" \
         #                            " WHERE id = @id",
         #                            params: { id: 1 }
         #
@@ -347,12 +347,13 @@ module Google
         #
         # @return [Google::Cloud::Bigquery::QueryData]
         #
-        # @example
+        # @example Query using standard SQL:
         #   require "google/cloud/bigquery"
         #
         #   bigquery = Google::Cloud::Bigquery.new
         #
-        #   data = bigquery.query "SELECT name FROM `my_proj.my_data.my_table`"
+        #   sql = "SELECT name FROM `my_project.my_dataset.my_table`"
+        #   data = bigquery.query sql
         #
         #   data.each do |row|
         #     puts row["name"]
@@ -363,8 +364,8 @@ module Google
         #
         #   bigquery = Google::Cloud::Bigquery.new
         #
-        #   data = bigquery.query "SELECT name FROM [my_proj:my_data.my_table]",
-        #                         legacy_sql: true
+        #   sql = "SELECT name FROM [my_project:my_dataset.my_table]"
+        #   data = bigquery.query sql, legacy_sql: true
         #
         #   data.each do |row|
         #     puts row["name"]
@@ -375,7 +376,7 @@ module Google
         #
         #   bigquery = Google::Cloud::Bigquery.new
         #
-        #   data = bigquery.query "SELECT name FROM `my_proj.my_data.my_table`"
+        #   data = bigquery.query "SELECT name FROM `my_dataset.my_table`"
         #
         #   data.all do |row|
         #     puts row["name"]
@@ -387,7 +388,7 @@ module Google
         #   bigquery = Google::Cloud::Bigquery.new
         #
         #   data = bigquery.query "SELECT name " \
-        #                         "FROM `my_proj.my_data.my_table`" \
+        #                         "FROM `my_dataset.my_table`" \
         #                         "WHERE id = ?",
         #                         params: [1]
         #
@@ -401,7 +402,7 @@ module Google
         #   bigquery = Google::Cloud::Bigquery.new
         #
         #   data = bigquery.query "SELECT name " \
-        #                         "FROM `my_proj.my_data.my_table`" \
+        #                         "FROM `my_dataset.my_table`" \
         #                         "WHERE id = @id",
         #                         params: { id: 1 }
         #
@@ -487,8 +488,8 @@ module Google
         #
         #   bigquery = Google::Cloud::Bigquery.new
         #
-        #   dataset = bigquery.create_dataset "my_dataset" do |table|
-        #     table.access.add_writer_user "writers@example.com"
+        #   dataset = bigquery.create_dataset "my_dataset" do |dataset|
+        #     dataset.access.add_writer_user "writers@example.com"
         #   end
         #
         def create_dataset dataset_id, name: nil, description: nil,
@@ -708,7 +709,7 @@ module Google
         #
         #   fourpm = bigquery.time 16, 0, 0
         #   data = bigquery.query "SELECT name " \
-        #                         "FROM `my_proj.my_data.my_table`" \
+        #                         "FROM `my_dataset.my_table`" \
         #                         "WHERE time_of_date = @time",
         #                         params: { time: fourpm }
         #
@@ -723,7 +724,7 @@ module Google
         #
         #   precise_time = bigquery.time 16, 35, 15.376541
         #   data = bigquery.query "SELECT name " \
-        #                         "FROM `my_proj.my_data.my_table`" \
+        #                         "FROM `my_dataset.my_table`" \
         #                         "WHERE time_of_date >= @time",
         #                         params: { time: precise_time }
         #

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

@@ -78,15 +78,15 @@ module Google
           end
 
           ##
-          # Retrieves all projects by repeatedly loading {#next} until {#next?}
-          # returns `false`. Calls the given block once for each project, which
-          # is passed as the parameter.
+          # Retrieves remaining results by repeatedly invoking {#next} until
+          # {#next?} returns `false`. Calls the given block once for each
+          # result, which is passed as the argument to the block.
           #
           # An Enumerator is returned if no block is given.
           #
-          # This method may make several API calls until all projects are
-          # retrieved. Be sure to use as narrow a search criteria as possible.
-          # Please use with caution.
+          # This method will make repeated API calls until all remaining results
+          # are retrieved. (Unlike `#each`, for example, which merely iterates
+          # over the results returned by a single API call.) Use with caution.
           #
           # @param [Integer] request_limit The upper limit of API requests to
           #   make to load all projects. Default is no limit.

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

@@ -130,8 +130,8 @@ module Google
         #
         #   bigquery = Google::Cloud::Bigquery.new
         #
-        #   q = "SELECT word FROM publicdata:samples.shakespeare"
-        #   job = bigquery.query_job q
+        #   sql = "SELECT word FROM publicdata.samples.shakespeare"
+        #   job = bigquery.query_job sql
         #
         #   job.wait_until_done!
         #   data = job.query_results

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

@@ -32,8 +32,8 @@ module Google
         #   dataset = bigquery.dataset "my_dataset"
         #   table = dataset.table "my_table"
         #
-        #   name_field = table.schema.field "name"
-        #   name_field.required? #=> true
+        #   field = table.schema.field "name"
+        #   field.required? #=> true
         class Field
           # @private
           MODES = %w( NULLABLE REQUIRED REPEATED )

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

@@ -61,6 +61,9 @@ module Google
             service.request_options.retries = @retries || 3
             service.request_options.timeout_sec      = @timeout
             service.request_options.open_timeout_sec = @timeout
+            service.request_options.header ||= {}
+            service.request_options.header["x-goog-api-client"] = \
+              "gl-ruby/#{RUBY_VERSION} gccl/#{Google::Cloud::Bigquery::VERSION}"
             service.authorization = @credentials.client
             service
           end
@@ -200,6 +203,12 @@ module Google
           end
         end
 
+        ##
+        # Cancel the job specified by jobId.
+        def cancel_job job_id
+          execute { service.cancel_job @project, job_id }
+        end
+
         ##
         # Returns the job specified by jobID.
         def get_job job_id

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

@@ -153,7 +153,7 @@ module Google
         #   dataset = bigquery.dataset "my_dataset"
         #   table = dataset.table "my_table"
         #
-        #   data = bigquery.query "SELECT name FROM #{table.query_id}"
+        #   data = bigquery.query "SELECT first_name FROM #{table.query_id}"
         #
         # @!group Attributes
         #
@@ -450,7 +450,7 @@ module Google
         # @param [Table, String] destination_table The destination for the
         #   copied data.
         # @param [String] create Specifies whether the job is allowed to create
-        #   new tables.
+        #   new tables. The default value is `needed`.
         #
         #   The following values are supported:
         #
@@ -567,7 +567,7 @@ module Google
         #   * `avro` - [Avro](http://avro.apache.org/)
         #   * `datastore_backup` - Cloud Datastore backup
         # @param [String] create Specifies whether the job is allowed to create
-        #   new tables.
+        #   new tables. The default value is `needed`.
         #
         #   The following values are supported:
         #
@@ -575,7 +575,7 @@ module Google
         #   * `never` - The table must already exist. A 'notFound' error is
         #     raised if the table does not exist.
         # @param [String] write Specifies how to handle data already present in
-        #   the table. The default value is `empty`.
+        #   the table. The default value is `append`.
         #
         #   The following values are supported:
         #

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

@@ -84,15 +84,15 @@ module Google
           end
 
           ##
-          # Retrieves all tables by repeatedly loading {#next} until {#next?}
-          # returns `false`. Calls the given block once for each table, which is
-          # passed as the parameter.
+          # Retrieves remaining results by repeatedly invoking {#next} until
+          # {#next?} returns `false`. Calls the given block once for each
+          # result, which is passed as the argument to the block.
           #
           # An Enumerator is returned if no block is given.
           #
-          # This method may make several API calls until all tables are
-          # retrieved. Be sure to use as narrow a search criteria as possible.
-          # Please use with caution.
+          # This method will make repeated API calls until all remaining results
+          # are retrieved. (Unlike `#each`, for example, which merely iterates
+          # over the results returned by a single API call.) Use with caution.
           #
           # @param [Integer] request_limit The upper limit of API requests to
           #   make to load all tables. Default is no limit.

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

@@ -30,7 +30,7 @@ module Google
       #
       #   fourpm = Google::Cloud::Bigquery::Time.new "16:00:00"
       #   data = bigquery.query "SELECT name " \
-      #                         "FROM `my_proj.my_data.my_table`" \
+      #                         "FROM `my_project.my_dataset.my_table`" \
       #                         "WHERE time_of_date = @time",
       #                         params: { time: fourpm }
       #
@@ -45,7 +45,7 @@ module Google
       #
       #   precise_time = Google::Cloud::Bigquery::Time.new "16:35:15.376541"
       #   data = bigquery.query "SELECT name " \
-      #                         "FROM `my_proj.my_data.my_table`" \
+      #                         "FROM `my_project.my_dataset.my_table`" \
       #                         "WHERE time_of_date >= @time",
       #                         params: { time: precise_time }
       #

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

@@ -16,7 +16,7 @@
 module Google
   module Cloud
     module Bigquery
-      VERSION = "0.24.0"
+      VERSION = "0.25.0"
     end
   end
 end

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

@@ -40,7 +40,7 @@ module Google
       #   bigquery = Google::Cloud::Bigquery.new
       #   dataset = bigquery.dataset "my_dataset"
       #   view = dataset.create_view "my_view",
-      #            "SELECT name, age FROM proj.dataset.users"
+      #            "SELECT name, age FROM `my_project.my_dataset.my_table`"
       #
       class View
         ##

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: google-cloud-bigquery
 version: !ruby/object:Gem::Version
-  version: 0.24.0
+  version: 0.25.0
 platform: ruby
 authors:
 - Mike Moore
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-03-04 00:00:00.000000000 Z
+date: 2017-04-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: google-cloud-core
@@ -17,14 +17,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.21.0
+        version: '1.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.21.0
+        version: '1.0'
 - !ruby/object:Gem::Dependency
   name: google-api-client
   requirement: !ruby/object:Gem::Requirement
@@ -222,7 +222,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.6.10
+rubygems_version: 2.6.11
 signing_key: 
 specification_version: 4
 summary: API Client library for Google BigQuery