Transactions and batches¶
Two ways to make several writes atomic (all of them happen, or none):
| Reads | Offline | Use it to | |
|---|---|---|---|
| Batch | No | Yes: queued, sent later | Write several documents together |
| Transaction | Yes, first | No: needs the server | Write from the current value (counters, transfers, unique names) |
Write batches¶
cities = db.collection_with_path("cities")
batch = db.batch()
batch.set_data({"name": "New York City"}, cities.document_with_path("NYC"))
batch.update_data({"population": 1_000_000}, cities.document_with_path("SF"))
batch.delete_document(cities.document_with_path("LA"))
batch.commit(on_committed)
def on_committed(error):
print("Saved" if error is None else error.description)
- A batch holds up to 500 writes.
- Use a batch once: make a new one for the next writes.
set_datain a batch takesmerge=Truetoo, and every value is converted like in a normal write; field values (increments, server timestamps) work.
Transactions¶
A transaction reads documents, then writes based on what it read. If another client changes those documents before the commit, Firestore runs the function again with the new data.
from pyios_firebase.firestore import TransactionException
sf = db.document_with_path("cities/SF")
def add_resident(transaction):
snapshot = transaction.get_document(sf)
population = snapshot.get("population")
if not isinstance(population, int):
raise TransactionException("SF has no population")
if population >= 1_000_000:
raise TransactionException("SF is full")
transaction.update_data({"population": population + 1}, sf)
return population + 1 # given to the callback
def on_done(result, error):
if error is not None:
print("Transaction failed:", error.description)
else:
print("Population is now", result)
db.run_transaction(add_resident, on_done)
Rules¶
- Reads first. Do every
transaction.get_document(...)before any write (set_data,update_data,delete_document). - No side effects. The function can run several times: do not change the screen or your app's state inside it. Do that in the callback.
- Return what you need. The function's return value (any Python object) is
the callback's
result. - Raise to stop. Raise any exception to abort: nothing is written, and the
callback gets an error whose
descriptionis the exception's message.TransactionExceptionis there for that, but any exception works. - Online only. A transaction needs the server; offline, it fails.
Example: a unique username¶
def claim_username(uid, name):
taken = db.document_with_path(f"usernames/{name}")
user = db.document_with_path(f"users/{uid}")
def claim(transaction):
if transaction.get_document(taken).exists:
raise TransactionException(f"{name} is taken")
transaction.set_data({"uid": uid}, taken)
transaction.update_data({"username": name}, user)
return name
db.run_transaction(claim, on_claimed)
Transactions or increments?¶
To add to a counter, FieldValue.field_value_for_integer_increment(n) is
simpler and works offline. Use a transaction when the new value depends on
more than a simple sum (a maximum, a check, several documents).