Batch(client)An abstraction representing a collected group of updates / deletes.
Used to build up a bulk mutation.
For example, the following snippet of code will put the two save
operations and the delete operation into the same mutation, and send
them to the server in a single API request:
.. testsetup:: batch
import uuid
from google.cloud import datastore
unique = str(uuid.uuid4())[0:8]
client = datastore.Client(namespace='ns{}'.format(unique))
.. doctest:: batch
>>> entity1 = datastore.Entity(client.key('EntityKind', 1234))
>>> entity2 = datastore.Entity(client.key('EntityKind', 2345))
>>> key3 = client.key('EntityKind', 3456)
>>> batch = client.batch()
>>> batch.begin()
>>> batch.put(entity1)
>>> batch.put(entity2)
>>> batch.delete(key3)
>>> batch.commit()
You can also use a batch as a context manager, in which case
commit will be called automatically if its block exits without
raising an exception:
.. doctest:: batch
>>> with client.batch() as batch:
... batch.put(entity1)
... batch.put(entity2)
... batch.delete(key3)
By default, no updates will be sent if the block exits with an error:
.. doctest:: batch
>>> def do_some_work(batch):
... return
>>> with client.batch() as batch:
... do_some_work(batch)
... raise Exception() # rolls back
Traceback (most recent call last):
...
Exception
.. testcleanup:: txn
with client.batch() as batch:
batch.delete(client.key('EntityKind', 1234))
batch.delete(client.key('EntityKind', 2345))
Parameter | |
|---|---|
| Name | Description |
client |
Client
The client used to connect to datastore. |
Properties
database
Getter for database in which the batch will run.
| Returns | |
|---|---|
| Type | Description |
| The database in which the batch will run. |
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()Begins a batch.
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.
Overridden by xref_Transaction.
| Exceptions | |
|---|---|
| Type | Description |
`ValueError | if the batch has already begun. |
commit
commit(retry=None, timeout=None)Commits the batch.
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.
| 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 batch is not in progress. |
current
current()Return the topmost batch / transaction, or None.
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)Remember an entity's state to be saved during commit.
When an entity has a partial key, calling commit sends it as
an insert mutation and the key is completed. On return,
the key for the entity passed in is updated to match the key ID
assigned by the server.
| Parameter | |
|---|---|
| Name | Description |
entity |
Entity
the entity to be saved. |
| Exceptions | |
|---|---|
| Type | Description |
`exceptions.ValueError | if the batch is not in progress, if entity has no key assigned, or if the key's project does not match ours. |
rollback
rollback()Rolls back the current batch.
Marks the batch as aborted (can't be used again).
Overridden by xref_Transaction.
| Exceptions | |
|---|---|
| Type | Description |
`exceptions.ValueError | if the batch is not in progress. |