Reading and writing¶
Write¶
Every write takes an optional callback (error), called once the server
has the write. Locally, the write applies at once: listeners on this device see
it immediately, even offline.
ref = db.reference("users/ada")
ref.set_value({"name": "Ada Lovelace", "born": 1815}) # replaces everything here
ref.child("born").set_value(1816) # one child
ref.update_child_values({"name": "Ada", "country": "UK"}) # only these children
ref.child("country").remove_value() # delete (or set_value(None))
| Method | Children not written |
|---|---|
set_value(value) |
Removed |
update_child_values(values) |
Kept |
remove_value() |
(everything here is removed) |
def on_saved(error):
if error is not None:
print(error.name, error.description) # for example PERMISSION_DENIED
ref.set_value({"name": "Ada"}, on_saved)
Update several locations at once¶
update_child_values keys can be paths, to write to many places
atomically: either every path is written, or none.
key = db.reference("posts").child_by_auto_id().key
post = {"author": uid, "title": title, "created": ServerValue.timestamp()}
db.reference().update_child_values({
f"posts/{key}": post,
f"user-posts/{uid}/{key}": post,
f"users/{uid}/post_count": ServerValue.increment(1),
})
Paths cannot be inside each other ("posts/p1" and "posts/p1/title"): that
raises ValueError (the SDK would abort the app). Put the inner value in the
outer one instead.
Read once¶
def on_user(snapshot, error):
if error is not None:
return show(error.description)
if snapshot.exists():
print(snapshot.value) # {"name": "Ada", "born": 1815}
db.reference("users/ada").get_data(on_user)
get_data asks the server, and falls back to the cache when offline. To use
the cache when there is one (and the server otherwise), read one event:
db.reference("users/ada").observe_once(DataEventType.VALUE, lambda snapshot, _: show(snapshot.value))
Listen¶
def on_value(snapshot, previous_key):
show_profile(snapshot.value)
observer = db.reference("users/ada").observe(DataEventType.VALUE, on_value)
...
observer.remove()
The callback runs at once with the current data, then on every change to the
location or anything below it. It gets (snapshot, previous_child_key);
for VALUE events the key is always None.
Listening downloads the whole location
A VALUE listener on rooms/general downloads every message of the room.
Listen to the smallest location you need, and use
child events and limits for lists.
ref.remove_all_observers() removes every observer of that location (not of
its children). When the server stops a listener (for example
PERMISSION_DENIED after sign-out), the optional cancel_callback gets the
error, and the observer is already removed:
Snapshots¶
snapshot.value |
The data as Python values, or None |
snapshot.key |
The location's key |
snapshot.exists(), snapshot.has_children(), snapshot.children_count |
|
snapshot.child("address/city"), snapshot.has_child("address") |
Data below |
for child in snapshot |
The children, in the query's order |
snapshot.priority, snapshot.export_value() |
Priorities, and the data with them (".value" / ".priority") |
snapshot.ref |
Where it was read from |
Transactions¶
Change a value from its current value, safely when many clients write at once:
from pyios_firebase.database import TransactionResult
def add_star(data):
post = data.value
if post is None:
return TransactionResult.success(data) # see the note below
stars = post.get("stars", {})
if uid in stars:
post["star_count"] -= 1
del stars[uid]
else:
post["star_count"] = post.get("star_count", 0) + 1
stars[uid] = True
post["stars"] = stars
data.value = post
return TransactionResult.success(data)
def on_done(error, committed, snapshot):
if error is not None:
print("Failed:", error.description)
elif committed:
print("Stars:", snapshot.value["star_count"])
db.reference(f"posts/{post_id}").run_transaction(add_star, on_done)
- The function gets a
MutableData(value,priority,child(path),children) and returnsTransactionResult.success(data)to write, orTransactionResult.abort()to write nothing. - It may run several times, on a background thread: whenever the server has other data, it runs again with that data. No side effects in it.
- The first run may see
Nonewhile the server has data: the SDK has nothing cached yet. Returnsuccessanyway; the SDK runs it again with the server's value. - If the function raises, the transaction is aborted and the callback's
errorhas the exception (domainTRANSACTION_ERROR_DOMAIN). local_events=Falseshows only the committed value to local listeners, not each attempt.
For a plain counter, ServerValue.increment(1) is simpler, and works offline.
Priorities¶
Each value can carry a priority (a number or a string), for
order_by_priority():
Most apps order by a child instead (Lists and queries).