Class Transaction (3.22.0)

Transaction(session)

Implement read-write transaction semantics for a session.

Parameter

Name	Description
session	`Session` the session used to perform the commit

Inheritance

builtins.object > google.cloud.spanner_v1._helpers._SessionWrapper > google.cloud.spanner_v1.snapshot._SnapshotBase > builtins.object > google.cloud.spanner_v1._helpers._SessionWrapper > google.cloud.spanner_v1.batch._BatchBase > Transaction

Methods

enter

__enter__()

Begin with block.

exit

__exit__(exc_type, exc_val, exc_tb)

End with block.

batch_update

batch_update(statements, request_options=None)

Perform a batch of DML statements via an ExecuteBatchDml request.

Parameters

Name	Description
statements	`Sequence[Union[ str, Tuple[str, Dict[str, Any], Dict[str, Union[dict, .types.Type]]]]]` List of DML statements, with optional params / param types. If passed, 'params' is a dict mapping names to the values for parameter replacement. Keys must match the names used in the corresponding DML statement. If 'params' is passed, 'param_types' must also be passed, as a dict mapping names to the type of value passed in 'params'.
request_options	`RequestOptions` (Optional) Common options for this request. If a dict is provided, it must be of the same form as the protobuf message RequestOptions.

Returns

Type	Description
Tuple(status, Sequence[int])	Status code, plus counts of rows affected by each completed DML statement. Note that if the status code is not ``OK``, the statement triggering the error will not have an entry in the list, nor will any statements following that one.

begin

begin()

Begin a transaction on the database.

Exceptions

Type	Description
ValueError	if the transaction is already begun, committed, or rolled back.

Returns

Type	Description
bytes	the ID for the newly-begun transaction.

commit

commit(return_commit_stats=False, request_options=None)

Commit mutations to the database.

Parameters

Name	Description
return_commit_stats	`bool` If true, the response will return commit stats which can be accessed though commit_stats.
request_options	`RequestOptions` (Optional) Common options for this request. If a dict is provided, it must be of the same form as the protobuf message RequestOptions.

Exceptions

Type	Description
ValueError	if there are no mutations to commit.

Returns

Type	Description
datetime	timestamp of the committed changes.

delete

delete(table, keyset)

Delete one or more table rows.

Parameters

Name	Description
table	`str` Name of the table to be modified.
keyset	`Keyset` Keys/ranges identifying rows to delete.

execute_sql

execute_sql(sql, params=None, param_types=None, query_mode=None, query_options=None, request_options=None, partition=None, retry=<_MethodDefault._DEFAULT_VALUE: <object object>>, timeout=<_MethodDefault._DEFAULT_VALUE: <object object>>)

Perform an ExecuteStreamingSql API request.

Parameters

Name	Description
sql	`str` SQL query statement
params	`dict, {str -> column value}` values for parameter replacement. Keys must match the names used in `sql`.
param_types	`dict[str -> Union[dict, .types.Type]]` (Optional) maps explicit types for one or more param values; required if parameters are passed.
query_mode	`QueryMode` Mode governing return of results / query plan. See: `QueryMode <https://cloud.google.com/spanner/reference/rpc/google.spanner.v1#google.spanner.v1.ExecuteSqlRequest.QueryMode>`_.
query_options	QueryOptions or `dict` (Optional) Query optimizer configuration to use for the given query. If a dict is provided, it must be of the same form as the protobuf message QueryOptions
request_options	`RequestOptions` (Optional) Common options for this request. If a dict is provided, it must be of the same form as the protobuf message RequestOptions.
partition	`bytes` (Optional) one of the partition tokens returned from `partition_query`.
retry	`google.api_core.retry.Retry` (Optional) The retry settings for this request.
timeout	`float` (Optional) The timeout for this request.

Exceptions

Type	Description
ValueError	for reuse of single-use snapshots, or if a transaction ID is already pending for multiple-use snapshots.

Returns

Type	Description
StreamedResultSet	a result set instance which can be used to consume rows.

execute_update

execute_update(dml, params=None, param_types=None, query_mode=None, query_options=None, request_options=None, *, retry=<_MethodDefault._DEFAULT_VALUE: <object object>>, timeout=<_MethodDefault._DEFAULT_VALUE: <object object>>)

Perform an ExecuteSql API request with DML.

Parameters

Name	Description
dml	`str` SQL DML statement
params	`dict, {str -> column value}` values for parameter replacement. Keys must match the names used in `dml`.
param_types	`dict[str -> Union[dict, .types.Type]]` (Optional) maps explicit types for one or more param values; required if parameters are passed.
query_mode	`QueryMode` Mode governing return of results / query plan. See: `QueryMode <https://cloud.google.com/spanner/reference/rpc/google.spanner.v1#google.spanner.v1.ExecuteSqlRequest.QueryMode>`_.
query_options	QueryOptions or `dict` (Optional) Options that are provided for query plan stability.
request_options	`RequestOptions` (Optional) Common options for this request. If a dict is provided, it must be of the same form as the protobuf message RequestOptions.
retry	`google.api_core.retry.Retry` (Optional) The retry settings for this request.
timeout	`float` (Optional) The timeout for this request.

