Package com.google.cloud.spanner

Class Options

java.lang.Object

com.google.cloud.spanner.Options

All Implemented Interfaces:

Serializable

public final class Options
extends Object
implements Serializable

Specifies options for various spanner operations

See Also:

• Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static interface	Options.AdminApiOption	Marker interface to mark options applicable to operations in admin API.
static interface	Options.CreateAdminApiOption	Marker interface to mark options applicable to Create operations in admin API.
static interface	Options.CreateUpdateDeleteAdminApiOption	Marker interface to mark options applicable to Create, Update and Delete operations in admin API.
static interface	Options.DeleteAdminApiOption	Marker interface to mark options applicable to Delete operations in admin API.
static interface	Options.ListOption	Marker interface to mark options applicable to list operations in admin API.
static interface	Options.QueryOption	Marker interface to mark options applicable to query operation.
static interface	Options.QueryUpdateOption	Marker interface for options that can be used with both executeQuery and executeUpdate.
static interface	Options.ReadAndQueryOption	Marker interface to mark options applicable to both Read and Query operations
static interface	Options.ReadOption	Marker interface to mark options applicable to read operation
static interface	Options.ReadQueryUpdateTransactionOption	Marker interface to mark options applicable to Read, Query, Update and Write operations
static enum	Options.RpcLockHint
static enum	Options.RpcOrderBy	OrderBy for an RPC invocation.
static enum	Options.RpcPriority	Priority for an RPC invocation.
static interface	Options.TransactionOption	Marker interface to mark options applicable to write operations
static interface	Options.UpdateAdminApiOption	Marker interface to mark options applicable to Update operations in admin API.
static interface	Options.UpdateOption	Marker interface to mark options applicable to update operation.
static interface	Options.UpdateTransactionOption	Marker interface to mark options applicable to Update and Write operations

Method Summary

Modifier and Type	Method	Description
static Options.ReadAndQueryOption	bufferRows(int bufferRows)
static Options.TransactionOption	commitStats()	Specifying this instructs the transaction to request CommitStats from the backend.
static com.google.cloud.spanner.Options.DataBoostQueryOption	dataBoostEnabled(Boolean dataBoostEnabled)	If this is for PartitionedRead or PartitionedQuery and this field is set to `true`, the request will be executed via Spanner independent compute resources.
static Options.ReadAndQueryOption	decodeMode(DecodeMode decodeMode)
static Options.ReadAndQueryOption	directedRead(DirectedReadOptions directedReadOptions)	Option to request DirectedRead for ReadOnlyTransaction and SingleUseTransaction.
boolean	equals(Object o)
static Options.DeleteAdminApiOption	etag(String etag)	Specifying this will help in optimistic concurrency control as a way to help prevent simultaneous deletes of an instance config from overwriting each other.
static Options.UpdateTransactionOption	excludeTxnFromChangeStreams()	Specifying this instructs the transaction to be excluded from being recorded in change streams with the DDL option `allow_txn_exclusion=true`.
static Options.ListOption	filter(String filter)	Specifying this will cause the given filter to be applied to the list operation.
int	hashCode()
static Options.TransactionOption	isolationLevel(TransactionOptions.IsolationLevel isolationLevel)	Specifying this instructs the transaction to request TransactionOptions.IsolationLevel from the backend.
static Options.QueryUpdateOption	lastStatement()	If set to true, this option marks the end of the transaction.
static Options.ReadOption	limit(long limit)	Specifying this will cause the read to yield at most this many rows.
static Options.ReadOption	lockHint(Options.RpcLockHint orderBy)
static Options.TransactionOption	maxCommitDelay(Duration maxCommitDelay)
static Options.TransactionOption	optimisticLock()	Deprecated. Use readLockMode(ReadLockMode) instead.
static Options.ReadOption	orderBy(Options.RpcOrderBy orderBy)	Specifies the order_by to use for the RPC.
static Options.ListOption	pageSize(int pageSize)	Specifying this will cause the list operations to fetch at most this many records in a page.
static Options.ListOption	pageToken(String pageToken)	Specifying this will cause the list operation to start fetching the record from this onwards.
static Options.ReadAndQueryOption	prefetchChunks(int prefetchChunks)	Specifying this will allow the client to prefetch up to prefetchChunks PartialResultSet chunks for read and query.
static Options.ReadQueryUpdateTransactionOption	priority(Options.RpcPriority priority)	Specifies the priority to use for the RPC.
static Options.TransactionOption	readLockMode(TransactionOptions.ReadWrite.ReadLockMode readLockMode)	Returns a Options.TransactionOption to set the desired TransactionOptions.ReadWrite.ReadLockMode for a read-write transaction.
static com.google.cloud.spanner.Options.RequestIdOption	requestId(XGoogSpannerRequestId reqId)
static Options.ReadQueryUpdateTransactionOption	tag(String name)	Specifying this will cause the reads, queries, updates and writes operations statistics collection to be grouped by tag.
String	toString()
static Options.CreateUpdateDeleteAdminApiOption	validateOnly(Boolean validateOnly)	Specifying this will not actually execute a request, and provide the same response.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Method Details

