google-cloud-bigquery 1.53.0 → 1.54.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '0844316676c10ea437a2901f4693a347786a147f4fb11af5de161083fba04edd'
-  data.tar.gz: 3a4a37fa591e5ff75d40680872fda8188dc136d011d9742e35a5d87611ebd81c
+  metadata.gz: cbfaf1f9de532a42e02ae04ce9a3373b337b401491a746a10e103c708b01d069
+  data.tar.gz: 3d7dd0f1213c69fcb79fee23f342f3e435c66842af1cc7569bf7c861f5f54773
 SHA512:
-  metadata.gz: 8a2aed50235c51c87c03a36ab5f2564d46fe5ffc1f98dee981b691c0f818ca3275511ce44ccb7f23786f324092eaf929bfcc2b79c100565984d6fa54e674c001
-  data.tar.gz: 56c77db151cf32224701742e1fa707a246ac8dd6df4802aead2eb7e017c8b5e3ce96960d4b1999194c054c20b1bcfdc8ee274d5a1a3954f50d6d6745a5451874
+  metadata.gz: 4144ce5964844c6f8aebc2e12049639a6e42c65d74458617b88836b7bccded75c061315548c49d0030f1667a8890496911e9d8334d518adc40c0b416dc968ffe
+  data.tar.gz: 46d49fb84f11c0b97211ba5099a11be5001a21b20df26a21a4a31843633abba9869dad0cb4f80a9674156c5a4d78d84af2cfef9b77ee52395987e8e7637ce7b9

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Release History
 
