Add DATETIME, TIME, and BYTES query parameters

README.md

@@ -53,7 +53,7 @@ The preview examples below demonstrate how to provide the **Project ID** and **C
 - [google-cloud-bigquery README](google-cloud-bigquery/README.md)
 - [google-cloud-bigquery API documentation](http://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud-bigquery/master/google/cloud/bigquery)
 - [google-cloud-bigquery on RubyGems](https://rubygems.org/gems/google-cloud-bigquery)
-- [Google Cloud BigQuery documentation](https://cloud.google.com/bigquery/docs)
+- [Google BigQuery documentation](https://cloud.google.com/bigquery/docs)
 
 #### Quick Start
 

google-cloud-bigquery/CHANGELOG.md

@@ -14,7 +14,7 @@
 
 ### 0.20.0 / 2016-08-26
 
-This gem contains the Google Cloud BigQuery service implementation for the `google-cloud` gem. The `google-cloud` gem replaces the old `gcloud` gem. Legacy code can continue to use the `gcloud` gem.
+This gem contains the Google BigQuery service implementation for the `google-cloud` gem. The `google-cloud` gem replaces the old `gcloud` gem. Legacy code can continue to use the `gcloud` gem.
 
 * Namespace is now `Google::Cloud`
 * The `google-cloud` gem is now an umbrella package for individual gems

google-cloud-bigquery/README.md

@@ -1,10 +1,10 @@
 # google-cloud-bigquery
 
-[Google Cloud 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 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 on RubyGems](https://rubygems.org/gems/google-cloud-bigquery)
-- [Google Cloud BigQuery documentation](https://cloud.google.com/bigquery/docs)
+- [Google BigQuery documentation](https://cloud.google.com/bigquery/docs)
 
 ## Quick Start
 

google-cloud-bigquery/acceptance/bigquery/named_params_test.rb

@@ -47,13 +47,25 @@
     skip "Don't know of any sample data that uses DATE values"
   end
 
-  it "queries the data with a time parameter" do
+  it "queries the data with a datetime parameter" do
+    skip "Don't know of any sample data that uses DATETIME values"
+  end
+
+  it "queries the data with a timestamp parameter" do
     rows = bigquery.query "SELECT subject FROM `bigquery-public-data.github_repos.commits` WHERE author.name = @author AND author.date < @date LIMIT 1", params: { author: "blowmage", date: Time.now }
 
     rows.class.must_equal Google::Cloud::Bigquery::QueryData
     rows.count.must_equal 1
   end
 
+  it "queries the data with a time parameter" do
+    skip "Don't know of any sample data that uses TIME values"
+  end
+
+  it "queries the data with a bytes parameter" do
+    skip "Don't know of any sample data that uses BYTES values"
+  end
+
   it "queries the data with an array parameter" do
     rows = bigquery.query "SELECT * FROM UNNEST (@list)", params: { list: [25,26,27,28,29] }
 

google-cloud-bigquery/acceptance/bigquery/positional_params_test.rb

@@ -47,13 +47,25 @@
     skip "Don't know of any sample data that uses DATE values"
   end
 
-  it "queries the data with a time parameter" do
+  it "queries the data with a datetime parameter" do
+    skip "Don't know of any sample data that uses DATETIME values"
+  end
+
+  it "queries the data with a timestamp parameter" do
     rows = bigquery.query "SELECT subject FROM `bigquery-public-data.github_repos.commits` WHERE author.name = ? AND author.date < ? LIMIT 1", params: ["blowmage", Time.now]
 
     rows.class.must_equal Google::Cloud::Bigquery::QueryData
     rows.count.must_equal 1
   end
 
+  it "queries the data with a time parameter" do
+    skip "Don't know of any sample data that uses TIME values"
+  end
+
+  it "queries the data with a bytes parameter" do
+    skip "Don't know of any sample data that uses BYTES values"
+  end
+
   it "queries the data with an array parameter" do
     rows = bigquery.query "SELECT * FROM UNNEST (?)", params: [[25,26,27,28,29]]
 

google-cloud-bigquery/lib/google/cloud/bigquery.rb

@@ -21,7 +21,7 @@ module Cloud
     ##
     # # Google Cloud BigQuery
     #
-    # Google Cloud BigQuery enables super-fast, SQL-like queries against massive
+    # Google BigQuery enables super-fast, SQL-like queries against massive
     # datasets, using the processing power of Google's infrastructure. To learn
     # more, read [What is
     # BigQuery?](https://cloud.google.com/bigquery/what-is-bigquery).
@@ -152,7 +152,7 @@ module Cloud
     #
     # Notice that in standard SQL, the format for a fully-qualified table name
     # uses back-ticks instead of brackets, and a dot instead of a semi-colon:
-    # ``my-dashed-project.dataset1.tableName``.
+    # <code>`my-dashed-project.dataset1.tableName`</code>.
     #
     # #### Query parameters
     #
@@ -173,6 +173,30 @@ module Cloud
     # As demonstrated above, passing the `params` option will automatically set
     # `standard_sql` to `true`.
     #
+    # #### Data types
+    #
+    # BigQuery standard SQL supports simple data types such as integers, as well
+    # as more complex types such as `ARRAY` and `STRUCT`.
+    #
+    # The BigQuery data types are converted to and from Ruby 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 and `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.
+    #
     # ### Synchronous queries
     #
     # Let's start with the simpler synchronous approach. Notice that this time

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

@@ -179,7 +179,7 @@ def default_expiration= new_default_expiration
         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 @@ def created_at
         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
@@ -520,6 +520,26 @@ def tables token: nil, max: nil
         # 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
@@ -669,6 +689,26 @@ def query_job query, params: nil, priority: "INTERACTIVE", cache: true,
         # 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

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

@@ -126,7 +126,7 @@ def failed?
         ##
         # 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 @@ def created_at
         # 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 @@ def started_at
         # 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

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

@@ -21,6 +21,7 @@
 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
@@ -95,6 +96,26 @@ def self.default_project
         # 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
@@ -247,6 +268,26 @@ def query_job query, params: nil, priority: "INTERACTIVE", cache: true,
         # 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
@@ -651,6 +692,51 @@ def projects token: nil, max: nil
           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.

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

@@ -19,6 +19,7 @@
 require "pathname"
 require "digest/md5"
 require "mime/types"
+require "date"
 
 module Google
   module Cloud
@@ -492,17 +493,34 @@ def to_query_param value
               parameter_type:  API::QueryParameterType.new(type: "STRING"),
               parameter_value: API::QueryParameterValue.new(value: value)
             )
-          elsif defined?(Date) && Date === value
+          elsif DateTime === value
+            return API::QueryParameter.new(
+              parameter_type:  API::QueryParameterType.new(type: "DATETIME"),
+              parameter_value: API::QueryParameterValue.new(
+                value: value.strftime("%Y-%m-%d %H:%M:%S.%6N"))
+            )
+          elsif Date === value
             return API::QueryParameter.new(
               parameter_type:  API::QueryParameterType.new(type: "DATE"),
               parameter_value: API::QueryParameterValue.new(value: value.to_s)
             )
-          # ActiveSupport adds to_time to String, which is awful...
-          elsif value.respond_to? :to_time
+          elsif ::Time === value
             return API::QueryParameter.new(
               parameter_type:  API::QueryParameterType.new(type: "TIMESTAMP"),
               parameter_value: API::QueryParameterValue.new(
-                value: value.to_time.strftime("%Y-%m-%d %H:%M:%S.%3N%:z"))
+                value: value.strftime("%Y-%m-%d %H:%M:%S.%6N%:z"))
+            )
+          elsif Bigquery::Time === value
+            return API::QueryParameter.new(
+              parameter_type:  API::QueryParameterType.new(type: "TIME"),
+              parameter_value: API::QueryParameterValue.new(value: value.value)
+            )
+          elsif value.respond_to?(:read) && value.respond_to?(:rewind)
+            value.rewind
+            return API::QueryParameter.new(
+              parameter_type:  API::QueryParameterType.new(type: "BYTES"),
+              parameter_value: API::QueryParameterValue.new(
+                value: value.read.force_encoding("ASCII-8BIT"))
             )
           elsif Array === value
             array_params = value.map { |param| to_query_param param }