Transaction(client, read_only=False, read_time=None)An abstraction representing datastore Transactions.
Transactions can be used to build up a bulk mutation and ensure all or none succeed (transactionally).
For example, the following snippet of code will put the two save
operations (either insert or upsert) into the same
mutation, and execute those within a transaction:
.. testsetup:: txn
import uuid
from google.cloud import datastore
unique = str(uuid.uuid4())[0:8]
client = datastore.Client(namespace='ns{}'.format(unique))
.. doctest:: txn
>>> entity1 = datastore.Entity(client.key('EntityKind', 1234))
>>> entity2 = datastore.Entity(client.key('EntityKind', 2345))
>>> with client.transaction():
... client.put_multi([entity1, entity2])
Because it derives from xref_Batch,
Transaction also provides put and delete methods:
.. doctest:: txn
with client.transaction() as xact: ... xact.put(entity1) ... xact.delete(entity2.key)
By default, the transaction is rolled back if the transaction block exits with an error:
.. doctest:: txn
>>> def do_some_work():
... return
>>> class SomeException(Exception):
... pass
>>> with client.transaction():
... do_some_work()
... raise SomeException # rolls back
Traceback (most recent call last):
...
SomeException
If the transaction block exits without an exception, it will commit by default.
Once you exit the transaction (or callwith client.transaction(): ... thing1 = datastore.Entity(key=client.key('Thing')) ... client.put(thing1)
commit), the
automatically generated ID will be assigned to the entity:
.. doctest:: txn
>>> with client.transaction():
... thing2 = datastore.Entity(key=client.key('Thing'))
... client.put(thing2)
... print(thing2.key.is_partial) # There is no ID on this key.
...
True
>>> print(thing2.key.is_partial) # There *is* an ID.
False
If you don't want to use the context manager you can initialize a transaction manually:
.. doctest:: txn
transaction = client.transaction() transaction.begin()
thing3 = datastore.Entity(key=client.key('Thing')) transaction.put(thing3)
transaction.commit()
.. testcleanup:: txn
with client.batch() as batch:
batch.delete(client.key('EntityKind', 1234))
batch.delete(client.key('EntityKind', 2345))
batch.delete(thing1.key)
batch.delete(thing2.key)
batch.delete(thing3.key)
Parameters | |
|---|---|
| Name | Description |
client |
Client
the client used to connect to datastore. |
read_only |
bool
indicates the transaction is read only. |
read_time |
datetime
(Optional) Time at which the transaction reads entities. Only allowed when |
Properties
database
Getter for database in which the batch will run.
| Returns | |
|---|---|
| Type | Description |
| The database in which the batch will run. |
id
Getter for the transaction ID.
| Returns | |
|---|---|
| Type | Description |
str | The ID of the current transaction. |
mutations
Getter for the changes accumulated by this batch.
Every batch is committed with a single commit request containing all
the work to be done as mutations. Inside a batch, calling put
with an entity, or delete with a key, builds up the request by
adding a new mutation. This getter returns the protobuf that has been
built-up so far.
| Returns | |
|---|---|
| Type | Description |
iterable | The list of .datastore_pb2.Mutation protobufs to be sent in the commit request. |
namespace
Getter for namespace in which the batch will run.
| Returns | |
|---|---|
| Type | Description |
| The namespace in which the batch will run. |
project
Getter for project in which the batch will run.
| Returns | |
|---|---|
| Type | Description |
| The project in which the batch will run. |
Methods
begin
begin(retry=None, timeout=None)Begins a transaction.
This method is called automatically when entering a with statement, however it can be called explicitly if you don't want to use a context manager.
| Parameters | |
|---|---|
| Name | Description |
retry |
A retry object used to retry requests. If |
timeout |
float
Time, in seconds, to wait for the request to complete. Note that if |
| Exceptions | |
|---|---|
| Type | Description |
`exceptions.ValueError | if the transaction has already begun. |
commit
commit(retry=None, timeout=None)Commits the transaction.
This is called automatically upon exiting a with statement, however it can be called explicitly if you don't want to use a context manager.
This method has necessary side-effects:
- Sets the current transaction's ID to None.
| Parameters | |
|---|---|
| Name | Description |
retry |
A retry object used to retry requests. If |
timeout |
float
Time, in seconds, to wait for the request to complete. Note that if |
current
current()Return the topmost transaction.
| Returns | |
|---|---|
| Type | Description |
Transaction or None | The current transaction (if any are active). |
delete
delete(key)Remember a key to be deleted during commit.
| Parameter | |
|---|---|
| Name | Description |
key |
Key
the key to be deleted. |
| Exceptions | |
|---|---|
| Type | Description |
`exceptions.ValueError | if the batch is not in progress, if key is not complete, or if the key's project does not match ours. |
put
put(entity)Adds an entity to be committed.
Ensures the transaction is not marked readonly. Please see documentation at xref_put
| Parameter | |
|---|---|
| Name | Description |
entity |
Entity
the entity to be saved. |
| Exceptions | |
|---|---|
| Type | Description |
`RuntimeError | if the transaction is marked ReadOnly |
rollback
rollback(retry=None, timeout=None)Rolls back the current transaction.
This method has necessary side-effects:
- Sets the current transaction's ID to None.
| Parameters | |
|---|---|
| Name | Description |
retry |
A retry object used to retry requests. If |
timeout |
float
Time, in seconds, to wait for the request to complete. Note that if |