Class Session (3.51.0) 

Session(database, labels=None, database_role=None)

Representation of a Cloud Spanner Session.

We can use a Session to:

  • create the session
  • Use exists to check for the existence of the session
  • drop the session

Parameters
Name Description
database Database

The database to which the session is bound.
labels dict (str -> str)

(Optional) User-assigned labels for the session.
database_role str

(Optional) user-assigned database_role for the session.

Properties

database_role

User-assigned database-role for the session.

Returns
Type Description
str the database role str (None if no database role were assigned).

labels

User-assigned labels for the session.

Returns
Type Description
dict (str -> str) the labels dict (empty if no labels were assigned.

last_use_time

"Approximate last use time of this session

Returns
Type Description
datetime the approximate last use time of this session

name

Session name used in requests.

"projects/../instances/../databases/../sessions/{session_id}"

Exceptions
Type Description
ValueError if session is not yet created
Returns
Type Description
str The session name.

session_id

Read-only ID, set by the back-end during create.

Methods

batch

batch()

Factory to create a batch for this session.

Exceptions
Type Description
ValueError if the session has not yet been created.
Returns
Type Description
Batch a batch bound to this session

create

create()

Create this session, bound to its database.

See https://cloud.google.com/spanner/reference/rpc/google.spanner.v1#google.spanner.v1.Spanner.CreateSession

Exceptions
Type Description
ValueError if session_id is already set.

delete

delete()

Delete this session.

See https://cloud.google.com/spanner/reference/rpc/google.spanner.v1#google.spanner.v1.Spanner.GetSession

Exceptions
Type Description
ValueError if session_id is not already set.
NotFound if the session does not exist

execute_sql

execute_sql(
    sql,
    params=None,
    param_types=None,
    query_mode=None,
    query_options=None,
    request_options=None,
    retry=_MethodDefault._DEFAULT_VALUE,
    timeout=_MethodDefault._DEFAULT_VALUE,
    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 -> google.spanner.v1.types.TypeCode}

(Optional) explicit types for one or more param values; overrides default type detection on the back-end.
query_mode google.spanner.v1.types.ExecuteSqlRequest.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) Options that are provided for query plan stability.
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.
retry google.api_core.retry.Retry

(Optional) The retry settings for this request.
timeout float

(Optional) The timeout for this request.
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.
Returns
Type Description
StreamedResultSet a result set instance which can be used to consume rows.

exists

exists()

Test for the existence of this session.

See https://cloud.google.com/spanner/reference/rpc/google.spanner.v1#google.spanner.v1.Spanner.GetSession

Returns
Type Description
bool True if the session exists on the back-end, else False.

ping

ping()

Ping the session to keep it alive by executing "SELECT 1".

Exceptions
Type Description
ValueError if session_id is not already set.

read

read(table, columns, keyset, index="", limit=0, 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
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.
Returns
Type Description
StreamedResultSet a result set instance which can be used to consume rows.

run_in_transaction

run_in_transaction(func, *args, **kw)

Perform a unit of work in a transaction, retrying on abort.

Parameters
Name Description
func callable

takes a required positional argument, the transaction, and additional positional / keyword arguments as supplied by the caller.
args tuple

additional positional arguments to be passed to func.
kw dict

(Optional) keyword arguments to be passed to func. If passed: "timeout_secs" will be removed and used to override the default retry timeout which defines maximum timestamp to continue retrying the transaction. "commit_request_options" will be removed and used to set the request options for the commit request. "max_commit_delay" will be removed and used to set the max commit delay for the request. "transaction_tag" will be removed and used to set the transaction tag for the request. "exclude_txn_from_change_streams" if true, instructs the transaction to be excluded from being recorded in change streams with the DDL option allow_txn_exclusion=true. This does not exclude the transaction from being recorded in the change streams with the DDL option allow_txn_exclusion being false or unset.
Exceptions
Type Description
Exception reraises any non-ABORT exceptions raised by func.
Returns
Type Description
Any The return value of func.

snapshot

snapshot(**kw)

Create a snapshot to perform a set of reads with shared staleness.

See https://cloud.google.com/spanner/reference/rpc/google.spanner.v1#google.spanner.v1.TransactionOptions.ReadOnly

Parameter
Name Description
kw dict

Passed through to Snapshot ctor.
Exceptions
Type Description
ValueError if the session has not yet been created.
Returns
Type Description
Snapshot a snapshot bound to this session

transaction

transaction()

Create a transaction to perform a set of reads with shared staleness.

Exceptions
Type Description
ValueError if the session has not yet been created.
Returns
Type Description
Transaction a transaction bound to this session