Class SpannerOptions.Builder (6.124.0) 

public static class SpannerOptions.Builder extends ServiceOptions.Builder<Spanner,SpannerOptions,SpannerOptions.Builder>

Builder for SpannerOptions instances.

Inheritance

java.lang.Object > com.google.cloud.ServiceOptions.Builder > SpannerOptions.Builder

Constructors

Builder()

protected Builder()

Methods

build()

public SpannerOptions build()
Returns
Type Description
SpannerOptions
Overrides
com.google.cloud.ServiceOptions.Builder.build()

disableAdministrativeRequestRetries()

public SpannerOptions.Builder disableAdministrativeRequestRetries()

Disables automatic retries of administrative requests that fail if the https://cloud.google.com/spanner/quotas#administrative_limits have been exceeded. You should disable these retries if you intend to handle these errors in your application.

Returns
Type Description
SpannerOptions.Builder

disableAutoTagging()

public SpannerOptions.Builder disableAutoTagging()
Returns
Type Description
SpannerOptions.Builder

disableDirectPath() (deprecated)

public SpannerOptions.Builder disableDirectPath()
Returns
Type Description
SpannerOptions.Builder

disableDynamicChannelPool()

public SpannerOptions.Builder disableDynamicChannelPool()

Disables dynamic channel pooling. When disabled, the client will use a static number of channels as configured by #setNumChannels(int).

Dynamic channel pooling is disabled by default, so this method is typically not needed unless you want to explicitly disable it after enabling it.

Returns
Type Description
SpannerOptions.Builder

disableGrpcGcpExtension()

public SpannerOptions.Builder disableGrpcGcpExtension()

Disables gRPC-GCP extension and uses GAX channel pool instead.

Returns
Type Description
SpannerOptions.Builder

disableLeaderAwareRouting()

public SpannerOptions.Builder disableLeaderAwareRouting()

Disable leader aware routing. Disabling leader aware routing would route all requests in RW/PDML transactions to any region.

Returns
Type Description
SpannerOptions.Builder

enableAutoTagging()

public SpannerOptions.Builder enableAutoTagging()
Returns
Type Description
SpannerOptions.Builder

enableDynamicChannelPool()

public SpannerOptions.Builder enableDynamicChannelPool()

Enables dynamic channel pooling. When enabled, the client will automatically scale the number of channels based on load. This requires the gRPC-GCP extension to be enabled.

Channels that the pool adds during scale-up are primed before they serve traffic: the client executes SELECT 1 with a multiplexed session on the new channel, and the pool only publishes the channel once that succeeds. See #createDefaultDynamicChannelPoolOptions() for the prime timeout and attempt defaults, and #setGcpChannelPoolOptions(GcpChannelPoolOptions) to customize them.

Dynamic channel pooling is disabled by default. Use this method to explicitly enable it. Note that calling #setNumChannels(int) will disable dynamic channel pooling even if this method was called.

Returns
Type Description
SpannerOptions.Builder

enableGrpcGcpExtension()

public SpannerOptions.Builder enableGrpcGcpExtension()

Enables gRPC-GCP extension with the default settings. This option is enabled by default.

Returns
Type Description
SpannerOptions.Builder

enableGrpcGcpExtension(GcpManagedChannelOptions options)

public SpannerOptions.Builder enableGrpcGcpExtension(GcpManagedChannelOptions options)

Enables gRPC-GCP extension and uses provided options for configuration. The metric registry and default Spanner metric labels will be added automatically.

Parameter
Name Description
options com.google.cloud.grpc.GcpManagedChannelOptions
Returns
Type Description
SpannerOptions.Builder

enableLeaderAwareRouting()

public SpannerOptions.Builder enableLeaderAwareRouting()

Enable leader aware routing. Leader aware routing would route all requests in RW/PDML transactions to the leader region.

Returns
Type Description
SpannerOptions.Builder

getAllowedClientLibTokens()

protected Set<String> getAllowedClientLibTokens()
Returns
Type Description
Set<String>
Overrides
com.google.cloud.ServiceOptions.Builder.getAllowedClientLibTokens()

getDatabaseAdminStubSettingsBuilder()

public DatabaseAdminStubSettings.Builder getDatabaseAdminStubSettingsBuilder()

Returns the DatabaseAdminStubSettings.Builder that will be used to build the SpannerRpc. Use this to set custom RetrySettings for individual gRPC methods.

