Transaction

Transaction

A reference to a transaction.

The Transaction object passed to a transaction's updateFunction provides the methods to read and write data within the transaction context. See runTransaction().

Constructor

new Transaction(firestore, requestTag, previousTransaction)

Parameters:
Name Type Description
firestore

The Firestore Database client.
requestTag

A unique client-assigned identifier for the scope of this transaction.
previousTransaction

If available, the failed transaction that is being retried.
Source:

Methods

create(documentRef, data) → {Transaction}

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

Parameters:
Name Type Description
documentRef DocumentReference

A reference to the document to be created.
data DocumentData

The object data to serialize as the document.
Source:
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(documentRef, preconditionopt) → {Transaction}

Deletes the document referred to by the provided DocumentReference.

Parameters:
Name Type Attributes Description
documentRef DocumentReference

A reference to the document to be deleted.
precondition Precondition <optional>

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 transaction if the document doesn't exist or was last updated at a different time.
Source:
Example
firestore.runTransaction(transaction => {
  let documentRef = firestore.doc('col/doc');
  transaction.delete(documentRef);
  return Promise.resolve();
});

get(refOrQuery) → {Promise}

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

Parameters:
Name Type Description
refOrQuery DocumentReference | Query

The document or query to return.
Source:
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(…documentRefsOrReadOptions) → {Promise.<Array.<DocumentSnapshot>>}

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

The first argument is required and must be of type DocumentReference followed by any additional DocumentReference documents. If used, the optional ReadOptions must be the last argument.

Parameters:
Name Type Attributes Description
documentRefsOrReadOptions DocumentReference | ReadOptions <repeatable>

The DocumentReferences to receive, followed by an optional field mask.
Source:
Example
let firstDoc = firestore.doc('col/doc1');
let secondDoc = firestore.doc('col/doc2');
let resultDoc = firestore.doc('col/doc3');

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

set(documentRef, data, optionsopt) → {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.

Parameters:
Name Type Attributes Description
documentRef DocumentReference

A reference to the document to be set.
data DocumentData

The object to serialize as the document.
options SetOptions <optional>

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.
mergeFields Array.<(string|FieldPath)> <optional>

If provided, set() only replaces the specified field paths. Any field path that is not specified is ignored and remains untouched.
Source:
Example
firestore.runTransaction(transaction => {
  let documentRef = firestore.doc('col/doc');
  transaction.set(documentRef, { foo: 'bar' });
  return Promise.resolve();
});

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

Updates fields in the document referred to by the provided [DocumentReference]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.

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 to enforce on this update.
Source:
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 });
    }
  });
});