Class Transaction (7.5.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 });
    }
  });
});