google-cloud-bigquery 0.21.0 → 0.23.0

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

@@ -74,6 +74,7 @@ module Google
         #   require "google/cloud/bigquery"
         #
         #   bigquery = Google::Cloud::Bigquery.new
+        #   dataset = bigquery.dataset "my_dataset"
         #   table = dataset.table "my_table"
         #
         #   data = table.data
@@ -94,6 +95,7 @@ module Google
         #   require "google/cloud/bigquery"
         #
         #   bigquery = Google::Cloud::Bigquery.new
+        #   dataset = bigquery.dataset "my_dataset"
         #   table = dataset.table "my_table"
         #
         #   data = table.data
@@ -129,6 +131,7 @@ module Google
         #   require "google/cloud/bigquery"
         #
         #   bigquery = Google::Cloud::Bigquery.new
+        #   dataset = bigquery.dataset "my_dataset"
         #   table = dataset.table "my_table"
         #
         #   table.data.all do |row|
@@ -139,6 +142,7 @@ module Google
         #   require "google/cloud/bigquery"
         #
         #   bigquery = Google::Cloud::Bigquery.new
+        #   dataset = bigquery.dataset "my_dataset"
         #   table = dataset.table "my_table"
         #
         #   words = table.data.all.map do |row|
@@ -149,6 +153,7 @@ module Google
         #   require "google/cloud/bigquery"
         #
         #   bigquery = Google::Cloud::Bigquery.new
+        #   dataset = bigquery.dataset "my_dataset"
         #   table = dataset.table "my_table"
         #
         #   table.data.all(request_limit: 10) do |row|

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

@@ -179,7 +179,7 @@ module Google
         def created_at
           ensure_full_data!
           begin
-            Time.at(Integer(@gapi.creation_time) / 1000.0)
+            ::Time.at(Integer(@gapi.creation_time) / 1000.0)
           rescue
             nil
           end
@@ -193,7 +193,7 @@ module Google
         def modified_at
           ensure_full_data!
           begin
-            Time.at(Integer(@gapi.last_modified_time) / 1000.0)
+            ::Time.at(Integer(@gapi.last_modified_time) / 1000.0)
           rescue
             nil
           end
@@ -229,14 +229,14 @@ module Google
         #   bigquery = Google::Cloud::Bigquery.new
         #   dataset = bigquery.dataset "my_dataset"
         #
-        #   dataset.access #=> [{"role"=>"OWNER",
-        #                  #     "specialGroup"=>"projectOwners"},
-        #                  #    {"role"=>"WRITER",
-        #                  #     "specialGroup"=>"projectWriters"},
-        #                  #    {"role"=>"READER",
-        #                  #     "specialGroup"=>"projectReaders"},
-        #                  #    {"role"=>"OWNER",
-        #                  #     "userByEmail"=>"123456789-...com"}]
+        #   dataset.access # [{"role"=>"OWNER",
+        #                  #   "specialGroup"=>"projectOwners"},
+        #                  #  {"role"=>"WRITER",
+        #                  #   "specialGroup"=>"projectWriters"},
+        #                  #  {"role"=>"READER",
+        #                  #   "specialGroup"=>"projectReaders"},
+        #                  #  {"role"=>"OWNER",
+        #                  #   "userByEmail"=>"123456789-...com"}]
         #
         # @example Manage the access rules by passing a block:
         #   require "google/cloud/bigquery"
@@ -322,7 +322,7 @@ module Google
         #
         #   bigquery = Google::Cloud::Bigquery.new
         #   dataset = bigquery.dataset "my_dataset"
-        #   table = dataset.create_table "my_table"
+        #   table = dataset.create_table "my_table",
         #                                name: "My Table",
         #                                description: "A description of table."
         #
@@ -336,7 +336,7 @@ module Google
         #     Google::Cloud::Bigquery::Schema::Field.new(
         #       "first_name", :string, mode: :required),
         #     Google::Cloud::Bigquery::Schema::Field.new(
-        #       "cities_lived", :record, mode: :repeated
+        #       "cities_lived", :record, mode: :repeated,
         #       fields: [
         #         Google::Cloud::Bigquery::Schema::Field.new(
         #           "place", :string, mode: :required),
@@ -520,10 +520,37 @@ module Google
         # Sets the current dataset as the default dataset in the query. Useful
         # for using unqualified table names.
         #
