google-cloud-bigquery 1.18.0 → 1.21.1

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

@@ -0,0 +1,165 @@
+# Copyright 2020 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 Routine
+        ##
+        # Routine::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 Routine::List with an array of routines.
+          def initialize arr = []
+            super arr
+          end
+
+          ##
+          # Whether there is a next page of routines.
+          #
+          # @return [Boolean]
+          #
+          # @example
+          #   require "google/cloud/bigquery"
+          #
+          #   bigquery = Google::Cloud::Bigquery.new
+          #   dataset = bigquery.dataset "my_dataset"
+          #
+          #   routines = dataset.routines
+          #   if routines.next?
+          #     next_routines = routines.next
+          #   end
+          #
+          def next?
+            !token.nil?
+          end
+
+          ##
+          # Retrieve the next page of routines.
+          #
+          # @return [Routine::List]
+          #
+          # @example
+          #   require "google/cloud/bigquery"
+          #
+          #   bigquery = Google::Cloud::Bigquery.new
+          #   dataset = bigquery.dataset "my_dataset"
+          #
+          #   routines = dataset.routines
+          #   if routines.next?
+          #     next_routines = routines.next
+          #   end
+          #
+          def next
+            return nil unless next?
+            ensure_service!
+            gapi = @service.list_routines @dataset_id, token: token, max: @max, filter: @filter
+            self.class.from_gapi gapi, @service, @dataset_id, @max, filter: @filter
+          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 routines. Default is no limit.
+          # @yield [routine] The block for accessing each routine.
+          # @yieldparam [Routine] routine The routine 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.routines.all do |routine|
+          #     puts routine.routine_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.routines.all.map do |routine|
+          #     routine.routine_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.routines.all(request_limit: 10) do |routine|
+          #     puts routine.routine_id
+          #   end
+          #
+          def all request_limit: nil
+            request_limit = request_limit.to_i if request_limit
+            return enum_for :all, request_limit: request_limit unless block_given?
+            results = self
+            loop do
+              results.each { |r| yield r }
+              if request_limit
+                request_limit -= 1
+                break if request_limit.negative?
+              end
+              break unless results.next?
+              results = results.next
+            end
+          end
+
+          ##
+          # @private New Routine::List from a response object.
+          def self.from_gapi gapi_list, service, dataset_id = nil, max = nil, filter: nil
+            routines = List.new(Array(gapi_list.routines).map { |gapi| Routine.from_gapi gapi, service })
+            routines.instance_variable_set :@token,      gapi_list.next_page_token
+            routines.instance_variable_set :@service,    service
+            routines.instance_variable_set :@dataset_id, dataset_id
+            routines.instance_variable_set :@max,        max
+            routines.instance_variable_set :@filter,     filter
+            routines
+          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/schema.rb

@@ -232,8 +232,8 @@ module Google
         #
         #   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")
+        #   table = dataset.table "my_table" do |t|
+        #     t.schema.load File.read("path/to/schema.json")
         #   end
         #
         def load source

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

@@ -78,12 +78,10 @@ module Google
         ##
         # Lists all datasets in the specified project to which you have
         # been granted the READER dataset role.
-        def list_datasets options = {}
+        def list_datasets all: nil, filter: nil, max: nil, token: nil
           # The list operation is considered idempotent
           execute backoff: true do
-            service.list_datasets \
-              @project, all: options[:all], filter: options[:filter],
-                        max_results: options[:max], page_token: options[:token]
+            service.list_datasets @project, all: all, filter: filter, max_results: max, page_token: token
           end
         end
 
@@ -133,10 +131,10 @@ module Google
         ##
         # Lists all tables in the specified dataset.
         # Requires the READER dataset role.
-        def list_tables dataset_id, options = {}
+        def list_tables dataset_id, max: nil, token: nil
           # The list operation is considered idempotent
           execute backoff: true do
-            service.list_tables @project, dataset_id, max_results: options[:max], page_token: options[:token]
+            service.list_tables @project, dataset_id, max_results: max, page_token: token
           end
         end
 
@@ -190,38 +188,45 @@ module Google
 
         ##
         # Retrieves data from the table.
-        def list_tabledata dataset_id, table_id, options = {}
+        def list_tabledata dataset_id, table_id, max: nil, token: nil, start: nil
           # The list operation is considered idempotent
           execute backoff: true do
             json_txt = service.list_table_data \
               @project, dataset_id, table_id,
