google-cloud-bigquery 1.4.0 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0e5f8cd4bec22402de2b7233c3c4ba9a7d92ff7fc84ee370387412377b32c94e
-  data.tar.gz: 2e102a74a171421dcb0115edd647e32d84bb603cf5c15cc90198028346d7a6f4
+  metadata.gz: af9dff48b04ef98b37b45d821fe7ea4689466762b0bd444428d4247c17265395
+  data.tar.gz: 284d6bf810306ef9afa8f1f369582dd88d85e754ac421955a6fe3065da1bc709
 SHA512:
-  metadata.gz: ff7105818d9ea95100fb85f64b6158a812c46875f7486c1aa159fc7cd1e53f3a466bc7fc74ae75c08a6a67e2afd97d5ac26f584a179ac4882ab5c9b03ca3abb2
-  data.tar.gz: d4d657b44eca87899820b86a001cda2bd60314e9f91e5601af6dba29b91aa651ce2584c4dcb6d9d9cd23be644c0bab8584d8145ec1802748f53275bbcc3819d1
+  metadata.gz: ae89b1e2cd62e4f76008601da97974ddf4fa866a05496a36b86d0a4d9124d470a1fbf6a1c374bcb704598cc1846cd251b68daa0a0d160bc6265094fd56071354
+  data.tar.gz: c2bdf1ee119196601002148ffa4ad3633b61224eebe677bd6c39873e9280dcca2a81ae89b5289d868bad7f242e7ade92071baf85e8bde8ea9bdaee7bc64b649f

data/README.md

@@ -47,6 +47,24 @@ data.each do |row|
 end
 ```
 
+## Enabling Logging
+
+To enable logging for this library, set the logger for the underlying [Google API Client](https://github.com/google/google-api-ruby-client/blob/master/README.md#logging) library. The logger that you set may be a Ruby stdlib [`Logger`](https://ruby-doc.org/stdlib-2.4.0/libdoc/logger/rdoc/Logger.html) as shown below, or a [`Google::Cloud::Logging::Logger`](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud-logging/latest/google/cloud/logging/logger) that will write logs to [Stackdriver Logging](https://cloud.google.com/logging/).
+
+If you do not set the logger explicitly and your application is running in a Rails environment, it will default to `Rails.logger`. Otherwise, if you do not set the logger and you are not using Rails, logging is disabled by default.
+
+Configuring a Ruby stdlib logger:
+
+```ruby
+require "logger"
+
+my_logger = Logger.new $stderr
+my_logger.level = Logger::WARN
+
+# Set the Google API Client logger
+Google::Apis.logger = my_logger
+```
+
 ## Supported Ruby Versions
 
 This library is supported on Ruby 2.0+.

data/lib/google/cloud/bigquery.rb

@@ -44,6 +44,34 @@ module Google
     # run these first examples without the need to set up billing or to load
     # data (although we'll show you how to do that too.)
     #
+    # ## Enabling Logging
+    #
+    # To enable logging for this library, set the logger for the underlying
+    # [Google API Client](https://github.com/google/google-api-ruby-client/blob/master/README.md#logging)
+    # library. The logger that you set may be a Ruby stdlib
+    # [`Logger`](https://ruby-doc.org/stdlib-2.4.0/libdoc/logger/rdoc/Logger.html)
+    # as shown below, or a
+    # [`Google::Cloud::Logging::Logger`](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud-logging/latest/google/cloud/logging/logger)
+    # that will write logs to [Stackdriver
+    # Logging](https://cloud.google.com/logging/).
+    #
+    # If you do not set the logger explicitly and your application is running in
+    # a Rails environment, it will default to `Rails.logger`. Otherwise, if you
+    # do not set the logger and you are not using Rails, logging is disabled by
+    # default.
+    #
+    # Configuring a Ruby stdlib logger:
+    #
+    # ```ruby
+    # require "logger"
+    #
+    # my_logger = Logger.new $stderr
+    # my_logger.level = Logger::WARN
+    #
+    # # Set the Google API Client logger
+    # Google::Apis.logger = my_logger
+    # ```
+    #
     # ## Listing Datasets and Tables
     #
     # A BigQuery project contains datasets, which in turn contain tables.
@@ -186,7 +214,8 @@ module Google
     # | `BOOL`      | `true`/`false` | |
     # | `INT64`     | `Integer`      | |
     # | `FLOAT64`   | `Float`        | |
-    # | `STRING`    | `STRING`       | |
+    # | `NUMERIC`   | `BigDecimal`   | Will be rounded to 9 decimal places |
+    # | `STRING`    | `String`       | |
     # | `DATETIME`  | `DateTime`     | `DATETIME` does not support time zone. |
     # | `DATE`      | `Date`         | |
     # | `TIMESTAMP` | `Time`         | |

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