+        # When using standard SQL and passing arguments using `params`, Ruby
+        # types are mapped to BigQuery types as follows:
+        #
+        # | BigQuery    | Ruby           | Notes  |
+        # |-------------|----------------|---|
+        # | `BOOL`      | `true`/`false` | |
+        # | `INT64`     | `Integer`      | |
+        # | `FLOAT64`   | `Float`        | |
+        # | `STRING`    | `STRING`       | |
+        # | `DATETIME`  | `DateTime`  | `DATETIME` does not support time zone. |
+        # | `DATE`      | `Date`         | |
+        # | `TIMESTAMP` | `Time`         | |
+        # | `TIME`      | `Google::Cloud::BigQuery::Time` | |
+        # | `BYTES`     | `File`, `IO`, `StringIO`, or similar | |
+        # | `ARRAY` | `Array` | Nested arrays, `nil` values are not supported. |
+        # | `STRUCT`    | `Hash`        | Hash keys may be strings or symbols. |
+        #
+        # See [Data Types](https://cloud.google.com/bigquery/docs/reference/standard-sql/data-types)
+        # for an overview of each BigQuery data type, including allowed values.
+        #
         # @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 [Array, Hash] params Standard SQL only. Used to pass query
+        #   arguments when the `query` string contains either positional (`?`)
+        #   or named (`@myparam`) query parameters. If value passed is an array
+        #   `["foo"]`, the query must use positional query parameters. If value
+        #   passed is a hash `{ myparam: "foo" }`, the query must use named
+        #   query parameters. When set, `legacy_sql` will automatically be set
+        #   to false and `standard_sql` to true.
         # @param [String] priority Specifies a priority for the query. Possible
         #   values include `INTERACTIVE` and `BATCH`. The default value is
         #   `INTERACTIVE`.
@@ -558,6 +585,25 @@ module Google
         # @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 [Boolean] legacy_sql Specifies whether to use BigQuery's
+        #   [legacy
+        #   SQL](https://cloud.google.com/bigquery/docs/reference/legacy-sql)
+        #   dialect for this query. If set to false, the query will use
+        #   BigQuery's [standard
+        #   SQL](https://cloud.google.com/bigquery/docs/reference/standard-sql/)
+        #   When set to false, the values of `large_results` and `flatten` are
+        #   ignored; the query will be run as if `large_results` is true and
+        #   `flatten` is false. Optional. The default value is true.
+        # @param [Boolean] standard_sql Specifies whether to use BigQuery's
+        #   [standard
+        #   SQL](https://cloud.google.com/bigquery/docs/reference/standard-sql/)
+        #   dialect for this query. If set to true, the query will use standard
+        #   SQL rather than the [legacy
+        #   SQL](https://cloud.google.com/bigquery/docs/reference/legacy-sql)
+        #   dialect. When set to true, the values of `large_results` and
+        #   `flatten` are ignored; the query will be run as if `large_results`
+        #   is true and `flatten` is false. Optional. The default value is
+        #   false.
         #
         # @return [Google::Cloud::Bigquery::QueryJob]
         #
@@ -575,13 +621,61 @@ module Google
         #     end
         #   end
         #
+        # @example Query using standard SQL:
+        #   require "google/cloud/bigquery"
+        #
+        #   bigquery = Google::Cloud::Bigquery.new
+        #
+        #   job = bigquery.query_job "SELECT name FROM my_table",
+        #                            standard_sql: true
+        #
+        #   job.wait_until_done!
+        #   if !job.failed?
+        #     job.query_results.each do |row|
+        #       puts row["name"]
+        #     end
+        #   end
+        #
+        # @example Query using positional query parameters:
+        #   require "google/cloud/bigquery"
+        #
+        #   bigquery = Google::Cloud::Bigquery.new
+        #
+        #   job = bigquery.query_job "SELECT name FROM my_table WHERE id = ?",
+        #                            params: [1]
+        #
+        #   job.wait_until_done!
+        #   if !job.failed?
+        #     job.query_results.each do |row|
+        #       puts row["name"]
+        #     end
+        #   end
+        #
+        # @example Query using named query parameters:
+        #   require "google/cloud/bigquery"
+        #
+        #   bigquery = Google::Cloud::Bigquery.new
+        #
+        #   job = bigquery.query_job "SELECT name FROM my_table WHERE id = @id",
+        #                            params: { id: 1 }
+        #
+        #   job.wait_until_done!
+        #   if !job.failed?
+        #     job.query_results.each do |row|
+        #       puts row["name"]
+        #     end
+        #   end
+        #
         # @!group Data
         #
