Class Transaction (4.15.1)

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)

constructor(firestore: Firestore, requestTag: string);

Constructs a new instance of the Transaction class

Parameters
NameDescription
firestore Firestore

The Firestore Database client.

requestTag string

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

Methods

create(documentRef, data)

create<T>(documentRef: firestore.DocumentReference<T>, data: T): 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
NameDescription
documentRef FirebaseFirestore.DocumentReference<T>

A reference to the document to be created.

data T

The object data to serialize as the document.

Returns
TypeDescription
Transaction

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

Type Parameter
NameDescription
T
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<T>(documentRef: DocumentReference<T>, precondition?: firestore.Precondition): this;

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

Parameters
NameDescription
documentRef DocumentReference<T>

A reference to the document to be deleted.

precondition firestore.Precondition

A precondition to enforce for this delete.

Returns
TypeDescription
this

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

Type Parameter
NameDescription
T
Example

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

get(query)

get<T>(query: Query<T>): Promise<QuerySnapshot<T>>;

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

Parameter
NameDescription
query Query<T>

A query to execute. {Promise

Returns
TypeDescription
Promise<QuerySnapshot<T>>
Type Parameter
NameDescription
T

get(documentRef)

get<T>(documentRef: DocumentReference<T>): Promise<DocumentSnapshot<T>>;

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

Parameter
NameDescription
documentRef DocumentReference<T>

A reference to the document to be read. {Promise

Returns
TypeDescription
Promise<DocumentSnapshot<T>>
Type Parameter
NameDescription
T

getAll(documentRefsOrReadOptions)

getAll<T>(...documentRefsOrReadOptions: Array<firestore.DocumentReference<T> | firestore.ReadOptions>): Promise<Array<DocumentSnapshot<T>>>;

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
NameDescription
documentRefsOrReadOptions Array<FirebaseFirestore.DocumentReference<T> | FirebaseFirestore.ReadOptions>

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

Returns
TypeDescription
Promise<Array<DocumentSnapshot<T>>>

{Promise<Array.

Type Parameter
NameDescription
T
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<T>(documentRef: firestore.DocumentReference<T>, data: Partial<T>, options: firestore.SetOptions): Transaction;
Parameters
NameDescription
documentRef FirebaseFirestore.DocumentReference<T>
data Partial<T>
options firestore.SetOptions
Returns
TypeDescription
Transaction
Type Parameter
NameDescription
T

set(documentRef, data)

set<T>(documentRef: firestore.DocumentReference<T>, data: T): Transaction;
Parameters
NameDescription
documentRef FirebaseFirestore.DocumentReference<T>
data T
Returns
TypeDescription
Transaction
Type Parameter
NameDescription
T

update(documentRef, dataOrField, preconditionOrValues)

update<T>(documentRef: firestore.DocumentReference<T>, dataOrField: firestore.UpdateData | 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
NameDescription
documentRef FirebaseFirestore.DocumentReference<T>

A reference to the document to be updated.

dataOrField FirebaseFirestore.UpdateData | 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
TypeDescription
Transaction

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

Type Parameter
NameDescription
T
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 }); } }); });