Cloud Firestore 支持讀取和寫入數據的原子操作。在一組原子操作中，要么所有操作都成功，要么都不應用。 Cloud Firestore 中有兩種類型的原子操作：
每個事務或批量寫入最多可以寫入 500 個文檔。有關與寫入相關的其他限制，請參閱配額和限制。
使用事務更新數據
使用 Cloud Firestore 客戶端庫，您可以將多個操作組合到一個事務中。當您想要根據字段的當前值或其他字段的值更新字段的值時，事務很有用。
事務由任意數量的get()操作和後跟任意數量的寫操作組成，例如set() 、 update()或delete() 。在並發編輯的情況下，Cloud Firestore 會再次運行整個事務。例如，如果一個事務讀取文檔，而另一個客戶端修改了這些文檔中的任何一個，Cloud Firestore 會重試該事務。此功能可確保事務在最新且一致的數據上運行。
事務從不部分應用寫入。所有寫入都在成功事務結束時執行。
使用事務時，請注意：
- 讀操作必須在寫操作之前進行。
- 如果並發編輯影響事務讀取的文檔，調用事務的函數（事務函數）可能會運行多次。
- 交易功能不應直接修改應用程序狀態。
- 當客戶端離線時，交易將失敗。
以下示例顯示如何創建和運行事務：
Web modular API
import { runTransaction } from "firebase/firestore";
try {
await runTransaction(db, async (transaction) => {
const sfDoc = await transaction.get(sfDocRef);
if (!sfDoc.exists()) {
throw "Document does not exist!";
}
const newPopulation = sfDoc.data().population + 1;
transaction.update(sfDocRef, { population: newPopulation });
});
console.log("Transaction successfully committed!");
} catch (e) {
console.log("Transaction failed: ", e);
}Web namespaced API
// Create a reference to the SF doc.
var sfDocRef = db.collection("cities").doc("SF");
// Uncomment to initialize the doc.
// sfDocRef.set({ population: 0 });
return db.runTransaction((transaction) => {
// This code may get re-run multiple times if there are conflicts.
return transaction.get(sfDocRef).then((sfDoc) => {
if (!sfDoc.exists) {
throw "Document does not exist!";
}
// Add one person to the city population.
// Note: this could be done without a transaction
// by updating the population using FieldValue.increment()
var newPopulation = sfDoc.data().population + 1;
transaction.update(sfDocRef, { population: newPopulation });
});
}).then(() => {
console.log("Transaction successfully committed!");
}).catch((error) => {
console.log("Transaction failed: ", error);
});迅速
注意：此產品不適用於 watchOS 和 App Clip 目標。
let sfReference = db.collection("cities").document("SF")
db.runTransaction({ (transaction, errorPointer) -> Any? in
let sfDocument: DocumentSnapshot
do {
try sfDocument = transaction.getDocument(sfReference)
} catch let fetchError as NSError {
errorPointer?.pointee = fetchError
return nil
}
guard let oldPopulation = sfDocument.data()?["population"] as? Int else {
let error = NSError(
domain: "AppErrorDomain",
code: -1,
userInfo: [
NSLocalizedDescriptionKey: "Unable to retrieve population from snapshot \(sfDocument)"
]
)
errorPointer?.pointee = error
return nil
}
// Note: this could be done without a transaction
// by updating the population using FieldValue.increment()
transaction.updateData(["population": oldPopulation + 1], forDocument: sfReference)
return nil
}) { (object, error) in
if let error = error {
print("Transaction failed: \(error)")
} else {
print("Transaction successfully committed!")
}
}目標-C
注意：此產品不適用於 watchOS 和 App Clip 目標。
FIRDocumentReference *sfReference =
[[self.db collectionWithPath:@"cities"] documentWithPath:@"SF"];
[self.db runTransactionWithBlock:^id (FIRTransaction *transaction, NSError **errorPointer) {
FIRDocumentSnapshot *sfDocument = [transaction getDocument:sfReference error:errorPointer];
if (*errorPointer != nil) { return nil; }
if (![sfDocument.data[@"population"] isKindOfClass:[NSNumber class]]) {
*errorPointer = [NSError errorWithDomain:@"AppErrorDomain" code:-1 userInfo:@{
NSLocalizedDescriptionKey: @"Unable to retreive population from snapshot"
}];
return nil;
}
NSInteger oldPopulation = [sfDocument.data[@"population"] integerValue];
// Note: this could be done without a transaction
// by updating the population using FieldValue.increment()
[transaction updateData:@{ @"population": @(oldPopulation + 1) } forDocument:sfReference];
return nil;
} completion:^(id result, NSError *error) {
if (error != nil) {
NSLog(@"Transaction failed: %@", error);
} else {
NSLog(@"Transaction successfully committed!");
}
}];Kotlin+KTX
val sfDocRef = db.collection("cities").document("SF")
db.runTransaction { transaction ->
val snapshot = transaction.get(sfDocRef)
// Note: this could be done without a transaction
// by updating the population using FieldValue.increment()
val newPopulation = snapshot.getDouble("population")!! + 1
transaction.update(sfDocRef, "population", newPopulation)
// Success
null
}.addOnSuccessListener { Log.d(TAG, "Transaction success!") }
.addOnFailureListener { e -> Log.w(TAG, "Transaction failure.", e) }Java
final DocumentReference sfDocRef = db.collection("cities").document("SF");
db.runTransaction(new Transaction.Function<Void>() {
@Override
public Void apply(@NonNull Transaction transaction) throws FirebaseFirestoreException {
DocumentSnapshot snapshot = transaction.get(sfDocRef);
// Note: this could be done without a transaction
// by updating the population using FieldValue.increment()
double newPopulation = snapshot.getDouble("population") + 1;
transaction.update(sfDocRef, "population", newPopulation);
// Success
return null;
}
}).addOnSuccessListener(new OnSuccessListener<Void>() {
@Override
public void onSuccess(Void aVoid) {
Log.d(TAG, "Transaction success!");
}
})
.addOnFailureListener(new OnFailureListener() {
@Override
public void onFailure(@NonNull Exception e) {
Log.w(TAG, "Transaction failure.", e);
}
});Dart
final sfDocRef = db.collection("cities").doc("SF");
db.runTransaction((transaction) async {
final snapshot = await transaction.get(sfDocRef);
// Note: this could be done without a transaction
// by updating the population using FieldValue.increment()
final newPopulation = snapshot.get("population") + 1;
transaction.update(sfDocRef, {"population": newPopulation});
}).then(
(value) => print("DocumentSnapshot successfully updated!"),
onError: (e) => print("Error updating document $e"),
);爪哇
Python
Python
C++
DocumentReference sf_doc_ref = db->Collection("cities").Document("SF");
db->RunTransaction([sf_doc_ref](Transaction& transaction,
std::string& out_error_message) -> Error {
Error error = Error::kErrorOk;
DocumentSnapshot snapshot =
transaction.Get(sf_doc_ref, &error, &out_error_message);
// Note: this could be done without a transaction by updating the
// population using FieldValue::Increment().
std::int64_t new_population =
snapshot.Get("population").integer_value() + 1;
transaction.Update(
sf_doc_ref,
{{"population", FieldValue::Integer(new_population)}});
return Error::kErrorOk;
}).OnCompletion([](const Future<void>& future) {
if (future.error() == Error::kErrorOk) {
std::cout << "Transaction success!" << std::endl;
} else {
std::cout << "Transaction failure: " << future.error_message() << std::endl;
}
});節點.js
去
PHP
統一
DocumentReference cityRef = db.Collection("cities").Document("SF");
db.RunTransactionAsync(transaction =>
{
return transaction.GetSnapshotAsync(cityRef).ContinueWith((snapshotTask) =>
{
DocumentSnapshot snapshot = snapshotTask.Result;
long newPopulation = snapshot.GetValue<long>("Population") + 1;
Dictionary<string, object> updates = new Dictionary<string, object>
{
{ "Population", newPopulation}
};
transaction.Update(cityRef, updates);
});
});C＃
紅寶石
從交易中傳遞信息
不要在您的事務函數中修改應用程序狀態。這樣做會引入並發問題，因為事務函數可以運行多次並且不能保證在 UI 線程上運行。相反，將您需要的信息傳遞到您的交易功能之外。以下示例建立在前面的示例之上，以顯示如何將信息傳遞出事務：
Web modular API
import { doc, runTransaction } from "firebase/firestore";
// Create a reference to the SF doc.
const sfDocRef = doc(db, "cities", "SF");
try {
const newPopulation = await runTransaction(db, async (transaction) => {
const sfDoc = await transaction.get(sfDocRef);
if (!sfDoc.exists()) {
throw "Document does not exist!";
}
const newPop = sfDoc.data().population + 1;
if (newPop <= 1000000) {
transaction.update(sfDocRef, { population: newPop });
return newPop;
} else {
return Promise.reject("Sorry! Population is too big");
}
});
console.log("Population increased to ", newPopulation);
} catch (e) {
// This will be a "population is too big" error.
console.error(e);
}Web namespaced API
// Create a reference to the SF doc.
var sfDocRef = db.collection("cities").doc("SF");
db.runTransaction((transaction) => {
return transaction.get(sfDocRef).then((sfDoc) => {
if (!sfDoc.exists) {
throw "Document does not exist!";
}
var newPopulation = sfDoc.data().population + 1;
if (newPopulation <= 1000000) {
transaction.update(sfDocRef, { population: newPopulation });
return newPopulation;
} else {
return Promise.reject("Sorry! Population is too big.");
}
});
}).then((newPopulation) => {
console.log("Population increased to ", newPopulation);
}).catch((err) => {
// This will be an "population is too big" error.
console.error(err);
});迅速
注意：此產品不適用於 watchOS 和 App Clip 目標。
let sfReference = db.collection("cities").document("SF")
db.runTransaction({ (transaction, errorPointer) -> Any? in
let sfDocument: DocumentSnapshot
do {
try sfDocument = transaction.getDocument(sfReference)
} catch let fetchError as NSError {
errorPointer?.pointee = fetchError
return nil
}
guard let oldPopulation = sfDocument.data()?["population"] as? Int else {
let error = NSError(
domain: "AppErrorDomain",
code: -1,
userInfo: [
NSLocalizedDescriptionKey: "Unable to retrieve population from snapshot \(sfDocument)"
]
)
errorPointer?.pointee = error
return nil
}
// Note: this could be done without a transaction
// by updating the population using FieldValue.increment()
let newPopulation = oldPopulation + 1
guard newPopulation <= 1000000 else {
let error = NSError(
domain: "AppErrorDomain",
code: -2,
userInfo: [NSLocalizedDescriptionKey: "Population \(newPopulation) too big"]
)
errorPointer?.pointee = error
return nil
}
transaction.updateData(["population": newPopulation], forDocument: sfReference)
return newPopulation
}) { (object, error) in
if let error = error {
print("Error updating population: \(error)")
} else {
print("Population increased to \(object!)")
}
}目標-C
注意：此產品不適用於 watchOS 和 App Clip 目標。
FIRDocumentReference *sfReference =
[[self.db collectionWithPath:@"cities"] documentWithPath:@"SF"];
[self.db runTransactionWithBlock:^id (FIRTransaction *transaction, NSError **errorPointer) {
FIRDocumentSnapshot *sfDocument = [transaction getDocument:sfReference error:errorPointer];
if (*errorPointer != nil) { return nil; }
if (![sfDocument.data[@"population"] isKindOfClass:[NSNumber class]]) {
*errorPointer = [NSError errorWithDomain:@"AppErrorDomain" code:-1 userInfo:@{
NSLocalizedDescriptionKey: @"Unable to retreive population from snapshot"
}];
return nil;
}
NSInteger population = [sfDocument.data[@"population"] integerValue];
population++;
if (population >= 1000000) {
*errorPointer = [NSError errorWithDomain:@"AppErrorDomain" code:-2 userInfo:@{
NSLocalizedDescriptionKey: @"Population too big"
}];
return @(population);
}
[transaction updateData:@{ @"population": @(population) } forDocument:sfReference];
return nil;
} completion:^(id result, NSError *error) {
if (error != nil) {
NSLog(@"Transaction failed: %@", error);
} else {
NSLog(@"Population increased to %@", result);
}
}];Kotlin+KTX
val sfDocRef = db.collection("cities").document("SF")
db.runTransaction { transaction ->
val snapshot = transaction.get(sfDocRef)
val newPopulation = snapshot.getDouble("population")!! + 1
if (newPopulation <= 1000000) {
transaction.update(sfDocRef, "population", newPopulation)
newPopulation
} else {
throw FirebaseFirestoreException(
"Population too high",
FirebaseFirestoreException.Code.ABORTED,
)
}
}.addOnSuccessListener { result ->
Log.d(TAG, "Transaction success: $result")
}.addOnFailureListener { e ->
Log.w(TAG, "Transaction failure.", e)
}Java
final DocumentReference sfDocRef = db.collection("cities").document("SF");
db.runTransaction(new Transaction.Function<Double>() {
@Override
public Double apply(@NonNull Transaction transaction) throws FirebaseFirestoreException {
DocumentSnapshot snapshot = transaction.get(sfDocRef);
double newPopulation = snapshot.getDouble("population") + 1;
if (newPopulation <= 1000000) {
transaction.update(sfDocRef, "population", newPopulation);
return newPopulation;
} else {
throw new FirebaseFirestoreException("Population too high",
FirebaseFirestoreException.Code.ABORTED);
}
}
}).addOnSuccessListener(new OnSuccessListener<Double>() {
@Override
public void onSuccess(Double result) {
Log.d(TAG, "Transaction success: " + result);
}
})
.addOnFailureListener(new OnFailureListener() {
@Override
public void onFailure(@NonNull Exception e) {
Log.w(TAG, "Transaction failure.", e);
}
});Dart
final sfDocRef = db.collection("cities").doc("SF");
db.runTransaction((transaction) {
return transaction.get(sfDocRef).then((sfDoc) {
final newPopulation = sfDoc.get("population") + 1;
transaction.update(sfDocRef, {"population": newPopulation});
return newPopulation;
});
}).then(
(newPopulation) => print("Population increased to $newPopulation"),
onError: (e) => print("Error updating document $e"),
);爪哇
Python
Python
C++
// This is not yet supported.
節點.js
去
PHP
統一
DocumentReference cityRef = db.Collection("cities").Document("SF");
db.RunTransactionAsync(transaction =>
{
return transaction.GetSnapshotAsync(cityRef).ContinueWith((task) =>
{
long newPopulation = task.Result.GetValue<long>("Population") + 1;
if (newPopulation <= 1000000)
{
Dictionary<string, object> updates = new Dictionary<string, object>
{
{ "Population", newPopulation}
};
transaction.Update(cityRef, updates);
return true;
}
else
{
return false;
}
});
}).ContinueWith((transactionResultTask) =>
{
if (transactionResultTask.Result)
{
Console.WriteLine("Population updated successfully.");
}
else
{
Console.WriteLine("Sorry! Population is too big.");
}
});C＃
紅寶石
交易失敗
事務可能因以下原因而失敗：
- 事務包含寫操作之後的讀操作。讀取操作必須始終在任何寫入操作之前進行。
- 事務讀取在事務外修改的文檔。在這種情況下，事務會自動再次運行。事務重試次數有限。
該事務超過了 10 MiB 的最大請求大小。
事務大小取決於事務修改的文檔和索引條目的大小。對於刪除操作，這包括目標文檔的大小和響應操作刪除的索引條目的大小。
失敗的事務會返回一個錯誤，並且不會向數據庫寫入任何內容。您不需要回滾事務； Cloud Firestore 會自動執行此操作。
批量寫入
如果您不需要讀取操作集中的任何文檔，則可以將多個寫入操作作為包含set() 、 update()或delete()操作的任意組合的單個批處理來執行。一批寫入以原子方式完成，並且可以寫入多個文檔。以下示例顯示瞭如何構建和提交寫入批處理：
Web modular API
import { writeBatch, doc } from "firebase/firestore";
// Get a new write batch
const batch = writeBatch(db);
// Set the value of 'NYC'
const nycRef = doc(db, "cities", "NYC");
batch.set(nycRef, {name: "New York City"});
// Update the population of 'SF'
const sfRef = doc(db, "cities", "SF");
batch.update(sfRef, {"population": 1000000});
// Delete the city 'LA'
const laRef = doc(db, "cities", "LA");
batch.delete(laRef);
// Commit the batch
await batch.commit();Web namespaced API
// Get a new write batch
var batch = db.batch();
// Set the value of 'NYC'
var nycRef = db.collection("cities").doc("NYC");
batch.set(nycRef, {name: "New York City"});
// Update the population of 'SF'
var sfRef = db.collection("cities").doc("SF");
batch.update(sfRef, {"population": 1000000});
// Delete the city 'LA'
var laRef = db.collection("cities").doc("LA");
batch.delete(laRef);
// Commit the batch
batch.commit().then(() => {
// ...
});迅速
注意：此產品不適用於 watchOS 和 App Clip 目標。
// Get new write batch
let batch = db.batch()
// Set the value of 'NYC'
let nycRef = db.collection("cities").document("NYC")
batch.setData([:], forDocument: nycRef)
// Update the population of 'SF'
let sfRef = db.collection("cities").document("SF")
batch.updateData(["population": 1000000 ], forDocument: sfRef)
// Delete the city 'LA'
let laRef = db.collection("cities").document("LA")
batch.deleteDocument(laRef)
// Commit the batch
batch.commit() { err in
if let err = err {
print("Error writing batch \(err)")
} else {
print("Batch write succeeded.")
}
}目標-C
注意：此產品不適用於 watchOS 和 App Clip 目標。
// Get new write batch
FIRWriteBatch *batch = [self.db batch];
// Set the value of 'NYC'
FIRDocumentReference *nycRef =
[[self.db collectionWithPath:@"cities"] documentWithPath:@"NYC"];
[batch setData:@{} forDocument:nycRef];
// Update the population of 'SF'
FIRDocumentReference *sfRef =
[[self.db collectionWithPath:@"cities"] documentWithPath:@"SF"];
[batch updateData:@{ @"population": @1000000 } forDocument:sfRef];
// Delete the city 'LA'
FIRDocumentReference *laRef =
[[self.db collectionWithPath:@"cities"] documentWithPath:@"LA"];
[batch deleteDocument:laRef];
// Commit the batch
[batch commitWithCompletion:^(NSError * _Nullable error) {
if (error != nil) {
NSLog(@"Error writing batch %@", error);
} else {
NSLog(@"Batch write succeeded.");
}
}];Kotlin+KTX
val nycRef = db.collection("cities").document("NYC")
val sfRef = db.collection("cities").document("SF")
val laRef = db.collection("cities").document("LA")
// Get a new write batch and commit all write operations
db.runBatch { batch ->
// Set the value of 'NYC'
batch.set(nycRef, City())
// Update the population of 'SF'
batch.update(sfRef, "population", 1000000L)
// Delete the city 'LA'
batch.delete(laRef)
}.addOnCompleteListener {
// ...
}Java
// Get a new write batch
WriteBatch batch = db.batch();
// Set the value of 'NYC'
DocumentReference nycRef = db.collection("cities").document("NYC");
batch.set(nycRef, new City());
// Update the population of 'SF'
DocumentReference sfRef = db.collection("cities").document("SF");
batch.update(sfRef, "population", 1000000L);
// Delete the city 'LA'
DocumentReference laRef = db.collection("cities").document("LA");
batch.delete(laRef);
// Commit the batch
batch.commit().addOnCompleteListener(new OnCompleteListener<Void>() {
@Override
public void onComplete(@NonNull Task<Void> task) {
// ...
}
});Dart
// Get a new write batch
final batch = db.batch();
// Set the value of 'NYC'
var nycRef = db.collection("cities").doc("NYC");
batch.set(nycRef, {"name": "New York City"});
// Update the population of 'SF'
var sfRef = db.collection("cities").doc("SF");
batch.update(sfRef, {"population": 1000000});
// Delete the city 'LA'
var laRef = db.collection("cities").doc("LA");
batch.delete(laRef);
// Commit the batch
batch.commit().then((_) {
// ...
});爪哇
Python
Python
C++
// Get a new write batch
WriteBatch batch = db->batch();
// Set the value of 'NYC'
DocumentReference nyc_ref = db->Collection("cities").Document("NYC");
batch.Set(nyc_ref, {});
// Update the population of 'SF'
DocumentReference sf_ref = db->Collection("cities").Document("SF");
batch.Update(sf_ref, {{"population", FieldValue::Integer(1000000)}});
// Delete the city 'LA'
DocumentReference la_ref = db->Collection("cities").Document("LA");
batch.Delete(la_ref);
// Commit the batch
batch.Commit().OnCompletion([](const Future<void>& future) {
if (future.error() == Error::kErrorOk) {
std::cout << "Write batch success!" << std::endl;
} else {
std::cout << "Write batch failure: " << future.error_message() << std::endl;
}
});節點.js
去
PHP
統一
WriteBatch batch = db.StartBatch();
// Set the data for NYC
DocumentReference nycRef = db.Collection("cities").Document("NYC");
Dictionary<string, object> nycData = new Dictionary<string, object>
{
{ "name", "New York City" }
};
batch.Set(nycRef, nycData);
// Update the population for SF
DocumentReference sfRef = db.Collection("cities").Document("SF");
Dictionary<string, object> updates = new Dictionary<string, object>
{
{ "Population", 1000000}
};
batch.Update(sfRef, updates);
// Delete LA
DocumentReference laRef = db.Collection("cities").Document("LA");
batch.Delete(laRef);
// Commit the batch
batch.CommitAsync();C＃
紅寶石
一次批量寫入最多可以包含 500 個操作。批次中的每個操作都單獨計入您的 Cloud Firestore 使用量。
與事務一樣，批量寫入是原子的。與事務不同，批量寫入不需要確保讀取的文檔保持未修改狀態，從而減少失敗案例。它們不受重試或因重試次數過多而失敗的影響。即使用戶的設備處於離線狀態，批處理寫入也會執行。
原子操作的數據驗證
對於移動/網絡客戶端庫，您可以使用Cloud Firestore 安全規則驗證數據。您可以確保相關文檔始終以原子方式更新，並且始終作為事務或批量寫入的一部分。使用getAfter()安全規則函數在一組操作完成後但在 Cloud Firestore 提交操作之前訪問和驗證文檔的狀態。
例如，假設cities示例的數據庫也包含一個countries集合。每個country文檔都使用last_updated字段來跟踪與該國家/地區相關的任何城市的上次更新時間。以下安全規則要求對city文檔的更新也必須自動更新相關國家的last_updated字段：
service cloud.firestore {
match /databases/{database}/documents {
// If you update a city doc, you must also
// update the related country's last_updated field.
match /cities/{city} {
allow write: if request.auth != null &&
getAfter(
/databases/$(database)/documents/countries/$(request.resource.data.country)
).data.last_updated == request.time;
}
match /countries/{country} {
allow write: if request.auth != null;
}
}
}
安全規則限制
在事務或批量寫入的安全規則中，除了批處理中每個單個文檔操作的正常 10 次調用限制之外，整個原子操作的文檔訪問調用限制為 20 次。
例如，考慮聊天應用程序的以下規則：
service cloud.firestore {
match /databases/{db}/documents {
function prefix() {
return /databases/{db}/documents;
}
match /chatroom/{roomId} {
allow read, write: if request.auth != null && roomId in get(/$(prefix())/users/$(request.auth.uid)).data.chats
|| exists(/$(prefix())/admins/$(request.auth.uid));
}
match /users/{userId} {
allow read, write: if request.auth != null && request.auth.uid == userId
|| exists(/$(prefix())/admins/$(request.auth.uid));
}
match /admins/{userId} {
allow read, write: if request.auth != null && exists(/$(prefix())/admins/$(request.auth.uid));
}
}
}
下面的片段說明了用於一些數據訪問模式的文檔訪問調用的數量：
// 0 document access calls used, because the rules evaluation short-circuits
// before the exists() call is invoked.
db.collection('user').doc('myuid').get(...);
// 1 document access call used. The maximum total allowed for this call
// is 10, because it is a single document request.
db.collection('chatroom').doc('mygroup').get(...);
// Initializing a write batch...
var batch = db.batch();
// 2 document access calls used, 10 allowed.
var group1Ref = db.collection("chatroom").doc("group1");
batch.set(group1Ref, {msg: "Hello, from Admin!"});
// 1 document access call used, 10 allowed.
var newUserRef = db.collection("users").doc("newuser");
batch.update(newUserRef, {"lastSignedIn": new Date()});
// 1 document access call used, 10 allowed.
var removedAdminRef = db.collection("admin").doc("otheruser");
batch.delete(removedAdminRef);
// The batch used a total of 2 + 1 + 1 = 4 document access calls, out of a total
// 20 allowed.
batch.commit();
有關如何解決由大量寫入和批量寫入引起的延遲問題、重疊事務爭用導致的錯誤以及其他問題的更多信息，請考慮查看故障排除頁面。