Python client library  |  Google Cloud (original) (raw)

Skip to main content

Stay organized with collections Save and categorize content based on your preferences.

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)

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

Seehttps://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 isexact_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 withmax_staleness and min_read_timestamp.

begin()

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, query_options=None, request_options=None, partition=None, retry=<_MethodDefault._DEFAULT_VALUE:

Perform an ExecuteStreamingSql 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_](spanner_v1/types.md#google.cloud.spanner_v1.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.
  • query_options – (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 (google.cloud.spanner_v1.types.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 (Retry) – (Optional) The retry settings for this request.
  • timeout (float) – (Optional) The timeout for this request.
  • data_boost_enabled – (Optional) If this is for a partitioned query and this field is set true, the request will be executed via offline access. If the field is set to true but the request does not setpartition_token, the API will return anINVALID_ARGUMENT error.
• 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, *, retry=<_MethodDefault._DEFAULT_VALUE:

Perform a PartitionQuery 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_](spanner_v1/types.md#google.cloud.spanner_v1.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 (Retry) – (Optional) The retry settings for this request.
  • timeout (float) – (Optional) The timeout for this request.
• Return type
  iterable of bytes
• Returns
  a sequence of partition tokens
• Raises
  ValueError – for single-use snapshots, or if a transaction ID is already associated with the snapshot.

partition_read(table, columns, keyset, index='', partition_size_bytes=None, max_partitions=None, *, retry=<_MethodDefault._DEFAULT_VALUE:

Perform a PartitionRead 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.
  • retry (Retry) – (Optional) The retry settings for this request.
  • timeout (float) – (Optional) The timeout for this request.
• Return type
  iterable of bytes
• Returns
  a sequence of partition tokens
• Raises
  ValueError – for single-use snapshots, or if a transaction ID is already associated with the snapshot.

read(table, columns, keyset, index='', limit=0, partition=None, request_options=None, data_boost_enabled=False, *, retry=<_MethodDefault._DEFAULT_VALUE:

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 withlimit.
  • request_options (google.cloud.spanner_v1.types.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 (Retry) – (Optional) The retry settings for this request.
  • timeout (float) – (Optional) The timeout for this request.
  • data_boost_enabled – (Optional) If this is for a partitioned read and this field is set true, the request will be executed via offline access. If the field is set to true but the request does not setpartition_token, the API will return anINVALID_ARGUMENT error.
• 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.

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-05-02 UTC.