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

Class Session (3.29.0)

Parameters

Properties

database_role

labels

name

session_id

Methods

batch

create

delete

execute_sql

exists

ping

read

run_in_transaction

snapshot

transaction