google-cloud-bigquery 1.11.2 → 1.12.0

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

@@ -0,0 +1,168 @@
+# Copyright 2019 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+require "delegate"
+
+module Google
+  module Cloud
+    module Bigquery
+      class Model
+        ##
+        # Model::List is a special case Array with additional values.
+        class List < DelegateClass(::Array)
+          ##
+          # If not empty, indicates that there are more records that match
+          # the request and this value should be passed to continue.
+          attr_accessor :token
+
+          ##
+          # @private Create a new Model::List with an array of models.
+          def initialize arr = []
+            super arr
+          end
+
+          ##
+          # Whether there is a next page of models.
+          #
+          # @return [Boolean]
+          #
+          # @example
+          #   require "google/cloud/bigquery"
+          #
+          #   bigquery = Google::Cloud::Bigquery.new
+          #   dataset = bigquery.dataset "my_dataset"
+          #
+          #   models = dataset.models
+          #   if models.next?
+          #     next_models = models.next
+          #   end
+          #
+          def next?
+            !token.nil?
+          end
+
+          ##
+          # Retrieve the next page of models.
+          #
+          # @return [Model::List]
+          #
+          # @example
+          #   require "google/cloud/bigquery"
+          #
+          #   bigquery = Google::Cloud::Bigquery.new
+          #   dataset = bigquery.dataset "my_dataset"
+          #
+          #   models = dataset.models
+          #   if models.next?
+          #     next_models = models.next
+          #   end
+          #
+          def next
+            return nil unless next?
+            ensure_service!
+            gapi = @service.list_models @dataset_id, token: token, max: @max
+            self.class.from_gapi gapi, @service, @dataset_id, @max
+          end
+
+          ##
+          # 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 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 models. Default is no limit.
+          # @yield [model] The block for accessing each model.
+          # @yieldparam [Model] model The model object.
+          #
+          # @return [Enumerator]
+          #
+          # @example Iterating each result by passing a block:
+          #   require "google/cloud/bigquery"
+          #
+          #   bigquery = Google::Cloud::Bigquery.new
+          #   dataset = bigquery.dataset "my_dataset"
+          #
+          #   dataset.models.all do |model|
+          #     puts model.model_id
+          #   end
+          #
+          # @example Using the enumerator by not passing a block:
+          #   require "google/cloud/bigquery"
+          #
+          #   bigquery = Google::Cloud::Bigquery.new
+          #   dataset = bigquery.dataset "my_dataset"
+          #
+          #   all_names = dataset.models.all.map do |model|
+          #     model.model_id
+          #   end
+          #
+          # @example Limit the number of API requests made:
+          #   require "google/cloud/bigquery"
+          #
+          #   bigquery = Google::Cloud::Bigquery.new
+          #   dataset = bigquery.dataset "my_dataset"
+          #
+          #   dataset.models.all(request_limit: 10) do |model|
+          #     puts model.model_id
+          #   end
+          #
+          def all request_limit: nil
+            request_limit = request_limit.to_i if request_limit
+            unless block_given?
+              return enum_for :all, request_limit: request_limit
+            end
+            results = self
+            loop do
+              results.each { |r| yield r }
+              if request_limit
+                request_limit -= 1
+                break if request_limit < 0
+              end
+              break unless results.next?
+              results = results.next
+            end
+          end
+
+          ##
+          # @private New Model::List from a response object.
+          def self.from_gapi gapi_list, service, dataset_id = nil, max = nil
+            models = List.new(Array(gapi_list[:models]).map do |gapi_json|
+              Model.from_gapi_json gapi_json, service
+            end)
+            models.instance_variable_set :@token,      gapi_list[:nextPageToken]
+            models.instance_variable_set :@service,    service
+            models.instance_variable_set :@dataset_id, dataset_id
+            models.instance_variable_set :@max,        max
+            models
+          end
+
+          protected
+
+          ##
+          # Raise an error unless an active service is available.
+          def ensure_service!
+            raise "Must have active connection" unless @service
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -238,6 +238,60 @@ module Google
           end
         end
 
