Class Transaction (3.42.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, 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,
    timeout=_MethodDefault._DEFAULT_VALUE,
    data_boost_enabled=False,
    directed_read_options=None,
)

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.
`directed_read_options`	`DirectedReadOptions or dict` (Optional) Request level option used to set the directed_read_options for all ReadRequests and ExecuteSqlRequests that indicates which replicas or regions should be used for non-transactional reads or queries.

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,
    timeout=_MethodDefault._DEFAULT_VALUE
)

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,
    timeout=_MethodDefault._DEFAULT_VALUE
)

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,
    timeout=_MethodDefault._DEFAULT_VALUE
)

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,
    data_boost_enabled=False,
    directed_read_options=None,
    *,
    retry=_MethodDefault._DEFAULT_VALUE,
    timeout=_MethodDefault._DEFAULT_VALUE
)

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.
`directed_read_options`	`DirectedReadOptions or dict` (Optional) Request level option used to set the directed_read_options for all ReadRequests and ExecuteSqlRequests that indicates which replicas or regions should be used for non-transactional reads or queries.

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.