Transaction API

Spanner read-write transaction support.

class google.cloud.spanner_v1.transaction.Transaction(session)

Implement read-write transaction semantics for a session.

  • Parameters

    session (Session) – the session used to perform the commit

  • Raises

    ValueError – if session has an existing transaction

_enter_()

Begin with block.

_exit_(exc_type, exc_val, exc_tb)

End with block.

batch_update(statements, request_options=None)

Perform a batch of DML statements via an ExecuteBatchDml request.

begin()

Begin a transaction on the database.

  • Return type

    bytes

  • Returns

    the ID for the newly-begun transaction.

  • Raises

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

commit(return_commit_stats=False, request_options=None)

Commit mutations to the database.

  • Parameters

    • return_commit_stats (bool) – If true, the response will return commit stats which can be accessed though commit_stats.

    • request_options (google.cloud.spanner_v1.types.RequestOptions) – (Optional) Common options for this request. If a dict is provided, it must be of the same form as the protobuf message RequestOptions.

  • Return type

    datetime

  • Returns

    timestamp of the committed changes.

  • Raises

    ValueError – if there are no mutations to commit.

committed( = Non )

Timestamp at which the transaction was successfully committed.

delete(table, keyset)

Delete one or more table rows.

  • Parameters

    • table (str) – Name of the table to be modified.

    • keyset (Keyset) – Keys/ranges identifying rows to delete.

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

Perform an ExecuteStreamingSql API request.

  • Parameters

    • 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](spanner_v1/types.md#google.cloud.spanner_v1.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.

    • query_options – (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 (google.cloud.spanner_v1.types.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 (Retry) – (Optional) The retry settings for this request.

    • timeout (float) – (Optional) The timeout for this request.

  • Return type

    StreamedResultSet

  • Returns

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

  • Raises

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

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

Perform an ExecuteSql API request with DML.

  • Parameters

    • 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](spanner_v1/types.md#google.cloud.spanner_v1.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.

    • query_options (QueryOptions or dict) – (Optional) Options that are provided for query plan stability.

    • request_options (google.cloud.spanner_v1.types.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 (Retry) – (Optional) The retry settings for this request.

    • timeout (float) – (Optional) The timeout for this request.

  • Return type

    int

  • Returns

    Count of rows affected by the DML statement.

insert(table, columns, values)

Insert one or more new table rows.

  • Parameters

    • 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(table, columns, values)

Insert/update one or more table rows.

  • Parameters

    • 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(sql, params=None, param_types=None, partition_size_bytes=None, max_partitions=None, *, retry=<_MethodDefault._DEFAULT_VALUE:

Perform a PartitionQuery API request.

  • Parameters

    • 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](spanner_v1/types.md#google.cloud.spanner_v1.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 (Retry) – (Optional) The retry settings for this request.

    • timeout (float) – (Optional) The timeout for this request.

  • Return type

    iterable of bytes

  • Returns

    a sequence of partition tokens

  • Raises

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

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

Perform a PartitionRead API request for rows in a table.

  • Parameters

    • 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 (Retry) – (Optional) The retry settings for this request.

    • timeout (float) – (Optional) The timeout for this request.

  • Return type

    iterable of bytes

  • Returns

    a sequence of partition tokens

  • Raises

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

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

Perform a StreamingRead API request for rows in a table.

  • Parameters

    • 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 (google.cloud.spanner_v1.types.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 (Retry) – (Optional) The retry settings for this request.

    • timeout (float) – (Optional) The timeout for this request.

  • Return type

    StreamedResultSet

  • Returns

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

  • Raises

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

replace(table, columns, values)

Replace one or more table rows.

  • Parameters

    • 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()

Roll back a transaction on the database.

update(table, columns, values)

Update one or more existing table rows.

  • Parameters

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