Class Session (3.43.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

NameDescription
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
TypeDescription
strthe database role str (None if no database role were assigned).

labels

User-assigned labels for the session.

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

name

Session name used in requests.

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

Exceptions
TypeDescription
ValueErrorif session is not yet created
Returns
TypeDescription
strThe 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
TypeDescription
ValueErrorif the session has not yet been created.
Returns
TypeDescription
Batcha 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
TypeDescription
ValueErrorif 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
TypeDescription
ValueErrorif session_id is not already set.
NotFoundif 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,
)

Perform an ExecuteStreamingSql API request.

Parameters
NameDescription
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
TypeDescription
StreamedResultSeta 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
TypeDescription
boolTrue if the session exists on the back-end, else False.

ping

ping()

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

Exceptions
TypeDescription
ValueErrorif 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
NameDescription
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
TypeDescription
StreamedResultSeta 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
NameDescription
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.

func callable

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

Exceptions
TypeDescription
Exceptionreraises any non-ABORT exceptions raised by func.
Returns
TypeDescription
AnyThe 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
NameDescription
kw dict

Passed through to Snapshot ctor.

Exceptions
TypeDescription
ValueErrorif the session has not yet been created.
Returns
TypeDescription
Snapshota snapshot bound to this session

transaction

transaction()

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

Exceptions
TypeDescription
ValueErrorif the session has not yet been created.
Returns
TypeDescription
Transactiona transaction bound to this session