-        def query_job query, priority: "INTERACTIVE", cache: true, table: nil,
-                      create: nil, write: nil, large_results: nil, flatten: nil
+        def query_job query, params: nil, priority: "INTERACTIVE", cache: true,
+                      table: nil, create: nil, write: nil, large_results: nil,
+                      flatten: nil, legacy_sql: nil, standard_sql: nil
           options = { priority: priority, cache: cache, table: table,
                       create: create, write: write,
-                      large_results: large_results, flatten: flatten }
+                      large_results: large_results, flatten: flatten,
+                      legacy_sql: legacy_sql, standard_sql: standard_sql,
+                      params: params }
           options[:dataset] ||= self
           ensure_service!
           gapi = service.query_job query, options
@@ -595,10 +689,37 @@ module Google
         # Sets the current dataset as the default dataset in the query. Useful
         # for using unqualified table names.
         #
+        # When using standard SQL and passing arguments using `params`, Ruby
+        # types are mapped to BigQuery types as follows:
+        #
+        # | BigQuery    | Ruby           | Notes  |
+        # |-------------|----------------|---|
+        # | `BOOL`      | `true`/`false` | |
+        # | `INT64`     | `Integer`      | |
+        # | `FLOAT64`   | `Float`        | |
+        # | `STRING`    | `STRING`       | |
+        # | `DATETIME`  | `DateTime`  | `DATETIME` does not support time zone. |
+        # | `DATE`      | `Date`         | |
+        # | `TIMESTAMP` | `Time`         | |
+        # | `TIME`      | `Google::Cloud::BigQuery::Time` | |
+        # | `BYTES`     | `File`, `IO`, `StringIO`, or similar | |
+        # | `ARRAY` | `Array` | Nested arrays, `nil` values are not supported. |
+        # | `STRUCT`    | `Hash`        | Hash keys may be strings or symbols. |
+        #
+        # See [Data Types](https://cloud.google.com/bigquery/docs/reference/standard-sql/data-types)
+        # for an overview of each BigQuery data type, including allowed values.
+        #
         # @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 [Array, Hash] params Standard SQL only. Used to pass query
+        #   arguments when the `query` string contains either positional (`?`)
+        #   or named (`@myparam`) query parameters. If value passed is an array
+        #   `["foo"]`, the query must use positional query parameters. If value
+        #   passed is a hash `{ myparam: "foo" }`, the query must use named
+        #   query parameters. When set, `legacy_sql` will automatically be set
+        #   to false and `standard_sql` to true.
         # @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
@@ -620,6 +741,25 @@ module Google
         #   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 [Boolean] legacy_sql Specifies whether to use BigQuery's
+        #   [legacy
+        #   SQL](https://cloud.google.com/bigquery/docs/reference/legacy-sql)
+        #   dialect for this query. If set to false, the query will use
+        #   BigQuery's [standard
+        #   SQL](https://cloud.google.com/bigquery/docs/reference/standard-sql/)
+        #   When set to false, the values of `large_results` and `flatten` are
+        #   ignored; the query will be run as if `large_results` is true and
+        #   `flatten` is false. Optional. The default value is true.
+        # @param [Boolean] standard_sql Specifies whether to use BigQuery's
+        #   [standard
+        #   SQL](https://cloud.google.com/bigquery/docs/reference/standard-sql/)
+        #   dialect for this query. If set to true, the query will use standard
+        #   SQL rather than the [legacy
+        #   SQL](https://cloud.google.com/bigquery/docs/reference/legacy-sql)
+        #   dialect. When set to true, the values of `large_results` and
+        #   `flatten` are ignored; the query will be run as if `large_results`
+        #   is true and `flatten` is false. Optional. The default value is
+        #   false.
         #
         # @return [Google::Cloud::Bigquery::QueryData]
         #
@@ -629,14 +769,54 @@ module Google
         #   bigquery = Google::Cloud::Bigquery.new
         #
         #   data = bigquery.query "SELECT name FROM my_table"
