Class Session (3.57.0)

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

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.
`is_multiplexed`	`bool` (Optional) whether this session is a multiplexed 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).

is_multiplexed

Whether this session is a multiplexed session.

Returns
Type	Description
`bool`	True if this is a multiplexed session, False otherwise.

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.

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. "isolation_level" sets the isolation level for the transaction.

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() -> google.cloud.spanner_v1.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

Class Session (3.57.0) Stay organized with collections Save and categorize content based on your preferences.

Parameters

Properties

database_role

is_multiplexed

labels

last_use_time

name

session_id

Methods

batch

create

delete

execute_sql

exists

ping

read

run_in_transaction

snapshot

transaction

Class Session (3.57.0)