Class Session (3.50.1)

Version 3.50.1

• 3.51.0 (latest)
• 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

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.

name

Session name used in requests.

Note: This property will not change if session_id does not, but the return value is not cached.

"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