+        #
+        #   data.each do |row|
+        #     puts row["name"]
+        #   end
+        #
+        # @example Query using standard SQL:
+        #   require "google/cloud/bigquery"
+        #
+        #   bigquery = Google::Cloud::Bigquery.new
+        #
+        #   data = bigquery.query "SELECT name FROM my_table",
+        #                         standard_sql: true
+        #
+        #   data.each do |row|
+        #     puts row["name"]
+        #   end
+        #
+        # @example Query using positional query parameters:
+        #   require "google/cloud/bigquery"
+        #
+        #   bigquery = Google::Cloud::Bigquery.new
+        #
+        #   data = bigquery.query "SELECT name FROM my_table WHERE id = ?",
+        #                         params: [1]
+        #
+        #   data.each do |row|
+        #     puts row["name"]
+        #   end
+        #
+        # @example Query using named query parameters:
+        #   require "google/cloud/bigquery"
+        #
+        #   bigquery = Google::Cloud::Bigquery.new
+        #
+        #   data = bigquery.query "SELECT name FROM my_table WHERE id = @id",
+        #                         params: { id: 1 }
+        #
         #   data.each do |row|
         #     puts row["name"]
         #   end
         #
         # @!group Data
         #
-        def query query, max: nil, timeout: 10000, dryrun: nil, cache: true
-          options = { max: max, timeout: timeout, dryrun: dryrun, cache: cache }
+        def query query, params: nil, max: nil, timeout: 10000, dryrun: nil,
+                  cache: true, legacy_sql: nil, standard_sql: nil
+          options = { max: max, timeout: timeout, dryrun: dryrun, cache: cache,
+                      legacy_sql: legacy_sql, standard_sql: standard_sql,
+                      params: params }
           options[:dataset] ||= dataset_id
           options[:project] ||= project_id
           ensure_service!

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

@@ -126,7 +126,7 @@ module Google
         ##
         # The time when the job was created.
         def created_at
-          Time.at(Integer(@gapi.statistics.creation_time) / 1000.0)
+          ::Time.at(Integer(@gapi.statistics.creation_time) / 1000.0)
         rescue
           nil
         end
@@ -136,7 +136,7 @@ module Google
         # This field is present after the job's state changes from `PENDING`
         # to either `RUNNING` or `DONE`.
         def started_at
-          Time.at(Integer(@gapi.statistics.start_time) / 1000.0)
+          ::Time.at(Integer(@gapi.statistics.start_time) / 1000.0)
         rescue
           nil
         end
@@ -145,7 +145,7 @@ module Google
         # The time when the job ended.
         # This field is present when the job's state is `DONE`.
         def ended_at
-          Time.at(Integer(@gapi.statistics.end_time) / 1000.0)
+          ::Time.at(Integer(@gapi.statistics.end_time) / 1000.0)
         rescue
           nil
         end

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

@@ -21,6 +21,7 @@ require "google/cloud/bigquery/dataset"
 require "google/cloud/bigquery/job"
 require "google/cloud/bigquery/query_data"
 require "google/cloud/bigquery/project/list"
+require "google/cloud/bigquery/time"
 
 module Google
   module Cloud
@@ -72,11 +73,11 @@ module Google
         #   require "google/cloud/bigquery"
         #
         #   bigquery = Google::Cloud::Bigquery.new(
-        #     project: "my-todo-project",
+        #     project: "my-project-id",
         #     keyfile: "/path/to/keyfile.json"
         #   )
         #
-        #   bigquery.project #=> "my-todo-project"
+        #   bigquery.project #=> "my-project-id"
         #
         def project
           service.project
@@ -95,10 +96,37 @@ module Google
         # Queries data using the [asynchronous
         # method](https://cloud.google.com/bigquery/querying-data).
         #
