Class Snapshot (3.46.0)

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

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.

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

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.