commitStats

public static Options.TransactionOption commitStats()

Specifying this instructs the transaction to request CommitStats from the backend.

optimisticLock

@Deprecated
public static Options.TransactionOption optimisticLock()

Deprecated.

Use readLockMode(ReadLockMode) instead.

Specifying this instructs the transaction to request Optimistic Lock from the backend. In this concurrency mode, operations during the execution phase, i.e., reads and queries, are performed without acquiring locks, and transactional consistency is ensured by running a validation process in the commit phase (when any needed locks are acquired). The validation process succeeds only if there are no conflicting committed transactions (that committed mutations to the read data at a commit timestamp after the read timestamp).

readLockMode

public static Options.TransactionOption readLockMode(TransactionOptions.ReadWrite.ReadLockMode readLockMode)

Returns a Options.TransactionOption to set the desired TransactionOptions.ReadWrite.ReadLockMode for a read-write transaction.

This option controls the locking behavior for read operations and queries within a read-write transaction. It works in conjunction with the transaction's TransactionOptions.IsolationLevel.

• TransactionOptions.ReadWrite.ReadLockMode.PESSIMISTIC: Read locks are acquired immediately on read. This mode only applies to SERIALIZABLE isolation. This mode prevents concurrent modifications by locking data throughout the transaction. This reduces commit-time aborts due to conflicts but can increase how long transactions wait for locks and the overall contention.
• TransactionOptions.ReadWrite.ReadLockMode.OPTIMISTIC: Locks for reads within the transaction are not acquired on read. Instead the locks are acquired on commit to validate that read/queried data has not changed since the transaction started. If a conflict is detected, the transaction will fail. This mode only applies to SERIALIZABLE isolation. This mode defers locking until commit, which can reduce contention and improve throughput. However, be aware that this increases the risk of transaction aborts if there's significant write competition on the same data.
• TransactionOptions.ReadWrite.ReadLockMode.READ_LOCK_MODE_UNSPECIFIED: This is the default if no mode is set. The locking behavior depends on the isolation level:
  • For REPEATABLE_READ isolation: Locking semantics default to OPTIMISTIC. However, validation checks at commit are only performed for queries using SELECT FOR UPDATE, statements with LOCK_SCANNED_RANGES hints, and DML statements.
    Note: It is an error to explicitly set ReadLockMode when the isolation level is REPEATABLE_READ.
  • For all other isolation levels: If the read lock mode is not set, it defaults to PESSIMISTIC locking.

isolationLevel

public static Options.TransactionOption isolationLevel(TransactionOptions.IsolationLevel isolationLevel)

Specifying this instructs the transaction to request TransactionOptions.IsolationLevel from the backend.

excludeTxnFromChangeStreams

public static Options.UpdateTransactionOption excludeTxnFromChangeStreams()

Specifying this instructs the transaction to be excluded from being recorded in change streams with the DDL option `allow_txn_exclusion=true`. This does not exclude the transaction from being recorded in the change streams with the DDL option `allow_txn_exclusion` being false or unset.

requestId

public static com.google.cloud.spanner.Options.RequestIdOption requestId(XGoogSpannerRequestId reqId)

limit

public static Options.ReadOption limit(long limit)

Specifying this will cause the read to yield at most this many rows. This should be greater than 0.

orderBy

public static Options.ReadOption orderBy(Options.RpcOrderBy orderBy)

Specifies the order_by to use for the RPC.

lockHint

public static Options.ReadOption lockHint(Options.RpcLockHint orderBy)

