Class Batch (2.22.0)

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

NameDescription
clientClient

The client used to connect to datastore.

Properties

database

Getter for database in which the batch will run.

Returns
TypeDescription
strThe 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
TypeDescription
iterableThe list of.datastore_pb2.Mutation protobufs to be sent in the commit request.

namespace

Getter for namespace in which the batch will run.

Returns
TypeDescription
strThe namespace in which the batch will run.

project

Getter for project in which the batch will run.

Returns
TypeDescription
strThe 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
TypeDescription
`ValueErrorif 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
NameDescription
retrygoogle.api_core.retry.Retry

A retry object used to retry requests. IfNone is specified, requests will be retried using a default configuration.

timeoutfloat

Time, in seconds, to wait for the request to complete. Note that ifretry is specified, the timeout applies to each individual attempt.

Exceptions
TypeDescription
`exceptions.ValueErrorif 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
NameDescription
keyKey

the key to be deleted.

Exceptions
TypeDescription
`exceptions.ValueErrorif the batch is not in progress, if key is not complete, or if the key'sproject does not match ours.

put

put(entity)
Parameter
NameDescription
entityEntity

the entity to be saved.

Exceptions
TypeDescription
`exceptions.ValueErrorif the batch is not in progress, if entity has no key assigned, or if the key'sproject does not match ours.

rollback

Exceptions
TypeDescription
`exceptions.ValueErrorif 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.