+        # When using standard SQL and passing arguments using `params`, Ruby
+        # types are mapped to BigQuery types as follows:
+        #
+        # | BigQuery    | Ruby           | Notes  |
+        # |-------------|----------------|---|
+        # | `BOOL`      | `true`/`false` | |
+        # | `INT64`     | `Integer`      | |
+        # | `FLOAT64`   | `Float`        | |
+        # | `STRING`    | `STRING`       | |
+        # | `DATETIME`  | `DateTime`  | `DATETIME` does not support time zone. |
+        # | `DATE`      | `Date`         | |
+        # | `TIMESTAMP` | `Time`         | |
+        # | `TIME`      | `Google::Cloud::BigQuery::Time` | |
+        # | `BYTES`     | `File`, `IO`, `StringIO`, or similar | |
+        # | `ARRAY` | `Array` | Nested arrays, `nil` values are not supported. |
+        # | `STRUCT`    | `Hash`        | Hash keys may be strings or symbols. |
+        #
+        # See [Data Types](https://cloud.google.com/bigquery/docs/reference/standard-sql/data-types)
+        # for an overview of each BigQuery data type, including allowed values.
+        #
         # @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 [Array, Hash] params Standard SQL only. Used to pass query
+        #   arguments when the `query` string contains either positional (`?`)
+        #   or named (`@myparam`) query parameters. If value passed is an array
+        #   `["foo"]`, the query must use positional query parameters. If value
+        #   passed is a hash `{ myparam: "foo" }`, the query must use named
+        #   query parameters. When set, `legacy_sql` will automatically be set
+        #   to false and `standard_sql` to true.
         # @param [String] priority Specifies a priority for the query. Possible
         #   values include `INTERACTIVE` and `BATCH`. The default value is
         #   `INTERACTIVE`.
@@ -135,6 +163,25 @@ module Google
         #   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.
+        # @param [Boolean] legacy_sql Specifies whether to use BigQuery's
+        #   [legacy
+        #   SQL](https://cloud.google.com/bigquery/docs/reference/legacy-sql)
+        #   dialect for this query. If set to false, the query will use
+        #   BigQuery's [standard
+        #   SQL](https://cloud.google.com/bigquery/docs/reference/standard-sql/)
+        #   When set to false, the values of `large_results` and `flatten` are
+        #   ignored; the query will be run as if `large_results` is true and
+        #   `flatten` is false. Optional. The default value is true.
+        # @param [Boolean] standard_sql Specifies whether to use BigQuery's
+        #   [standard
+        #   SQL](https://cloud.google.com/bigquery/docs/reference/standard-sql/)
+        #   dialect for this query. If set to true, the query will use standard
+        #   SQL rather than the [legacy
+        #   SQL](https://cloud.google.com/bigquery/docs/reference/legacy-sql)
+        #   dialect. When set to true, the values of `large_results` and
+        #   `flatten` are ignored; the query will be run as if `large_results`
+        #   is true and `flatten` is false. Optional. The default value is
+        #   false.
         #
         # @return [Google::Cloud::Bigquery::QueryJob]
         #
@@ -153,14 +200,66 @@ module Google
         #     end
         #   end
         #
-        def query_job query, priority: "INTERACTIVE", cache: true, table: nil,
-                      create: nil, write: nil, large_results: nil, flatten: nil,
-                      dataset: nil
+        # @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`",
+        #                            standard_sql: true
+        #
+        #   job.wait_until_done!
+        #   if !job.failed?
+        #     job.query_results.each do |row|
+        #       puts row["name"]
+        #     end
+        #   end
+        #
+        # @example Query using positional query parameters:
+        #   require "google/cloud/bigquery"
+        #
+        #   bigquery = Google::Cloud::Bigquery.new
+        #
+        #   job = bigquery.query_job "SELECT name FROM " \
+        #                            "`my_proj.my_data.my_table`" \
+        #                            " WHERE id = ?",
+        #                            params: [1]
+        #
+        #   job.wait_until_done!
+        #   if !job.failed?
+        #     job.query_results.each do |row|
+        #       puts row["name"]
+        #     end
+        #   end
+        #
+        # @example Query using named query parameters:
+        #   require "google/cloud/bigquery"
+        #
+        #   bigquery = Google::Cloud::Bigquery.new
+        #
+        #   job = bigquery.query_job "SELECT name FROM " \
+        #                            "`my_proj.my_data.my_table`" \
+        #                            " WHERE id = @id",
+        #                            params: { id: 1 }
+        #
+        #   job.wait_until_done!
+        #   if !job.failed?
+        #     job.query_results.each do |row|
+        #       puts row["name"]
+        #     end
+        #   end
+        #
+        def query_job query, params: nil, priority: "INTERACTIVE", cache: true,
+                      table: nil, create: nil, write: nil, large_results: nil,
+                      flatten: nil, dataset: nil, legacy_sql: nil,
+                      standard_sql: nil
           ensure_service!
           options = { priority: priority, cache: cache, table: table,
                       create: create, write: write,
                       large_results: large_results, flatten: flatten,
-                      dataset: dataset }
+                      dataset: dataset, legacy_sql: legacy_sql,
+                      standard_sql: standard_sql, params: params }
           gapi = service.query_job query, options
           Job.from_gapi gapi, service
         end