+        ##
+        # Lists all models in the specified dataset.
+        # Requires the READER dataset role.
+        def list_models dataset_id, max: nil, token: nil
+          options = { skip_deserialization: true }
+          # The list operation is considered idempotent
+          execute backoff: true do
+            json_txt = service.list_models @project, dataset_id,
+                                           max_results: max,
+                                           page_token:  token,
+                                           options:     options
+            JSON.parse json_txt, symbolize_names: true
+          end
+        end
+
+        # Gets the specified model resource by model ID.
+        # This method does not return the data in the model,
+        # it only returns the model resource,
+        # which describes the structure of this model.
+        def get_model dataset_id, model_id
+          # The get operation is considered idempotent
+          execute backoff: true do
+            json_txt = service.get_model @project, dataset_id, model_id,
+                                         options: { skip_deserialization: true }
+            JSON.parse json_txt, symbolize_names: true
+          end
+        end
+
+        ##
+        # Updates information in an existing model, replacing fields that
+        # are provided in the submitted model resource.
+        def patch_model dataset_id, model_id, patched_model_gapi, etag = nil
+          patch_with_backoff = false
+          options = { skip_deserialization: true }
+          if etag
+            options[:header] = { "If-Match" => etag }
+            # The patch with etag operation is considered idempotent
+            patch_with_backoff = true
+          end
+          execute backoff: patch_with_backoff do
+            json_txt = service.patch_model @project, dataset_id, model_id,
+                                           patched_model_gapi,
+                                           options: options
+            JSON.parse json_txt, symbolize_names: true
+          end
+        end
+
+        ##
+        # Deletes the model specified by modelId from the dataset.
+        # If the model contains data, all the data will be deleted.
+        def delete_model dataset_id, model_id
+          execute { service.delete_model @project, dataset_id, model_id }
+        end
+
         ##
         # Lists all jobs in the specified project to which you have
         # been granted the READER job role.

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