-              max_results: options.delete(:max),
-              page_token:  options.delete(:token),
-              start_index: options.delete(:start),
+              max_results: max,
+              page_token:  token,
+              start_index: start,
               options:     { skip_deserialization: true }
             JSON.parse json_txt, symbolize_names: true
           end
         end
 
-        def insert_tabledata dataset_id, table_id, rows, options = {}
+        def insert_tabledata dataset_id, table_id, rows, insert_ids: nil, ignore_unknown: nil, skip_invalid: nil
           json_rows = Array(rows).map { |row| Convert.to_json_row row }
-          insert_tabledata_json_rows dataset_id, table_id, json_rows, options
+          insert_tabledata_json_rows dataset_id, table_id, json_rows, insert_ids:     insert_ids,
+                                                                      ignore_unknown: ignore_unknown,
+                                                                      skip_invalid:   skip_invalid
         end
 
-        def insert_tabledata_json_rows dataset_id, table_id, json_rows, options = {}
-          rows_and_ids = Array(json_rows).zip Array(options[:insert_ids])
+        def insert_tabledata_json_rows dataset_id, table_id, json_rows, insert_ids: nil, ignore_unknown: nil,
+                                       skip_invalid: nil
+          rows_and_ids = Array(json_rows).zip Array(insert_ids)
           insert_rows = rows_and_ids.map do |json_row, insert_id|
-            insert_id ||= SecureRandom.uuid
-            {
-              insertId: insert_id,
-              json:     json_row
-            }
+            if insert_id == :skip
+              { json: json_row }
+            else
+              insert_id ||= SecureRandom.uuid
+              {
+                insertId: insert_id,
+                json:     json_row
+              }
+            end
           end
 
           insert_req = {
             rows:                insert_rows,
-            ignoreUnknownValues: options[:ignore_unknown],
-            skipInvalidRows:     options[:skip_invalid]
+            ignoreUnknownValues: ignore_unknown,
+            skipInvalidRows:     skip_invalid
           }.to_json
 
           # The insertAll with insertId operation is considered idempotent
@@ -281,17 +286,69 @@ module Google
           execute { service.delete_model @project, dataset_id, model_id }
         end
 
+        ##
+        # Creates a new routine in the dataset.
+        def insert_routine dataset_id, new_routine_gapi
+          execute { service.insert_routine @project, dataset_id, new_routine_gapi }
+        end
+
+        ##
+        # Lists all routines in the specified dataset.
+        # Requires the READER dataset role.
+        # Unless readMask is set in the request, only the following fields are populated:
+        #   etag, projectId, datasetId, routineId, routineType, creationTime, lastModifiedTime, and language.
+        def list_routines dataset_id, max: nil, token: nil, filter: nil
+          # The list operation is considered idempotent
+          execute backoff: true do
+            service.list_routines @project, dataset_id, max_results: max,
+                                                        page_token:  token,
+                                                        filter:      filter
+          end
+        end
+
+        ##
+        # Gets the specified routine resource by routine ID.
+        def get_routine dataset_id, routine_id
+          # The get operation is considered idempotent
+          execute backoff: true do
+            service.get_routine @project, dataset_id, routine_id
+          end
+        end
+
+        ##
+        # Updates information in an existing routine, replacing the entire routine resource.
+        def update_routine dataset_id, routine_id, new_routine_gapi
+          update_with_backoff = false
+          options = {}
+          if new_routine_gapi.etag
+            options[:header] = { "If-Match" => new_routine_gapi.etag }
+            # The update with etag operation is considered idempotent
+            update_with_backoff = true
+          end
+          execute backoff: update_with_backoff do
+            service.update_routine @project, dataset_id, routine_id, new_routine_gapi, options: options
+          end
+        end
+
+        ##
+        # Deletes the routine specified by routine_id from the dataset.
+        def delete_routine dataset_id, routine_id
+          execute { service.delete_routine @project, dataset_id, routine_id }
+        end
+
         ##
         # Lists all jobs in the specified project to which you have
         # been granted the READER job role.
-        def list_jobs options = {}
+        def list_jobs all: nil, token: nil, max: nil, filter: nil, min_created_at: nil, max_created_at: nil,
+                      parent_job_id: nil
           # The list operation is considered idempotent
