Class SpannerOptions.Builder (6.56.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

Inherited Members

com.google.cloud.ServiceOptions.Builder.build()

com.google.cloud.ServiceOptions.Builder.getAllowedClientLibTokens()

com.google.cloud.ServiceOptions.Builder.self()

com.google.cloud.ServiceOptions.Builder.setClientLibToken(java.lang.String)

com.google.cloud.ServiceOptions.Builder.setClock(com.google.api.core.ApiClock)

com.google.cloud.ServiceOptions.Builder.setCredentials(com.google.auth.Credentials)

com.google.cloud.ServiceOptions.Builder.setHeaderProvider(com.google.api.gax.rpc.HeaderProvider)

com.google.cloud.ServiceOptions.Builder.setHost(java.lang.String)

com.google.cloud.ServiceOptions.Builder.setProjectId(java.lang.String)

com.google.cloud.ServiceOptions.Builder.setQuotaProjectId(java.lang.String)

com.google.cloud.ServiceOptions.Builder.setRetrySettings(com.google.api.gax.retrying.RetrySettings)

com.google.cloud.ServiceOptions.Builder.setServiceFactory(com.google.cloud.ServiceFactory<ServiceT,OptionsT>)

com.google.cloud.ServiceOptions.Builder.setServiceRpcFactory(com.google.cloud.spi.ServiceRpcFactory<OptionsT>)

com.google.cloud.ServiceOptions.Builder.setTransportOptions(com.google.cloud.TransportOptions)

com.google.cloud.ServiceOptions.Builder.setUniverseDomain(java.lang.String)

Object.clone()

Object.equals(Object)

Object.finalize()

Object.getClass()

Object.hashCode()

Object.notify()

Object.notifyAll()

Object.toString()

Object.wait()

Object.wait(long)

Object.wait(long,int)

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`

disableDirectPath()

public SpannerOptions.Builder disableDirectPath()

Returns
Type	Description
`SpannerOptions.Builder`

disableGrpcGcpExtension()

public SpannerOptions.Builder disableGrpcGcpExtension()

Disables gRPC-GCP extension.

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`

enableGrpcGcpExtension()

public SpannerOptions.Builder enableGrpcGcpExtension()

Enables gRPC-GCP extension with the default settings.

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.

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`

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`

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`

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`

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:

#setChannelConfigurator(ApiFunction)
#setHost(String)
#setNumChannels(int)
#setInterceptorProvider(GrpcInterceptorProvider)
#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)

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`

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:

Query options for a specific query
Environment variables
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`

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`

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`

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`

setPartitionedDmlTimeout(Duration timeout)

public SpannerOptions.Builder setPartitionedDmlTimeout(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`	`org.threeten.bp.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)