Class Transaction (3.0.0) 

Transaction(session)

Implement read-write transaction semantics for a session.

Parameter
Name Description
session Session

the session used to perform the commit

Methods

__enter__

__enter__()

Begin with block.

__exit__

__exit__(exc_type, exc_val, exc_tb)

End with block.

batch_update

batch_update(statements)

Perform a batch of DML statements via an ExecuteBatchDml request.

Parameter
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'.
Returns
Type Description
Tuple(status, Sequence[int]) Status code, plus counts of rows affected by each completed DML statement. Note that if the staus 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()

Commit mutations to the database.

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, 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
partition bytes

(Optional) one of the partition tokens returned from partition_query.
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
)

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.
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
)

Perform a ParitionQuery 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.
Exceptions
Type Description
ValueError for single-use snapshots, or if a transaction ID is already associtated 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
)

Perform a ParitionRead 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.
Exceptions
Type Description
ValueError for single-use snapshots, or if a transaction ID is already associtated with the snapshot.
Returns
Type Description
iterable of bytes a sequence of partition tokens

read

read(table, columns, keyset, index="", limit=0, partition=None)

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.
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.