The library will automatically use the defaults defined in DatabaseAdminStubSettings if no custom settings are set. The defaults are the same as the defaults that are used by DatabaseAdminSettings, and are generated from the file spanner_admin_database_gapic.yaml. Retries are configured for idempotent methods but not for non-idempotent methods.

You can set the same RetrySettings for all unary methods by calling this:


 builder
     .getDatabaseAdminStubSettingsBuilder()
     .applyToAllUnaryMethods(
         new ApiFunction<UnaryCallSettings.Builder<?, ?>, Void>() {
           public Void apply(Builder<?, ?> input) {
             input.setRetrySettings(retrySettings);
             return null;
           }
         });
Returns
Type Description
DatabaseAdminStubSettings.Builder

getInstanceAdminStubSettingsBuilder()

public InstanceAdminStubSettings.Builder getInstanceAdminStubSettingsBuilder()

Returns the InstanceAdminStubSettings.Builder that will be used to build the SpannerRpc. Use this to set custom RetrySettings for individual gRPC methods.

The library will automatically use the defaults defined in InstanceAdminStubSettings if no custom settings are set. The defaults are the same as the defaults that are used by InstanceAdminSettings, and are generated from the file spanner_admin_instance_gapic.yaml. Retries are configured for idempotent methods but not for non-idempotent methods.

You can set the same RetrySettings for all unary methods by calling this:


 builder
     .getInstanceAdminStubSettingsBuilder()
     .applyToAllUnaryMethods(
         new ApiFunction<UnaryCallSettings.Builder<?, ?>, Void>() {
           public Void apply(Builder<?, ?> input) {
             input.setRetrySettings(retrySettings);
             return null;
           }
         });
Returns
Type Description
InstanceAdminStubSettings.Builder

getSpannerStubSettingsBuilder()

public SpannerStubSettings.Builder getSpannerStubSettingsBuilder()

Returns the SpannerStubSettings.Builder that will be used to build the SpannerRpc. Use this to set custom RetrySettings for individual gRPC methods.

The library will automatically use the defaults defined in SpannerStubSettings if no custom settings are set. The defaults are the same as the defaults that are used by SpannerSettings, and are generated from the file spanner_gapic.yaml. Retries are configured for idempotent methods but not for non-idempotent methods.

For streaming queries and reads, configure executeStreamingSqlSettings() and streamingReadSettings(), respectively. Set maxAttempts=1 to disable streaming retries; an empty set of retryable codes does not disable retries for intrinsically retryable errors. Defaults allow unlimited streaming resumes. When customizing retry settings, set the total timeout explicitly: calling toBuilder() on the stub's retry settings copies GAPIC's generated one-hour totalTimeout; set it to zero explicitly for unlimited resumes. Limits apply to consecutive failures and reset when the stream makes progress by returning a new resume token.

You can set the same RetrySettings for all unary methods by calling this:


 builder
     .getSpannerStubSettingsBuilder()
     .applyToAllUnaryMethods(
         new ApiFunction<UnaryCallSettings.Builder<?, ?>, Void>() {
           public Void apply(Builder<?, ?> input) {
             input.setRetrySettings(retrySettings);
             return null;
           }
         });
Returns
Type Description
SpannerStubSettings.Builder

login(String username, char[] password)

public SpannerOptions.Builder login(String username, char[] password)

Authenticates to Spanner Omni using the provided username and password, and configures the resulting token for use in subsequent Spanner API calls.

Note: The provided password array will be cleared (zeroed out) by this method for security purposes.

Parameters
Name Description
username String

The username for login.
password char[]

The password for login.
Returns
Type Description
SpannerOptions.Builder

this builder

setAsyncExecutorProvider(SpannerOptions.CloseableExecutorProvider provider)

public SpannerOptions.Builder setAsyncExecutorProvider(SpannerOptions.CloseableExecutorProvider provider)

Sets the ExecutorProvider to use for high-level async calls that need an executor, such as fetching results for an AsyncResultSet.

Async methods will use a sensible default if no custom ExecutorProvider has been set. The default ExecutorProvider uses a cached thread pool containing a maximum of 8 threads. The pool is lazily initialized and will not create any threads if the user application does not use any async methods. It will also scale down the thread usage if the async load allows for that.

Call SpannerOptions#createAsyncExecutorProvider(int, long, TimeUnit) to create a provider with a custom pool size or call FixedCloseableExecutorProvider#create(ScheduledExecutorService) to create a CloseableExecutorProvider from a standard Java ScheduledExecutorService.