@@ -169,10 +268,37 @@ module Google
         # Queries data using the [synchronous
         # method](https://cloud.google.com/bigquery/querying-data).
         #
+        # When using standard SQL and passing arguments using `params`, Ruby
+        # types are mapped to BigQuery types as follows:
+        #
+        # | BigQuery    | Ruby           | Notes  |
+        # |-------------|----------------|---|
+        # | `BOOL`      | `true`/`false` | |
+        # | `INT64`     | `Integer`      | |
+        # | `FLOAT64`   | `Float`        | |
+        # | `STRING`    | `STRING`       | |
+        # | `DATETIME`  | `DateTime`  | `DATETIME` does not support time zone. |
+        # | `DATE`      | `Date`         | |
+        # | `TIMESTAMP` | `Time`         | |
+        # | `TIME`      | `Google::Cloud::BigQuery::Time` | |
+        # | `BYTES`     | `File`, `IO`, `StringIO`, or similar | |
+        # | `ARRAY` | `Array` | Nested arrays, `nil` values are not supported. |
+        # | `STRUCT`    | `Hash`        | Hash keys may be strings or symbols. |
+        #
+        # See [Data Types](https://cloud.google.com/bigquery/docs/reference/standard-sql/data-types)
+        # for an overview of each BigQuery data type, including allowed values.
+        #
         # @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 [Array, Hash] params Standard SQL only. Used to pass query
+        #   arguments when the `query` string contains either positional (`?`)
+        #   or named (`@myparam`) query parameters. If value passed is an array
+        #   `["foo"]`, the query must use positional query parameters. If value
+        #   passed is a hash `{ myparam: "foo" }`, the query must use named
+        #   query parameters. When set, `legacy_sql` will automatically be set
+        #   to false and `standard_sql` to true.
         # @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
@@ -201,6 +327,25 @@ module Google
         # @param [String] project Specifies the default projectId to assume for
         #   any unqualified table names in the query. Only used if `dataset`
         #   option is set.
+        # @param [Boolean] legacy_sql Specifies whether to use BigQuery's
+        #   [legacy
+        #   SQL](https://cloud.google.com/bigquery/docs/reference/legacy-sql)
+        #   dialect for this query. If set to false, the query will use
+        #   BigQuery's [standard
+        #   SQL](https://cloud.google.com/bigquery/docs/reference/standard-sql/)
+        #   When set to false, the values of `large_results` and `flatten` are
+        #   ignored; the query will be run as if `large_results` is true and
+        #   `flatten` is false. Optional. The default value is true.
+        # @param [Boolean] standard_sql Specifies whether to use BigQuery's
+        #   [standard
+        #   SQL](https://cloud.google.com/bigquery/docs/reference/standard-sql/)
+        #   dialect for this query. If set to true, the query will use standard
+        #   SQL rather than the [legacy
+        #   SQL](https://cloud.google.com/bigquery/docs/reference/legacy-sql)
+        #   dialect. When set to true, the values of `large_results` and
+        #   `flatten` are ignored; the query will be run as if `large_results`
+        #   is true and `flatten` is false. Optional. The default value is
+        #   false.
         #
         # @return [Google::Cloud::Bigquery::QueryData]
         #
@@ -210,6 +355,19 @@ module Google
         #   bigquery = Google::Cloud::Bigquery.new
         #
         #   data = bigquery.query "SELECT name FROM [my_proj:my_data.my_table]"
+        #
+        #   data.each do |row|
+        #     puts row["name"]
+        #   end
+        #
+        # @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`",
+        #                         standard_sql: true
+        #
         #   data.each do |row|
         #     puts row["name"]
         #   end
@@ -220,15 +378,47 @@ module Google
         #   bigquery = Google::Cloud::Bigquery.new
         #
         #   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
