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\Google\Cloud\Firestore\Transaction. Single modifications can be made using the various methods on Google\Cloud\Firestore\Google\Cloud\Firestore\DocumentReference.
Example:
use Google\Cloud\Firestore\FirestoreClient;
$firestore = new FirestoreClient();
$batch = $firestore->bulkWriter();
Namespace
Google \ Cloud \ FirestoreMethods
__construct
Parameters | |
---|---|
Name | Description |
connection |
Google\Cloud\Firestore\Connection\ConnectionInterface
A connection to Cloud Firestore |
valueMapper |
Google\Cloud\Firestore\ValueMapper
A Value Mapper instance |
database |
string
The current database |
options |
array
Configuration options is an array.
|
↳ maxBatchSize |
int
Maximum number of requests per BulkWriter batch. Defaults to |
↳ greedilySend |
bool
Flag to indicate whether BulkWriter greedily sends batches. Defaults to |
↳ isThrottlingEnabled |
bool
Flag to indicate whether rate of sending writes can be throttled. Defaults to |
↳ initialOpsPerSecond |
int
Initial number of operations per second. Defaults to |
↳ maxOpsPerSecond |
int
Maximum number of operations per second. Defaults to |
↳ 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 |
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\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 |
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\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 |
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\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\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\Google\Cloud\Firestore\FieldPath">Google\Cloud\Firestore\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 |
array[]
A list of arrays of form
|
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 |
Returns | |
---|---|
Type | Description |
array | [https://firebase.google.com/docs/firestore/reference/rpc/google.firestore.v1beta1#BatchWriteResponse](BatchWriteResponse) |
commit
Commit writes to the database.
Not to be used together with flush / close.
Example:
$batch->commit();
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'