Version History (fa4563d)

Report an Issue

Batches

Create / interact with a batch of updates / deletes.

Batches provide the ability to execute multiple operations in a single request to the Cloud Datastore API.

See https://cloud.google.com/datastore/docs/concepts/entities#Datastore_Batch_operations

class gcloud.datastore.batch.Batch(client)

Bases: object

An abstraction representing a collected group of updates / deletes.

Used to build up a bulk mutuation.

For example, the following snippet of code will put the two save operations and the delete operatiuon into the same mutation, and send them to the server in a single API request:

>>> from gcloud.datastore.batch import Batch
>>> batch = Batch()
>>> batch.put(entity1)
>>> batch.put(entity2)
>>> batch.delete(key3)
>>> batch.commit()

You can also use a batch as a context manager, in which case the commit will be called automatically if its block exits without raising an exception:

>>> with 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:

>>> with Batch() as batch:
...   do_some_work(batch)
...   raise Exception() # rolls back

Parameters:client (gcloud.datastore.client.Client) – The client used to connect to datastore.

add_auto_id_entity(entity)

Adds an entity to the list of entities to update with IDs.

When an entity has a partial key, calling save() adds an insert_auto_id entry in the mutation. In order to make sure we update the Entity once the transaction is committed, we need to keep track of which entities to update (and the order is important).

When you call save() on an entity inside a transaction, if the entity has a partial key, it adds itself to the list of entities to be updated once the transaction is committed by calling this method.

Parameters:entity (gcloud.datastore.entity.Entity) – The entity to be updated with a completed key. Raises:ValueError if the entity’s key is alread completed.

begin()

No-op

Overridden by gcloud.datastore.transaction.Transaction.

commit()

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.

connection

Getter for connection over which the batch will run.

Return type:gcloud.datastore.connection.Connection Returns:The connection over which the batch will run.

current()

Return the topmost batch / transaction, or None.

dataset_id

Getter for dataset ID in which the batch will run.

Return type:str Returns:The dataset ID in which the batch will run.

delete(key)

Remember a key to be deleted durring commit.

Parameters:key (gcloud.datastore.key.Key) – the key to be deleted. Raises:ValueError if key is not complete, or if the key’s dataset_id does not match ours.

mutation

Getter for the current mutation.

Every batch is committed with a single Mutation representing the ‘work’ to be done as part of the batch. Inside a batch, calling batch.put() with an entity, or batch.delete with a key, builds up the mutation. This getter returns the Mutation protobuf that has been built-up so far.

Return type:gcloud.datastore._datastore_v1_pb2.Mutation Returns:The Mutation protobuf to be sent in the commit request.

namespace

Getter for namespace in which the batch will run.

Return type:str Returns:The namespace in which the batch will run.

put(entity)

Remember an entity’s state to be saved during commit.

Note

Any existing properties for the entity will be replaced by those currently set on this instance. Already-stored properties which do not correspond to keys set on this instance will be removed from the datastore.

Note

Property values which are “text” (‘unicode’ in Python2, ‘str’ in Python3) map to ‘string_value’ in the datastore; values which are “bytes” (‘str’ in Python2, ‘bytes’ in Python3) map to ‘blob_value’.

Parameters:entity (gcloud.datastore.entity.Entity) – the entity to be saved. Raises:ValueError if entity has no key assigned, or if the key’s dataset_id does not match ours.

rollback()

No-op

Overridden by gcloud.datastore.transaction.Transaction.