Class Snapshot (3.50.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,
    column_info=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.
`column_info`	`dict` (Optional) dict of mapping between column names and additional column information. An object where column names as keys and custom objects as corresponding values for deserialization. It's specifically useful for data types like protobuf where deserialization logic is on user-specific code. When provided, the custom object enables deserialization of backend-received column data. If not provided, data remains serialized as bytes for Proto Messages and integer for Proto Enums.

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,
    column_info=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`.
`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.
`column_info`	`dict` (Optional) dict of mapping between column names and additional column information. An object where column names as keys and custom objects as corresponding values for deserialization. It's specifically useful for data types like protobuf where deserialization logic is on user-specific code. When provided, the custom object enables deserialization of backend-received column data. If not provided, data remains serialized as bytes for Proto Messages and integer for Proto Enums.

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.