google-cloud-spanner 2.26.0 → 2.28.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cafab317421fcff06f127fb2d156c722f67b8e5d1914ae68d3e0ec8b56db4f76
-  data.tar.gz: 26820cba11c9d0a94d5dbaaff4c28ea0581c25ef3d7a9876d39ef5ca42fe5edc
+  metadata.gz: 850ac8a54d873ff6d92cc7d7b835abd1d0fd980d22529296b036b67d5c4ecbfe
+  data.tar.gz: 585441baf49b27942fddc9876044221965fe9edd475bdf8f6c53f463a3a75cf0
 SHA512:
-  metadata.gz: 58624fe569f909d5923f897fc02c6865c4861dd289ec5b1f58aead9ae01b87968ebd7b5e23d0305e4661011fd4bc2e3479cc08c08ef0c19b320daa2e68300fca
-  data.tar.gz: c011acec4ad559505de0b89e77dae6d2046f7e00768a421f4bd347ff25a3b8ee35673f1714037528e1d13572e054486ded0fd666d253df9b322a2c90ef19a1bf
+  metadata.gz: dca36d5f2479c792b0c7e10051cf52915314c76de12581d09ff8284ae8e591430d2d67f779c71b2956580e4f970054ddcac3d3f8429ed8ced759b8cd0be0339a
+  data.tar.gz: 887212c39b640de69edf12df3bca506494a7bb65c6f0b102eb80cefb3c41e8c3511b027f18334669ab58a9d1ba7114ab1d5bdc83d4982c39521ff4d542b94344

data/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Release History
 