Returns

Type	Description
int	Count of rows affected by the DML statement.

insert

insert(table, columns, values)

Insert one or more new table rows.

Parameters

Name	Description
table	`str` Name of the table to be modified.
columns	`list of str` Name of the table columns to be modified.
values	`list of lists` Values to be modified.

insert_or_update

insert_or_update(table, columns, values)

Insert/update one or more table rows.

Parameters

Name	Description
table	`str` Name of the table to be modified.
columns	`list of str` Name of the table columns to be modified.
values	`list of lists` Values to be modified.

partition_query

partition_query(sql, params=None, param_types=None, partition_size_bytes=None, max_partitions=None, *, retry=<_MethodDefault._DEFAULT_VALUE: <object object>>, timeout=<_MethodDefault._DEFAULT_VALUE: <object object>>)

Perform a PartitionQuery API request.

Parameters

Name	Description
sql	`str` SQL query statement
params	`dict, {str -> column value}` values for parameter replacement. Keys must match the names used in `sql`.
param_types	`dict[str -> Union[dict, .types.Type]]` (Optional) maps explicit types for one or more param values; required if parameters are passed.
partition_size_bytes	`int` (Optional) desired size for each partition generated. The service uses this as a hint, the actual partition size may differ.
max_partitions	`int` (Optional) desired maximum number of partitions generated. The service uses this as a hint, the actual number of partitions may differ.
retry	`google.api_core.retry.Retry` (Optional) The retry settings for this request.
timeout	`float` (Optional) The timeout for this request.

Exceptions

Type	Description
ValueError	for single-use snapshots, or if a transaction ID is already associated with the snapshot.

Returns

Type	Description
iterable of bytes	a sequence of partition tokens

partition_read

partition_read(table, columns, keyset, index='', partition_size_bytes=None, max_partitions=None, *, retry=<_MethodDefault._DEFAULT_VALUE: <object object>>, timeout=<_MethodDefault._DEFAULT_VALUE: <object object>>)

Perform a PartitionRead API request for rows in a table.

Parameters

Name	Description
table	`str` name of the table from which to fetch data
columns	`list of str` names of columns to be retrieved
keyset	`KeySet` keys / ranges identifying rows to be retrieved
index	`str` (Optional) name of index to use, rather than the table's primary key
partition_size_bytes	`int` (Optional) desired size for each partition generated. The service uses this as a hint, the actual partition size may differ.
max_partitions	`int` (Optional) desired maximum number of partitions generated. The service uses this as a hint, the actual number of partitions may differ.
retry	`google.api_core.retry.Retry` (Optional) The retry settings for this request.
timeout	`float` (Optional) The timeout for this request.

Exceptions

Type	Description
ValueError	for single-use snapshots, or if a transaction ID is already associated with the snapshot.

Returns

Type	Description
iterable of bytes	a sequence of partition tokens

read

read(table, columns, keyset, index='', limit=0, partition=None, request_options=None, *, retry=<_MethodDefault._DEFAULT_VALUE: <object object>>, timeout=<_MethodDefault._DEFAULT_VALUE: <object object>>)

Perform a StreamingRead API request for rows in a table.

Parameters

Name	Description
table	`str` name of the table from which to fetch data
columns	`list of str` names of columns to be retrieved
keyset	`KeySet` keys / ranges identifying rows to be retrieved
index	`str` (Optional) name of index to use, rather than the table's primary key
limit	`int` (Optional) maximum number of rows to return. Incompatible with `partition`.
partition	`bytes` (Optional) one of the partition tokens returned from `partition_read`. Incompatible with `limit`.
request_options	`RequestOptions` (Optional) Common options for this request. If a dict is provided, it must be of the same form as the protobuf message RequestOptions. Please note, the `transactionTag` setting will be ignored for snapshot as it's not supported for read-only transactions.
retry	`google.api_core.retry.Retry` (Optional) The retry settings for this request.
timeout	`float` (Optional) The timeout for this request.

Exceptions

Type	Description
ValueError	for reuse of single-use snapshots, or if a transaction ID is already pending for multiple-use snapshots.

Returns

Type	Description
StreamedResultSet	a result set instance which can be used to consume rows.

replace

replace(table, columns, values)

Replace one or more table rows.

Parameters

Name	Description
table	`str` Name of the table to be modified.
columns	`list of str` Name of the table columns to be modified.
values	`list of lists` Values to be modified.

rollback

rollback()

Roll back a transaction on the database.

update

update(table, columns, values)

Update one or more existing table rows.

Parameters

Name	Description
table	`str` Name of the table to be modified.
columns	`list of str` Name of the table columns to be modified.
values	`list of lists` Values to be modified.