Writing data¶
Every write takes an optional callback, (error), called when the server
has the write. Locally the write applies at once: listeners see it straight
away, and it is sent when the device is online.
Add a document with a generated ID¶
def on_added(ref, error):
if error is None:
print("Added with ID", ref.document_id)
db.collection_with_path("users").add_document_with_data(
{"first": "Ada", "last": "Lovelace", "born": 1815},
on_added,
)
add_document_with_data also returns the DocumentReference at once, before
the server answers. To know the ID before writing (for example to store it
in the document itself), make the reference first:
ref = db.collection_with_path("users").document_with_auto_id()
ref.set_data({"id": ref.document_id, "first": "Ada"})
Generated IDs are random, not ordered by time: to sort by creation, store a timestamp field.
Set a document¶
set_data creates the document, or replaces all of it:
city = db.collection_with_path("cities").document_with_path("LA")
city.set_data({"name": "Los Angeles", "state": "CA", "country": "USA"}, callback=on_done)
Merge into a document¶
Keep the fields you do not write, and create the document if it is missing:
Or write only some fields of the data you pass:
city.set_data_merge_fields(
{"name": "LA", "population": 3_800_000, "ignored": "not written"},
["name", "population"],
on_done,
)
Update fields¶
update_data changes only the given fields. The document must exist
(otherwise the error is NOT_FOUND):
Use dots for nested fields, so the other fields of the map stay:
db.document_with_path("users/ada").update_data({
"address.city": "London", # only this key of "address"
"settings.theme": "dark",
})
| Method | Document missing | Other fields |
|---|---|---|
set_data(data) |
Created | Removed |
set_data(data, merge=True) |
Created | Kept |
set_data_merge_fields(data, fields) |
Created | Kept |
update_data(data) |
Error NOT_FOUND |
Kept |
Field values¶
FieldValue sentinels ask the server to change a field from its current value,
without reading it first:
from pyios_firebase.firestore import FieldValue
city = db.document_with_path("cities/DC")
city.update_data({
"regions": FieldValue.field_value_for_array_union(["greater_virginia"]), # add if missing
"tags": FieldValue.field_value_for_array_remove(["old"]), # remove every "old"
"population": FieldValue.field_value_for_integer_increment(1), # atomic +1
"rating": FieldValue.field_value_for_double_increment(0.5),
"updated_at": FieldValue.field_value_for_server_timestamp(), # the server's time
"legacy_field": FieldValue.field_value_for_delete(), # remove the field
})
| Field value | Effect |
|---|---|
field_value_for_server_timestamp() |
The server's time when it applies the write |
field_value_for_delete() |
Removes the field (update_data, or set_data with merge=True) |
field_value_for_integer_increment(n) / field_value_for_double_increment(x) |
Adds to the number (a missing field counts as 0) |
field_value_for_array_union([...]) |
Adds the values that are not in the array yet |
field_value_for_array_remove([...]) |
Removes every copy of the values |
Increments are atomic, so many clients can add to a counter at once. A single document takes about one sustained write per second: for busy counters, spread them over several documents (distributed counters).
Delete¶
Deleting a document does not delete its sub-collections: their documents stay, at the same paths. Delete them one by one, or from a server (the Firebase CLI, or a Cloud Function).
Deleting a field: update_data({"field": FieldValue.field_value_for_delete()}).
Write several documents at once¶
To write several documents atomically (all or nothing), use a batch. To write from the current value, use a transaction.
Data that cannot be stored¶
Values Firestore cannot store raise TypeError before anything is sent; see
Python values.