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()
.
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, precondition
opt
)
→ {
Transaction
}
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();
});
```
get
(refOrQuery)
→ {Promise}
Retrieve a document or a query result from the database. Holds a
pessimistic lock on all returned documents.
Parameters:
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, options
opt
)
→ {
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.