+### 2.28.0 (2025-10-22)
+
+#### Features
+
+* Add support for order_by and lock_hint options ([#182](https://github.com/googleapis/ruby-spanner/issues/182))
+ 
+#### Bug Fixes
+
+* use create Transaction when retrying when enumerating rows in `Spanner::Results` ([#191](https://github.com/googleapis/ruby-spanner/issues/191))
+* run explicit BeginTransaction in Client#transaction for mutation-only payloads ([#191](https://github.com/googleapis/ruby-spanner/issues/191))
+* Transaction#initialize is no longer incorrectly marked as public in documentation ([#191](https://github.com/googleapis/ruby-spanner/issues/191))
+* several field accessors in Partition are no longer incorrectly marked as public in documentation ([#191](https://github.com/googleapis/ruby-spanner/issues/191))
+* session keepalive uses Process.clock_gettime instead of Time.now ([#185](https://github.com/googleapis/ruby-spanner/pull/185)) 
+
+### 2.27.0 (2025-05-28)
+
+#### Features
+
+* Spanner Interval type ([#162](https://github.com/googleapis/ruby-spanner/issues/162)) 
+* Updated required Ruby version to 3.1 ([#160](https://github.com/googleapis/ruby-spanner/issues/160)) 
+
 ### 2.26.0 (2025-03-24)
 
 #### Features

data/lib/google/cloud/spanner/backup/job/list.rb

@@ -33,8 +33,9 @@ module Google
           #   {Google::Cloud::Spanner::Admin::Database.database_admin}.list_backup_operations instead.
           #
           class List < DelegateClass(::Array)
+            # The `Spanner::Service` reference.
             # @private
-            # The gRPC Service object.
+            # @return [::Google::Cloud::Spanner::Service]
             attr_accessor :service
 
             # @private
@@ -148,13 +149,14 @@ module Google
               end
             end
 
-            ##
-            # @private
-            #
-            # New Backup::Job::List from a
+            # Creates a new `Spanner::Backup::Job::List` of `Gapic::Operation` operations from a
             # `Gapic::PagedEnumerable<Google::Longrunning::Operation>`
             # object. Operation object is a backup operation.
-            #
+            # @param grpc [::Gapic::PagedEnumerable<::Google::Longrunning::Operation>]
+            #   Wrapped `Gapic::PagedEnumberable` reference.
+            # @param service [::Google::Cloud::Spanner::Service] A `Spanner::Service` reference.
+            # @private
+            # @return [::Google::Cloud::Spanner::Backup::Job::List]
             def self.from_grpc grpc, service
               operations_client =
                 service.databases.instance_variable_get "@operations_client"

data/lib/google/cloud/spanner/backup/job.rb

@@ -58,12 +58,14 @@ module Google
         #   end
         #
         class Job
-          ##
-          # @private The `Gapic::Operation` gRPC object.
+          # The wrapped `Gapic::Operation` object.
+          # @private
+          # @return [::Gapic::Operation]
           attr_accessor :grpc
 
-          ##
-          # @private The gRPC Service object.
+          # The `Spanner::Service` reference.
+          # @private
+          # @return [::Google::Cloud::Spanner::Service]
           attr_accessor :service
 
           ##
@@ -265,8 +267,11 @@ module Google
             Convert.timestamp_to_time @grpc.metadata.cancel_time
           end
 
-          ##
-          # @private New Backup::Job from a `Gapic::Operation` object.
+          # Create a new Backup::Job from a `Gapic::Operation` object.
+          # @param grpc [::Gapic::Operation`] The wrapped `Gapic::Operation` object.
+          # @param service [::Google::Cloud::Spanner::Service] A `Spanner::Service` reference.
+          # @private
+          # @return [::Google::Cloud::Spanner::Backup::Job]
           def self.from_grpc grpc, service
             new.tap do |job|
               job.instance_variable_set :@grpc, grpc

data/lib/google/cloud/spanner/batch_client.rb

@@ -63,8 +63,18 @@ module Google
       #     new_partition
       #
       class BatchClient
-        ##
-        # @private Creates a new Spanner BatchClient instance.
+        # Creates a new Spanner BatchClient instance.
+        # @param project [::Google::Cloud::Spanner::Project] A `Spanner::Project` ref.
+        # @param instance_id [::String] Instance id, e.g. `"my-instance"`.
+        # @param database_id [::String] Database id, e.g. `"my-database"`.
+        # @param session_labels [::Hash, nil] Optional. The labels to be applied to all sessions
+        #   created by the client. Example: `"team" => "billing-service"`.
+        # @param query_options [::Hash, nil] Optional. A hash of values to specify the custom
+        #   query options for executing SQL query. Example parameter `:optimizer_version`.
+        # @param directed_read_options [::Hash, nil] Optional. Client options used to set
+        #   the `directed_read_options` for all ReadRequests and ExecuteSqlRequests.
+        #   Converts to `V1::DirectedReadOptions`. Example option: `:exclude_replicas`.
+        # @private
         def initialize project, instance_id, database_id, session_labels: nil,
                        query_options: nil, directed_read_options: nil
           @project = project
@@ -404,15 +414,18 @@ module Google
 
         protected
 
-        ##
-        # @private Raise an error unless an active connection to the service is
+        # Raise an error unless an active connection to the service is
         # available.
+        # @private
+        # @raise [StandardError]
+        # @return [nil]
         def ensure_service!
           raise "Must have active connection to service" unless @project.service
         end
 
-        ##
         # New session for each use.
+        # @private
+        # @return [::Google::Cloud::Spanner::Session]
         def session
           ensure_service!
           grpc = @project.service.create_session \

data/lib/google/cloud/spanner/batch_write_results.rb

@@ -92,9 +92,9 @@ module Google
         #
         # @yield [::Google::Cloud::Spanner::BatchWriteResults::BatchResult]
         #
-        def each &block
+        def each(&)
           if defined? @results
-            @results.each(&block)
+            @results.each(&)
           else
             results = []
             @enumerable.each do |grpc|

data/lib/google/cloud/spanner/client.rb

@@ -51,12 +51,26 @@ module Google
       #   end
       #
       class Client
-        ##
+        # A semi-arbitrary constant for thread-wide global parameter name
         # @private
         IS_TRANSACTION_RUNNING_KEY = "ruby_spanner_is_transaction_running".freeze
 
-        ##
-        # @private Creates a new Spanner Client instance.
+        # Creates a new Spanner Client instance.
+        # @param project [::Google::Cloud::Spanner::Project] A `Spanner::Project` ref.
+        # @param instance_id [::String] Instance id, e.g. `"my-instance"`.
+        # @param database_id [::String] Database id, e.g. `"my-database"`.
+        # @param session_labels [::Hash, nil] Optional. The labels to be applied to all sessions
+        #   created by the client. Example: `"team" => "billing-service"`.
+        # @param pool_opts [::Hash] Optional. `Spanner::Pool` creation options.
+        #   Example parameter: `:keepalive`.
+        # @param query_options [::Hash, nil] Optional. A hash of values to specify the custom
+        #   query options for executing SQL query. Example parameter `:optimizer_version`.
+        # @param database_role [::String, nil] Optional. The Spanner session creator role.
+        #   Example: `analyst`
+        # @param directed_read_options [::Hash, nil] Optional. Client options used to set
+        #   the `directed_read_options` for all ReadRequests and ExecuteSqlRequests.
+        #   Converts to `V1::DirectedReadOptions`. Example option: `:exclude_replicas`.
+        # @private
         def initialize project, instance_id, database_id, session_labels: nil,
                        pool_opts: {}, query_options: nil, database_role: nil,
                        directed_read_options: nil
@@ -89,7 +103,7 @@ module Google
         end
 
         # The Spanner project connected to.
-        # @return [Project]
+        # @return [::Google::Cloud::Spanner::Project]
         def project
           @project
         end
@@ -878,6 +892,14 @@ module Google
         #      and all replicas are exhausted without finding a healthy replica,
         #      Spanner will wait for a replica in the list to become available,
         #      requests may fail due to DEADLINE_EXCEEDED errors.
+        # @param [::Google::Cloud::Spanner::V1::ReadRequest::OrderBy] order_by An option to control the order in which
+        #   rows are returned from a read.
+        #   To see the available options refer to
+        #   [Google::Cloud::Spanner::V1::ReadRequest::OrderBy](https://cloud.google.com/ruby/docs/reference/google-cloud-spanner-v1/latest/Google-Cloud-Spanner-V1-ReadRequest-OrderBy)
+        # @param [::Google::Cloud::Spanner::V1::ReadRequest::LockHint] lock_hint A lock hint mechanism for reads done
+        #   within a transaction.
+        #   To see the available options refer to
+        #   [Google::Cloud::Spanner::V1::ReadRequest::LockHint](https://cloud.google.com/ruby/docs/reference/google-cloud-spanner-v1/latest/Google-Cloud-Spanner-V1-ReadRequest-LockHint)
         #
         # @return [Google::Cloud::Spanner::Results] The results of the read.
         #
@@ -962,7 +984,7 @@ module Google
         #
         def read table, columns, keys: nil, index: nil, limit: nil,
                  single_use: nil, request_options: nil, call_options: nil,
-                 directed_read_options: nil
+                 directed_read_options: nil, order_by: nil, lock_hint: nil
           validate_single_use_args! single_use
           ensure_service!
 
@@ -981,7 +1003,9 @@ module Google
                               request_options: request_options,
                               call_options: call_options,
                               directed_read_options: directed_read_options || @directed_read_options,
-                              route_to_leader: route_to_leader
+                              route_to_leader: route_to_leader,
+                              order_by: order_by,
+                              lock_hint: lock_hint
           end
           results
         end
@@ -2102,15 +2126,28 @@ module Google
             begin
               Thread.current[IS_TRANSACTION_RUNNING_KEY] = true
               yield tx
-              transaction_id = nil
-              transaction_id = tx.transaction_id if tx.existing_transaction?
-              commit_resp = @project.service.commit \
-                tx.session.path, tx.mutations,
+
+              unless tx.existing_transaction?
+                # This can happen if the yielded `tx` object was only used to add mutations.
+                # Then it never called any RPCs and didn't create a server-side Transaction object.
+                # In which case we should make an explicit BeginTransaction call here.
+                tx.safe_begin_transaction!(
+                  exclude_from_change_streams: exclude_txn_from_change_streams,
+                  request_options: request_options,
+                  call_options: call_options
+                )
+              end
+
+              transaction_id = tx.transaction_id
+              commit_resp = @project.service.commit(
+                tx.session.path,
+                tx.mutations,
                 transaction_id: transaction_id,
                 exclude_txn_from_change_streams: exclude_txn_from_change_streams,
                 commit_options: commit_options,
                 request_options: request_options,
                 call_options: call_options
+              )
               resp = CommitResponse.from_grpc commit_resp
               commit_options ? resp : resp.timestamp
             rescue GRPC::Aborted,
@@ -2409,17 +2446,21 @@ module Google
           @pool.reset
         end
 
-        ##
+        # Creates a new Session objece.
+        # @param multiplexed [::Boolean] Optional. Default to `false`.
+        #   If `true`, specifies a multiplexed session.
         # @private
-        # Creates a new session object every time.
-        def create_new_session
+        # @return [::Google::Cloud::Spanner::Session]
+        def create_new_session multiplexed: false
           ensure_service!
           grpc = @project.service.create_session \
             Admin::Database::V1::DatabaseAdmin::Paths.database_path(
               project: project_id, instance: instance_id, database: database_id
             ),
             labels: @session_labels,
-            database_role: @database_role
+            database_role: @database_role,
+            multiplexed: multiplexed
+
           Session.from_grpc grpc, @project.service, query_options: @query_options
         end
 

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

@@ -19,6 +19,7 @@ require "stringio"
 require "base64"
 require "bigdecimal"
 require "google/cloud/spanner/data"
+require "google/cloud/spanner/interval"
 
 module Google
   module Cloud
@@ -108,6 +109,8 @@ module Google
               else
                 Google::Protobuf::Value.new string_value: obj.to_json
               end
+            when Interval
+              obj.to_s
             when Google::Protobuf::MessageExts
               proto_class = obj.class
               content = proto_class.encode obj
@@ -252,6 +255,8 @@ module Google
               BigDecimal value.string_value
             when :JSON
               JSON.parse value.string_value
+            when :INTERVAL
+              Interval.parse value.string_value
             when :PROTO
               descriptor = Google::Protobuf::DescriptorPool.generated_pool.lookup(type.proto_type_fqn).msgclass
               content = Base64.decode64 value.string_value

data/lib/google/cloud/spanner/instance.rb

@@ -74,11 +74,16 @@ module Google
       #   end
       #
       class Instance
-        ##
-        # @private The gRPC Service object.
+        # The `Spanner::Service` reference.
+        # @private
+        # @return [::Google::Cloud::Spanner::Service]
         attr_accessor :service
 
-        # @private Creates a new Instance instance.
+        # Creates a new `Spanner::Instance` instance.
+        # @param grpc [::Google::Cloud::Spanner::Admin::Instance::V1::Instance]
+        #   The protobuf `V1::Instance` underlying object.
+        # @param service [::Google::Cloud::Spanner::Service] A `Spanner::Service` reference.
+        # @private
         def initialize grpc, service
           @grpc = grpc
           @service = service
@@ -957,9 +962,13 @@ module Google
           grpc.permissions
         end
 
-        ##
-        # @private Creates a new Instance instance from a
+        # Creates a new Instance instance from a
         # `Google::Cloud::Spanner::Admin::Instance::V1::Instance`.
+        # @param grpc [::Google::Cloud::Spanner::Admin::Instance::V1::Instance]
+        #   The protobuf `V1::Instance` underlying object.
+        # @param service [::Google::Cloud::Spanner::Service] A `Spanner::Service` reference.
+        # @private
+        # @return [::Google::Cloud::Spanner::Instance]
         def self.from_grpc grpc, service
           new grpc, service
         end

data/lib/google/cloud/spanner/interval.rb

@@ -0,0 +1,309 @@
+# Copyright 2017 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 Spanner
+      ##
+      # # Interval
+      #
+      # Represents an interval of time by storing the time components
+      # in months, days and nanoseconds.
+      #
+      # @example
+      #   require "google/cloud/spanner"
+      #
+      #   iso_8601_string = "P1Y2M3DT4H5M6S"
+      #   interval = Google::Cloud::Spanner::Interval::parse iso_8601_string
+      #
+      #   puts interval # "P1Y2M3DT4H5M6S"
+      class Interval
+        NANOSECONDS_IN_A_SECOND = 1_000_000_000
+        NANOSECONDS_IN_A_MINUTE = NANOSECONDS_IN_A_SECOND * 60
+        NANOSECONDS_IN_AN_HOUR = NANOSECONDS_IN_A_MINUTE * 60
+        NANOSECONDS_IN_A_MILLISECOND = 1_000_000
+        NANOSECONDS_IN_A_MICROSECOND = 1_000
+        MAX_MONTHS = 120_000
+        MIN_MONTHS = -MAX_MONTHS
+        MAX_DAYS = 3_660_000
+        MIN_DAYS = -MAX_DAYS
+        MAX_NANOSECONDS = 316_224_000_000_000_000_000
+        MIN_NANOSECONDS = -316_224_000_000_000_000_000
+
+        private_constant :NANOSECONDS_IN_A_SECOND, :NANOSECONDS_IN_A_MINUTE, :NANOSECONDS_IN_AN_HOUR,
+                         :NANOSECONDS_IN_A_MILLISECOND, :NANOSECONDS_IN_A_MICROSECOND, :MAX_MONTHS,
+                         :MIN_MONTHS, :MAX_DAYS, :MIN_DAYS, :MAX_NANOSECONDS, :MIN_NANOSECONDS
+
+        class << self
+          # rubocop:disable Metrics/AbcSize
+          # rubocop:disable Metrics/MethodLength
+
+          # Parses an ISO8601 string and returns an Interval instance.
+          #
+          # The accepted format for the ISO8601 standard is:
+          # `P[n]Y[n]M[n]DT[n]H[n]M[n[.fraction]]S`
+          # where `n` represents an integer number.
+          #
+          # @param interval_string [String] An ISO8601 formatted string.
+          # @return [Google::Cloud::Spanner::Interval]
+          #
+          # @example
+          #   require "google/cloud/spanner"
+          #
+          #   iso_8601_string = "P1Y2M3DT4H5M6S"
+          #   interval = Google::Cloud::Spanner::Interval::parse iso_8601_string
+          #
+          #   puts interval # "P1Y2M3DT4H5M6S"
+          #
+          def parse interval_string
+            pattern = /^
+              P(?!$)
+              (?:(?<years>-?\d+)Y)?
+              (?:(?<months>-?\d+)M)?
+              (?:(?<days>-?\d+)D)?
+              (?:T(?!$)
+              (?:(?<hours>-?\d+)H)?
+              (?:(?<minutes>-?\d+)M)?
+              (?:(?<seconds>-?(?!S)\d*(?:[.,]\d{1,9})?)S)?)?
+              $
+            /x
+            interval_months = 0
+            interval_days = 0
+            interval_nanoseconds = 0
+
+            matches = interval_string.match pattern
+
+            raise ArgumentError, "The provided string does not follow ISO8601 standard." if matches.nil?
+
+            raise ArgumentError, "The provided string does not follow ISO8601 standard." if matches.captures.empty?
+
+            interval_months += matches[:years].to_i * 12 if matches[:years]
+
+            interval_months += matches[:months].to_i if matches[:months]
+
+            interval_days = matches[:days].to_i if matches[:days]
+
+            interval_nanoseconds += matches[:hours].to_i * NANOSECONDS_IN_AN_HOUR if matches[:hours]
+
+            interval_nanoseconds += matches[:minutes].to_i * NANOSECONDS_IN_A_MINUTE if matches[:minutes]
+
+            # Only seconds can be fractional. Both period and comma are valid inputs.
+            if matches[:seconds]
+              interval_nanoseconds += (matches[:seconds].gsub(",", ".").to_f * NANOSECONDS_IN_A_SECOND).to_i
+            end
+
+            Interval.new interval_months, interval_days, interval_nanoseconds
+          end
+
+          # rubocop:enable Metrics/AbcSize
+          # rubocop:enable Metrics/MethodLength
+
+          # Returns an Interval instance with the given months.
+          #
+          # @param months [Integer]
+          # @return [Interval]
+          def from_months months
+            Interval.new months, 0, 0
+          end
+
+          # Returns an Interval instance with the given days.
+          #
+          # @param days [Integer]
+          # @return [Interval]
+          def from_days days
+            Interval.new 0, days, 0
+          end
+
+          # Returns an Interval instance with the given seconds.
+          #
+          # @param seconds [Integer]
+          # @return [Interval]
+          def from_seconds seconds
+            nanoseconds = seconds * NANOSECONDS_IN_A_SECOND
+            Interval.new 0, 0, nanoseconds
+          end
+
+          # Returns an Interval instance with the given milliseconds.
+          #
+          # @param milliseconds [Integer]
+          # @return [Interval]
+          def from_milliseconds milliseconds
+            nanoseconds = milliseconds * NANOSECONDS_IN_A_MILLISECOND
+            Interval.new 0, 0, nanoseconds
+          end
+
+          # Returns an Interval instance with the given microseconds.
+          #
+          # @param microseconds [Integer]
+          # @return [Interval]
+          def from_microseconds microseconds
+            nanoseconds = microseconds * NANOSECONDS_IN_A_MICROSECOND
+            Interval.new 0, 0, nanoseconds
+          end
+
+          # Returns an Interval instance with the given nanoseconds.
+          #
+          # @param nanoseconds [Integer]
+          # @return [Interval]
+          def from_nanoseconds nanoseconds
+            Interval.new 0, 0, nanoseconds
+          end
+        end
+
+
+        # Converts the [Interval] to an ISO8601 Standard string.
+        # @return [String] The interval's ISO8601 string representation.
+        def to_s
+          # Memoizing it as the logic can be a bit heavy.
+          @to_s ||= to_string
+        end
+
+        ##
+        # @private Creates a new Google::Cloud::Spanner instance.
+        def initialize months, days, nanoseconds
+          if months > MAX_MONTHS || months < MIN_MONTHS
+            raise ArgumentError, "The Interval class supports months from #{MIN_MONTHS} to #{MAX_MONTHS}."
+          end
+          @months = months
+
+          if days > MAX_DAYS || days < MIN_DAYS
+            raise ArgumentError, "The Interval class supports days from #{MIN_DAYS} to #{MAX_DAYS}."
+          end
+          @days = days
+
+          if nanoseconds > MAX_NANOSECONDS || nanoseconds < MIN_NANOSECONDS
+            raise ArgumentError, "The Interval class supports nanoseconds from #{MIN_NANOSECONDS} to #{MAX_NANOSECONDS}"
+          end
+          @nanoseconds = nanoseconds
+        end
+
+
+        # @return [Integer] The numbers of months in the time interval.
+        attr_reader :months
+
+        # @return [Integer] The numbers of days in the time interval.
+        attr_reader :days
+
+        # @return [Integer] The numbers of nanoseconds in the time interval.
+        attr_reader :nanoseconds
+
+
+        ##
+        # Standard value equality check for this object.
+        #
+        # @param [Object] other An object to compare with.
+        # @return [Boolean]
+        def eql? other
+          other.is_a?(Interval) &&
+            months == other.months &&
+            days == other.days &&
+            nanoseconds == other.nanoseconds
+        end
+        alias == eql?
+
+        ##
+        # Generate standard hash code for this object.
+        #
+        # @return [Integer]
+        #
+        def hash
+          @hash ||= [@months, @days, @nanoseconds].hash
+        end
+
+        private
+
+        def match_sign value
+          value.negative? ? -1 : 1
+        end
+
+        # rubocop:disable Metrics/AbcSize
+        # rubocop:disable Metrics/CyclomaticComplexity
+        # rubocop:disable Metrics/PerceivedComplexity
+
+        # Converts [Interval] to an ISO8601 Standard string.
+        # @return [String] The interval's ISO8601 string representation.
+        def to_string
+          # Months should be converted to years and months.
+          years = @months.fdiv(12).truncate
+          months = @months % (match_sign(@months) * 12)
+
+          days = @days
+
+          # Nanoseconds should be converted to hours, minutes and seconds components.
+          remaining_nanoseconds = @nanoseconds
+
+          hours = (remaining_nanoseconds.abs / NANOSECONDS_IN_AN_HOUR) * match_sign(remaining_nanoseconds)
+          remaining_nanoseconds %= (match_sign(remaining_nanoseconds) * NANOSECONDS_IN_AN_HOUR)
+          minutes = (remaining_nanoseconds.abs / NANOSECONDS_IN_A_MINUTE) * match_sign(remaining_nanoseconds)
+          remaining_nanoseconds %= (match_sign(remaining_nanoseconds) * NANOSECONDS_IN_A_MINUTE)
+
+          # Only seconds can be fractional, and can have a maximum of 9 characters after decimal. Therefore,
+          # we convert the remaining nanoseconds to an integer for formatting.
+          seconds = (remaining_nanoseconds.abs / NANOSECONDS_IN_A_SECOND) * match_sign(remaining_nanoseconds)
+          nanoseconds = remaining_nanoseconds % (match_sign(remaining_nanoseconds) * NANOSECONDS_IN_A_SECOND)
+
+          interval_string = ["P"]
+
+          interval_string.append "#{years}Y" if years.nonzero?
+
+          interval_string.append "#{months}M" if months.nonzero?
+
+          interval_string.append "#{days}D" if days.nonzero?
+
+          if hours.nonzero? || minutes.nonzero? || seconds.nonzero? || nanoseconds.nonzero?
+            interval_string.append "T"
+
+            interval_string.append "#{hours}H" if hours.nonzero?
+
+            interval_string.append "#{minutes}M" if minutes.nonzero?
+
+            if seconds.nonzero? || nanoseconds.nonzero?
+              interval_string.append "#{format_seconds seconds, nanoseconds}S"
+            end
+          end
+
+          return "P0Y" if interval_string == ["P"]
+
+          interval_string.join
+        end
+
+        # rubocop:enable Metrics/AbcSize
+        # rubocop:enable Metrics/CyclomaticComplexity
+        # rubocop:enable Metrics/PerceivedComplexity
+
+        # Formats decimal values to be in multiples of 3 length.
+        # @return [String]
+        def format_seconds seconds, nanoseconds
+          return seconds if nanoseconds.zero?
+          add_sign = seconds.zero? && nanoseconds.negative?
+
+          nanoseconds_str = nanoseconds.abs.to_s.rjust 9, "0"
+          nanoseconds_str = nanoseconds_str.gsub(/0+$/, "")
+
+          target_length =
+            if nanoseconds_str.length <= 3
+              3
+            elsif nanoseconds_str.length <= 6
+              6
+            else
+              9
+            end
+
+          nanoseconds_str = (nanoseconds_str + ("0" * target_length))[0...target_length]
+          "#{add_sign ? '-' : ''}#{seconds}.#{nanoseconds_str}"
+        end
+      end
+    end
+  end
+end

data/lib/google/cloud/spanner/partition.rb

@@ -44,8 +44,14 @@ module Google
       #   results = batch_snapshot.execute_partition partition
       #
       class Partition
-        # @ private
+        # A `V1::ExecuteSqlRequest` that is related to this partition.
+        # @private
+        # @return [::Google::Cloud::Spanner::V1::ExecuteSqlRequest]
         attr_reader :execute
+
+        # A `V1::ReadRequest` that is related to this partition.
+        # @private
+        # @return [::Google::Cloud::Spanner::V1::ReadRequest]
         attr_reader :read
 
         ##