@@ -0,0 +1,291 @@
+# Copyright 2019 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+module Google
+  module Cloud
+    module Bigquery
+      ##
+      # BigQuery standard SQL is compliant with the SQL 2011 standard and has
+      # extensions that support querying nested and repeated data.
+      module StandardSql
+        ##
+        # A field or a column.
+        class Field
+          ##
+          # @private Create an empty StandardSql::Field object.
+          def initialize
+            @gapi_json = nil
+          end
+
+          ##
+          # The name of the field. (Can be absent for struct fields.)
+          #
+          # @return [String, nil]
+          #
+          def name
+            return nil if @gapi_json[:name] == "".freeze
+
+            @gapi_json[:name]
+          end
+
+          ##
+          # The type of the field.
+          #
+          # @return [DataType]
+          #
+          def type
+            DataType.from_gapi_json @gapi_json[:type]
+          end
+
+          ##
+          # @private New StandardSql::Field from a JSON object.
+          def self.from_gapi_json gapi_json
+            new.tap do |f|
+              f.instance_variable_set :@gapi_json, gapi_json
+            end
+          end
+        end
+
+        ##
+        # The type of a field or a column.
+        class DataType
+          ##
+          # @private Create an empty StandardSql::DataType object.
+          def initialize
+            @gapi_json = nil
+          end
+
+          ##
+          # The top level type of this field.
+          #
+          # Can be any standard SQL data type (e.g., "INT64", "DATE", "ARRAY").
+          #
+          # @see https://cloud.google.com/bigquery/docs/reference/standard-sql/data-types
+          #   Standard SQL Data Types
+          #
+          # @return [String]
+          #
+          def type_kind
+            @gapi_json[:typeKind]
+          end
+
+          ##
+          # The type of a fields when DataType is an Array. (See #array?)
+          #
+          # @return [DataType, nil]
+          #
+          def array_element_type
+            return if @gapi_json[:arrayElementType].nil?
+
+            DataType.from_gapi_json @gapi_json[:arrayElementType]
+          end
+
+          ##
+          # The fields of the struct. (See #struct?)
+          #
+          # @return [StructType, nil]
+          #
+          def struct_type
+            return if @gapi_json[:structType].nil?
+
+            StructType.from_gapi_json @gapi_json[:structType]
+          end
+
+          ##
+          # Checks if the {#type_kind} of the field is `INT64`.
+          #
+          # @return [Boolean] `true` when `INT64`, `false` otherwise.
+          #
+          # @!group Helpers
+          #
+          def int?
+            type_kind == "INT64".freeze
+          end
+
+          ##
+          # Checks if the {#type_kind} of the field is `FLOAT64`.
+          #
+          # @return [Boolean] `true` when `FLOAT64`, `false` otherwise.
+          #
+          # @!group Helpers
+          #
+          def float?
+            type_kind == "FLOAT64".freeze
+          end
+
+          ##
+          # Checks if the {#type_kind} of the field is `NUMERIC`.
+          #
+          # @return [Boolean] `true` when `NUMERIC`, `false` otherwise.
+          #
+          # @!group Helpers
+          #
+          def numeric?
+            type_kind == "NUMERIC".freeze
+          end
+
+          ##
+          # Checks if the {#type_kind} of the field is `BOOL`.
+          #
+          # @return [Boolean] `true` when `BOOL`, `false` otherwise.
+          #
+          # @!group Helpers
+          #
+          def boolean?
+            type_kind == "BOOL".freeze
+          end
+
+          ##
+          # Checks if the {#type_kind} of the field is `STRING`.
+          #
+          # @return [Boolean] `true` when `STRING`, `false` otherwise.
+          #
+          # @!group Helpers
+          #
+          def string?
+            type_kind == "STRING".freeze
+          end
+
+          ##
+          # Checks if the {#type_kind} of the field is `BYTES`.
+          #
+          # @return [Boolean] `true` when `BYTES`, `false` otherwise.
+          #
+          # @!group Helpers
+          #
+          def bytes?
+            type_kind == "BYTES".freeze
+          end
+
+          ##
+          # Checks if the {#type_kind} of the field is `DATE`.
+          #
+          # @return [Boolean] `true` when `DATE`, `false` otherwise.
+          #
+          # @!group Helpers
+          #
+          def date?
+            type_kind == "DATE".freeze
+          end
+
+          ##
+          # Checks if the {#type_kind} of the field is `DATETIME`.
+          #
+          # @return [Boolean] `true` when `DATETIME`, `false` otherwise.
+          #
+          # @!group Helpers
+          #
+          def datetime?
+            type_kind == "DATETIME".freeze
+          end
+
+          ##
+          # Checks if the {#type_kind} of the field is `GEOGRAPHY`.
+          #
+          # @return [Boolean] `true` when `GEOGRAPHY`, `false` otherwise.
+          #
+          # @!group Helpers
+          #
+          def geography?
+            type_kind == "GEOGRAPHY".freeze
+          end
+
+          ##
+          # Checks if the {#type_kind} of the field is `TIME`.
+          #
+          # @return [Boolean] `true` when `TIME`, `false` otherwise.
+          #
+          # @!group Helpers
+          #
+          def time?
+            type_kind == "TIME".freeze
+          end
+
+          ##
+          # Checks if the {#type_kind} of the field is `TIMESTAMP`.
+          #
+          # @return [Boolean] `true` when `TIMESTAMP`, `false` otherwise.
+          #
+          # @!group Helpers
+          #
+          def timestamp?
+            type_kind == "TIMESTAMP".freeze
+          end
+
+          ##
+          # Checks if the {#type_kind} of the field is `ARRAY`.
+          #
+          # @return [Boolean] `true` when `ARRAY`, `false` otherwise.
+          #
+          # @!group Helpers
+          #
+          def array?
+            type_kind == "ARRAY".freeze
+          end
+
+          ##
+          # Checks if the {#type_kind} of the field is `STRUCT`.
+          #
+          # @return [Boolean] `true` when `STRUCT`, `false` otherwise.
+          #
+          # @!group Helpers
+          #
+          def struct?
+            type_kind == "STRUCT".freeze
+          end
+
+          ##
+          # @private New StandardSql::DataType from a JSON object.
+          def self.from_gapi_json gapi_json
+            new.tap do |dt|
+              dt.instance_variable_set :@gapi_json, gapi_json
+            end
+          end
+        end
+
+        ##
+        # The type of a `STRUCT` field or a column.
+        class StructType
+          ##
+          # @private Create an empty StandardSql::DataType object.
+          def initialize
+            @gapi_json = nil
+          end
+
+          ##
+          # The top level type of this field.
+          #
+          # Can be any standard SQL data type (e.g., "INT64", "DATE", "ARRAY").
+          #
+          # @return [Array<Field>]
+          #
+          def fields
+            Array(@gapi_json[:fields]).map do |field_gapi_json|
+              Field.from_gapi_json field_gapi_json
+            end
+          end
+
+          ##
+          # @private New StandardSql::StructType from a JSON object.
+          def self.from_gapi_json gapi_json
+            new.tap do |st|
+              st.instance_variable_set :@gapi_json, gapi_json
+            end
+          end
+        end
+      end
+    end
+  end
+end