Skip to content

Cloud Firestore

Cloud Firestore is a NoSQL document database: documents (dicts of fields) live in collections, and documents can hold sub-collections. Clients read and write directly, and can listen to changes live.

from pyios_firebase.firestore import Firestore

db = Firestore.firestore()

db.collection_with_path("cities").document_with_path("LA").set_data(
    {"name": "Los Angeles", "state": "CA", "population": 3_800_000}
)

Installation

  1. Add the FirebaseFirestore Swift package product (Installation).
  2. In the Firebase console, open Firestore Database and create the database. Start in test mode only while developing.
  3. Write security rules before you ship: the client talks to the database directly, so the rules are what protects your data.

App configuration

What the app's build needs for this product. To combine several products, list them all in one products; see App configuration.

pyproject.toml
[[tool.kivy.ios.include_files]]
dest = "."
sources = ["GoogleService-Info.plist"]

[tool.kivy.ios.native.swift_packages.Firebase]
url = "https://github.com/firebase/firebase-ios-sdk.git"
requirement = { from = "13.1.1" }
products = ["FirebaseFirestore"]

[tool.kivy.ios.xcode.build_settings]
OTHER_LDFLAGS = "$(inherited) -ObjC"
  1. File > Add Package Dependencies..., https://github.com/firebase/firebase-ios-sdk.git, and pick FirebaseFirestore.
  2. Build Settings > Other Linker Flags: add -ObjC.
  3. Add GoogleService-Info.plist to the app target.

The data model

flowchart LR
    C1[("cities")] --> D1["SF<br/>name: San Francisco<br/>population: 860000"]
    C1 --> D2["LA<br/>name: Los Angeles<br/>population: 3800000"]
    D1 --> C2[("landmarks")]
    C2 --> D3["golden-gate<br/>type: bridge"]
Python object What it points to Get it with
Firestore The database Firestore.firestore()
CollectionReference A collection db.collection_with_path("cities"), doc.collection_with_path("landmarks")
DocumentReference A document (it may not exist yet) collection.document_with_path("SF"), db.document_with_path("cities/SF"), collection.document_with_auto_id()
Query Some documents of a collection, sorted and filtered collection.query_where_field_...(...), db.collection_group_with_id("landmarks")
DocumentSnapshot One document as read the callback of get_document or a listener
QuerySnapshot The documents of a query, as read the callback of get_documents or a listener

References are only paths: making one reads nothing and costs nothing. Paths alternate collection / document: "cities/SF/landmarks/golden-gate".

Guides

Use the local emulator

Point Firestore at the emulator right after core.configure(), before any other Firestore call:

core.configure()
Firestore.firestore().use_emulator("127.0.0.1", 8080)

use_emulator sets the host and turns TLS off (the emulator speaks plain HTTP/2; the SDK's own useEmulator only sets the host). See Emulator Suite.

Offline

Firestore keeps a cache on the device. Reads work offline from it; writes are applied locally at once (listeners see them, with has_pending_writes) and sent when the device is online again. A write's callback runs only when the server has it, so offline it waits: do not block the UI on it.

Errors

Firestore errors have the domain "FIRFirestoreErrorDomain" and the gRPC status codes:

error.code Name Usual cause
1 CANCELLED The operation was cancelled
3 INVALID_ARGUMENT A bad value or query
4 DEADLINE_EXCEEDED It took too long (a slow network)
5 NOT_FOUND update_data on a document that does not exist
6 ALREADY_EXISTS Creating a document that exists
7 PERMISSION_DENIED The security rules do not allow it (signed in?)
8 RESOURCE_EXHAUSTED A quota was exceeded
9 FAILED_PRECONDITION The query needs an index: the message has a link to create it
10 ABORTED A transaction kept conflicting
14 UNAVAILABLE No connection to the server (offline)
16 UNAUTHENTICATED The request has no valid credentials

Values Firestore cannot store raise TypeError at once, before anything is sent (Python values).

Limits worth knowing

Limit Value
Document size 1 MiB
Writes in a batch or transaction 500
in, array-contains-any values 30
not-in values 10
Depth of sub-collections 100
Sustained writes to one document about 1 per second

See the full quotas and limits.