- 3.46.0 (latest)
- 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 API
Wrapper for Cloud Spanner Session objects.
google.cloud.spanner_v1.session.DEFAULT_RETRY_TIMEOUT_SECS( = 3 )
Default timeout used by Session.run_in_transaction()
.
class google.cloud.spanner_v1.session.Session(database, labels=None)
Bases: object
Representation of a Cloud Spanner Session.
We can use a Session
to:
create()
the sessionUse
exists()
to check for the existence of the sessiondrop()
the sessionParameters
batch()
Factory to create a batch for this session.
Return type
Returns
a batch bound to this session
Raises
ValueError – if the session has not yet been created.
create()
Create this session, bound to its database.
Raises
ValueError
ifsession_id
is already set.
delete()
Delete this session.
Raises
ValueError – if
session_id
is not already set.NotFound – if the session does not exist
execute_sql(sql, params=None, param_types=None, query_mode=None, query_options=None, request_options=None, retry=<_MethodDefault._DEFAULT_VALUE:
Perform an ExecuteStreamingSql
API request.
Parameters
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 ->
TypeCode
}) – (Optional) explicit types for one or more param values; overrides default type detection on the back-end.query_mode (
QueryMode
) – Mode governing return of results / query plan. See: QueryMode.query_options (
QueryOptions
ordict
) – (Optional) Options that are provided for query plan stability.request_options (
google.cloud.spanner_v1.types.RequestOptions
) – (Optional) Common options for this request. If a dict is provided, it must be of the same form as the protobuf messageRequestOptions
.retry (
Retry
) – (Optional) The retry settings for this request.timeout (float) – (Optional) The timeout for this request.
Return type
Returns
a result set instance which can be used to consume rows.
exists()
Test for the existence of this session.
Return type
Returns
True if the session exists on the back-end, else False.
property labels()
User-assigned labels for the session.
Return type
dict (str -> str)
Returns
the labels dict (empty if no labels were assigned.
property name()
Session name used in requests.
NOTE: This property will not change if session_id
does not, but the
return value is not cached.
The session name is of the form
"projects/../instances/../databases/../sessions/{session_id}"
Return type
Returns
The session name.
Raises
ValueError – if session is not yet created
ping()
Ping the session to keep it alive by executing “SELECT 1”.
Raises
ValueError: if
session_id
is not already set.
read(table, columns, keyset, index='', limit=0)
Perform a StreamingRead
API request for rows in a table.
Parameters
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 retrievedindex (str) – (Optional) name of index to use, rather than the table’s primary key
limit (int) – (Optional) maximum number of rows to return
Return type
Returns
a result set instance which can be used to consume rows.
run_in_transaction(func, *args, **kw)
Perform a unit of work in a transaction, retrying on abort.
Parameters
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.
Return type
Any
Returns
The return value of
func
.Raises
Exception – reraises any non-ABORT exceptions raised by
func
.
property session_id()
Read-only ID, set by the back-end during create()
.
snapshot(**kw)
Create a snapshot to perform a set of reads with shared staleness.
Parameters
Return type
Returns
a snapshot bound to this session
Raises
ValueError – if the session has not yet been created.
transaction()
Create a transaction to perform a set of reads with shared staleness.
Return type
Returns
a transaction bound to this session
Raises
ValueError – if the session has not yet been created.
Session Pools API
Pools managing shared Session objects.
class google.cloud.spanner_v1.pool.AbstractSessionPool(labels=None)
Bases: object
Specifies required API for concrete session pool implementations.
Parameters
labels (dict* (str -> str) or [None*](https://python.readthedocs.io/en/latest/library/constants.html#None)) – (Optional) user-assigned labels for sessions created by the pool.
bind(database)
Associate the pool with a database.
Parameters
database (
Database
) – database used by the pool to create sessions when needed.
Concrete implementations of this method may pre-fill the pool using the database.
Raises
NotImplementedError – abstract method
clear()
Delete all sessions in the pool.
Concrete implementations of this method are allowed to raise an error to signal that the pool is full, or to block until it is not full.
Raises
NotImplementedError – abstract method
get()
Check a session out from the pool.
Concrete implementations of this method are allowed to raise an error to signal that the pool is exhausted, or to block until a session is available.
Raises
NotImplementedError – abstract method
property labels()
User-assigned labels for sessions created by the pool.
Return type
dict (str -> str)
Returns
labels assigned by the user
put(session)
Return a session to the pool.
Parameters
session (
Session
) – the session being returned.
Concrete implementations of this method are allowed to raise an error to signal that the pool is full, or to block until it is not full.
Raises
NotImplementedError – abstract method
session(**kwargs)
Check out a session from the pool.
Parameters
kwargs – (optional) keyword arguments, passed through to the returned checkout.
Return type
SessionCheckout
Returns
a checkout instance, to be used as a context manager for accessing the session and returning it to the pool.
class google.cloud.spanner_v1.pool.BurstyPool(target_size=10, labels=None)
Bases: google.cloud.spanner_v1.pool.AbstractSessionPool
Concrete session pool implementation:
“Pings” existing sessions via
session.exists()
before returning them.Creates a new session, rather than blocking, when
get()
is called on an empty pool.Discards the returned session, rather than blocking, when
put()
is called on a full pool.Parameters
target_size (int) – max pool size
labels (dict* (str -> str) or [None*](https://python.readthedocs.io/en/latest/library/constants.html#None)) – (Optional) user-assigned labels for sessions created by the pool.
bind(database)
Associate the pool with a database.
Parameters
database (
Database
) – database used by the pool to create sessions when needed.
clear()
Delete all sessions in the pool.
get()
Check a session out from the pool.
Return type
Session
Returns
an existing session from the pool, or a newly-created session.
put(session)
Return a session to the pool.
Never blocks: if the pool is full, the returned session is discarded.
Parameters
session (
Session
) – the session being returned.
class google.cloud.spanner_v1.pool.FixedSizePool(size=10, default_timeout=10, labels=None)
Bases: google.cloud.spanner_v1.pool.AbstractSessionPool
Concrete session pool implementation:
Pre-allocates / creates a fixed number of sessions.
“Pings” existing sessions via
session.exists()
before returning them, and replaces expired sessions.Blocks, with a timeout, when
get()
is called on an empty pool. Raises after timing out.Raises when
put()
is called on a full pool. That error is never expected in normal practice, as users should be callingget()
followed byput()
whenever in need of a session.Parameters
size (int) – fixed pool size
default_timeout (int) – default timeout, in seconds, to wait for a returned session.
labels (dict* (str -> str) or [None*](https://python.readthedocs.io/en/latest/library/constants.html#None)) – (Optional) user-assigned labels for sessions created by the pool.
bind(database)
Associate the pool with a database.
Parameters
database (
Database
) – database used by the pool to used to create sessions when needed.
clear()
Delete all sessions in the pool.
get(timeout=None)
Check a session out from the pool.
Parameters
timeout (int) – seconds to block waiting for an available session
Return type
Session
Returns
an existing session from the pool, or a newly-created session.
Raises
six.moves.queue.Empty
if the queue is empty.
put(session)
Return a session to the pool.
Never blocks: if the pool is full, raises.
Parameters
session (
Session
) – the session being returned.Raises
six.moves.queue.Full
if the queue is full.
class google.cloud.spanner_v1.pool.PingingPool(size=10, default_timeout=10, ping_interval=3000, labels=None)
Bases: google.cloud.spanner_v1.pool.AbstractSessionPool
Concrete session pool implementation:
Pre-allocates / creates a fixed number of sessions.
Sessions are used in “round-robin” order (LRU first).
“Pings” existing sessions in the background after a specified interval via an API call (
session.ping()
).Blocks, with a timeout, when
get()
is called on an empty pool. Raises after timing out.Raises when
put()
is called on a full pool. That error is never expected in normal practice, as users should be callingget()
followed byput()
whenever in need of a session.
The application is responsible for calling ping()
at appropriate
times, e.g. from a background thread.
Parameters
size (int) – fixed pool size
default_timeout (int) – default timeout, in seconds, to wait for a returned session.
ping_interval (int) – interval at which to ping sessions.
labels (dict* (str -> str) or [None*](https://python.readthedocs.io/en/latest/library/constants.html#None)) – (Optional) user-assigned labels for sessions created by the pool.
bind(database)
Associate the pool with a database.
Parameters
database (
Database
) – database used by the pool to create sessions when needed.
clear()
Delete all sessions in the pool.
get(timeout=None)
Check a session out from the pool.
Parameters
timeout (int) – seconds to block waiting for an available session
Return type
Session
Returns
an existing session from the pool, or a newly-created session.
Raises
six.moves.queue.Empty
if the queue is empty.
ping()
Refresh maybe-expired sessions in the pool.
This method is designed to be called from a background thread, or during the “idle” phase of an event loop.
put(session)
Return a session to the pool.
Never blocks: if the pool is full, raises.
Parameters
session (
Session
) – the session being returned.Raises
six.moves.queue.Full
if the queue is full.
class google.cloud.spanner_v1.pool.SessionCheckout(pool, **kwargs)
Bases: object
Context manager: hold session checked out from a pool.
Parameters
pool (concrete subclass of
AbstractSessionPool
) – Pool from which to check out a session.kwargs – extra keyword arguments to be passed to
pool.get()
.
class google.cloud.spanner_v1.pool.TransactionPingingPool(size=10, default_timeout=10, ping_interval=3000, labels=None)
Bases: google.cloud.spanner_v1.pool.PingingPool
Concrete session pool implementation:
In addition to the features of PingingPool
, this class
creates and begins a transaction for each of its sessions at startup.
When a session is returned to the pool, if its transaction has been
committed or rolled back, the pool creates a new transaction for the
session and pushes the transaction onto a separate queue of “transactions
to begin.” The application is responsible for flushing this queue
as appropriate via the pool’s begin_pending_transactions()
method.
Parameters
size (int) – fixed pool size
default_timeout (int) – default timeout, in seconds, to wait for a returned session.
ping_interval (int) – interval at which to ping sessions.
labels (dict* (str -> str) or [None*](https://python.readthedocs.io/en/latest/library/constants.html#None)) – (Optional) user-assigned labels for sessions created by the pool.
begin_pending_transactions()
Begin all transactions for sessions added to the pool.
bind(database)
Associate the pool with a database.
Parameters
database (
Database
) – database used by the pool to create sessions when needed.
put(session)
Return a session to the pool.
Never blocks: if the pool is full, raises.
Parameters
session (
Session
) – the session being returned.Raises
six.moves.queue.Full
if the queue is full.