-          min_creation_time = Convert.time_to_millis options[:min_created_at]
-          max_creation_time = Convert.time_to_millis options[:max_created_at]
+          min_creation_time = Convert.time_to_millis min_created_at
+          max_creation_time = Convert.time_to_millis max_created_at
           execute backoff: true do
-            service.list_jobs @project, all_users: options[:all], max_results: options[:max],
-                                        page_token: options[:token], projection: "full", state_filter: options[:filter],
-                                        min_creation_time: min_creation_time, max_creation_time: max_creation_time
+            service.list_jobs @project, all_users: all, max_results: max,
+                                        page_token: token, projection: "full", state_filter: filter,
+                                        min_creation_time: min_creation_time, max_creation_time: max_creation_time,
+                                        parent_job_id: parent_job_id
           end
         end
 
@@ -329,15 +386,15 @@ module Google
 
         ##
         # Returns the query data for the job
-        def job_query_results job_id, options = {}
+        def job_query_results job_id, location: nil, max: nil, token: nil, start: nil, timeout: nil
           # The get operation is considered idempotent
           execute backoff: true do
             service.get_job_query_results @project, job_id,
-                                          location:    options.delete(:location),
-                                          max_results: options.delete(:max),
-                                          page_token:  options.delete(:token),
-                                          start_index: options.delete(:start),
-                                          timeout_ms:  options.delete(:timeout)
+                                          location:    location,
+                                          max_results: max,
+                                          page_token:  token,
+                                          start_index: start,
+                                          timeout_ms:  timeout
           end
         end
 
@@ -405,9 +462,9 @@ module Google
 
         ##
         # Lists all projects to which you have been granted any project role.
-        def list_projects options = {}
+        def list_projects max: nil, token: nil
           execute backoff: true do
-            service.list_projects max_results: options[:max], page_token: options[:token]
+            service.list_projects max_results: max, page_token: token
           end
         end
 
@@ -485,10 +542,10 @@ module Google
             sleep delay
           end
 
-          def initialize options = {}
-            @retries = (options[:retries] || Backoff.retries).to_i
-            @reasons = (options[:reasons] || Backoff.reasons).to_a
-            @backoff =  options[:backoff] || Backoff.backoff
+          def initialize retries: nil, reasons: nil, backoff: nil
+            @retries = (retries || Backoff.retries).to_i
+            @reasons = (reasons || Backoff.reasons).to_a
+            @backoff = backoff || Backoff.backoff
           end
 
           def execute

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

@@ -18,89 +18,226 @@ module Google
     module Bigquery
       ##
       # BigQuery standard SQL is compliant with the SQL 2011 standard and has
-      # extensions that support querying nested and repeated data.
+      # extensions that support querying nested and repeated data. See {Routine} and {Argument}.
+      #
+      # @example
+      #   require "google/cloud/bigquery"
+      #
+      #   bigquery = Google::Cloud::Bigquery.new
+      #   dataset = bigquery.dataset "my_dataset"
+      #   routine = dataset.create_routine "my_routine" do |r|
+      #     r.routine_type = "SCALAR_FUNCTION"
+      #     r.language = :SQL
+      #     r.body = "(SELECT SUM(IF(elem.name = \"foo\",elem.val,null)) FROM UNNEST(arr) AS elem)"
+      #     r.arguments = [
+      #       Google::Cloud::Bigquery::Argument.new(
+      #         name: "arr",
+      #         argument_kind: "FIXED_TYPE",
+      #         data_type: Google::Cloud::Bigquery::StandardSql::DataType.new(
+      #           type_kind: "ARRAY",
+      #           array_element_type: Google::Cloud::Bigquery::StandardSql::DataType.new(
+      #             type_kind: "STRUCT",
+      #             struct_type: Google::Cloud::Bigquery::StandardSql::StructType.new(
+      #               fields: [
+      #                 Google::Cloud::Bigquery::StandardSql::Field.new(
+      #                   name: "name",
+      #                   type: Google::Cloud::Bigquery::StandardSql::DataType.new(type_kind: "STRING")
+      #                 ),
+      #                 Google::Cloud::Bigquery::StandardSql::Field.new(
+      #                   name: "val",
+      #                   type: Google::Cloud::Bigquery::StandardSql::DataType.new(type_kind: "INT64")
+      #                 )
+      #               ]
+      #             )
+      #           )
+      #         )
+      #       )
+      #     ]
+      #   end
+      #
       module StandardSql
         ##
