Cloud Firestore Client - Class BulkWriter (1.46.0)

Reference documentation and code samples for the Cloud Firestore Client class BulkWriter.

Enqueue and write multiple mutations to Cloud Firestore.

This class may be used directly for multiple non-transactional writes with automatic retry on failure. To run changes in a transaction (with automatic retry/rollback on failure), use Google\Cloud\Firestore\Transaction. Single modifications can be made using the various methods on Google\Cloud\Firestore\DocumentReference.

Example:

use Google\Cloud\Firestore\FirestoreClient;

$firestore = new FirestoreClient();
$batch = $firestore->bulkWriter();

Enqueue a document creation.

This operation will fail (when committed) if the document already exists.

Example:

$batch->create($documentName, [
    'name' => 'John'
]);

Enqueue a set mutation.

Unless $options['merge'] is set to `true, this method replaces all fields in a Firestore document.

Example: ``` $batch->set($documentName, [ 'name' => 'John' ]);

Enqueue an update with field paths and values.

Merges provided data with data stored in Firestore.

Calling this method on a non-existent document will raise an exception.

This method supports various sentinel values, to perform special operations on fields. Available sentinel values are provided as methods, found in Google\Cloud\Firestore\FieldValue.

Note that field names must be provided using field paths, encoded either as a dot-delimited string (i.e. foo.bar), or an instance of Google\Cloud\Firestore\FieldPath. Nested arrays are not allowed.

Please note that conflicting paths will result in an exception. Paths conflict when one path indicates a location nested within another path. For instance, path a.b cannot be set directly if path a is also provided.

Example:

$batch->update($documentName, [
    ['path' => 'name', 'value' => 'John'],
    ['path' => 'country', 'value' => 'USA'],
    ['path' => 'cryptoCurrencies.bitcoin', 'value' => 0.5],
    ['path' => 'cryptoCurrencies.ethereum', 'value' => 10],
    ['path' => 'cryptoCurrencies.litecoin', 'value' => 5.51]
]);

// Google Cloud PHP provides special field values to enable operations such
// as deleting fields or setting the value to the current server timestamp.
use Google\Cloud\Firestore\FieldValue;

$batch->update($documentName, [
    ['path' => 'country', 'value' => FieldValue::deleteField()],
    ['path' => 'lastLogin', 'value' => FieldValue::serverTimestamp()]
]);

// If your field names contain special characters (such as `.`, or symbols),
// using <xref uid="\Google\Cloud\Firestore\FieldPath">Google\Cloud\Firestore\FieldPath</xref> will properly escape each element.

use Google\Cloud\Firestore\FieldPath;

$batch->update($documentName, [
    ['path' => new FieldPath(['cryptoCurrencies', 'big$$$coin']), 'value' => 5.51]
]);

Delete a Firestore document.

Example:

$batch->delete($documentName);

Flushes the enqueued writes in batches with auto-retries. Please note:

• This method is blocking and may execute many sequential batch write requests.

• Gradually ramps up writes as specified by the 500/50/5 rule.
  • Does not guarantee the order of writes.
  • Accepts unique document references only. Read more: Ramping up traffic

Example:

$batch->flush();

See also:

• Commit

Rollback a transaction.

If the class was created without a Transaction ID, this method will fail. Not to be used together with flush / close.

This method is intended for use internally and should not be considered part of the public API.

Check if the BulkWriter has any writes enqueued.

Close the bulk writer instance for further writes.

Also, flushes all retries and pending writes.

Gets updated backoff duration provided last status code and backoff duration.

Change the maximum delay time for rescheduling a failed mutation or awaiting a batch creation.