feat(spanner): add cache updates API

google-cloud-spanner-v1/.owlbot-manifest.json

@@ -63,6 +63,7 @@
     "snippets/spanner/execute_batch_dml.rb",
     "snippets/spanner/execute_sql.rb",
     "snippets/spanner/execute_streaming_sql.rb",
+    "snippets/spanner/fetch_cache_update.rb",
     "snippets/spanner/get_session.rb",
     "snippets/spanner/list_sessions.rb",
     "snippets/spanner/partition_query.rb",

google-cloud-spanner-v1/gapic_metadata.json

@@ -89,6 +89,11 @@
               "methods": [
                 "batch_write"
               ]
+            },
+            "FetchCacheUpdate": {
+              "methods": [
+                "fetch_cache_update"
+              ]
             }
           }
         }

google-cloud-spanner-v1/lib/google/cloud/spanner/v1/spanner/client.rb

@@ -2325,6 +2325,108 @@ def batch_write request, options = nil
               raise ::Google::Cloud::Error.from_error(e)
             end
 
+            ##
+            # Retrieves a cache update for a given database.
+            #
+            # This RPC can be used to warm up the client cache by fetching key recipes
+            # and server information for a given database. It is recommended to call
+            # this RPC at the beginning of the client's lifecycle, prior to any other
+            # data plane operations.
+            #
+            # The cache update is returned as a stream because the response can be too
+            # large to fit into a single `CacheUpdate` message.
+            #
+            # @overload fetch_cache_update(request, options = nil)
+            #   Pass arguments to `fetch_cache_update` via a request object, either of type
+            #   {::Google::Cloud::Spanner::V1::FetchCacheUpdateRequest} or an equivalent Hash.
+            #
+            #   @param request [::Google::Cloud::Spanner::V1::FetchCacheUpdateRequest, ::Hash]
+            #     A request object representing the call parameters. Required. To specify no
+            #     parameters, or to keep all the default parameter values, pass an empty Hash.
+            #   @param options [::Gapic::CallOptions, ::Hash]
+            #     Overrides the default settings for this call, e.g, timeout, retries, etc. Optional.
+            #
+            # @overload fetch_cache_update(database: nil, max_recipe_count: nil, max_range_count: nil)
+            #   Pass arguments to `fetch_cache_update` via keyword arguments. Note that at
+            #   least one keyword argument is required. To specify no parameters, or to keep all
+            #   the default parameter values, pass an empty Hash as a request object (see above).
+            #
+            #   @param database [::String]
+            #     Required. The database for which to retrieve the cache update.
+            #   @param max_recipe_count [::Integer]
+            #     Optional. The maximum number of key recipes to return in the response.
+            #     If not set, a default limit of 100 will be used.
+            #   @param max_range_count [::Integer]
+            #     Optional. The maximum number of ranges to return in the response.
+            #     If not set, a default limit of 10000 will be used.
+            #
+            # @yield [response, operation] Access the result along with the RPC operation
+            # @yieldparam response [::Enumerable<::Google::Cloud::Spanner::V1::CacheUpdate>]
+            # @yieldparam operation [::GRPC::ActiveCall::Operation]
+            #
+            # @return [::Enumerable<::Google::Cloud::Spanner::V1::CacheUpdate>]
+            #
+            # @raise [::Google::Cloud::Error] if the RPC is aborted.
+            #
+            # @example Basic example
+            #   require "google/cloud/spanner/v1"
+            #
+            #   # Create a client object. The client can be reused for multiple calls.
+            #   client = Google::Cloud::Spanner::V1::Spanner::Client.new
+            #
+            #   # Create a request. To set request fields, pass in keyword arguments.
+            #   request = Google::Cloud::Spanner::V1::FetchCacheUpdateRequest.new
+            #
+            #   # Call the fetch_cache_update method to start streaming.
+            #   output = client.fetch_cache_update request
+            #
+            #   # The returned object is a streamed enumerable yielding elements of type
+            #   # ::Google::Cloud::Spanner::V1::CacheUpdate
+            #   output.each do |current_response|
+            #     p current_response
+            #   end
+            #
+            def fetch_cache_update request, options = nil
+              raise ::ArgumentError, "request must be provided" if request.nil?
+
+              request = ::Gapic::Protobuf.coerce request, to: ::Google::Cloud::Spanner::V1::FetchCacheUpdateRequest
+
+              # Converts hash and nil to an options object
+              options = ::Gapic::CallOptions.new(**options.to_h) if options.respond_to? :to_h
+
+              # Customize the options with defaults
+              metadata = @config.rpcs.fetch_cache_update.metadata.to_h
+
+              # Set x-goog-api-client, x-goog-user-project and x-goog-api-version headers
+              metadata[:"x-goog-api-client"] ||= ::Gapic::Headers.x_goog_api_client \
+                lib_name: @config.lib_name, lib_version: @config.lib_version,
+                gapic_version: ::Google::Cloud::Spanner::V1::VERSION
+              metadata[:"x-goog-api-version"] = API_VERSION unless API_VERSION.empty?
+              metadata[:"x-goog-user-project"] = @quota_project_id if @quota_project_id
+
+              header_params = {}
+              if request.database
+                header_params["database"] = request.database
+              end
+
+              request_params_header = header_params.map { |k, v| "#{k}=#{v}" }.join("&")
+              metadata[:"x-goog-request-params"] ||= request_params_header
+
+              options.apply_defaults timeout:      @config.rpcs.fetch_cache_update.timeout,
+                                     metadata:     metadata,
+                                     retry_policy: @config.rpcs.fetch_cache_update.retry_policy
+
+              options.apply_defaults timeout:      @config.timeout,
+                                     metadata:     @config.metadata,
+                                     retry_policy: @config.retry_policy
+
+              @spanner_stub.call_rpc :fetch_cache_update, request, options: options do |response, operation|
+                yield response, operation if block_given?
+              end
+            rescue ::GRPC::BadStatus => e
+              raise ::Google::Cloud::Error.from_error(e)
+            end
+
             ##
             # Configuration class for the Spanner API.
             #