@@ -16,6 +16,7 @@
 require "google/apis/bigquery_v2"
 require "stringio"
 require "base64"
+require "bigdecimal"
 require "time"
 require "date"
 
@@ -34,7 +35,8 @@ module Google
       # | `BOOL`      | `true`/`false` | |
       # | `INT64`     | `Integer`      | |
       # | `FLOAT64`   | `Float`        | |
-      # | `STRING`    | `STRING`       | |
+      # | `NUMERIC`   | `BigDecimal`   | Will be rounded to 9 decimal places |
+      # | `STRING`    | `String`       | |
       # | `DATETIME`  | `DateTime`  | `DATETIME` does not support time zone. |
       # | `DATE`      | `Date`         | |
       # | `TIMESTAMP` | `Time`         | |
@@ -84,6 +86,8 @@ module Google
             Integer value[:v]
           elsif field.type == "FLOAT"
             Float value[:v]
+          elsif field.type == "NUMERIC"
+            BigDecimal value[:v]
           elsif field.type == "BOOLEAN"
             (value[:v] == "true" ? true : (value[:v] == "false" ? false : nil))
           elsif field.type == "BYTES"
@@ -132,6 +136,15 @@ module Google
               parameter_value: Google::Apis::BigqueryV2::QueryParameterValue.new(
                 value: value)
             )