Parameter
Name Description
provider SpannerOptions.CloseableExecutorProvider
Returns
Type Description
SpannerOptions.Builder

setAutoTaggingPackages(String[] autoTaggingPackages)

public SpannerOptions.Builder setAutoTaggingPackages(String[] autoTaggingPackages)
Parameter
Name Description
autoTaggingPackages String[]
Returns
Type Description
SpannerOptions.Builder

setAutoTaggingPackages(List<String> autoTaggingPackages)

public SpannerOptions.Builder setAutoTaggingPackages(List<String> autoTaggingPackages)
Parameter
Name Description
autoTaggingPackages List<String>
Returns
Type Description
SpannerOptions.Builder

setAutoTaggingTracerLimit(int autoTaggingTracerLimit)

public SpannerOptions.Builder setAutoTaggingTracerLimit(int autoTaggingTracerLimit)
Parameter
Name Description
autoTaggingTracerLimit int
Returns
Type Description
SpannerOptions.Builder

setAutoThrottleAdministrativeRequests()

public SpannerOptions.Builder setAutoThrottleAdministrativeRequests()

Instructs the client library to automatically throttle the number of administrative requests if the rate of administrative requests generated by this Spanner instance will exceed the administrative limits Cloud Spanner. The default behavior is to not throttle any requests. If the limit is exceeded, Cloud Spanner will return a RESOURCE_EXHAUSTED error. More information on the administrative limits can be found here: https://cloud.google.com/spanner/quotas#administrative_limits. Setting this option is not a guarantee that the rate will never be exceeded, as this option will only throttle requests coming from this client. Additional requests from other clients could still cause the limit to be exceeded.

Returns
Type Description
SpannerOptions.Builder

setBuiltInMetricsEnabled(boolean enableBuiltInMetrics)

public SpannerOptions.Builder setBuiltInMetricsEnabled(boolean enableBuiltInMetrics)

Sets whether to enable or disable the Cloud Monitoring export destination for Spanner built-in client metrics. Built-in metrics are enabled by default.

This flag controls only the default Cloud Monitoring (GCM) export destination on non-Omni clients. It has no effect on a client-metrics provider configured with #setClientMetricsProvider(MetricsProvider); that caller-owned OpenTelemetry destination is controlled separately by the configured provider.

On InstanceType#OMNI clients the GCM sink is unavailable, so this flag does not enable Cloud Monitoring export there.

Parameter
Name Description
enableBuiltInMetrics boolean
Returns
Type Description
SpannerOptions.Builder

setCaCertificate(String caCertificate)

public SpannerOptions.Builder setCaCertificate(String caCertificate)

Configures the server root CA certificate for SSL/TLS authentication. The CA certificate is loaded dynamically and reloaded automatically when rotated on disk.

Parameter
Name Description
caCertificate String

Path to the server root CA certificate file.
Returns
Type Description
SpannerOptions.Builder

setCallContextConfigurator(SpannerOptions.CallContextConfigurator callContextConfigurator)

public SpannerOptions.Builder setCallContextConfigurator(SpannerOptions.CallContextConfigurator callContextConfigurator)

Configures a client-level CallContextConfigurator to apply custom gRPC options, timeouts, or credentials to RPCs executed by this Spanner client.

By default, Spanner clients allow customizing call options on individual requests using gRPC's thread-local io.grpc.Context with #CALL_CONTEXT_CONFIGURATOR_KEY. While useful for fine-grained per-RPC overrides, managing thread-local context can be cumbersome or error-prone in asynchronous, reactive, or multi-threaded pipelines where operations jump across threads. Setting a CallContextConfigurator here applies client-wide across all requests executed by this client instance without requiring thread-local context propagation.