-        # A field or a column.
+        # A field or a column. See {Routine} and {Argument}.
+        #
+        # @example
+        #   require "google/cloud/bigquery"
+        #
+        #   bigquery = Google::Cloud::Bigquery.new
+        #   dataset = bigquery.dataset "my_dataset"
+        #   routine = dataset.create_routine "my_routine" do |r|
+        #     r.routine_type = "SCALAR_FUNCTION"
+        #     r.language = :SQL
+        #     r.body = "(SELECT SUM(IF(elem.name = \"foo\",elem.val,null)) FROM UNNEST(arr) AS elem)"
+        #     r.arguments = [
+        #       Google::Cloud::Bigquery::Argument.new(
+        #         name: "arr",
+        #         argument_kind: "FIXED_TYPE",
+        #         data_type: Google::Cloud::Bigquery::StandardSql::DataType.new(
+        #           type_kind: "ARRAY",
+        #           array_element_type: Google::Cloud::Bigquery::StandardSql::DataType.new(
+        #             type_kind: "STRUCT",
+        #             struct_type: Google::Cloud::Bigquery::StandardSql::StructType.new(
+        #               fields: [
+        #                 Google::Cloud::Bigquery::StandardSql::Field.new(
+        #                   name: "name",
+        #                   type: Google::Cloud::Bigquery::StandardSql::DataType.new(type_kind: "STRING")
+        #                 ),
+        #                 Google::Cloud::Bigquery::StandardSql::Field.new(
+        #                   name: "val",
+        #                   type: Google::Cloud::Bigquery::StandardSql::DataType.new(type_kind: "INT64")
+        #                 )
+        #               ]
+        #             )
+        #           )
+        #         )
+        #       )
+        #     ]
+        #   end
+        #
         class Field
           ##
-          # @private Create an empty StandardSql::Field object.
-          def initialize
-            @gapi_json = nil
+          # Creates a new, immutable StandardSql::Field object.
+          #
+          # @overload initialize(name, type)
+          #   @param [String] name The name of the field. Optional. Can be absent for struct fields.
+          #   @param [StandardSql::DataType, String] type The type of the field. Optional. Absent if not explicitly
+          #     specified (e.g., `CREATE FUNCTION` statement can omit the return type; in this case the output parameter
+          #     does not have this "type" field).
+          #
+          def initialize **kwargs
+            # Convert client object kwargs to a gapi object
+            kwargs[:type] = DataType.gapi_from_string_or_data_type kwargs[:type] if kwargs[:type]
+            @gapi = Google::Apis::BigqueryV2::StandardSqlField.new(**kwargs)
           end
 
           ##
-          # The name of the field. (Can be absent for struct fields.)
+          # The name of the field. Optional. Can be absent for struct fields.
           #
           # @return [String, nil]
           #
           def name
-            return nil if @gapi_json[:name] == "".freeze
-
-            @gapi_json[:name]
+            return if @gapi.name == "".freeze
+            @gapi.name
           end
 
           ##
-          # The type of the field.
+          # The type of the field. Optional. Absent if not explicitly specified (e.g., `CREATE FUNCTION` statement can
+          # omit the return type; in this case the output parameter does not have this "type" field).
           #
-          # @return [DataType]
+          # @return [DataType, nil] The type of the field.
           #
           def type
-            DataType.from_gapi_json @gapi_json[:type]
+            DataType.from_gapi @gapi.type if @gapi.type
+          end
+
+          ##
+          # @private New Google::Apis::BigqueryV2::StandardSqlField object.
+          def to_gapi
+            @gapi
           end
 
           ##
-          # @private New StandardSql::Field from a JSON object.
-          def self.from_gapi_json gapi_json
+          # @private New StandardSql::Field from a Google::Apis::BigqueryV2::StandardSqlField object.
+          def self.from_gapi gapi
             new.tap do |f|
-              f.instance_variable_set :@gapi_json, gapi_json
+              f.instance_variable_set :@gapi, gapi
             end
           end
         end
 
         ##
