@google-cloud/firestore 0.14.1 » Class: Transaction

Transaction

class

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().

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/doc3');

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() merges the values specified in its data argument. Fields omitted from this set() call remain untouched. mergeFields Optional Array of (string or FieldPath) If provided, set() only replaces the specified field paths. Any field path that is not specified is ignored and remains 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 });
    }
  });
});