Methods

create

create(documentRef, data) returns Transaction

Create the document referred to by the provided DocumentReference. The operation will fail the transaction if a document exists at the specified location.

Parameter

documentRef

DocumentReference

A reference to the document to be created.

data

DocumentData

The object data to serialize as the document.

Returns

Transaction 

This Transaction instance. Used for chaining method calls.

Example

firestore.runTransaction(transaction => {
  let documentRef = firestore.doc('col/doc');
  return transaction.get(documentRef).then(doc => {
    if (!doc.exists) {
      transaction.create(documentRef, { foo: 'bar' });
    }
  });
});

delete

delete(documentRef, precondition) returns Transaction

Deletes the document referred to by the provided [DocumentReference] DocumentReference.

Parameter

documentRef

DocumentReference

A reference to the document to be deleted.

precondition

Optional

Precondition

A precondition to enforce for this delete.

Values in precondition have the following properties:

Parameter

lastUpdateTime

Optional

string

If set, enforces that the document was last updated at lastUpdateTime (as ISO 8601 string). Fails the transaction if the document doesn't exist or was last updated at a different time.

Returns

Transaction 

This Transaction instance. Used for chaining method calls.

Example

firestore.runTransaction(transaction => {
  let documentRef = firestore.doc('col/doc');
  transaction.delete(documentRef);
  return Promise.resolve();
});

get

get(refOrQuery) returns Promise

Retrieve a document or a query result from the database. Holds a pessimistic lock on all returned documents.

Parameter

refOrQuery

(DocumentReference or Query)

The document or query to return.

Returns

Promise 

A Promise that resolves with a DocumentSnapshot or QuerySnapshot for the returned documents.

Example

firestore.runTransaction(transaction => {
  let documentRef = firestore.doc('col/doc');
  return transaction.get(documentRef).then(doc => {
    if (doc.exists) {
      transaction.update(documentRef, { count: doc.get('count') + 1 });
    } else {
      transaction.create(documentRef, { count: 1 });
    }
  });
});

getAll

getAll(...documents) returns Promise containing Array of DocumentSnapshot

Retrieves multiple documents from Firestore. Holds a pessimistic lock on all returned documents.

Parameter

documents

DocumentReference

The document references to receive.

Value may be repeated.

Returns

Promise containing Array of DocumentSnapshot 

A Promise that contains an array with the resulting document snapshots.

Example

let firstDoc = firestore.doc('col/doc1');
let secondDoc = firestore.doc('col/doc2');
let resultDoc = firestore.doc('col/doc2');

firestore.runTransaction(transaction => {
  return transaction.getAll(firstDoc, secondDoc).then(docs => {
    transaction.set(resultDoc, {
      sum: docs[1].get('count') + docs[2].get('count')
    });
  });
});

set

set(documentRef, data, options) returns Transaction

Writes 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.

Parameter

documentRef

DocumentReference

A reference to the document to be set.

data

DocumentData

The object to serialize as the document.

options

Optional

SetOptions

An object to configure the set behavior.

Values in options have the following properties:

Parameter

merge

Optional

boolean

If true, set() only replaces the values specified in its data argument. Fields omitted from this set() call remain untouched.

Returns

Transaction 

This Transaction instance. Used for chaining method calls.

Example

firestore.runTransaction(transaction => {
  let documentRef = firestore.doc('col/doc');
  transaction.set(documentRef, { foo: 'bar' });
  return Promise.resolve();
});

update

update(documentRef, dataOrField, ...preconditionOrValues) returns Transaction

Updates fields in the document referred to by the provided DocumentReference. The update will fail if applied to a document that does not exist.

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.

Parameter

documentRef

DocumentReference

A reference to the document to be updated.

dataOrField

(UpdateData, string, or 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, any type, string, or FieldPath)

An alternating list of field paths and values to update or a Precondition to to enforce on this update.

Value may be repeated.

Returns

Transaction 

This Transaction instance. Used for chaining method calls.

Example

firestore.runTransaction(transaction => {
  let documentRef = firestore.doc('col/doc');
  return transaction.get(documentRef).then(doc => {
    if (doc.exists) {
      transaction.update(documentRef, { count: doc.get('count') + 1 });
    } else {
      transaction.create(documentRef, { count: 1 });
    }
  });
});