- 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
Database API
User friendly container for Cloud Spanner Database.
class google.cloud.spanner_v1.database.BatchCheckout(database)
Bases: object
Context manager for using a batch from a database.
Inside the context manager, checks out a session from the database, creates a batch from it, making the batch available.
Caller must not use the batch to perform API requests outside the scope of the context manager.
Parameters
database (
Database
) – database to use
_enter_()
Begin with
block.
_exit_(exc_type, exc_val, exc_tb)
End with
block.
class google.cloud.spanner_v1.database.BatchSnapshot(database, read_timestamp=None, exact_staleness=None)
Bases: object
Wrapper for generating and processing read / query batches.
Parameters
database (
Database
) – database to useread_timestamp (
datetime.datetime
) – Execute all reads at the given timestamp.exact_staleness (
datetime.timedelta
) – Execute all reads at a timestamp that isexact_staleness
old.
close()
Clean up underlying session.
NOTE: If the transaction has been shared across multiple machines, calling this on any machine would invalidate the transaction everywhere. Ideally this would be called when data has been read from all the partitions.
execute_sql(*args, **kw)
Convenience method: perform query operation via snapshot.
See execute_sql()
.
classmethod from_dict(database, mapping)
Reconstruct an instance from a mapping.
Parameters
database (
Database
) – database to usemapping (mapping) – serialized state of the instance
Return type
BatchSnapshot
generate_query_batches(sql, params=None, param_types=None, partition_size_bytes=None, max_partitions=None)
Start a partitioned query operation.
Uses the PartitionQuery
API request to start a partitioned
query operation. Returns a list of batch information needed to
peform the actual queries.
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 -> Union[dict, *[types.Type](gapic/v1/types.md#google.cloud.spanner_v1.types.Type)]*]) – (Optional) maps explicit types for one or more param values; required if parameters are passed.
partition_size_bytes (int) – (Optional) desired size for each partition generated. The service uses this as a hint, the actual partition size may differ.
partition_size_bytes – (Optional) desired size for each partition generated. The service uses this as a hint, the actual partition size may differ.
max_partitions (int) – (Optional) desired maximum number of partitions generated. The service uses this as a hint, the actual number of partitions may differ.
Return type
iterable of dict
Returns
mappings of information used peform actual partitioned reads via
process_read_batch()
.
generate_read_batches(table, columns, keyset, index='', partition_size_bytes=None, max_partitions=None)
Start a partitioned batch read operation.
Uses the PartitionRead
API request to initiate the partitioned
read. Returns a list of batch information needed to perform the
actual reads.
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
partition_size_bytes (int) – (Optional) desired size for each partition generated. The service uses this as a hint, the actual partition size may differ.
max_partitions (int) – (Optional) desired maximum number of partitions generated. The service uses this as a hint, the actual number of partitions may differ.
Return type
iterable of dict
Returns
mappings of information used peform actual partitioned reads via
process_read_batch()
.
process(batch)
Process a single, partitioned query or read.
Parameters
batch (mapping) – one of the mappings returned from an earlier call to
generate_query_batches()
.Return type
Returns
a result set instance which can be used to consume rows.
Raises
ValueError – if batch does not contain either ‘read’ or ‘query’
process_query_batch(batch)
Process a single, partitioned query.
Parameters
batch (mapping) – one of the mappings returned from an earlier call to
generate_query_batches()
.Return type
Returns
a result set instance which can be used to consume rows.
process_read_batch(batch)
Process a single, partitioned read.
Parameters
batch (mapping) – one of the mappings returned from an earlier call to
generate_read_batches()
.Return type
Returns
a result set instance which can be used to consume rows.
read(*args, **kw)
Convenience method: perform read operation via snapshot.
See read()
.
to_dict()
Return state as a dictionary.
Result can be used to serialize the instance and reconstitute
it later using from_dict()
.
Return type
class google.cloud.spanner_v1.database.Database(database_id, instance, ddl_statements=(), pool=None)
Bases: object
Representation of a Cloud Spanner Database.
We can use a Database
to:
create()
the databasereload()
the databaseupdate()
the databasedrop()
the databaseParameters
database_id (str) – The ID of the database.
instance (
Instance
) – The instance that owns the database.ddl_statements (list of string) – (Optional) DDL statements, excluding the CREATE DATABASE statement.
pool (concrete subclass of
AbstractSessionPool
.) – (Optional) session pool to be used by database. If not passed, the database will construct an instance ofBurstyPool
.
batch()
Return an object which wraps a batch.
The wrapper must be used as a context manager, with the batch as the value returned by the wrapper.
Return type
BatchCheckout
Returns
new wrapper
batch_snapshot(read_timestamp=None, exact_staleness=None)
Return an object which wraps a batch read / query.
Parameters
read_timestamp (
datetime.datetime
) – Execute all reads at the given timestamp.exact_staleness (
datetime.timedelta
) – Execute all reads at a timestamp that isexact_staleness
old.
Return type
BatchSnapshot
Returns
new wrapper
create()
Create this database within its instance
Inclues any configured schema assigned to ddl_statements
.
Return type
Operation
Returns
a future used to poll the status of the create request
Raises
Conflict – if the database already exists
NotFound – if the instance owning the database does not exist
property ddl_statements()
DDL Statements used to define database schema.
See cloud.google.com/spanner/docs/data-definition-language
Return type
sequence of string
Returns
the statements
drop()
Drop this database.
execute_partitioned_dml(dml, params=None, param_types=None)
Execute a partitionable DML statement.
Parameters
dml (str) – DML statement
params (dict, **{str -> column value}) – values for parameter replacement. Keys must match the names used in
dml
.param_types (dict[str -> Union[dict, *[types.Type](gapic/v1/types.md#google.cloud.spanner_v1.types.Type)]*]) – (Optional) maps explicit types for one or more param values; required if parameters are passed.
Return type
Returns
Count of rows affected by the DML statement.
exists()
Test whether this database exists.
Return type
Returns
True if the database exists, else false.
classmethod from_pb(database_pb, instance, pool=None)
Creates an instance of this class from a protobuf.
Parameters
database_pb (
google.spanner.v2.spanner_instance_admin_pb2.Instance
) – A instance protobuf object.instance (
Instance
) – The instance that owns the database.pool (concrete subclass of
AbstractSessionPool
.) – (Optional) session pool to be used by database.
Return type
Database
Returns
The database parsed from the protobuf response.
Raises
ValueError – if the instance name does not match the expected format or if the parsed project ID does not match the project ID on the instance’s client, or if the parsed instance ID does not match the instance’s ID.
property name()
Database name used in requests.
NOTE: This property will not change if database_id
does not, but the
return value is not cached.
The database name is of the form
"projects/../instances/../databases/{database_id}"
Return type
Returns
The database name.
reload()
Reload this database.
Refresh any configured schema into ddl_statements
.
Raises
NotFound – if the database does not exist
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 timeout.
Return type
Returns
timestamp of committed transaction
session(labels=None)
Factory to create a session for this database.
Parameters
labels (dict* (str -> str) or [None*](https://python.readthedocs.io/en/latest/library/constants.html#None)) – (Optional) user-assigned labels for the session.
Return type
Returns
a session bound to this database.
snapshot(**kw)
Return an object which wraps a snapshot.
The wrapper must be used as a context manager, with the snapshot as the value returned by the wrapper.
Parameters
Return type
SnapshotCheckout
Returns
new wrapper
property spanner_api()
Helper for session-related API calls.
update_ddl(ddl_statements, operation_id='')
Update DDL for this database.
Apply any configured schema from ddl_statements
.
Parameters
Return type
google.api_core.operation.Operation
Returns
an operation instance
Raises
NotFound – if the database does not exist
class google.cloud.spanner_v1.database.SnapshotCheckout(database, **kw)
Bases: object
Context manager for using a snapshot from a database.
Inside the context manager, checks out a session from the database, creates a snapshot from it, making the snapshot available.
Caller must not use the snapshot to perform API requests outside the scope of the context manager.
Parameters
_enter_()
Begin with
block.
_exit_(exc_type, exc_val, exc_tb)
End with
block.