WriteBatch - Documentation

new WriteBatch()

A Firestore WriteBatch that can be used to atomically commit multiple write operations at once.

Methods

commit() → {Promise.<Array.<WriteResult>>}

Atomically commits all pending operations to the database and verifies all preconditions. Fails the entire write if any precondition is not met.

Returns:

Type	Description
Promise.<Array.<WriteResult>>	A Promise that resolves when this batch completes.

Example

```
let writeBatch = firestore.batch();
let documentRef = firestore.doc('col/doc');

writeBatch.set(documentRef, {foo: 'bar'});

writeBatch.commit().then(() => {
  console.log('Successfully executed batch.');
});
```

create(documentRef, data) → {WriteBatch}

Create a document with the provided object values. This will fail the batch if a document exists at its location.

Parameters:

Name	Type	Description
`documentRef`	DocumentReference	A reference to the document to be created.
`data`	T	The object to serialize as the document.

Returns:

Type	Description
WriteBatch	This WriteBatch instance. Used for chaining method calls.

Throws:

If the provided input is not a valid Firestore document.
Type Error

Example

```
let writeBatch = firestore.batch();
let documentRef = firestore.collection('col').doc();

writeBatch.create(documentRef, {foo: 'bar'});

writeBatch.commit().then(() => {
  console.log('Successfully executed batch.');
});
```

delete(documentRef, preconditionopt) → {WriteBatch}

Deletes a document from the database.

Parameters:

Name Type Attributes Description

documentRef

DocumentReference

A reference to the document to be deleted.

precondition

Precondition

A precondition to enforce for this delete.

Properties

Name	Type	Attributes	Description
`lastUpdateTime`	Timestamp	<optional>	If set, enforces that the document was last updated at lastUpdateTime. Fails the batch if the document doesn't exist or was last updated at a different time.
`exists`	boolean	<optional>	If set to true, enforces that the target document must or must not exist.

Returns:

Type	Description
WriteBatch	This WriteBatch instance. Used for chaining method calls.

Example

```
let writeBatch = firestore.batch();
let documentRef = firestore.doc('col/doc');

writeBatch.delete(documentRef);

writeBatch.commit().then(() => {
  console.log('Successfully executed batch.');
});
```

set(documentRef, data, optionsopt) → {WriteBatch}

Write to the document referred to by the provided DocumentReference. If the document does not exist yet, it will be created. If you pass SetOptions, the provided data can be merged into the existing document.

Parameters:

Name Type Attributes Description

documentRef

DocumentReference

A reference to the document to be set.

data

T | Partial.<T>

The object to serialize as the document.

options

SetOptions

An object to configure the set behavior.

Properties

Name	Type	Attributes	Description
`merge`	boolean	<optional>	If true, set() merges the values specified in its data argument. Fields omitted from this set() call remain untouched. If your input sets any field to an empty map, all nested fields are overwritten.
`mergeFields`	Array.<(string\|FieldPath)>	<optional>	If provided, set() only replaces the specified field paths. Any field path that is no specified is ignored and remains untouched. If your input sets any field to an empty map, all nested fields are overwritten.

Returns:

Type	Description
WriteBatch	This WriteBatch instance. Used for chaining method calls.

Throws:

If the provided input is not a valid Firestore document.
Type Error

Example

```
let writeBatch = firestore.batch();
let documentRef = firestore.doc('col/doc');

writeBatch.set(documentRef, {foo: 'bar'});

writeBatch.commit().then(() => {
  console.log('Successfully executed batch.');
});
```

update(documentRef, dataOrField, …preconditionOrValues) → {WriteBatch}

Update fields of the document referred to by the provided DocumentReference. If the document doesn't yet exist, the update fails and the entire batch will be rejected.

The update() method accepts either an object with field paths encoded as keys and field values encoded as values, or a variable number of arguments that alternate between field paths and field values. Nested fields can be updated by providing dot-separated field path strings or by providing FieldPath objects.

A Precondition restricting this update can be specified as the last argument.

Parameters:

Name	Type	Attributes	Description
`documentRef`	DocumentReference		A reference to the document to be updated.
`dataOrField`	UpdateData \| string \| FieldPath		An object containing the fields and values with which to update the document or the path of the first field to update.
`preconditionOrValues`	Precondition \| * \| string \| FieldPath	<repeatable>	An alternating list of field paths and values to update or a Precondition to restrict this update.

Returns:

Type	Description
WriteBatch	This WriteBatch instance. Used for chaining method calls.

Throws:

If the provided input is not valid Firestore data.
Type Error

Example

```
let writeBatch = firestore.batch();
let documentRef = firestore.doc('col/doc');

writeBatch.update(documentRef, {foo: 'bar'});

writeBatch.commit().then(() => {
  console.log('Successfully executed batch.');
});
```