TransactionOptions

Options to use for transactions.

JSON representation
{"excludeTxnFromChangeStreams":boolean,"isolationLevel":enum (IsolationLevel),// Union fieldmode can be only one of the following:"readWrite":{object (ReadWrite)},"partitionedDml":{object (PartitionedDml)},"readOnly":{object (ReadOnly)}// End of list of possible types for union fieldmode.}
Fields
excludeTxnFromChangeStreams

boolean

WhenexcludeTxnFromChangeStreams is set totrue, it prevents read or write transactions from being tracked in change streams.

  • If the DDL optionallow_txn_exclusion is set totrue, then the updates made within this transaction aren't recorded in the change stream.

  • If you don't set the DDL optionallow_txn_exclusion or if it's set tofalse, then the updates made within this transaction are recorded in the change stream.

WhenexcludeTxnFromChangeStreams is set tofalse or not set, modifications from this transaction are recorded in all change streams that are tracking columns modified by these transactions.

TheexcludeTxnFromChangeStreams option can only be specified for read-write or partitioned DML transactions, otherwise the API returns anINVALID_ARGUMENT error.

isolationLevel

enum (IsolationLevel)

Isolation level for the transaction.

Union fieldmode. Required. The type of transaction.mode can be only one of the following:
readWrite

object (ReadWrite)

Transaction may write.

Authorization to begin a read-write transaction requiresspanner.databases.beginOrRollbackReadWriteTransaction permission on thesession resource.

partitionedDml

object (PartitionedDml)

Partitioned DML transaction.

Authorization to begin a Partitioned DML transaction requiresspanner.databases.beginPartitionedDmlTransaction permission on thesession resource.

readOnly

object (ReadOnly)

Transaction does not write.

Authorization to begin a read-only transaction requiresspanner.databases.beginReadOnlyTransaction permission on thesession resource.

ReadWrite

Message type to initiate a read-write transaction. Currently this transaction type has no options.

JSON representation
{"multiplexedSessionPreviousTransactionId":string}
Fields
multiplexedSessionPreviousTransactionId

string (bytes format)

Optional. Clients should pass the transaction ID of the previous transaction attempt that was aborted if this transaction is being executed on a multiplexed session.

A base64-encoded string.

PartitionedDml

This type has no fields.

Message type to initiate a Partitioned DML transaction.

ReadOnly

Message type to initiate a read-only transaction.

JSON representation
{"returnReadTimestamp":boolean,// Union fieldtimestamp_bound can be only one of the following:"strong":boolean,"minReadTimestamp":string,"maxStaleness":string,"readTimestamp":string,"exactStaleness":string// End of list of possible types for union fieldtimestamp_bound.}
Fields
returnReadTimestamp

boolean

If true, the Cloud Spanner-selected read timestamp is included in theTransaction message that describes the transaction.

Union fieldtimestamp_bound. How to choose the timestamp for the read-only transaction.timestamp_bound can be only one of the following:
strong

boolean

sessions.read at a timestamp where all previously committed transactions are visible.

minReadTimestamp

string (Timestamp format)

Executes all reads at a timestamp >=minReadTimestamp.

This is useful for requesting fresher data than some previous read, or data that is fresh enough to observe the effects of some previously committed transaction whose timestamp is known.

Note that this option can only be used in single-use transactions.

A timestamp in RFC3339 UTC "Zulu" format, accurate to nanoseconds. Example:"2014-10-02T15:01:23.045123456Z".

Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples:"2014-10-02T15:01:23Z","2014-10-02T15:01:23.045123456Z" or"2014-10-02T15:01:23+05:30".

maxStaleness

string (Duration format)

sessions.read data at a timestamp >=NOW - maxStaleness seconds. Guarantees that all writes that have committed more than the specified number of seconds ago are visible. Because Cloud Spanner chooses the exact timestamp, this mode works even if the client's local clock is substantially skewed from Cloud Spanner commit timestamps.

Useful for reading the freshest data available at a nearby replica, while bounding the possible staleness if the local replica has fallen behind.

Note that this option can only be used in single-use transactions.

A duration in seconds with up to nine fractional digits, ending with 's'. Example:"3.5s".

readTimestamp

string (Timestamp format)

Executes all reads at the given timestamp. Unlike other modes, reads at a specific timestamp are repeatable; the same read at the same timestamp always returns the same data. If the timestamp is in the future, the read is blocked until the specified timestamp, modulo the read's deadline.

Useful for large scale consistent reads such as mapreduces, or for coordinating many reads against a consistent snapshot of the data.

A timestamp in RFC3339 UTC "Zulu" format, accurate to nanoseconds. Example:"2014-10-02T15:01:23.045123456Z".

Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples:"2014-10-02T15:01:23Z","2014-10-02T15:01:23.045123456Z" or"2014-10-02T15:01:23+05:30".

exactStaleness

string (Duration format)

Executes all reads at a timestamp that isexactStaleness old. The timestamp is chosen soon after the read is started.

Guarantees that all writes that have committed more than the specified number of seconds ago are visible. Because Cloud Spanner chooses the exact timestamp, this mode works even if the client's local clock is substantially skewed from Cloud Spanner commit timestamps.

Useful for reading at nearby replicas without the distributed timestamp negotiation overhead ofmaxStaleness.

A duration in seconds with up to nine fractional digits, ending with 's'. Example:"3.5s".

IsolationLevel

IsolationLevel is used when setting theisolation level for a transaction.

Enums
ISOLATION_LEVEL_UNSPECIFIED

Default value.

If the value is not specified, theSERIALIZABLE isolation level is used.

SERIALIZABLEAll transactions appear as if they executed in a serial order, even if some of the reads, writes, and other operations of distinct transactions actually occurred in parallel. Spanner assigns commit timestamps that reflect the order of committed transactions to implement this property. Spanner offers a stronger guarantee than serializability called external consistency. For more information, seeTrueTime and external consistency.
REPEATABLE_READ

All reads performed during the transaction observe a consistent snapshot of the database, and the transaction is only successfully committed in the absence of conflicts between its updates and any concurrent updates that have occurred since that snapshot. Consequently, in contrast toSERIALIZABLE transactions, only write-write conflicts are detected in snapshot transactions.

This isolation level does not support read-only and partitioned DML transactions.

WhenREPEATABLE_READ is specified on a read-write transaction, the locking semantics default toOPTIMISTIC.

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-12-12 UTC.