Class Batch (2.22.0) Stay organized with collections Save and categorize content based on your preferences.
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 twosaveoperations and thedelete operation into the same mutation, and sendthem to the server in a single API request:
.. testsetup:: batch
import uuidfrom google.cloud importdatastoreunique = 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 casecommit will be called automatically if its block exits withoutraising 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 backTraceback (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 | ClientThe 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 allthe work to be done as mutations. Inside a batch, callingputwith an entity, ordelete with a key, builds up the request byadding a new mutation. This getter returns the protobuf that has beenbuilt-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 withstatement, however it can be called explicitly if you don't wantto 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 acontext manager.
| Parameters | |
|---|---|
| Name | Description |
retry | A retry object used to retry requests. If |
timeout | floatTime, 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 duringcommit.
| Parameter | |
|---|---|
| Name | Description |
key | Keythe 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'sproject does not match ours. |
put
put(entity)Remember an entity's state to be saved duringcommit.
commit sends it asaninsert mutation and the key is completed. On return,the key for theentity passed in is updated to match the key IDassigned by the server.| Parameter | |
|---|---|
| Name | Description |
entity | Entitythe 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'sproject 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. |
Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2025-12-16 UTC.