@@ -2588,6 +2690,11 @@ class Rpcs
                 # @return [::Gapic::Config::Method]
                 #
                 attr_reader :batch_write
+                ##
+                # RPC-specific configuration for `fetch_cache_update`
+                # @return [::Gapic::Config::Method]
+                #
+                attr_reader :fetch_cache_update
 
                 # @private
                 def initialize parent_rpcs = nil
@@ -2623,6 +2730,8 @@ def initialize parent_rpcs = nil
                   @partition_read = ::Gapic::Config::Method.new partition_read_config
                   batch_write_config = parent_rpcs.batch_write if parent_rpcs.respond_to? :batch_write
                   @batch_write = ::Gapic::Config::Method.new batch_write_config
+                  fetch_cache_update_config = parent_rpcs.fetch_cache_update if parent_rpcs.respond_to? :fetch_cache_update
+                  @fetch_cache_update = ::Gapic::Config::Method.new fetch_cache_update_config
 
                   yield self if block_given?
                 end

google-cloud-spanner-v1/proto_docs/google/spanner/v1/spanner.rb

@@ -1197,6 +1197,24 @@ class BatchWriteResponse
           include ::Google::Protobuf::MessageExts
           extend ::Google::Protobuf::MessageExts::ClassMethods
         end
+
+        # The request for
+        # {::Google::Cloud::Spanner::V1::Spanner::Client#fetch_cache_update FetchCacheUpdate}.
+        # @!attribute [rw] database
+        #   @return [::String]
+        #     Required. The database for which to retrieve the cache update.
+        # @!attribute [rw] max_recipe_count
+        #   @return [::Integer]
+        #     Optional. The maximum number of key recipes to return in the response.
+        #     If not set, a default limit of 100 will be used.
+        # @!attribute [rw] max_range_count
+        #   @return [::Integer]
+        #     Optional. The maximum number of ranges to return in the response.
+        #     If not set, a default limit of 10000 will be used.
+        class FetchCacheUpdateRequest
+          include ::Google::Protobuf::MessageExts
+          extend ::Google::Protobuf::MessageExts::ClassMethods
+        end
       end
     end
   end

google-cloud-spanner-v1/snippets/snippet_metadata_google.spanner.v1.json

@@ -650,6 +650,46 @@
           "type": "FULL"
         }
       ]
+    },
+    {
+      "region_tag": "spanner_v1_generated_Spanner_FetchCacheUpdate_sync",
+      "title": "Snippet for the fetch_cache_update call in the Spanner service",
+      "description": "This is an auto-generated example demonstrating basic usage of Google::Cloud::Spanner::V1::Spanner::Client#fetch_cache_update.",
+      "file": "spanner/fetch_cache_update.rb",
+      "language": "RUBY",
+      "client_method": {
+        "short_name": "fetch_cache_update",
+        "full_name": "::Google::Cloud::Spanner::V1::Spanner::Client#fetch_cache_update",
+        "async": false,
+        "parameters": [
+          {
+            "type": "::Google::Cloud::Spanner::V1::FetchCacheUpdateRequest",
+            "name": "request"
+          }
+        ],
+        "result_type": "::Google::Cloud::Spanner::V1::CacheUpdate",
+        "client": {
+          "short_name": "Spanner::Client",
+          "full_name": "::Google::Cloud::Spanner::V1::Spanner::Client"
+        },
+        "method": {
+          "short_name": "FetchCacheUpdate",
+          "full_name": "google.spanner.v1.Spanner.FetchCacheUpdate",
+          "service": {
+            "short_name": "Spanner",
+            "full_name": "google.spanner.v1.Spanner"
+          }
+        }
+      },
+      "canonical": true,
+      "origin": "API_DEFINITION",
+      "segments": [
+        {
+          "start": 20,
+          "end": 49,
+          "type": "FULL"
+        }
+      ]
     }
   ]
 }