+### 1.54.0 (2025-08-15)
+
+#### Features
+
+* Add support for format_options_use_int64_timestamp ([#30755](https://github.com/googleapis/google-cloud-ruby/issues/30755)) 
+* load job external table options ([#30743](https://github.com/googleapis/google-cloud-ruby/issues/30743)) 
+
 ### 1.53.0 (2025-08-12)
 
 #### Features

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

@@ -60,6 +60,10 @@ module Google
           end
         end
 
+        def self.is_int? value
+          /\A\s*[-+]?\d+\s*\z/.match? value.to_s
+        end
+
         # rubocop:disable all
 
         def self.format_value value, field
@@ -96,7 +100,12 @@ module Google
           elsif field.type == "BYTES"
             StringIO.new Base64.decode64 value[:v]
           elsif field.type == "TIMESTAMP"
-            ::Time.at Float(value[:v])
+            if is_int?(value[:v])
+              # Convert microseconds to seconds
+              ::Time.at Rational(Integer(value[:v]), 1_000_000)
+            else
+              ::Time.at Rational(value[:v])
+            end
           elsif field.type == "TIME"
             Bigquery::Time.new value[:v]
           elsif field.type == "DATETIME"

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

@@ -66,6 +66,10 @@ module Google
         # @private The query Job gapi object, or nil if from Table#data.
         attr_accessor :job_gapi
 
+        ##
+        # @private Whether to output timestamp as usec int64.
+        attr_accessor :format_options_use_int64_timestamp
+
         # @private
         def initialize arr = []
           @service = nil
@@ -473,8 +477,9 @@ module Google
           data_json = service.list_tabledata \
             @table_gapi.table_reference.dataset_id,
             @table_gapi.table_reference.table_id,
-            token: token
-          self.class.from_gapi_json data_json, @table_gapi, job_gapi, @service
+            token: token,
+            format_options_use_int64_timestamp: @format_options_use_int64_timestamp
+          self.class.from_gapi_json data_json, @table_gapi, job_gapi, @service, @format_options_use_int64_timestamp
         end
 
         ##
@@ -549,7 +554,7 @@ module Google
 
         ##
         # @private New Data from a response object.
-        def self.from_gapi_json gapi_json, table_gapi, job_gapi, service
+        def self.from_gapi_json gapi_json, table_gapi, job_gapi, service, format_options_use_int64_timestamp
           rows = gapi_json[:rows] || []
           rows = Convert.format_rows rows, table_gapi.schema.fields unless rows.empty?
 
@@ -558,6 +563,7 @@ module Google
           data.gapi_json = gapi_json
           data.job_gapi = job_gapi
           data.service = service
+          data.format_options_use_int64_timestamp = format_options_use_int64_timestamp
           data
         end
 

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

@@ -1710,6 +1710,8 @@ module Google
         #   `flatten` is false. Optional. The default value is false.
         # @param [String] session_id The ID of an existing session. See the
         #   `create_session` param in {#query_job} and {Job#session_id}.
+        # @param [Boolean] format_options_use_int64_timestamp Output timestamp
+        #   as usec int64. Default is true.
         # @yield [job] a job configuration object
         # @yieldparam [Google::Cloud::Bigquery::QueryJob::Updater] job a job
         #   configuration object for setting additional options for the query.
@@ -1864,6 +1866,7 @@ module Google
                   standard_sql: nil,
                   legacy_sql: nil,
                   session_id: nil,
+                  format_options_use_int64_timestamp: true,
                   &block
           job = query_job query,
                           params: params,
@@ -1877,7 +1880,7 @@ module Google
           job.wait_until_done!
           ensure_job_succeeded! job
 
-          job.data max: max
+          job.data max: max, format_options_use_int64_timestamp: format_options_use_int64_timestamp
         end
 
         ##

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

@@ -367,6 +367,177 @@ module Google
             @gapi.csv_options.skip_leading_rows = row_count
           end
 
+          ##
+          # Specifies a string that represents a null value in a CSV file. For
+          # example, if you specify `\N`, BigQuery interprets `\N` as a null value when
+          # querying a CSV file. The default value is the empty string. If you set this
+          # property to a custom value, BigQuery throws an error if an empty string is
+          # present for all data types except for STRING and BYTE. For STRING and BYTE
+          # columns, BigQuery interprets the empty string as an empty value.
+          #
+          # @return [String, nil] The null marker string. `nil` if not set.
+          #
+          # @example
+          #   require "google/cloud/bigquery"
+          #
+          #   bigquery = Google::Cloud::Bigquery.new
+          #
+          #   csv_url = "gs://bucket/path/to/data.csv"
+          #   csv_table = bigquery.external csv_url do |csv|
+          #     csv.null_marker = "\N"
+          #   end
+          #
+          #   csv_table.null_marker #=> "\N"
+          #
+          def null_marker
+            @gapi.csv_options.null_marker
+          end
+
+          ##
+          # Sets a string that represents a null value in a CSV file. For
+          # example, if you specify `\N`, BigQuery interprets `\N` as a null value when
+          # querying a CSV file. The default value is the empty string. If you set this
+          # property to a custom value, BigQuery throws an error if an empty string is
+          # present for all data types except for STRING and BYTE. For STRING and BYTE
+          # columns, BigQuery interprets the empty string as an empty value.
+          #
+          # @param [String, nil] null_marker The null marker string. `nil` to unset.
+          #
+          # @example
+          #   require "google/cloud/bigquery"
+          #
+          #   bigquery = Google::Cloud::Bigquery.new
+          #
+          #   csv_url = "gs://bucket/path/to/data.csv"
+          #   csv_table = bigquery.external csv_url do |csv|
+          #     csv.null_marker = "\N"
+          #   end
+          #
+          #   csv_table.null_marker #=> "\N"
+          #
+          def null_marker= null_marker
+            frozen_check!
+            @gapi.csv_options.null_marker = null_marker
+          end
+
+          ##
+          # The list of strings represented as SQL NULL value in a CSV file.
+          # null_marker and null_markers can't be set at the same time. If null_marker is
+          # set, null_markers has to be not set. If null_markers is set, null_marker has
+          # to be not set. If both null_marker and null_markers are set at the same time,
+          # a user error would be thrown. Any strings listed in null_markers, including
+          # empty string would be interpreted as SQL NULL. This applies to all column
+          # types.
+          #
+          # @return [Array<String>] The array of null marker strings.
+          #
+          # @example
+          #   require "google/cloud/bigquery"
+          #
+          #   bigquery = Google::Cloud::Bigquery.new
+          #
+          #   csv_url = "gs://bucket/path/to/data.csv"
+          #   csv_table = bigquery.external csv_url do |csv|
+          #     csv.null_markers = ["\N", "NULL"]
+          #   end
+          #
+          #   csv_table.null_markers #=> ["\N", "NULL"]
+          #
+          def null_markers
+            @gapi.csv_options.null_markers || []
+          end
+
+          ##
+          # Sets the list of strings represented as SQL NULL value in a CSV file.
+          # null_marker and null_markers can't be set at the same time. If null_marker is
+          # set, null_markers has to be not set. If null_markers is set, null_marker has
+          # to be not set. If both null_marker and null_markers are set at the same time,
+          # a user error would be thrown. Any strings listed in null_markers, including
+          # empty string would be interpreted as SQL NULL. This applies to all column
+          # types.
+          #
+          # @param [Array<String>] null_markers The array of null marker strings.
+          #
+          #
+          # @example
+          #   require "google/cloud/bigquery"
+          #
+          #   bigquery = Google::Cloud::Bigquery.new
+          #
+          #   csv_url = "gs://bucket/path/to/data.csv"
+          #   csv_table = bigquery.external csv_url do |csv|
+          #     csv.null_markers = ["\N", "NULL"]
+          #   end
+          #
+          #   csv_table.null_markers #=> ["\N", "NULL"]
+          #
+          def null_markers= null_markers
+            frozen_check!
+            @gapi.csv_options.null_markers = null_markers
+          end
+
+          # Controls the strategy used to match loaded columns to the schema.
+          # If not set, a sensible default is chosen based on how the schema is
+          # provided. If autodetect is used, then columns are matched by name.
+          # Otherwise, columns are matched by position. This is done to keep the
+          # behavior backward-compatible.
+          #
+          # Acceptable values are:
+          # - `POSITION`: matches by position. Assumes columns are ordered the
+          #   same way as the schema.
+          # - `NAME`: matches by name. Reads the header row as column names and
+          #   reorders columns to match the schema.
+          #
+          # @return [String, nil] The source column match value. `nil` if not set.
+          #
+          # @example
+          #   require "google/cloud/bigquery"
+          #
+          #   bigquery = Google::Cloud::Bigquery.new
+          #
+          #   csv_url = "gs://bucket/path/to/data.csv"
+          #   csv_table = bigquery.external csv_url do |csv|
+          #     csv.source_column_match = "NAME"
+          #   end
+          #
+          #   csv_table.source_column_match #=> "NAME"
+          #
+          def source_column_match
+            @gapi.csv_options.source_column_match
+          end
+
+          # Sets the strategy used to match loaded columns to the schema.
+          # If not set, a sensible default is chosen based on how the schema is
+          # provided. If autodetect is used, then columns are matched by name.
+          # Otherwise, columns are matched by position. This is done to keep the
+          # behavior backward-compatible. Optional.
+          #
+          # Acceptable values are:
+          # - `POSITION`: matches by position. Assumes columns are ordered the
+          #   same way as the schema.
+          # - `NAME`: matches by name. Reads the header row as column names and
+          #   reorders columns to match the schema.
+          #
+          # @param [String, nil] source_column_match The new source column match value. `nil` to unset.
+          #
+          #
+          # @example
+          #   require "google/cloud/bigquery"
+          #
+          #   bigquery = Google::Cloud::Bigquery.new
+          #
+          #   csv_url = "gs://bucket/path/to/data.csv"
+          #   csv_table = bigquery.external csv_url do |csv|
+          #     csv.source_column_match = "NAME"
+          #   end
+          #
+          #   csv_table.source_column_match #=> "NAME"
+          #
+          def source_column_match= source_column_match
+            frozen_check!
+            @gapi.csv_options.source_column_match = source_column_match
+          end
+
           ##
           # The schema for the data.
           #

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

@@ -744,6 +744,222 @@ module Google
             @gapi.hive_partitioning_options.source_uri_prefix = source_uri_prefix
           end
 
+          ##
+          # Time zone used when parsing timestamp values that do not have specific
+          # time zone information (e.g. `2024-04-20 12:34:56`). The expected format
+          # is an IANA timezone string (e.g. `America/Los_Angeles`).
+          #
+          # @return [String, nil] The IANA time zone name. `nil` if not set.
+          #
+          # @example
+          #   require "google/cloud/bigquery"
+          #
+          #   bigquery = Google::Cloud::Bigquery.new
+          #
+          #   external_data = bigquery.external "gs://bucket/path/to/data.csv" do |ext|
+          #     ext.time_zone = "America/Los_Angeles"
+          #   end
+          #
+          #   external_data.time_zone #=> "America/Los_Angeles"
+          #
+          def time_zone
+            @gapi.time_zone
+          end
+
+          ##
+          # Sets the time zone used when parsing timestamp values that do not have
+          # specific time zone information (e.g. `2024-04-20 12:34:56`). The expected
+          # format is an IANA timezone string (e.g. `America/Los_Angeles`).
+          #
+          # @param [String, nil] time_zone The IANA time zone name. `nil` to unset.
+          #
+          # @example
+          #   require "google/cloud/bigquery"
+          #
+          #   bigquery = Google::Cloud::Bigquery.new
+          #
+          #   external_data = bigquery.external "gs://bucket/path/to/data.csv" do |ext|
+          #     ext.time_zone = "America/Los_Angeles"
+          #   end
+          #
+          #   external_data.time_zone #=> "America/Los_Angeles"
+          #
+          def time_zone= time_zone
+            frozen_check!
+            @gapi.time_zone = time_zone
+          end
+
+          ##
+          # Format used to parse TIME values. Supports C-style and SQL-style values.
+          #
+          # @return [String, nil] The time format pattern. `nil` if not set.
+          #
+          # @example
+          #   require "google/cloud/bigquery"
+          #
+          #   bigquery = Google::Cloud::Bigquery.new
+          #
+          #   external_data = bigquery.external "gs://bucket/path/to/data.csv" do |ext|
+          #     ext.time_format = "%H:%M:%S"
+          #   end
+          #
+          #   external_data.time_format #=> "%H:%M:%S"
+          #
+          def time_format
+            @gapi.time_format
+          end
+
+          ##
+          # Sets the format used to parse TIME values. Supports C-style and SQL-style
+          # values.
+          #
+          # @param [String, nil] time_format The time format pattern. `nil` if not set.
+          #
+          # @example
+          #   require "google/cloud/bigquery"
+          #
+          #   bigquery = Google::Cloud::Bigquery.new
+          #
+          #   external_data = bigquery.external "gs://bucket/path/to/data.csv" do |ext|
+          #     ext.time_format = "%H:%M:%S"
+          #   end
+          #
+          #   external_data.time_format #=> "%H:%M:%S"
+          #
+          def time_format= time_format
+            frozen_check!
+            @gapi.time_format = time_format
+          end
+
+          ##
+          # Format used to parse TIMESTAMP values. Supports C-style and SQL-style
+          # values.
+          #
+          # @return [String, nil] The timestamp format pattern. `nil` if not set.
+          #
+          # @example
+          #   require "google/cloud/bigquery"
+          #
+          #   bigquery = Google::Cloud::Bigquery.new
+          #
+          #   external_data = bigquery.external "gs://bucket/path/to/data.csv" do |ext|
+          #     ext.timestamp_format = "%Y-%m-%d %H:%M:%S.%f %z"
+          #   end
+          #
+          #   external_data.timestamp_format #=> "%Y-%m-%d %H:%M:%S.%f %z"
+          #
+          def timestamp_format
+            @gapi.timestamp_format
+          end
+
+          ##
+          # Sets the format used to parse TIMESTAMP values. Supports C-style and SQL-style
+          # values.
+          #
+          # @param [String, nil] timestamp_format The timestamp format pattern. `nil` to unset.
+          #
+          # @example
+          #   require "google/cloud/bigquery"
+          #
+          #   bigquery = Google::Cloud::Bigquery.new
+          #
+          #   external_data = bigquery.external "gs://bucket/path/to/data.csv" do |ext|
+          #     ext.timestamp_format = "%Y-%m-%d %H:%M:%S.%f %z"
+          #   end
+          #
+          #   external_data.timestamp_format #=> "%Y-%m-%d %H:%M:%S.%f %z"
+          #
+          def timestamp_format= timestamp_format
+            frozen_check!
+            @gapi.timestamp_format = timestamp_format
+          end
+
+          ##
+          # Format used to parse DATETIME values. Supports C-style and SQL-style
+          # values.
+          #
+          # @return [String, nil] The datetime format pattern. `nil` if not set.
+          #
+          # @example
+          #   require "google/cloud/bigquery"
+          #
+          #   bigquery = Google::Cloud::Bigquery.new
+          #
+          #   external_data = bigquery.external "gs://bucket/path/to/data.csv" do |ext|
+          #     ext.datetime_format = "%Y-%m-%d %H:%M:%S"
+          #   end
+          #
+          #   external_data.datetime_format #=> "%Y-%m-%d %H:%M:%S"
+          #
+          def datetime_format
+            @gapi.datetime_format
+          end
+
+          ##
+          # Sets the format used to parse DATETIME values. Supports C-style and SQL-style
+          # values.
+          #
+          # @param [String, nil] datetime_format The datetime format pattern. `nil` to unset.
+          #
+          # @example
+          #   require "google/cloud/bigquery"
+          #
+          #   bigquery = Google::Cloud::Bigquery.new
+          #
+          #   external_data = bigquery.external "gs://bucket/path/to/data.csv" do |ext|
+          #     ext.datetime_format = "%Y-%m-%d %H:%M:%S"
+          #   end
+          #
+          #   external_data.datetime_format #=> "%Y-%m-%d %H:%M:%S"
+          #
+          def datetime_format= datetime_format
+            frozen_check!
+            @gapi.datetime_format = datetime_format
+          end
+
+          ##
+          # Format used to parse DATE values. Supports C-style and SQL-style
+          # values.
+          #
+          # @return [String, nil] The date format pattern. `nil` if not set.
+          #
+          # @example
+          #   require "google/cloud/bigquery"
+          #
+          #   bigquery = Google::Cloud::Bigquery.new
+          #
+          #   external_data = bigquery.external "gs://bucket/path/to/data.csv" do |ext|
+          #     ext.date_format = "%Y-%m-%d"
+          #   end
+          #
+          #   external_data.date_format #=> "%Y-%m-%d"
+          #
+          def date_format
+            @gapi.date_format
+          end
+
+          ##
+          # Sets the format used to parse DATE values. Supports C-style and SQL-style
+          # values.
+          #
+          # @param [String, nil] date_format The date format pattern. `nil` to unset.
+          #
+          # @example
+          #   require "google/cloud/bigquery"
+          #
+          #   bigquery = Google::Cloud::Bigquery.new
+          #
+          #   external_data = bigquery.external "gs://bucket/path/to/data.csv" do |ext|
+          #     ext.date_format = "%Y-%m-%d"
+          #   end
+          #
+          #   external_data.date_format #=> "%Y-%m-%d"
+          #
+          def date_format= date_format
+            frozen_check!
+            @gapi.date_format = date_format
+          end
+
           ##
           # @private Google API Client object.
           def to_gapi

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

@@ -652,6 +652,90 @@ module Google
           @gapi.configuration.load.clustering.fields if clustering?
         end
 
+        ##
+        # Format used to parse DATE values. Supports C-style and SQL-style
+        # values.
+        #
+        # @return [String, nil] The date format pattern, such as
+        #   `%Y-%m-%d`. `nil` if not set.
+        def date_format
+          @gapi.configuration.load.date_format
+        end
+
+        ##
+        # Format used to parse DATETIME values. Supports C-style and SQL-style
+        # values.
+        #
+        # @return [String, nil] The datetime format pattern, such as
+        #   `%Y-%m-%d %H:%M:%S`. `nil` if not set.
+        def datetime_format
+          @gapi.configuration.load.datetime_format
+        end
+
+        ##
+        # Format used to parse TIME values. Supports C-style and SQL-style
+        # values.
+        #
+        # @return [String, nil] The time format pattern, such as
+        #   `%H:%M:%S`. `nil` if not set.
+        def time_format
+          @gapi.configuration.load.time_format
+        end
+
+        ##
+        # Format used to parse TIMESTAMP values. Supports C-style and SQL-style
+        # values.
+        #
+        # @return [String, nil] The timestamp format pattern, such as
+        #   `%Y-%m-%d %H:%M:%S.%f %z`. `nil` if not set.
+        def timestamp_format
+          @gapi.configuration.load.timestamp_format
+        end
+
+        ##
+        # A list of strings represented as SQL NULL value in a CSV file.
+        # null_marker and null_markers can't be set at the same time. If null_marker
+        # is set, null_markers has to be not set. If null_markers is set, null_marker
+        # has to be not set. If both null_marker and null_markers are set at the same
+        # time, a user error would be thrown. Any strings listed in null_markers,
+        # including empty string would be interpreted as SQL NULL. This applies to all
+        # column types.
+        #
+        # @return [Array<String>] The array of null marker strings.
+        def null_markers
+          @gapi.configuration.load.null_markers || []
+        end
+
+        ##
+        # Controls the strategy used to match loaded columns to the schema. If
+        # not set, a sensible default is chosen based on how the schema is provided.
+        # If autodetect is used, then columns are matched by name. Otherwise,
+        # columns are matched by position. This is done to keep the behavior
+        # backward-compatible.
+        #
+        # Acceptable values are:
+        # * `POSITION` - matches by position. This assumes that the columns are
+        #   ordered the same way as the schema.
+        # * `NAME` - matches by name. This reads the header row as column names
+        #   and reorders columns to match the field names in the schema.
+        #
+        # @return [String, nil] The source column match strategy, such as
+        #   `POSITION`. `nil` if not set.
+        def source_column_match
+          @gapi.configuration.load.source_column_match
+        end
+
+        ##
+        # Time zone used when parsing timestamp values that do not have specific
+        # time zone information (e.g. `2024-04-20 12:34:56`). The expected format
+        # is an IANA timezone string (e.g. `America/Los_Angeles`).
+        #
+        # @return [String, nil] The IANA time zone name, such as
+        #   `America/Los_Angeles`. `nil` if not set.
+        def time_zone
+          @gapi.configuration.load.time_zone
+        end
+
         ##
         # Yielded to a block to accumulate changes for a patch request.
         class Updater < LoadJob
@@ -2585,6 +2669,89 @@ module Google
             @gapi.configuration.load.clustering.fields = fields
           end
 
+          ##
+          # Sets the format used to parse DATE values. Supports C-style and SQL-style
+          # values.
+          #
+          # @param [String, nil] date_format The date format pattern, such as
+          #   `%Y-%m-%d`. `nil` to unset.
+          def date_format= date_format
+            @gapi.configuration.load.update! date_format: date_format
+          end
+
+          ##
+          # Sets the format used to parse DATETIME values. Supports C-style and SQL-style
+          # values.
+          #
+          # @param [String, nil] datetime_format The datetime format pattern, such as
+          #   `%Y-%m-%d %H:%M:%S`. `nil` to unset.
+          def datetime_format= datetime_format
+            @gapi.configuration.load.update! datetime_format: datetime_format
+          end
+
+          ##
+          # Sets the format used to parse TIME values. Supports C-style and SQL-style
+          # values.
+          #
+          # @param [String, nil] time_format The time format pattern, such as
+          #   `%H:%M:%S`. `nil` to unset.
+          def time_format= time_format
+            @gapi.configuration.load.update! time_format: time_format
+          end
+
+          ##
+          # Sets the format used to parse TIMESTAMP values. Supports C-style and SQL-style
+          # values.
+          #
+          # @param [String, nil] timestamp_format The timestamp format pattern, such as
+          #   `%Y-%m-%d %H:%M:%S.%f %z`. `nil` to unset.
+          def timestamp_format= timestamp_format
+            @gapi.configuration.load.update! timestamp_format: timestamp_format
+          end
+
+          ##
+          # Sets the list of strings represented as SQL NULL value in a CSV file.
+          # null_marker and null_markers can't be set at the same time. If null_marker is
+          # set, null_markers has to be not set. If null_markers is set, null_marker has
+          # to be not set. If both null_marker and null_markers are set at the same time,
+          # a user error would be thrown. Any strings listed in null_markers, including
+          # empty string would be interpreted as SQL NULL. This applies to all column
+          # types.
+          #
+          # @param [Array<String>] null_markers The array of null marker strings.
+          def null_markers= null_markers
+            @gapi.configuration.load.update! null_markers: null_markers
+          end
+
+          # Sets the strategy used to match loaded columns to the schema.
+          # If not set, a sensible default is chosen based on how the schema is
+          # provided. If autodetect is used, then columns are matched by name.
+          # Otherwise, columns are matched by position. This is done to keep the
+          # behavior backward-compatible.
+          #
+          # Acceptable values are:
+          # - `POSITION`: matches by position. Assumes columns are ordered the
+          #   same way as the schema.
+          # - `NAME`: matches by name. Reads the header row as column names and
+          #   reorders columns to match the schema.
+          #
+          # @param [String, nil] source_column_match The new source column match value.
+          #   `nil` to unset.
+          def source_column_match= source_column_match
+            @gapi.configuration.load.update! source_column_match: source_column_match
+          end
+
+          ##
+          # Sets the time zone used when parsing timestamp values that do not have
+          # specific time zone information (e.g. `2024-04-20 12:34:56`). The expected
+          # format is an IANA timezone string (e.g. `America/Los_Angeles`).
+          #
+          # @param [String, nil] time_zone The IANA time zone name, such as
+          #   `America/Los_Angeles`. `nil` to unset.
+          def time_zone= time_zone
+            @gapi.configuration.load.update! time_zone: time_zone
+          end
+
           def cancel
             raise "not implemented in #{self.class}"
           end

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

@@ -783,6 +783,9 @@ module Google
         #   `flatten` is false. Optional. The default value is false.
         # @param [String] session_id The ID of an existing session. See the
         #   `create_session` param in {#query_job} and {Job#session_id}.
+        # @param [Boolean] format_options_use_int64_timestamp Output timestamp
+        #   as usec int64. Default is true.
+        #
         # @yield [job] a job configuration object
         # @yieldparam [Google::Cloud::Bigquery::QueryJob::Updater] job a job
         #   configuration object for setting additional options for the query.
@@ -929,6 +932,7 @@ module Google
                   standard_sql: nil,
                   legacy_sql: nil,
                   session_id: nil,
+                  format_options_use_int64_timestamp: true,
                   &block
           job = query_job query,
                           params: params,
@@ -953,7 +957,7 @@ module Google
             end
           end
 
-          job.data max: max
+          job.data max: max, format_options_use_int64_timestamp: format_options_use_int64_timestamp
         end
 
         ##

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

@@ -723,6 +723,8 @@ module Google
         #   identifying the result set.
         # @param [Integer] max Maximum number of results to return.
         # @param [Integer] start Zero-based index of the starting row to read.
+        # @param [Boolean] format_options_use_int64_timestamp Output timestamp
+        #   as usec int64. Default is true.
         #
         # @return [Google::Cloud::Bigquery::Data] An object providing access to
         #   data read from the destination table for the job.
@@ -745,20 +747,21 @@ module Google
         #   # Retrieve the next page of results
         #   data = data.next if data.next?
         #
-        def data token: nil, max: nil, start: nil
+        def data token: nil, max: nil, start: nil, format_options_use_int64_timestamp: true
           return nil unless done?
-          return Data.from_gapi_json({ rows: [] }, nil, @gapi, service) if dryrun?
+          return Data.from_gapi_json({ rows: [] }, nil, @gapi, service, format_options_use_int64_timestamp) if dryrun?
           if ddl? || dml? || !ensure_schema!
             data_hash = { totalRows: nil, rows: [] }
-            return Data.from_gapi_json data_hash, nil, @gapi, service
+            return Data.from_gapi_json data_hash, nil, @gapi, service, format_options_use_int64_timestamp
           end
 
           data_hash = service.list_tabledata destination_table_dataset_id,
                                              destination_table_table_id,
                                              token: token,
                                              max: max,
-                                             start: start
-          Data.from_gapi_json data_hash, destination_table_gapi, @gapi, service
+                                             start: start,
+                                             format_options_use_int64_timestamp: format_options_use_int64_timestamp
+          Data.from_gapi_json data_hash, destination_table_gapi, @gapi, service, format_options_use_int64_timestamp
         end
         alias query_results data
 

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

@@ -244,7 +244,8 @@ module Google
 
         ##
         # Retrieves data from the table.
-        def list_tabledata dataset_id, table_id, max: nil, token: nil, start: nil
+        def list_tabledata dataset_id, table_id, max: nil, token: nil, start: nil,
+                           format_options_use_int64_timestamp: nil
           # The list operation is considered idempotent
           execute backoff: true do
             json_txt = service.list_table_data \
@@ -252,7 +253,8 @@ module Google
               max_results: max,
               page_token:  token,
               start_index: start,
-              options:     { skip_deserialization: true }
+              options:     { skip_deserialization: true },
+              format_options_use_int64_timestamp: format_options_use_int64_timestamp
             JSON.parse json_txt, symbolize_names: true
           end
         end
@@ -456,7 +458,8 @@ module Google
 
         ##
         # Returns the query data for the job
-        def job_query_results job_id, location: nil, max: nil, token: nil, start: nil, timeout: nil
+        def job_query_results job_id, location: nil, max: nil, token: nil,
+                              start: nil, timeout: nil, format_options_use_int64_timestamp: nil
           # The get operation is considered idempotent
           execute backoff: true do
             service.get_job_query_results @project, job_id,
@@ -464,7 +467,8 @@ module Google
                                           max_results: max,
                                           page_token:  token,
                                           start_index: start,
-                                          timeout_ms:  timeout
+                                          timeout_ms:  timeout,
+                                          format_options_use_int64_timestamp: format_options_use_int64_timestamp
           end
         end
 

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

@@ -1701,6 +1701,8 @@ module Google
         #
         # @param [Integer] max Maximum number of results to return.
         # @param [Integer] start Zero-based index of the starting row to read.
+        # @param [Boolean] format_options_use_int64_timestamp Output timestamp
+        #   as usec int64. Default is true.
         #
         # @return [Google::Cloud::Bigquery::Data]
         #
@@ -1735,11 +1737,12 @@ module Google
         #
         # @!group Data
         #
-        def data token: nil, max: nil, start: nil
+        def data token: nil, max: nil, start: nil, format_options_use_int64_timestamp: true
           ensure_service!
           reload! unless resource_full?
-          data_json = service.list_tabledata dataset_id, table_id, token: token, max: max, start: start
-          Data.from_gapi_json data_json, gapi, nil, service
+          data_json = service.list_tabledata dataset_id, table_id, token: token, max: max, start: start,
+format_options_use_int64_timestamp: format_options_use_int64_timestamp
+          Data.from_gapi_json data_json, gapi, nil, service, format_options_use_int64_timestamp
         end
 
         ##

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

@@ -16,7 +16,7 @@
 module Google
   module Cloud
     module Bigquery
-      VERSION = "1.53.0".freeze
+      VERSION = "1.54.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.53.0
+  version: 1.54.0
 platform: ruby
 authors:
 - Mike Moore