Batch API (CloudCode)

The Batch API should be used whenever many save() or destroy() operations are used in CloudCode.

Instead of using one network request per operation, it batches all of them into a single network request. This can significantly improve the performance of the task.

// Without batch

await obj1.save();
await obj2.save();
await obj3.destroy();

// Doing the same with DB.Batch:

var batch = new DB.Batch();

// These operations only add the objects to the batch, but does not perform any actions on the server yet.
batch.save(obj1);
batch.save(obj2);
batch.destroy(obj3);

// This executes all operations in the batch in a single network request.
await batch.execute();

Large batches

If the batch contains more than 1000 operations, it will internally be split into separate smaller network requests.

Error handling

The execute() function can throw an Error, typically in these scenarios:

1. A network error occurred. This could be before or after the server received and processed the batch.

2. An attempt is made to update (save) an object that has been deleted elsewhere.

3. There is a data-model mismatch (e.g. a model was deleted on the backend while the CloudCode task is still running).

It is safe to attempt recovery from these errors by performing batch.execute() again. Any objects that have been confirmed as saved (e.g. the first part of a large batch) will not be saved again. Duplicate objects will not be created, since the IDs for new objects are generated by the task, not by the backend.

Note that error types (2) and (3) above are generally not recoverable by retrying the same batch.