Transaction

Transaction

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

Members

_backoff

undefined if transaction is read only

_readOnlyReadTime

Optional, could be set only if transaction is read only

_transactionIdPromise

Promise that resolves to the transaction ID of the current attempt. It is lazily initialised upon the first read. Upon retry, it is reset and _prevTransactionId is set

_writeBatch

undefined if transaction is read only

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.
Returns:
Type Description
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(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.
exists boolean <optional>

If set, enforces that the target document must or must not exist.
Returns:
Type Description
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();
});
```

execute()

Executes this pipeline and returns a Promise to represent the asynchronous operation.

The returned Promise can be used to track the progress of the pipeline execution and retrieve the results (or handle any errors) asynchronously.

The pipeline results are returned in a `PipelineSnapshot` object, which contains a list of `PipelineResult` objects. Each `PipelineResult` typically represents a single key/value map that has passed through all the stages of the pipeline, however this might differ depending on the stages involved in the pipeline. For example:

  • If there are no stages or only transformation stages, each `PipelineResult` represents a single document.
  • If there is an aggregation, only a single `PipelineResult` is returned, representing the aggregated results over the entire dataset .
  • If there is an aggregation stage with grouping, each `PipelineResult` represents a distinct group and its associated aggregated values.
Returns:
Type Description

A Promise representing the asynchronous pipeline execution.
Example
```typescript
const futureResults = await transaction
  .execute(
    firestore.pipeline().collection("books")
      .where(greaterThan(field("rating"), 4.5))
      .select("title", "author", "rating"));
```

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.
Returns:
Type Description
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(…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.
Returns:
Type Description
Promise.<Array.<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[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 T | Partial.<T>

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. If your input sets any field to an empty map, all nested fields are overwritten.
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. If your input sets any field to an empty map, all nested fields are overwritten.
Returns:
Type Description
Transaction

This Transaction instance. Used for chaining method calls.
Throws:

If the provided input is not a valid Firestore document.

Type
Error
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.
Returns:
Type Description
Transaction

This Transaction instance. Used for chaining method calls.
Throws:

If the provided input is not valid Firestore data.

Type
Error
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 });
    }
  });
});
```

withLazyStartedTransaction()

Given a function that performs a read operation, ensures that the first one is provided with new transaction options and all subsequent ones are queued upon the resulting transaction ID.