Class Snapshot (3.22.1)

Snapshot(
    session,
    read_timestamp=None,
    min_read_timestamp=None,
    max_staleness=None,
    exact_staleness=None,
    multi_use=False,
)

Allow a set of reads / SQL statements with shared staleness.

See https://cloud.google.com/spanner/reference/rpc/google.spanner.v1#google.spanner.v1.TransactionOptions.ReadOnly

If no options are passed, reads will use the strong model, reading at a timestamp where all previously committed transactions are visible.

Parameters

Name	Description
session	`Session` The session used to perform the commit.
read_timestamp	`datetime.datetime` Execute all reads at the given timestamp.
min_read_timestamp	`datetime.datetime` Execute all reads at a timestamp >= `min_read_timestamp`.
max_staleness	`datetime.timedelta` Read data at a timestamp >= NOW - `max_staleness` seconds.
exact_staleness	`datetime.timedelta` Execute all reads at a timestamp that is `exact_staleness` old.
multi_use	`bool` If true, multiple `read` / `execute_sql` calls can be performed with the snapshot in the context of a read-only transaction, used to ensure isolation / consistency. Incompatible with `max_staleness` and `min_read_timestamp`.

Inheritance

builtins.object > google.cloud.spanner_v1._helpers._SessionWrapper > google.cloud.spanner_v1.snapshot._SnapshotBase > Snapshot

Methods

begin

begin()

Begin a read-only 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.

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.

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.