+        # @example Query using positional query parameters:
+        #   require "google/cloud/bigquery"
+        #
+        #   bigquery = Google::Cloud::Bigquery.new
+        #
+        #   data = bigquery.query "SELECT name " \
+        #                         "FROM [my_proj:my_data.my_table]" \
+        #                         "WHERE id = ?",
+        #                         params: [1]
+        #
+        #   data.each do |row|
+        #     puts row["name"]
+        #   end
+        #
+        # @example Query using named query parameters:
+        #   require "google/cloud/bigquery"
+        #
+        #   bigquery = Google::Cloud::Bigquery.new
+        #
+        #   data = bigquery.query "SELECT name " \
+        #                         "FROM [my_proj:my_data.my_table]" \
+        #                         "WHERE id = @id",
+        #                         params: { id: 1 }
+        #
+        #   data.each do |row|
+        #     puts row["name"]
+        #   end
+        #
+        def query query, params: nil, max: nil, timeout: 10000, dryrun: nil,
+                  cache: true, dataset: nil, project: nil, legacy_sql: nil,
+                  standard_sql: nil
           ensure_service!
           options = { max: max, timeout: timeout, dryrun: dryrun, cache: cache,
-                      dataset: dataset, project: project }
+                      dataset: dataset, project: project,
+                      legacy_sql: legacy_sql, standard_sql: standard_sql,
+                      params: params }
           gapi = service.query query, options
           QueryData.from_gapi gapi, service
         end
@@ -273,7 +463,8 @@ module Google
         #   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
+        # @yieldparam [Google::Cloud::Bigquery::Dataset] access the object
+        #   accepting rules
         #
         # @return [Google::Cloud::Bigquery::Dataset]
         #
@@ -293,21 +484,13 @@ module Google
         #                                     name: "My Dataset",
         #                                     description: "This is my Dataset"
         #
-        # @example Access rules can be provided with the `access` option:
-        #   require "google/cloud/bigquery"
-        #
-        #   bigquery = Google::Cloud::Bigquery.new
-        #
-        #   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/bigquery"
         #
         #   bigquery = Google::Cloud::Bigquery.new
         #
-        #   dataset = bigquery.create_dataset "my_dataset" do |access|
-        #     access.add_writer_user "writers@example.com"
+        #   dataset = bigquery.create_dataset "my_dataset" do |table|
+        #     table.access.add_writer_user "writers@example.com"
         #   end
         #
         def create_dataset dataset_id, name: nil, description: nil,
@@ -509,6 +692,51 @@ module Google
           Project::List.from_gapi gapi, service, max
         end
 
+        ##
+        # Creates a Bigquery::Time object to represent a time, independent of a
+        # specific date.
+        #
+        # @param [Integer] hour Hour, valid values from 0 to 23.
+        # @param [Integer] minute Minute, valid values from 0 to 59.
+        # @param [Integer, Float] second Second, valid values from 0 to 59. Can
+        #   contain microsecond precision.
+        #
+        # @return [Bigquery::Time]
+        #
+        # @example
+        #   require "google/cloud/bigquery"
+        #
+        #   bigquery = Google::Cloud::Bigquery.new
+        #
+        #   fourpm = bigquery.time 16, 0, 0
+        #   data = bigquery.query "SELECT name " \
+        #                         "FROM [my_proj:my_data.my_table]" \
+        #                         "WHERE time_of_date = @time",
+        #                         params: { time: fourpm }
+        #
+        #   data.each do |row|
+        #     puts row["name"]
+        #   end
+        #
+        # @example Create Time with fractional seconds:
+        #   require "google/cloud/bigquery"
+        #
+        #   bigquery = Google::Cloud::Bigquery.new
+        #
+        #   precise_time = bigquery.time 16, 35, 15.376541
+        #   data = bigquery.query "SELECT name " \
+        #                         "FROM [my_proj:my_data.my_table]" \
+        #                         "WHERE time_of_date >= @time",
+        #                         params: { time: precise_time }
+        #
+        #   data.each do |row|
+        #     puts row["name"]
+        #   end
+        #
+        def time hour, minute, second
+          Bigquery::Time.new "#{hour}:#{minute}:#{second}"
+        end
+
         ##
         # @private New Project from a Google API Client object, using the
         # same Credentials as this project.