+          elsif BigDecimal === value
+            # Round to precision of 9
+            value_str = value.finite? ? value.round(9).to_s("F") : value.to_s
+            return Google::Apis::BigqueryV2::QueryParameter.new(
+              parameter_type:  Google::Apis::BigqueryV2::QueryParameterType.new(
+                type: "NUMERIC"),
+              parameter_value: Google::Apis::BigqueryV2::QueryParameterValue.new(
+                value: value_str)
+            )
           elsif String === value
             return Google::Apis::BigqueryV2::QueryParameter.new(
               parameter_type:  Google::Apis::BigqueryV2::QueryParameterType.new(

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

@@ -686,7 +686,8 @@ module Google
         # | `BOOL`      | `true`/`false` | |
         # | `INT64`     | `Integer`      | |
         # | `FLOAT64`   | `Float`        | |
-        # | `STRING`    | `STRING`       | |
+        # | `NUMERIC`   | `BigDecimal`   | Will be rounded to 9 decimal places |
+        # | `STRING`    | `String`       | |
         # | `DATETIME`  | `DateTime`  | `DATETIME` does not support time zone. |
         # | `DATE`      | `Date`         | |
         # | `TIMESTAMP` | `Time`         | |
@@ -942,7 +943,8 @@ module Google
         # | `BOOL`      | `true`/`false` | |
         # | `INT64`     | `Integer`      | |
         # | `FLOAT64`   | `Float`        | |
-        # | `STRING`    | `STRING`       | |
+        # | `NUMERIC`   | `BigDecimal`   | Will be rounded to 9 decimal places |
+        # | `STRING`    | `String`       | |
         # | `DATETIME`  | `DateTime`  | `DATETIME` does not support time zone. |
         # | `DATE`      | `Date`         | |
         # | `TIMESTAMP` | `Time`         | |

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

@@ -107,7 +107,8 @@ module Google
         # | `BOOL`      | `true`/`false` | |
         # | `INT64`     | `Integer`      | |
         # | `FLOAT64`   | `Float`        | |
-        # | `STRING`    | `STRING`       | |
+        # | `NUMERIC`   | `BigDecimal`   | Will be rounded to 9 decimal places |
+        # | `STRING`    | `String`       | |
         # | `DATETIME`  | `DateTime`  | `DATETIME` does not support time zone. |
         # | `DATE`      | `Date`         | |
         # | `TIMESTAMP` | `Time`         | |
@@ -365,7 +366,8 @@ module Google
         # | `BOOL`      | `true`/`false` | |
         # | `INT64`     | `Integer`      | |
         # | `FLOAT64`   | `Float`        | |
-        # | `STRING`    | `STRING`       | |
+        # | `NUMERIC`   | `BigDecimal`   | Will be rounded to 9 decimal places |
+        # | `STRING`    | `String`       | |
         # | `DATETIME`  | `DateTime`  | `DATETIME` does not support time zone. |
         # | `DATE`      | `Date`         | |
         # | `TIMESTAMP` | `Time`         | |

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

@@ -14,6 +14,7 @@
 
 
 require "google/cloud/bigquery/schema/field"
+require "json"
 
 module Google
   module Cloud
@@ -44,6 +45,67 @@ module Google
       #   end
       #
       class Schema
+        class << self
+          ##
+          # Load a schema from a JSON file.
+          #
+          # The JSON schema file is the same as for the [`bq`
+          # CLI](https://cloud.google.com/bigquery/docs/schemas#specifying_a_json_schema_file)
+          # consisting of an array of JSON objects containing the following:
+          # - `name`: The column [name](https://cloud.google.com/bigquery/docs/schemas#column_names)
+          # - `type`: The column's [data
+          #   type](https://cloud.google.com/bigquery/docs/schemas#standard_sql_data_types)
+          # - `description`: (Optional) The column's [description](https://cloud.google.com/bigquery/docs/schemas#column_descriptions)
+          # - `mode`: (Optional) The column's [mode](https://cloud.google.com/bigquery/docs/schemas#modes)
+          #   (if unspecified, mode defaults to `NULLABLE`)
+          # - `fields`: If `type` is `RECORD`, an array of objects defining
+          #   child fields with these properties
+          #
+          # @param [IO, String, Array<Hash>] source An `IO` containing the JSON
+          #   schema, a `String` containing the JSON schema, or an `Array` of
+          #   `Hash`es containing the schema details.
+          #
+          # @return [Schema] A schema.
+          #
+          # @example
+          #   require "google/cloud/bigquery"
+          #
+          #   schema = Google::Cloud::Bigquery::Schema.load(
+          #     File.read("schema.json")
+          #   )
+          #
+          def load source
+            new.load source
+          end
+
+          ##
+          # Write a schema as JSON to a file.
+          #
+          # The JSON schema file is the same as for the [`bq`
+          # CLI](https://cloud.google.com/bigquery/docs/schemas#specifying_a_json_schema_file).
+          #
+          # @param [IO, String] schema An `Google::Cloud::Bigquery::Schema`.
+          #
+          # @param [IO, String] destination An `IO` to which to write the
+          #   schema, or a `String` containing the filename to write to.
+          #
+          # @return [Schema] The schema so that commands are chainable.
+          #
+          # @example
+          #   require "google/cloud/bigquery"
+          #
+          #   bigquery = Google::Cloud::Bigquery.new
+          #   dataset = bigquery.dataset "my_dataset"
+          #   table = dataset.table "my_table"
+          #   schema = Google::Cloud::Bigquery::Schema.dump(
+          #     table.schema,
+          #     "schema.json"
+          #   )
+          #
+          def dump schema, destination
+            schema.dump destination
+          end
+        end
         ##
         # The fields of the table schema.
         #
@@ -123,6 +185,83 @@ module Google
           fields.empty?
         end
 
+        ##
+        # Load the schema from a JSON file.
+        #
+        # The JSON schema file is the same as for the [`bq`
+        # CLI](https://cloud.google.com/bigquery/docs/schemas#specifying_a_json_schema_file)
+        # consisting of an array of JSON objects containing the following:
+        # - `name`: The column [name](https://cloud.google.com/bigquery/docs/schemas#column_names)
+        # - `type`: The column's [data
+        #   type](https://cloud.google.com/bigquery/docs/schemas#standard_sql_data_types)
+        # - `description`: (Optional) The column's [description](https://cloud.google.com/bigquery/docs/schemas#column_descriptions)
+        # - `mode`: (Optional) The column's [mode](https://cloud.google.com/bigquery/docs/schemas#modes)
+        #   (if unspecified, mode defaults to `NULLABLE`)
+        # - `fields`: If `type` is `RECORD`, an array of objects defining child
+        #   fields with these properties
+        #
+        # @param [IO, String, Array<Hash>] source An `IO` containing the JSON
+        #   schema, a `String` containing the JSON schema, or an `Array` of
+        #   `Hash`es containing the schema details.
+        #
+        # @return [Schema] The schema so that commands are chainable.
+        #
+        # @example
+        #   require "google/cloud/bigquery"
+        #
+        #   bigquery = Google::Cloud::Bigquery.new
+        #   dataset = bigquery.dataset "my_dataset"
+        #   table = dataset.table "my_table" do |table|
+        #     table.schema.load File.read("path/to/schema.json")
+        #   end
+        #
+        def load source
+          if source.respond_to?(:rewind) && source.respond_to?(:read)
+            source.rewind
+            schema_json = String source.read
+          elsif source.is_a? Array
+            schema_json = JSON.dump source
+          else
+            schema_json = String source
+          end
+
+          schema_json = %({"fields":#{schema_json}})
+
+          @gapi = Google::Apis::BigqueryV2::TableSchema.from_json schema_json
+
+          self
+        end
+
+        ##
+        # Write the schema as JSON to a file.
+        #
+        # The JSON schema file is the same as for the [`bq`
+        # CLI](https://cloud.google.com/bigquery/docs/schemas#specifying_a_json_schema_file).
+        #
+        # @param [IO, String] destination An `IO` to which to write the schema,
+        #   or a `String` containing the filename to write to.
+        #
+        # @return [Schema] The schema so that commands are chainable.
+        #
+        # @example
+        #   require "google/cloud/bigquery"
+        #
+        #   bigquery = Google::Cloud::Bigquery.new
+        #   dataset = bigquery.dataset "my_dataset"
+        #   table = dataset.table "my_table"
+        #   table.schema.dump "schema.json"
+        #
+        def dump destination
+          if destination.respond_to?(:rewind) && destination.respond_to?(:write)
+            destination.rewind
+            destination.write JSON.dump(fields.map(&:to_hash))
+          else
+            File.write String(destination), JSON.dump(fields.map(&:to_hash))
+          end
+
+          self
+        end
+
         ##
         # Adds a string field to the schema.
         #
@@ -171,6 +310,24 @@ module Google
           add_field name, :float, description: description, mode: mode
         end
 
+        ##
+        # Adds a numeric number field to the schema. Numeric is a
+        # fixed-precision numeric type with 38 decimal digits, 9 that follow the
+        # decimal point.
+        #
+        # @param [String] name The field name. The name must contain only
+        #   letters (a-z, A-Z), numbers (0-9), or underscores (_), and must
+        #   start with a letter or underscore. The maximum length is 128
+        #   characters.
+        # @param [String] description A description of the field.
+        # @param [Symbol] mode The field's mode. The possible values are
+        #   `:nullable`, `:required`, and `:repeated`. The default value is
+        #   `:nullable`.
+        #
+        def numeric name, description: nil, mode: :nullable
+          add_field name, :numeric, description: description, mode: mode
+        end
+
         ##
         # Adds a boolean field to the schema.
         #

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

@@ -40,8 +40,8 @@ module Google
           MODES = %w[NULLABLE REQUIRED REPEATED].freeze
 
           # @private
-          TYPES = %w[STRING INTEGER INT64 FLOAT FLOAT64 BOOLEAN BOOL BYTES
-                     TIMESTAMP TIME DATETIME DATE RECORD STRUCT].freeze
+          TYPES = %w[STRING INTEGER INT64 FLOAT FLOAT64 NUMERIC BOOLEAN BOOL
+                     BYTES TIMESTAMP TIME DATETIME DATE RECORD STRUCT].freeze
 
           ##
           # The name of the field.
@@ -72,10 +72,10 @@ module Google
           #
           # @return [String] The field data type. Possible values include
           #   `STRING`, `BYTES`, `INTEGER`, `INT64` (same as `INTEGER`),
-          #   `FLOAT`, `FLOAT64` (same as `FLOAT`), `BOOLEAN`, `BOOL` (same as
-          #   `BOOLEAN`), `TIMESTAMP`, `DATE`, `TIME`, `DATETIME`, `RECORD`
-          #   (where `RECORD` indicates that the field contains a nested schema)
-          #   or `STRUCT` (same as `RECORD`).
+          #   `FLOAT`, `FLOAT64` (same as `FLOAT`), `NUMERIC`, `BOOLEAN`, `BOOL`
+          #   (same as `BOOLEAN`), `TIMESTAMP`, `DATE`, `TIME`, `DATETIME`,
+          #   `RECORD` (where `RECORD` indicates that the field contains a
+          #   nested schema) or `STRUCT` (same as `RECORD`).
           #
           def type
             @gapi.type
@@ -86,10 +86,10 @@ module Google
           #
           # @param [String] new_type The data type. Possible values include
           #   `STRING`, `BYTES`, `INTEGER`, `INT64` (same as `INTEGER`),
-          #   `FLOAT`, `FLOAT64` (same as `FLOAT`), `BOOLEAN`, `BOOL` (same as
-          #   `BOOLEAN`), `TIMESTAMP`, `DATE`, `TIME`, `DATETIME`, `RECORD`
-          #   (where `RECORD` indicates that the field contains a nested schema)
-          #   or `STRUCT` (same as `RECORD`).
+          #   `FLOAT`, `FLOAT64` (same as `FLOAT`), `NUMERIC`, `BOOLEAN`, `BOOL`
+          #   (same as `BOOLEAN`), `TIMESTAMP`, `DATE`, `TIME`, `DATETIME`,
+          #   `RECORD` (where `RECORD` indicates that the field contains a
+          #   nested schema) or `STRUCT` (same as `RECORD`).
           #
           def type= new_type
             @gapi.update! type: verify_type(new_type)
@@ -190,6 +190,15 @@ module Google
             type == "FLOAT" || type == "FLOAT64"
           end
 
+          ##
+          # Checks if the type of the field is `NUMERIC`.
+          #
+          # @return [Boolean] `true` when `NUMERIC`, `false` otherwise.
+          #
+          def numeric?
+            type == "NUMERIC"
+          end
+
           ##
           # Checks if the type of the field is `BOOLEAN`.
           #
@@ -353,6 +362,28 @@ module Google
             add_field name, :float, description: description, mode: mode
           end
 
+          ##
+          # Adds a numeric number field to the schema. Numeric is a
+          # fixed-precision numeric type with 38 decimal digits, 9 that follow
+          # the decimal point.
+          #
+          # This can only be called on fields that are of type `RECORD`.
+          #
+          # @param [String] name The field name. The name must contain only
+          #   letters (a-z, A-Z), numbers (0-9), or underscores (_), and must
+          #   start with a letter or underscore. The maximum length is 128
+          #   characters.
+          # @param [String] description A description of the field.
+          # @param [Symbol] mode The field's mode. The possible values are
+          #   `:nullable`, `:required`, and `:repeated`. The default value is
+          #   `:nullable`.
+          #
+          def numeric name, description: nil, mode: :nullable
+            record_check!
+
+            add_field name, :numeric, description: description, mode: mode
+          end
+
           ##
           # Adds a boolean field to the nested schema of a record field.
           #
@@ -542,6 +573,18 @@ module Google
             to_gapi.to_h == other.to_gapi.to_h
           end
 
+          # @private
+          def to_hash
+            h = {
+              name: name,
+              type: type,
+              mode: mode
+            }
+            h[:description] = description if description
+            h[:fields] = fields.map(&:to_hash) if record?
+            h
+          end
+
           protected
 
           def frozen_check!

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

@@ -700,6 +700,11 @@ module Google
         #   schema. If `false`, the fields will be added to the existing schema.
         #   When a table already contains data, schema changes must be additive.
         #   Thus, the default value is `false`.
+        #   When loading from a file this will always replace the schema, no
+        #   matter what `replace` is set to. You can update the schema (for
+        #   example, for a table that already contains data) by providing a
+        #   schema file that includes the existing schema plus any new
+        #   fields.
         # @yield [schema] a block for setting the schema
         # @yieldparam [Schema] schema the object accepting the schema
         #
@@ -720,6 +725,16 @@ module Google
         #     end
         #   end
         #
+        # @example Load the schema from a file
+        #   require "google/cloud/bigquery"
+        #
+        #   bigquery = Google::Cloud::Bigquery.new
+        #   dataset = bigquery.dataset "my_dataset"
+        #   table = dataset.create_table "my_table"
+        #   table.schema do |schema|
+        #     schema.load File.open("schema.json")
+        #   end
+        #
         # @!group Attributes
         #
         def schema replace: false
@@ -2427,6 +2442,11 @@ module Google
           #   schema. If `false`, the fields will be added to the existing
           #   schema. When a table already contains data, schema changes must be
           #   additive. Thus, the default value is `false`.
+          #   When loading from a file this will always replace the schema, no
+          #   matter what `replace` is set to. You can update the schema (for
+          #   example, for a table that already contains data) by providing a
+          #   schema file that includes the existing schema plus any new
+          #   fields.
           # @yield [schema] a block for setting the schema
           # @yieldparam [Schema] schema the object accepting the schema
           #
@@ -2449,6 +2469,19 @@ module Google
           #     end
           #   end
           #
+          # @example Load the schema from a file
+          #   require "google/cloud/bigquery"
+          #
+          #   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."
+          #     t.schema do |s|
+          #       s.load File.open("schema.json")
+          #     end
+          #   end
+          #
           # @!group Schema
           #
           def schema replace: false

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

@@ -16,7 +16,7 @@
 module Google
   module Cloud
     module Bigquery
-      VERSION = "1.4.0".freeze
+      VERSION = "1.5.0".freeze
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: google-cloud-bigquery
 version: !ruby/object:Gem::Version
-  version: 1.4.0
+  version: 1.5.0
 platform: ruby
 authors:
 - Mike Moore
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-05-07 00:00:00.000000000 Z
+date: 2018-05-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: google-cloud-core
@@ -251,7 +251,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.7.6
+rubygems_version: 2.7.7
 signing_key: 
 specification_version: 4
 summary: API Client library for Google BigQuery