Class Snapshot (3.65.0)

3.65.0 (latest) 3.64.0 3.63.0 3.62.0 3.61.0 3.60.0 3.59.0 3.58.0 3.57.0 3.56.0 3.55.0 3.54.0 3.53.0 3.52.0 3.51.0 3.50.1 3.46.0 3.45.0 3.44.0 3.43.0 3.42.0 3.41.0 3.40.1 3.39.0 3.38.0 3.37.0 3.36.0 3.35.1 3.34.0 3.33.0 3.32.0 3.31.0 3.30.0 3.29.0 3.28.0 3.27.1 3.26.0 3.25.0 3.24.0 3.23.0 3.22.2 3.21.0 3.20.0 3.19.0 3.18.0 3.17.0 3.16.0 3.15.1 3.14.1 3.13.0 3.12.1 3.11.1 3.10.0 3.9.0 3.8.0 3.7.0 3.6.0 3.5.0 3.4.0 3.3.0 3.2.0 3.1.0 3.0.0 2.1.1 2.0.0 1.19.3 1.18.0 1.17.1 1.16.0 1.15.1 1.14.0 1.13.0 1.12.0 1.11.0 1.10.0

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

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

Methods

begin

begin() -> bytes

Begins a transaction on the database.

Exceptions
Type	Description
ValueError	if the transaction has already begun.

Returns
Type	Description
bytes	identifier for the transaction.

execute_sql

execute_sql(
    sql,
    params=None,
    param_types=None,
    query_mode=None,
    query_options=None,
    request_options=None,
    last_statement=False,
    partition=None,
    retry=_MethodDefault._DEFAULT_VALUE,
    timeout=_MethodDefault._DEFAULT_VALUE,
    data_boost_enabled=False,
    directed_read_options=None,
    column_info=None,
    lazy_decode=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.
last_statement	bool If set to true, this option marks the end of the transaction. The transaction should be committed or aborted after this statement executes, and attempts to execute any other requests against this transaction (including reads and queries) will be rejected. Mixing mutations with statements that are marked as the last statement is not allowed. For DML statements, setting this option may cause some error reporting to be deferred until commit time (e.g. validation of unique constraints). Given this, successful execution of a DML statement should not be assumed until the transaction commits.
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.
lazy_decode	bool (Optional) If this argument is set to true, the iterator returns the underlying protobuf values instead of decoded Python objects. This reduces the time that is needed to iterate through large result sets. The application is responsible for decoding the data that is needed. The returned row iterator contains two functions that can be used for this. iterator.decode_row(row) decodes all the columns in the given row to an array of Python objects. iterator.decode_column(row, column_index) decodes one specific column in the given row.

Exceptions
Type	Description
ValueError	if the Transaction already used to execute a read request, but is not a multi-use transaction or has not begun.

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.

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.

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,
    lazy_decode=False
)

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.
lazy_decode	bool (Optional) If this argument is set to true, the iterator returns the underlying protobuf values instead of decoded Python objects. This reduces the time that is needed to iterate through large result sets. The application is responsible for decoding the data that is needed. The returned row iterator contains two functions that can be used for this. iterator.decode_row(row) decodes all the columns in the given row to an array of Python objects. iterator.decode_column(row, column_index) decodes one specific column in the given row.

Exceptions
Type	Description
ValueError	if the Transaction already used to execute a read request, but is not a multi-use transaction or has not begun.

Returns
Type	Description
StreamedResultSet	a result set instance which can be used to consume rows.