The Cloud Firestore ODM is currently in alpha. Expect breaking changes, API changes and more. The documentation is still a work in progress. See the discussion for more details.
A reference provides full type-safe access to a Firestore Collection and Documents.
The ODM provides a useful
FirestoreBuilder widget which allows you to access your Firestore data
via the ODM.
Provide a collection reference instance to the
FirestoreBuilder, returning a builder:
In the above example, a realtime subscription is created by the
FirestoreBuilder widget and
returns all of the documents within the
users collection as a
UserDocumentSnapshot. This usage
of the ODM guarantees the following:
- Each snapshot document is a
- The data of the model instance is fully validated. If any remote data does not pass model validation an error will be thrown.
UserDocumentSnapshot provides access to the
User model and the
Similar to collections, you can provide the
FirestoreBuilder widget a document reference to a
specific document instead by calling the
Much like regular Firestore SDK usage, if the document does not exist a snapshot will still
be returned. In this example, we first check for existence before accessing the
Another powerful use-case of the ODM is the generation of type-safe querying.
Models define exactly what our data schema is, therefore this allows the ODM to generate useful type-safe methods for querying.
User model when generated generates some powerful query capabilities:
If a value is passed which does not satisfy a validator (e.g. minimum age) an error will be thrown.
Similar to querying collections, provide a query to the
If any of the query constraints are modified, the state of the builder will be reset.
Through FirestoreBuilder, it is possible to optionally optimize widget rebuilds, using the select method on a reference. The basic idea is; rather than listening to the entire snapshot, select allows us to listen to only a part of the snapshot.
For example, if we have a document that returns a Person instance, we could voluntarily only listen to that person's name by doing:
By doing so, now Text will rebuild only when the person's name changes. If that person's age changes, this won't rebuild our Text.
Note: This is a client only optimization. The underlying Firestore SDKs will still continue to subscribe to and receive updates for the entire snapshot and therefore this will not reduce any associated billing costs.