Class Session (3.22.0)

Version 3.22.0

• 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)

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.

Inheritance

builtins.object > Session

Properties

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: <object object>>, timeout=<_MethodDefault._DEFAULT_VALUE: <object object>>)

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.

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)

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

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
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.
func	callable takes a required positional argument, the transaction, and additional positional / keyword arguments as supplied by the caller.

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