This configurator applies to all RPCs executed by DatabaseClient, Spanner, DatabaseAdminClient, and InstanceAdminClient instances obtained from this client library. Note that raw GAPIC generated clients (such as Spanner#createDatabaseAdminClient() and Spanner#createInstanceAdminClient()) bypass this configurator and should be configured via #setDatabaseAdminStubSettings and #setInstanceAdminStubSettings.

Implementations of CallContextConfigurator configured at the client level must be thread-safe as they are shared across all concurrent operations executed by this client.

If both a client-level configurator and a thread-local configurator (via #CALL_CONTEXT_CONFIGURATOR_KEY) are present when an RPC is executed:

  1. The client-level configurator is evaluated first to establish the baseline call context.
  2. The thread-local configurator is evaluated next using that baseline context.
  3. Any options returned by the thread-local configurator are merged on top of the client-level options, allowing per-call configurations to override or extend client-level defaults.

Example: Configure a client-level stream wait timeout of 30 seconds for streaming SQL queries to detect stalled streams faster:


 SpannerOptions options =
     SpannerOptions.newBuilder()
         .setProjectId("my-project")
         .setCallContextConfigurator(
             new CallContextConfigurator() {
               @Override
               public <ReqT, RespT> ApiCallContext configure(
                   ApiCallContext context, ReqT request, MethodDescriptor<ReqT, RespT> method) {
                 if (method == SpannerGrpc.getExecuteStreamingSqlMethod()) {
                   return context.withStreamWaitTimeoutDuration(Duration.ofSeconds(30));
                 }
                 return null;
               }
             })
         .build();

You can also use SpannerCallContextTimeoutConfigurator if you only need to adjust standard timeouts across RPC types:


 SpannerOptions options =
     SpannerOptions.newBuilder()
         .setProjectId("my-project")
         .setCallContextConfigurator(
             SpannerCallContextTimeoutConfigurator.create()
                 .withExecuteQueryTimeoutDuration(Duration.ofSeconds(30)))
         .build();
Parameter
Name Description
callContextConfigurator SpannerOptions.CallContextConfigurator

the configurator to apply to all RPCs, or null to clear
Returns
Type Description
SpannerOptions.Builder

this Builder instance

setCallCredentialsProvider(SpannerOptions.CallCredentialsProvider callCredentialsProvider)

public SpannerOptions.Builder setCallCredentialsProvider(SpannerOptions.CallCredentialsProvider callCredentialsProvider)

Sets a CallCredentialsProvider that can deliver CallCredentials to use on a per-gRPC basis.

Parameter
Name Description
callCredentialsProvider SpannerOptions.CallCredentialsProvider
Returns
Type Description
SpannerOptions.Builder

setChannelConfigurator(ApiFunction<ManagedChannelBuilder,ManagedChannelBuilder> channelConfigurator)

public SpannerOptions.Builder setChannelConfigurator(ApiFunction<ManagedChannelBuilder,ManagedChannelBuilder> channelConfigurator)

Sets an ApiFunction that will be used to configure the transport channel. This will only be used if no custom TransportChannelProvider has been set.

Parameter
Name Description
channelConfigurator ApiFunction<io.grpc.ManagedChannelBuilder,io.grpc.ManagedChannelBuilder>
Returns
Type Description
SpannerOptions.Builder

setChannelEndpointCacheFactory(ChannelEndpointCacheFactory channelEndpointCacheFactory)

public SpannerOptions.Builder setChannelEndpointCacheFactory(ChannelEndpointCacheFactory channelEndpointCacheFactory)
Parameter
Name Description
channelEndpointCacheFactory ChannelEndpointCacheFactory
Returns
Type Description
SpannerOptions.Builder

setChannelProvider(TransportChannelProvider channelProvider)

public SpannerOptions.Builder setChannelProvider(TransportChannelProvider channelProvider)

Sets the ChannelProvider. GapicSpannerRpc would create a default one if none is provided.

Setting a custom TransportChannelProvider also overrides any other settings that affect the default channel provider. These must be set manually on the custom TransportChannelProvider instead of on SpannerOptions. The settings of SpannerOptions that have no effect if you set a custom TransportChannelProvider are:

  1. #setChannelConfigurator(ApiFunction)
  2. #setHost(String)
  3. #setNumChannels(int)
  4. #setInterceptorProvider(GrpcInterceptorProvider)
  5. #setHeaderProvider(com.google.api.gax.rpc.HeaderProvider)
Parameter
Name Description
channelProvider TransportChannelProvider
Returns
Type Description
SpannerOptions.Builder

setClientLibToken(String clientLibToken)

public SpannerOptions.Builder setClientLibToken(String clientLibToken)
Parameter
Name Description
clientLibToken String
Returns
Type Description
SpannerOptions.Builder
Overrides
com.google.cloud.ServiceOptions.Builder.setClientLibToken(java.lang.String)

setClientMetricsProvider(MetricsProvider metricsProvider)

public SpannerOptions.Builder setClientMetricsProvider(MetricsProvider metricsProvider)

Sets the MetricsProvider that controls client-metrics export to a caller-owned OpenTelemetry destination. Defaults to DefaultMetricsProvider#INSTANCE, which does not configure a caller-owned destination. Use NoopMetricsProvider#INSTANCE to disable caller-owned client metrics explicitly, or CustomOpenTelemetryMetricsProvider to record the same Spanner client instruments on a caller-provided OpenTelemetry instance.

Client metrics are independent of the built-in Cloud Monitoring (GCM) export controlled by #setBuiltInMetricsEnabled(boolean) and the SPANNER_DISABLE_BUILTIN_METRICS environment variable. A custom client-metrics provider keeps recording when the GCM sink is disabled. On non-Omni clients, the GCM and client-metrics destinations can both be active. On InstanceType#OMNI clients, the GCM sink is unavailable and a custom provider is the way to export client metrics.

Client metrics are not recorded when the client runs against the Spanner emulator, regardless of the configured MetricsProvider.

Parameter
Name Description
metricsProvider MetricsProvider
Returns
Type Description
SpannerOptions.Builder

setCompressorName(String compressorName)

public SpannerOptions.Builder setCompressorName(String compressorName)

Sets the compression to use for all gRPC calls. The compressor must be a valid name known in the CompressorRegistry. This will enable compression both from the client to the server and from the server to the client.

Supported values are:

  • gzip: Enable gzip compression
  • identity: Disable compression
  • null: Use default compression
Parameter
Name Description
compressorName String
Returns
Type Description
SpannerOptions.Builder

setDatabaseRole(String databaseRole)

public SpannerOptions.Builder setDatabaseRole(String databaseRole)

Sets the database role that should be used for connections that are created by this instance. The database role that is used determines the access permissions that a connection has. This can for example be used to create connections that are only permitted to access certain tables.

Parameter
Name Description
databaseRole String
Returns
Type Description
SpannerOptions.Builder

setDecodeMode(DecodeMode decodeMode)

public SpannerOptions.Builder setDecodeMode(DecodeMode decodeMode)

Specifies how values that are returned from a query should be decoded and converted from protobuf values into plain Java objects.

Parameter
Name Description
decodeMode DecodeMode
Returns
Type Description
SpannerOptions.Builder

setDefaultClientContext(RequestOptions.ClientContext clientContext)

public SpannerOptions.Builder setDefaultClientContext(RequestOptions.ClientContext clientContext)

Sets the default RequestOptions.ClientContext for all requests.

Parameter
Name Description
clientContext RequestOptions.ClientContext
Returns
Type Description
SpannerOptions.Builder

setDefaultQueryOptions(DatabaseId database, ExecuteSqlRequest.QueryOptions defaultQueryOptions)

public SpannerOptions.Builder setDefaultQueryOptions(DatabaseId database, ExecuteSqlRequest.QueryOptions defaultQueryOptions)

Sets the default QueryOptions that will be used for all queries on the specified database. Query options can also be specified on a per-query basis and as environment variables. The precedence of these settings are:

  1. Query options for a specific query
  2. Environment variables
  3. These default query options

Each QueryOption value that is used for a query is determined individually based on the above precedence. If for example a value for QueryOptions#getOptimizerVersion() is specified in an environment variable and a value for QueryOptions#getOptimizerStatisticsPackage() is specified for a specific query, both values will be used for the specific query. Environment variables are only read during the initialization of a SpannerOptions instance. Changing an environment variable after initializing a SpannerOptions instance will not have any effect on that instance.

Parameters
Name Description
database DatabaseId
defaultQueryOptions ExecuteSqlRequest.QueryOptions
Returns
Type Description
SpannerOptions.Builder

setDefaultTransactionOptions(SpannerOptions.Builder.DefaultReadWriteTransactionOptions defaultReadWriteTransactionOptions)

public SpannerOptions.Builder setDefaultTransactionOptions(SpannerOptions.Builder.DefaultReadWriteTransactionOptions defaultReadWriteTransactionOptions)

Sets the DefaultReadWriteTransactionOptions for read-write transactions.

Parameter
Name Description
defaultReadWriteTransactionOptions SpannerOptions.Builder.DefaultReadWriteTransactionOptions
Returns
Type Description
SpannerOptions.Builder

setDirectedReadOptions(DirectedReadOptions directedReadOptions)

public SpannerOptions.Builder setDirectedReadOptions(DirectedReadOptions directedReadOptions)

Sets the DirectedReadOption that specify which replicas or regions should be used for non-transactional reads or queries.

DirectedReadOptions set at the request level will take precedence over the options set using this method.

An example below of how DirectedReadOptions can be constructed by including a replica.


 DirectedReadOptions.newBuilder()
           .setIncludeReplicas(
               IncludeReplicas.newBuilder()
                   .addReplicaSelections(
                       ReplicaSelection.newBuilder().setLocation("us-east1").build()))
           .build();
           }
Parameter
Name Description
directedReadOptions DirectedReadOptions
Returns
Type Description
SpannerOptions.Builder

setEmulatorHost(String emulatorHost)

public SpannerOptions.Builder setEmulatorHost(String emulatorHost)

Sets the host of an emulator to use. By default the value is read from an environment variable. If the environment variable is not set, this will be null.

Parameter
Name Description
emulatorHost String
Returns
Type Description
SpannerOptions.Builder

setEnableApiTracing(boolean enableApiTracing)

public SpannerOptions.Builder setEnableApiTracing(boolean enableApiTracing)

Creates and sets an com.google.api.gax.tracing.ApiTracer for the RPCs that are executed by this client. Enabling this creates traces for each individual RPC execution, including events/annotations when an RPC is retried or fails. The traces are only exported if an OpenTelemetry or OpenCensus trace exporter has been configured for the client.

Parameter
Name Description
enableApiTracing boolean
Returns
Type Description
SpannerOptions.Builder

setEnableDirectAccess(boolean enableDirectAccess)

public SpannerOptions.Builder setEnableDirectAccess(boolean enableDirectAccess)
Parameter
Name Description
enableDirectAccess boolean
Returns
Type Description
SpannerOptions.Builder

setEnableEndToEndTracing(boolean enableEndToEndTracing)

public SpannerOptions.Builder setEnableEndToEndTracing(boolean enableEndToEndTracing)

Sets whether to enable end to end tracing. Enabling this option will create the trace spans at the Spanner layer. By default, end to end tracing is disabled. Enabling end to end tracing requires OpenTelemetry to be set up. Simply enabling this option won't generate traces at Spanner layer.

Parameter
Name Description
enableEndToEndTracing boolean
Returns
Type Description
SpannerOptions.Builder

setEnableExtendedTracing(boolean enableExtendedTracing)

public SpannerOptions.Builder setEnableExtendedTracing(boolean enableExtendedTracing)

Sets whether to enable extended OpenTelemetry tracing. Enabling this option will add the following additional attributes to the traces that are generated by the client:

  • db.statement: Contains the SQL statement that is being executed.
  • thread.name: The name of the thread that executes the statement.
Parameter
Name Description
enableExtendedTracing boolean
Returns
Type Description
SpannerOptions.Builder

setExperimentalHost(String host) (deprecated)

public SpannerOptions.Builder setExperimentalHost(String host)

Deprecated. Use #setType(InstanceType) instead.

Parameter
Name Description
host String
Returns
Type Description
SpannerOptions.Builder

setGcpChannelPoolOptions(GcpManagedChannelOptions.GcpChannelPoolOptions gcpChannelPoolOptions)

public SpannerOptions.Builder setGcpChannelPoolOptions(GcpManagedChannelOptions.GcpChannelPoolOptions gcpChannelPoolOptions)

Sets the channel pool options for dynamic channel pooling. Use this to configure the dynamic channel pool behavior when #enableDynamicChannelPool() is enabled.

If not set, Spanner-specific defaults will be used (see #createDefaultDynamicChannelPoolOptions()). Values that are left unset in the given options are filled in from those defaults.

Channels that the pool adds during scale-up are primed with SELECT 1 on a multiplexed session before they are published. A channel primer, prime timeout, or prime attempt count that is set in the given options takes precedence over the Spanner primer and its defaults.

Example usage:


 SpannerOptions options = SpannerOptions.newBuilder()
     .setProjectId("my-project")
     .enableDynamicChannelPool()
     .setGcpChannelPoolOptions(
         GcpChannelPoolOptions.newBuilder()
             .setMaxSize(15)
             .setMinSize(3)
             .setInitSize(5)
             .setDynamicScaling(10, 30, Duration.ofMinutes(5))
             .build())
     .build();
Parameter
Name Description
gcpChannelPoolOptions com.google.cloud.grpc.GcpManagedChannelOptions.GcpChannelPoolOptions

the channel pool options to use
Returns
Type Description
SpannerOptions.Builder

this builder for chaining

setGrpcGcpOtelMetricsEnabled(boolean enableGrpcGcpOtelMetrics)

public SpannerOptions.Builder setGrpcGcpOtelMetricsEnabled(boolean enableGrpcGcpOtelMetrics)

Sets whether to enable or disable grpc-gcp OpenTelemetry metrics injection. When disabled, Spanner will not automatically inject an OpenTelemetry io.opentelemetry.api.metrics.Meter into grpc-gcp. If a Meter or MetricRegistry is explicitly provided via GcpManagedChannelOptions, those settings will still be honored.

Parameter
Name Description
enableGrpcGcpOtelMetrics boolean
Returns
Type Description
SpannerOptions.Builder

setGrpcKeepAliveTime(Duration grpcKeepAliveTime)

public SpannerOptions.Builder setGrpcKeepAliveTime(Duration grpcKeepAliveTime)

Sets the keep-alive time for gRPC connections. The default is 120 seconds. Note that the client-side keepalive time is clamped to a minimum of 10 seconds by gRPC.

Parameter
Name Description
grpcKeepAliveTime Duration
Returns
Type Description
SpannerOptions.Builder

setGrpcKeepAliveTimeout(Duration grpcKeepAliveTimeout)

public SpannerOptions.Builder setGrpcKeepAliveTimeout(Duration grpcKeepAliveTimeout)

Sets the keep-alive timeout for gRPC connections. The default is 20 seconds. Note that the client-side keepalive timeout is clamped to a minimum of 20 milliseconds by gRPC.

Parameter
Name Description
grpcKeepAliveTimeout Duration
Returns
Type Description
SpannerOptions.Builder

setHost(String host)

public SpannerOptions.Builder setHost(String host)
Parameter
Name Description
host String
Returns
Type Description
SpannerOptions.Builder
Overrides
com.google.cloud.ServiceOptions.Builder.setHost(java.lang.String)

setInterceptorProvider(GrpcInterceptorProvider interceptorProvider)

public SpannerOptions.Builder setInterceptorProvider(GrpcInterceptorProvider interceptorProvider)

Sets the GrpcInterceptorProvider. GapicSpannerRpc would create a default one if none is provided.

Parameter
Name Description
interceptorProvider GrpcInterceptorProvider
Returns
Type Description
SpannerOptions.Builder

setMonitoringHost(String monitoringHost) (deprecated)

public SpannerOptions.Builder setMonitoringHost(String monitoringHost)

Sets the monitoring host to be used for Built-in client side metrics

Parameter
Name Description
monitoringHost String
Returns
Type Description
SpannerOptions.Builder

setNumChannels(int numChannels)

public SpannerOptions.Builder setNumChannels(int numChannels)

Sets the number of gRPC channels to use. By default 4 channels are created per SpannerOptions.

Parameter
Name Description
numChannels int
Returns
Type Description
SpannerOptions.Builder

setOpenTelemetry(OpenTelemetry openTelemetry)

public SpannerOptions.Builder setOpenTelemetry(OpenTelemetry openTelemetry)

Sets OpenTelemetry object to be used for Spanner Metrics and Traces. GlobalOpenTelemetry will be used as fallback if this options is not set.

Parameter
Name Description
openTelemetry io.opentelemetry.api.OpenTelemetry
Returns
Type Description
SpannerOptions.Builder

setPartitionedDmlTimeout(Duration timeout)

public SpannerOptions.Builder setPartitionedDmlTimeout(Duration timeout)

This method is obsolete. Use #setPartitionedDmlTimeoutDuration(Duration) instead.

Parameter
Name Description
timeout org.threeten.bp.Duration
Returns
Type Description
SpannerOptions.Builder

setPartitionedDmlTimeoutDuration(Duration timeout)

public SpannerOptions.Builder setPartitionedDmlTimeoutDuration(Duration timeout)

Sets a timeout specifically for Partitioned DML statements executed through DatabaseClient#executePartitionedUpdate(Statement, UpdateOption...). The default is 2 hours.

Parameter
Name Description
timeout Duration
Returns
Type Description
SpannerOptions.Builder

setPrefetchChunks(int prefetchChunks)

public SpannerOptions.Builder setPrefetchChunks(int prefetchChunks)

Specifying this will allow the client to prefetch up to prefetchChunks PartialResultSet chunks for each read and query. The data size of each chunk depends on the server implementation but a good rule of thumb is that each chunk will be up to 1 MiB. Larger values reduce the likelihood of blocking while consuming results at the cost of greater memory consumption. prefetchChunks should be greater than 0. To get good performance choose a value that is large enough to allow buffering of chunks for an entire row. Apart from the buffered chunks, there can be at most one more row buffered in the client. This can be overridden on a per read/query basis by Options#prefetchChunks(). If unspecified, we will use a default value (currently 4).

Parameter
Name Description
prefetchChunks int
Returns
Type Description
SpannerOptions.Builder

setRetrySettings(RetrySettings retrySettings)

public SpannerOptions.Builder setRetrySettings(RetrySettings retrySettings)

SpannerOptions.Builder does not support global retry settings, as it creates three different gRPC clients: Spanner, DatabaseAdminClient and InstanceAdminClient. Instead of calling this method, you should set specific RetrySettings for each of the underlying gRPC clients by calling respectively #getSpannerStubSettingsBuilder(), #getDatabaseAdminStubSettingsBuilder() or #getInstanceAdminStubSettingsBuilder().

Parameter
Name Description
retrySettings RetrySettings
Returns
Type Description
SpannerOptions.Builder
Overrides
com.google.cloud.ServiceOptions.Builder.setRetrySettings(com.google.api.gax.retrying.RetrySettings)

setSessionLabels(Map<String,String> sessionLabels)

public SpannerOptions.Builder setSessionLabels(Map<String,String> sessionLabels)

Sets the labels to add to all Sessions created in this client.

Parameter
Name Description
sessionLabels Map<String,String>

Map from label key to label value. Label key and value cannot be null. For more information on valid syntax see api docs .
Returns
Type Description
SpannerOptions.Builder

setSessionPoolOption(SessionPoolOptions sessionPoolOptions)

public SpannerOptions.Builder setSessionPoolOption(SessionPoolOptions sessionPoolOptions)

Sets the options for managing the session pool. If not specified then the default SessionPoolOptions is used.

Parameter
Name Description
sessionPoolOptions SessionPoolOptions
Returns
Type Description
SpannerOptions.Builder

setTrackTransactionStarter()

public SpannerOptions.Builder setTrackTransactionStarter()

Instructs the client library to track the first request of each read/write transaction. This statement will include a BeginTransaction option and will return a transaction id as part of its result. All other statements in the same transaction must wait for this first statement to finish before they can proceed. By setting this option the client library will throw a SpannerException with ErrorCode#DEADLINE_EXCEEDED for any subsequent statement that has waited for at least 60 seconds for the first statement to return a transaction id, including the stacktrace of the initial statement that should have returned a transaction id.

Returns
Type Description
SpannerOptions.Builder

setTransportOptions(TransportOptions transportOptions)

public SpannerOptions.Builder setTransportOptions(TransportOptions transportOptions)
Parameter
Name Description
transportOptions com.google.cloud.TransportOptions
Returns
Type Description
SpannerOptions.Builder
Overrides
com.google.cloud.ServiceOptions.Builder.setTransportOptions(com.google.cloud.TransportOptions)

setType(SpannerOptions.InstanceType instanceType)

public SpannerOptions.Builder setType(SpannerOptions.InstanceType instanceType)

Specifies the type of Spanner instance to connect to (CLOUD or OMNI). Setting it to OMNI is mandatory when connecting to a Spanner Omni instance.

Parameter
Name Description
instanceType SpannerOptions.InstanceType
Returns
Type Description
SpannerOptions.Builder

setUseVirtualThreads(boolean useVirtualThreads)

protected SpannerOptions.Builder setUseVirtualThreads(boolean useVirtualThreads)

Enables/disables the use of virtual threads for the gRPC executor. Setting this option only has any effect on Java 21 and higher. In all other cases, the option will be ignored.

Parameter
Name Description
useVirtualThreads boolean
Returns
Type Description
SpannerOptions.Builder

useClientCert(String clientCertificate, String clientCertificateKey)

public SpannerOptions.Builder useClientCert(String clientCertificate, String clientCertificateKey)

Configures mTLS authentication using the provided client certificate and key files. mTLS via useClientCert is only supported for Spanner Omni instances. Certificates and keys are loaded dynamically and reloaded automatically when rotated on disk.

Parameters
Name Description
clientCertificate String

Path to the client certificate file.
clientCertificateKey String

Path to the client private key file.
Returns
Type Description
SpannerOptions.Builder

usePlainText()

public SpannerOptions.Builder usePlainText()

usePlainText will configure the transport to use plaintext (no TLS) and will set credentials to com.google.cloud.NoCredentials to avoid sending authentication over an unsecured channel.

Returns
Type Description
SpannerOptions.Builder