google-cloud-spanner-v1/snippets/spanner/fetch_cache_update.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+# Copyright 2026 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.
+
+# Auto-generated by gapic-generator-ruby. DO NOT EDIT!
+
+# [START spanner_v1_generated_Spanner_FetchCacheUpdate_sync]
+require "google/cloud/spanner/v1"
+
+##
+# Snippet for the fetch_cache_update call in the Spanner service
+#
+# This snippet has been automatically generated and should be regarded as a code
+# template only. It will require modifications to work:
+# - It may require correct/in-range values for request initialization.
+# - It may require specifying regional endpoints when creating the service
+# client as shown in https://cloud.google.com/ruby/docs/reference.
+#
+# This is an auto-generated example demonstrating basic usage of
+# Google::Cloud::Spanner::V1::Spanner::Client#fetch_cache_update.
+#
+def fetch_cache_update
+  # Create a client object. The client can be reused for multiple calls.
+  client = Google::Cloud::Spanner::V1::Spanner::Client.new
+
+  # Create a request. To set request fields, pass in keyword arguments.
+  request = Google::Cloud::Spanner::V1::FetchCacheUpdateRequest.new
+
+  # Call the fetch_cache_update method to start streaming.
+  output = client.fetch_cache_update request
+
+  # The returned object is a streamed enumerable yielding elements of type
+  # ::Google::Cloud::Spanner::V1::CacheUpdate
+  output.each do |current_response|
+    p current_response
+  end
+end
+# [END spanner_v1_generated_Spanner_FetchCacheUpdate_sync]

google-cloud-spanner-v1/test/google/cloud/spanner/v1/spanner_test.rb

@@ -1228,6 +1228,83 @@ def test_batch_write
     end
   end
 
+  def test_fetch_cache_update
+    # Create GRPC objects.
+    grpc_response = ::Google::Cloud::Spanner::V1::CacheUpdate.new
+    grpc_operation = GRPC::ActiveCall::Operation.new nil
+    grpc_channel = GRPC::Core::Channel.new "localhost:8888", nil, :this_channel_is_insecure
+    grpc_options = {}
+
+    # Create request parameters for a server streaming method.
+    database = "hello world"
+    max_recipe_count = 42
+    max_range_count = 42
+
+    fetch_cache_update_client_stub = ClientStub.new [grpc_response].to_enum, grpc_operation do |name, request, options:|
+      assert_equal :fetch_cache_update, name
+      assert_kind_of ::Google::Cloud::Spanner::V1::FetchCacheUpdateRequest, request
+      assert_equal "hello world", request["database"]
+      assert_equal 42, request["max_recipe_count"]
+      assert_equal 42, request["max_range_count"]
+      refute_nil options
+    end
+
+    Gapic::ServiceStub.stub :new, fetch_cache_update_client_stub do
+      # Create client
+      client = ::Google::Cloud::Spanner::V1::Spanner::Client.new do |config|
+        config.credentials = grpc_channel
+      end
+
+      # Use hash object
+      client.fetch_cache_update({ database: database, max_recipe_count: max_recipe_count, max_range_count: max_range_count }) do |response, operation|
+        assert_kind_of Enumerable, response
+        response.to_a.each do |r|
+          assert_kind_of ::Google::Cloud::Spanner::V1::CacheUpdate, r
+        end
+        assert_equal grpc_operation, operation
+      end
+
+      # Use named arguments
+      client.fetch_cache_update database: database, max_recipe_count: max_recipe_count, max_range_count: max_range_count do |response, operation|
+        assert_kind_of Enumerable, response
+        response.to_a.each do |r|
+          assert_kind_of ::Google::Cloud::Spanner::V1::CacheUpdate, r
+        end
+        assert_equal grpc_operation, operation
+      end
+
+      # Use protobuf object
+      client.fetch_cache_update ::Google::Cloud::Spanner::V1::FetchCacheUpdateRequest.new(database: database, max_recipe_count: max_recipe_count, max_range_count: max_range_count) do |response, operation|
+        assert_kind_of Enumerable, response
+        response.to_a.each do |r|
+          assert_kind_of ::Google::Cloud::Spanner::V1::CacheUpdate, r
+        end
+        assert_equal grpc_operation, operation
+      end
+
+      # Use hash object with options
+      client.fetch_cache_update({ database: database, max_recipe_count: max_recipe_count, max_range_count: max_range_count }, grpc_options) do |response, operation|
+        assert_kind_of Enumerable, response
+        response.to_a.each do |r|
+          assert_kind_of ::Google::Cloud::Spanner::V1::CacheUpdate, r
+        end
+        assert_equal grpc_operation, operation
+      end
+
+      # Use protobuf object with options
+      client.fetch_cache_update(::Google::Cloud::Spanner::V1::FetchCacheUpdateRequest.new(database: database, max_recipe_count: max_recipe_count, max_range_count: max_range_count), grpc_options) do |response, operation|
+        assert_kind_of Enumerable, response
+        response.to_a.each do |r|
+          assert_kind_of ::Google::Cloud::Spanner::V1::CacheUpdate, r
+        end
+        assert_equal grpc_operation, operation
+      end
+
+      # Verify method calls
+      assert_equal 5, fetch_cache_update_client_stub.call_rpc_count
+    end
+  end
+
   def test_configure
     grpc_channel = GRPC::Core::Channel.new "localhost:8888", nil, :this_channel_is_insecure