Class Transaction (7.9.0)

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

Transaction

Package

@google-cloud/firestore

Constructors

(constructor)(firestore, requestTag, transactionOptions)

constructor(firestore: Firestore, requestTag: string, transactionOptions?: firestore.ReadWriteTransactionOptions | firestore.ReadOnlyTransactionOptions);

Constructs a new instance of the Transaction class

Parameters
Name Description
firestore Firestore

The Firestore Database client.

requestTag string

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

transactionOptions FirebaseFirestore.ReadWriteTransactionOptions | FirebaseFirestore.ReadOnlyTransactionOptions

The user-defined options for this transaction.

Methods

create(documentRef, data)

create<AppModelType, DbModelType extends firestore.DocumentData>(documentRef: firestore.DocumentReference<AppModelType, DbModelType>, data: firestore.WithFieldValue<AppModelType>): Transaction;

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

Parameters
Name Description
documentRef FirebaseFirestore.DocumentReference<AppModelType, DbModelType>

A reference to the document to be created.

data FirebaseFirestore.WithFieldValue<AppModelType>

The object data to serialize as the document.

Returns
Type Description
Transaction

{Transaction} This Transaction instance. Used for chaining method calls.

Type Parameters
Name Description
AppModelType
DbModelType
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, precondition)

delete(documentRef: DocumentReference<any, any>, precondition?: firestore.Precondition): this;

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

Parameters
Name Description
documentRef DocumentReference<any, any>

A reference to the document to be deleted.

precondition firestore.Precondition

A precondition to enforce for this delete.

Returns
Type Description
this

{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(query)

get<AppModelType, DbModelType extends firestore.DocumentData>(query: firestore.Query<AppModelType, DbModelType>): Promise<QuerySnapshot<AppModelType, DbModelType>>;

Retrieves a query result. Holds a pessimistic lock on all returned documents.

Parameter
Name Description
query FirebaseFirestore.Query<AppModelType, DbModelType>

A query to execute. {Promise

Returns
Type Description
Promise<QuerySnapshot<AppModelType, DbModelType>>
Type Parameters
Name Description
AppModelType
DbModelType

get(documentRef)

get<AppModelType, DbModelType extends firestore.DocumentData>(documentRef: firestore.DocumentReference<AppModelType, DbModelType>): Promise<DocumentSnapshot<AppModelType, DbModelType>>;

Reads the document referenced by the provided DocumentReference. Holds a pessimistic lock on the returned document.

Parameter
Name Description
documentRef FirebaseFirestore.DocumentReference<AppModelType, DbModelType>

A reference to the document to be read. {Promise

Returns
Type Description
Promise<DocumentSnapshot<AppModelType, DbModelType>>
Type Parameters
Name Description
AppModelType
DbModelType

get(aggregateQuery)

get<AppModelType, DbModelType extends firestore.DocumentData, AggregateSpecType extends firestore.AggregateSpec>(aggregateQuery: firestore.AggregateQuery<AggregateSpecType, AppModelType, DbModelType>): Promise<AggregateQuerySnapshot<AggregateSpecType, AppModelType, DbModelType>>;

Retrieves an aggregate query result. Holds a pessimistic lock on all documents that were matched by the underlying query.

Parameter
Name Description
aggregateQuery FirebaseFirestore.AggregateQuery<AggregateSpecType, AppModelType, DbModelType>

An aggregate query to execute. An AggregateQuerySnapshot for the retrieved data.

Returns
Type Description
Promise<AggregateQuerySnapshot<AggregateSpecType, AppModelType, DbModelType>>
Type Parameters
Name Description
AppModelType
DbModelType
AggregateSpecType

getAll(documentRefsOrReadOptions)

getAll<AppModelType, DbModelType extends firestore.DocumentData>(...documentRefsOrReadOptions: Array<firestore.DocumentReference<AppModelType, DbModelType> | firestore.ReadOptions>): Promise<Array<DocumentSnapshot<AppModelType, DbModelType>>>;

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.

Parameter
Name Description
documentRefsOrReadOptions Array<FirebaseFirestore.DocumentReference<AppModelType, DbModelType> | FirebaseFirestore.ReadOptions>

The DocumentReferences to receive, followed by an optional field mask.

Returns
Type Description
Promise<Array<DocumentSnapshot<AppModelType, DbModelType>>>

{Promise<Array.

Type Parameters
Name Description
AppModelType
DbModelType
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, options)

set<AppModelType, DbModelType extends firestore.DocumentData>(documentRef: firestore.DocumentReference<AppModelType, DbModelType>, data: firestore.PartialWithFieldValue<AppModelType>, options: firestore.SetOptions): Transaction;
Parameters
Name Description
documentRef FirebaseFirestore.DocumentReference<AppModelType, DbModelType>
data FirebaseFirestore.PartialWithFieldValue<AppModelType>
options firestore.SetOptions
Returns
Type Description
Transaction
Type Parameters
Name Description
AppModelType
DbModelType

set(documentRef, data)

set<AppModelType, DbModelType extends firestore.DocumentData>(documentRef: firestore.DocumentReference<AppModelType, DbModelType>, data: firestore.WithFieldValue<AppModelType>): Transaction;
Parameters
Name Description
documentRef FirebaseFirestore.DocumentReference<AppModelType, DbModelType>
data FirebaseFirestore.WithFieldValue<AppModelType>
Returns
Type Description
Transaction
Type Parameters
Name Description
AppModelType
DbModelType

update(documentRef, dataOrField, preconditionOrValues)

update<AppModelType, DbModelType extends firestore.DocumentData>(documentRef: firestore.DocumentReference<AppModelType, DbModelType>, dataOrField: firestore.UpdateData<DbModelType> | string | firestore.FieldPath, ...preconditionOrValues: Array<firestore.Precondition | unknown | string | firestore.FieldPath>): 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 Description
documentRef FirebaseFirestore.DocumentReference<AppModelType, DbModelType>

A reference to the document to be updated.

dataOrField FirebaseFirestore.UpdateData<DbModelType> | string | FirebaseFirestore.FieldPath

An object containing the fields and values with which to update the document or the path of the first field to update.

preconditionOrValues Array<FirebaseFirestore.Precondition | unknown | string | FirebaseFirestore.FieldPath>

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

Returns
Type Description
Transaction

{Transaction} This Transaction instance. Used for chaining method calls.

Type Parameters
Name Description
AppModelType
DbModelType
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 });
    }
  });
});