prefetchChunks

public static Options.ReadAndQueryOption prefetchChunks(int prefetchChunks)

Specifying this will allow the client to prefetch up to prefetchChunks PartialResultSet chunks for 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.

bufferRows

public static Options.ReadAndQueryOption bufferRows(int bufferRows)

priority

public static Options.ReadQueryUpdateTransactionOption priority(Options.RpcPriority priority)

Specifies the priority to use for the RPC.

maxCommitDelay

public static Options.TransactionOption maxCommitDelay(Duration maxCommitDelay)

tag

public static Options.ReadQueryUpdateTransactionOption tag(String name)

Specifying this will cause the reads, queries, updates and writes operations statistics collection to be grouped by tag.

pageSize

public static Options.ListOption pageSize(int pageSize)

Specifying this will cause the list operations to fetch at most this many records in a page.

dataBoostEnabled

public static com.google.cloud.spanner.Options.DataBoostQueryOption dataBoostEnabled(Boolean dataBoostEnabled)

If this is for PartitionedRead or PartitionedQuery and this field is set to `true`, the request will be executed via Spanner independent compute resources.

lastStatement

public static Options.QueryUpdateOption lastStatement()

If set to true, this option marks the end of the transaction. The transaction should be committed or aborted after this statement executes, and attempts to execute any other requests against this transaction (including reads and queries) will be rejected. Mixing mutations with statements that are marked as the last statement is not allowed.

For DML statements, setting this option may cause some error reporting to be deferred until commit time (e.g. validation of unique constraints). Given this, successful execution of a DML statement should not be assumed until the transaction commits.

pageToken

public static Options.ListOption pageToken(String pageToken)

Specifying this will cause the list operation to start fetching the record from this onwards.

filter

public static Options.ListOption filter(String filter)

Specifying this will cause the given filter to be applied to the list operation. List operations that support this options are:

• InstanceAdminClient.listInstances(com.google.cloud.spanner.Options.ListOption...)

If this option is passed to any other list operation, it will throw an IllegalArgumentException.

Parameters:

filter - An expression for filtering the results of the request. Filter rules are case insensitive. Some examples of using filters are:

• name:* The entity has a name.
• name:Howl The entity's name contains "howl".
• name:HOWL Equivalent to above.
• NAME:howl Equivalent to above.
• labels.env:* The entity has the label env.
• labels.env:dev The entity has a label env whose value contains "dev".
• name:howl labels.env:dev The entity's name contains "howl" and it has the label env whose value contains "dev".

etag

public static Options.DeleteAdminApiOption etag(String etag)

Specifying this will help in optimistic concurrency control as a way to help prevent simultaneous deletes of an instance config from overwriting each other. Operations that support this option are:

• InstanceAdminClient.deleteInstanceConfig(java.lang.String, com.google.cloud.spanner.Options.DeleteAdminApiOption...)

validateOnly

public static Options.CreateUpdateDeleteAdminApiOption validateOnly(Boolean validateOnly)

Specifying this will not actually execute a request, and provide the same response. Operations that support this option are:

• InstanceAdminClient.createInstanceConfig(com.google.cloud.spanner.InstanceConfigInfo, com.google.cloud.spanner.Options.CreateAdminApiOption...)
• InstanceAdminClient.updateInstanceConfig(com.google.cloud.spanner.InstanceConfigInfo, java.lang.Iterable<com.google.cloud.spanner.InstanceConfigInfo.InstanceConfigField>, com.google.cloud.spanner.Options.UpdateAdminApiOption...)
• InstanceAdminClient.deleteInstanceConfig(java.lang.String, com.google.cloud.spanner.Options.DeleteAdminApiOption...)

directedRead

public static Options.ReadAndQueryOption directedRead(DirectedReadOptions directedReadOptions)

Option to request DirectedRead for ReadOnlyTransaction and SingleUseTransaction.

The DirectedReadOptions can be used to indicate which replicas or regions should be used for non-transactional reads or queries. Not all requests can be sent to non-leader replicas. In particular, some requests such as reads within read-write transactions must be sent to a designated leader replica. These requests ignore DirectedReadOptions.

decodeMode

public static Options.ReadAndQueryOption decodeMode(DecodeMode decodeMode)

toString

public String toString()

Overrides:

toString in class Object

equals

public boolean equals(Object o)

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object