Class Snapshot (3.38.0)

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

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

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

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.