Cloud Firestore Client - Class BulkWriter (1.47.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();

Namespace

Google \ Cloud \ Firestore

Methods

__construct

Parameters
Name Description
connection Google\Cloud\Firestore\Connection\ConnectionInterface

A connection to Cloud Firestore This object is created by FirestoreClient, and should not be instantiated outside of this client.
valueMapper Google\Cloud\Firestore\ValueMapper

A Value Mapper instance
database string

The current database
options array

Configuration options is an array.

Please note that the default values are experiementally derived after
performance evaluations. The underlying constants may change in backwards-
incompatible ways. Please use with caution, and test thoroughly when
upgrading.

For legacy reasons if provided as `string` or `null`, its assumed
to be transaction id for Google\Cloud\Firestore\WriteBatch.
↳ maxBatchSize int

Maximum number of requests per BulkWriter batch. Defaults to 20.
↳ greedilySend bool

Flag to indicate whether BulkWriter greedily sends batches. Defaults to true.
↳ isThrottlingEnabled bool

Flag to indicate whether rate of sending writes can be throttled. Defaults to true.
↳ initialOpsPerSecond int

Initial number of operations per second. Defaults to 20.
↳ maxOpsPerSecond int

Maximum number of operations per second. Defaults to 500.
↳ isRetryable callable

Default retry handler for individial writes status code to be retried. Should accept error code and return true if retryable.

create

Enqueue a document creation.

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

Example:

$batch->create($documentName, [
    'name' => 'John'
]);
Parameters
Name Description
document Google\Cloud\Firestore\DocumentReference|string

The document to target, either as a string document name, or DocumentReference object. Please note that DocumentReferences will be used only for the document name. Field data must be provided in the $fields argument.
fields array

An array containing fields, where keys are the field names, and values are field values. Nested arrays are allowed. Note that unlike Google\Cloud\Firestore\DocumentReference::update(), field paths are NOT supported by this method.
options array

Configuration options
Returns
Type Description
Google\Cloud\Firestore\BulkWriter

set

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' ]);

Parameters
Name Description
document Google\Cloud\Firestore\DocumentReference|string

The document to target, either as a string document name, or DocumentReference object. Please note that DocumentReferences will be used only for the document name. Field data must be provided in the $fields argument.
fields array

An array containing fields, where keys are the field names, and values are field values. Nested arrays are allowed. Note that unlike Google\Cloud\Firestore\BulkWriter::update(), field paths are NOT supported by this method.
options array

Configuration Options
↳ merge bool

If true, unwritten fields will be preserved. Otherwise, they will be overwritten (removed). Defaults to false.
Returns
Type Description
Google\Cloud\Firestore\BulkWriter

update

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]
]);
Parameters
Name Description
document Google\Cloud\Firestore\DocumentReference|string

The document to target, either as a string document name, or DocumentReference object. Please note that DocumentReferences will be used only for the document name. Field data must be provided in the $data argument.
data array[]

A list of arrays of form [FieldPath|string $path, mixed $value].
options array

Configuration options
Returns
Type Description
Google\Cloud\Firestore\BulkWriter

delete

Delete a Firestore document.

Example:

$batch->delete($documentName);
Parameters
Name Description
document Google\Cloud\Firestore\DocumentReference|string

The document to target, either as a string document name, or DocumentReference object.
options array

Configuration Options
Returns
Type Description
Google\Cloud\Firestore\BulkWriter

flush

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();
Parameter
Name Description
waitForRetryableFailures bool

Flag to indicate whether to wait for retryable failures. Defaults to false.
Returns
Type Description
array [https://firebase.google.com/docs/firestore/reference/rpc/google.firestore.v1beta1#BatchWriteResponse](BatchWriteResponse)

commit

See also:

Parameter
Name Description
options array

Configuration Options
Returns
Type Description
array [https://firebase.google.com/docs/firestore/reference/rpc/google.firestore.v1beta1#commitresponse](CommitResponse)

rollback

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.

Parameter
Name Description
options array

Configuration Options
Returns
Type Description
void

isEmpty

Check if the BulkWriter has any writes enqueued.

Returns
Type Description
bool

close

Close the bulk writer instance for further writes.

Also, flushes all retries and pending writes.

Returns
Type Description
array [https://firebase.google.com/docs/firestore/reference/rpc/google.firestore.v1beta1#BatchWriteResponse](BatchWriteResponse)

getBackoffDuration

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

Parameters
Name Description
lastStatus int

Previous status code of batchWrite
backoffDurationInMillis int

Previous backoff duration in milliseconds
Returns
Type Description
int

setMaxRetryTimeInMs

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

Parameter
Name Description
maxTime int

The maximum delay time in millis for rescheduling a failed mutation or awaiting a batch creation.
Returns
Type Description
void

Constants

TYPE_UPDATE

Value: 'update'

TYPE_SET

Value: 'set'

TYPE_CREATE

Value: 'create'

TYPE_DELETE

Value: 'delete'

TYPE_TRANSFORM

Value: 'transform'