Snapshot API#

Model a set of read-only queries to a database as a snapshot.

class google.cloud.spanner_v1.snapshot.Snapshot(session, read_timestamp=None, min_read_timestamp=None, max_staleness=None, exact_staleness=None, multi_use=False)[source]#

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

begin()[source]#

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

execute_sql(sql, params=None, param_types=None, query_mode=None, partition=None, retry=<object object>, timeout=<object object>)#

Perform an ExecuteStreamingSql API request.

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

partition_query(sql, params=None, param_types=None, partition_size_bytes=None, max_partitions=None)#

Perform a ParitionQuery 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]]) – (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.

Return type

iterable of bytes

Returns

a sequence of partition tokens

Raises

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

partition_read(table, columns, keyset, index='', partition_size_bytes=None, max_partitions=None)#

Perform a ParitionRead 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.

Return type

iterable of bytes

Returns

a sequence of partition tokens

Raises

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

read(table, columns, keyset, index='', limit=0, partition=None)#

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.

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.