-        # The type of a field or a column.
+        # The type of a variable, e.g., a function argument. See {Routine} and {Argument}.
+        #
+        # @example
+        #   require "google/cloud/bigquery"
+        #
+        #   bigquery = Google::Cloud::Bigquery.new
+        #   dataset = bigquery.dataset "my_dataset"
+        #   routine = dataset.create_routine "my_routine" do |r|
+        #     r.routine_type = "SCALAR_FUNCTION"
+        #     r.language = :SQL
+        #     r.body = "(SELECT SUM(IF(elem.name = \"foo\",elem.val,null)) FROM UNNEST(arr) AS elem)"
+        #     r.arguments = [
+        #       Google::Cloud::Bigquery::Argument.new(
+        #         name: "arr",
+        #         argument_kind: "FIXED_TYPE",
+        #         data_type: Google::Cloud::Bigquery::StandardSql::DataType.new(
+        #           type_kind: "ARRAY",
+        #           array_element_type: Google::Cloud::Bigquery::StandardSql::DataType.new(
+        #             type_kind: "STRUCT",
+        #             struct_type: Google::Cloud::Bigquery::StandardSql::StructType.new(
+        #               fields: [
+        #                 Google::Cloud::Bigquery::StandardSql::Field.new(
+        #                   name: "name",
+        #                   type: Google::Cloud::Bigquery::StandardSql::DataType.new(type_kind: "STRING")
+        #                 ),
+        #                 Google::Cloud::Bigquery::StandardSql::Field.new(
+        #                   name: "val",
+        #                   type: Google::Cloud::Bigquery::StandardSql::DataType.new(type_kind: "INT64")
+        #                 )
+        #               ]
+        #             )
+        #           )
+        #         )
+        #       )
+        #     ]
+        #   end
+        #
+        # @see https://cloud.google.com/bigquery/docs/reference/standard-sql/data-types Standard SQL Data Types
+        #
         class DataType
           ##
-          # @private Create an empty StandardSql::DataType object.
-          def initialize
-            @gapi_json = nil
+          # Creates a new, immutable StandardSql::DataType object.
+          #
+          # @overload initialize(type_kind, array_element_type, struct_type)
+          #   @param [String] type_kind The top level type of this field. Required. Can be [any standard SQL data
+          #     type](https://cloud.google.com/bigquery/docs/reference/standard-sql/data-types) (e.g., `INT64`, `DATE`,
+          #     `ARRAY`).
+          #   @param [DataType, String] array_element_type The type of the array's elements, if {#type_kind} is `ARRAY`.
+          #     See {#array?}. Optional.
+          #   @param [StructType] struct_type The fields of the struct, in order, if {#type_kind} is `STRUCT`. See
+          #     {#struct?}. Optional.
+          #
+          def initialize **kwargs
+            # Convert client object kwargs to a gapi object
+            if kwargs[:array_element_type]
+              kwargs[:array_element_type] = self.class.gapi_from_string_or_data_type kwargs[:array_element_type]
+            end
+            kwargs[:struct_type] = kwargs[:struct_type].to_gapi if kwargs[:struct_type]
+
+            @gapi = Google::Apis::BigqueryV2::StandardSqlDataType.new(**kwargs)
           end
 
           ##
-          # The top level type of this field.
-          #
-          # Can be any standard SQL data type (e.g., "INT64", "DATE", "ARRAY").
+          # The top level type of this field. Required. 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
+          # @see https://cloud.google.com/bigquery/docs/reference/standard-sql/data-types Standard SQL Data Types
           #
-          # @return [String]
+          # @return [String] The upper case type.
           #
           def type_kind
-            @gapi_json[:typeKind]
+            @gapi.type_kind
           end
 
           ##
-          # The type of a fields when DataType is an Array. (See #array?)
+          # The type of the array's elements, if {#type_kind} is `ARRAY`. See {#array?}. Optional.
           #
           # @return [DataType, nil]
           #
           def array_element_type
-            return if @gapi_json[:arrayElementType].nil?
-
-            DataType.from_gapi_json @gapi_json[:arrayElementType]
+            return if @gapi.array_element_type.nil?
+            DataType.from_gapi @gapi.array_element_type
           end
 
           ##
-          # The fields of the struct. (See #struct?)
+          # The fields of the struct, in order, if {#type_kind} is `STRUCT`. See {#struct?}. Optional.
           #
           # @return [StructType, nil]
           #
           def struct_type
-            return if @gapi_json[:structType].nil?
-
-            StructType.from_gapi_json @gapi_json[:structType]
+            return if @gapi.struct_type.nil?
+            StructType.from_gapi @gapi.struct_type
           end
 
           ##
@@ -247,41 +384,108 @@ module Google
           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
