public final class Options implements Serializable
Specifies options for various spanner operations
Static Methods
beginTransactionOption(Options.BeginTransactionOption option)
public static Options.ReadOnlyTransactionOption beginTransactionOption(Options.BeginTransactionOption option)
Specifies how a multi-use read-only transaction should be started. The default is BeginTransactionOption#EXPLICIT.
bufferRows(int bufferRows)
public static Options.ReadAndQueryOption bufferRows(int bufferRows)
| Parameter |
| Name |
Description |
bufferRows |
int
|
clientContext(RequestOptions.ClientContext clientContext)
public static Options.ReadQueryUpdateTransactionOption clientContext(RequestOptions.ClientContext clientContext)
Specifying this will add the given client context to the request. The client context is used to
pass side-channel or configuration information to the backend, such as a user ID for a
parameterized secure view.
commitStats()
public static Options.TransactionOption commitStats()
Specifying this instructs the transaction to request CommitStats from the backend.
dataBoostEnabled(Boolean dataBoostEnabled)
public static 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.
| Parameter |
| Name |
Description |
dataBoostEnabled |
Boolean
|
| Returns |
| Type |
Description |
com.google.cloud.spanner.Options.DataBoostQueryOption |
|
decodeMode(DecodeMode decodeMode)
public static Options.ReadAndQueryOption decodeMode(DecodeMode decodeMode)
directedRead(DirectedReadOptions directedReadOptions)
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.
etag(String 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:
| Parameter |
| Name |
Description |
etag |
String
|
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.
filter(String 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:
If this option is passed to any other list operation, it will throw an
IllegalArgumentException.
| Parameter |
| Name |
Description |
filter |
String
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".
|
isolationLevel(TransactionOptions.IsolationLevel isolationLevel)
public static Options.TransactionOption isolationLevel(TransactionOptions.IsolationLevel isolationLevel)
Specifying this instructs the transaction to request IsolationLevel from the backend.
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.
limit(long 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.
| Parameter |
| Name |
Description |
limit |
long
|
lockHint(Options.RpcLockHint orderBy)
public static Options.ReadOption lockHint(Options.RpcLockHint orderBy)
maxCommitDelay(Duration maxCommitDelay)
public static Options.TransactionOption maxCommitDelay(Duration maxCommitDelay)
| Parameter |
| Name |
Description |
maxCommitDelay |
Duration
|
optimisticLock() (deprecated)
public static Options.TransactionOption optimisticLock()
Deprecated. Use Options#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).
orderBy(Options.RpcOrderBy orderBy)
public static Options.ReadOption orderBy(Options.RpcOrderBy orderBy)
Specifies the order_by to use for the RPC.
pageSize(int 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.
| Parameter |
| Name |
Description |
pageSize |
int
|
pageToken(String pageToken)
public static Options.ListOption pageToken(String pageToken)
Specifying this will cause the list operation to start fetching the record from this onwards.
| Parameter |
| Name |
Description |
pageToken |
String
|
prefetchChunks(int 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.
| Parameter |
| Name |
Description |
prefetchChunks |
int
|
priority(Options.RpcPriority priority)
public static Options.ReadQueryUpdateTransactionOption priority(Options.RpcPriority priority)
Specifies the priority to use for the RPC.
readLockMode(TransactionOptions.ReadWrite.ReadLockMode readLockMode)
public static Options.TransactionOption readLockMode(TransactionOptions.ReadWrite.ReadLockMode readLockMode)
Returns a TransactionOption to set the desired 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 IsolationLevel.
- 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.
- 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.
- 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.
requestId(XGoogSpannerRequestId reqId)
public static Options.RequestIdOption requestId(XGoogSpannerRequestId reqId)
| Returns |
| Type |
Description |
com.google.cloud.spanner.Options.RequestIdOption |
|
tag(String name)
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.
| Parameter |
| Name |
Description |
name |
String
|
validateOnly(Boolean 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:
| Parameter |
| Name |
Description |
validateOnly |
Boolean
|
Methods
equals(Object o)
public boolean equals(Object o)
| Parameter |
| Name |
Description |
o |
Object
|
Overrides
hashCode()
| Returns |
| Type |
Description |
int |
|
Overrides
toString()
| Returns |
| Type |
Description |
String |
|
Overrides
