Class Batch (2.21.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 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
str 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
str The namespace in which the batch will run.

project

Getter for project in which the batch will run.

Returns
Type Description
str 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 google.api_core.retry.Retry

A retry object used to retry requests. If None is specified, requests will be retried using a default configuration.
timeout float

Time, in seconds, to wait for the request to complete. Note that if retry is specified, the timeout applies to each individual attempt.
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.