+          # @private New Google::Apis::BigqueryV2::StandardSqlDataType object.
+          def to_gapi
+            @gapi
+          end
+
+          ##
+          # @private New StandardSql::DataType from a Google::Apis::BigqueryV2::StandardSqlDataType object.
+          def self.from_gapi gapi
+            new.tap do |f|
+              f.instance_variable_set :@gapi, gapi
+            end
+          end
+
+          ##
+          # @private New Google::Apis::BigqueryV2::StandardSqlDataType from a String or StandardSql::DataType object.
+          def self.gapi_from_string_or_data_type data_type
+            return if data_type.nil?
+            if data_type.is_a? StandardSql::DataType
+              data_type.to_gapi
+            elsif data_type.is_a? Hash
+              data_type
+            elsif data_type.is_a?(String) || data_type.is_a?(Symbol)
+              Google::Apis::BigqueryV2::StandardSqlDataType.new type_kind: data_type.to_s.upcase
+            else
+              raise ArgumentError, "Unable to convert #{data_type} to Google::Apis::BigqueryV2::StandardSqlDataType"
             end
           end
         end
 
         ##
-        # The type of a `STRUCT` field or a column.
+        # The fields of a `STRUCT` type. See {DataType#struct_type}. See {Routine} and {Argument}.
+        #
+        # @example
+        #   require "google/cloud/bigquery"
+        #
+        #   bigquery = Google::Cloud::Bigquery.new
+        #   dataset = bigquery.dataset "my_dataset"
+        #   routine = dataset.create_routine "my_routine" do |r|
+        #     r.routine_type = "SCALAR_FUNCTION"
+        #     r.language = :SQL
+        #     r.body = "(SELECT SUM(IF(elem.name = \"foo\",elem.val,null)) FROM UNNEST(arr) AS elem)"
+        #     r.arguments = [
+        #       Google::Cloud::Bigquery::Argument.new(
+        #         name: "arr",
+        #         argument_kind: "FIXED_TYPE",
+        #         data_type: Google::Cloud::Bigquery::StandardSql::DataType.new(
+        #           type_kind: "ARRAY",
+        #           array_element_type: Google::Cloud::Bigquery::StandardSql::DataType.new(
+        #             type_kind: "STRUCT",
+        #             struct_type: Google::Cloud::Bigquery::StandardSql::StructType.new(
+        #               fields: [
+        #                 Google::Cloud::Bigquery::StandardSql::Field.new(
+        #                   name: "name",
+        #                   type: Google::Cloud::Bigquery::StandardSql::DataType.new(type_kind: "STRING")
+        #                 ),
+        #                 Google::Cloud::Bigquery::StandardSql::Field.new(
+        #                   name: "val",
+        #                   type: Google::Cloud::Bigquery::StandardSql::DataType.new(type_kind: "INT64")
+        #                 )
+        #               ]
+        #             )
+        #           )
+        #         )
+        #       )
+        #     ]
+        #   end
+        #
         class StructType
           ##
-          # @private Create an empty StandardSql::DataType object.
-          def initialize
-            @gapi_json = nil
+          # Creates a new, immutable StandardSql::StructType object.
+          #
+          # @overload initialize(fields)
+          #   @param [Array<Field>] fields The fields of the struct. Required.
+          #
+          def initialize **kwargs
+            # Convert each field client object to gapi object, if fields given (self.from_gapi does not pass kwargs)
+            kwargs[:fields] = kwargs[:fields]&.map(&:to_gapi) if kwargs[:fields]
+            @gapi = Google::Apis::BigqueryV2::StandardSqlStructType.new(**kwargs)
           end
 
           ##
-          # The top level type of this field.
+          # The fields of the struct.
           #
-          # Can be any standard SQL data type (e.g., "INT64", "DATE", "ARRAY").
-          #
-          # @return [Array<Field>]
+          # @return [Array<Field>] A frozen array of fields.
           #
           def fields
-            Array(@gapi_json[:fields]).map do |field_gapi_json|
-              Field.from_gapi_json field_gapi_json
-            end
+            Array(@gapi.fields).map do |field_gapi|
+              Field.from_gapi field_gapi
+            end.freeze
+          end
+
+          ##
+          # @private New Google::Apis::BigqueryV2::StandardSqlStructType object.
+          def to_gapi
+            @gapi
           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
+          # @private New StandardSql::StructType from a Google::Apis::BigqueryV2::StandardSqlStructType object.
+          def self.from_gapi gapi
+            new.tap do |f|
+              f.instance_variable_set :@gapi, gapi
             end
           end
         end