Skip to content

Reading and querying

There are two ways to read:

  • once: get_document / get_documents, on this page;
  • live: add_snapshot_listener, called again on every change (Realtime updates).

Read one document

def on_city(snapshot, error):
    if error is not None:
        print("Read failed:", error.description)
        return
    if snapshot.exists:
        print(snapshot.document_id, snapshot.data)
        print(snapshot.get("name"), snapshot["address.city"])
    else:
        print("No such document")


db.document_with_path("cities/SF").get_document(on_city)

A missing document is not an error: snapshot.exists is False and snapshot.data is {}.

From the cache or the server

from pyios_firebase.firestore import FIRFirestoreSource

doc.get_document(on_city, source=FIRFirestoreSource.Cache)    # only the device's cache
doc.get_document(on_city, source=FIRFirestoreSource.Server)   # only the server (fails offline)

Default (the default) asks the server, and falls back to the cache when offline. snapshot.metadata.is_from_cache tells which one answered.

Read many documents

def on_cities(snapshot, error):
    if error is not None:
        return
    print(len(snapshot), "cities")
    for doc in snapshot:
        print(doc.document_id, doc.data)


db.collection_with_path("cities").get_documents(on_cities)

A QuerySnapshot works like a list of DocumentSnapshot: len(snapshot), snapshot[0], snapshot[-1], for doc in snapshot. It also has is_empty, documents, document_changes, metadata and query.

Every document is a read

Reading a whole collection counts each of its documents on your bill. Filter and limit, or count on the server with aggregation.

Filters

Each method returns a new query, so you can chain them:

cities = db.collection_with_path("cities")

cities.query_where_field_is_equal_to("state", "CA")
cities.query_where_field_is_not_equal_to("country", "USA")
cities.query_where_field_is_less_than("population", 100_000)
cities.query_where_field_is_greater_than_or_equal_to("population", 1_000_000)
cities.query_where_field_array_contains("regions", "west_coast")
cities.query_where_field_array_contains_any("regions", ["west_coast", "east_coast"])
cities.query_where_field_in("country", ["USA", "Japan"])
cities.query_where_field_not_in("country", ["USA", "Japan"])
Method Matches documents where the field...
query_where_field_is_equal_to / is_not_equal_to is (not) equal to the value
query_where_field_is_less_than / ..._or_equal_to is smaller
query_where_field_is_greater_than / ..._or_equal_to is bigger
query_where_field_array_contains is an array holding the value
query_where_field_array_contains_any is an array holding any of the values (up to 30)
query_where_field_in is one of the values (up to 30)
query_where_field_not_in is none of the values (up to 10)

An empty list, a list with more values than the limit, or a str instead of a list raises ValueError / TypeError before the query is made. The SDK would abort the app on an empty list, and the server would reject a long one.

Several filters are joined with AND. Filter values are converted like any value: compare timestamps with a datetime, references with a DocumentReference.

OR and AND filters

from pyios_firebase.firestore import Filter

cities.query_where_filter(
    Filter.or_filter_with_filters([
        Filter.filter_where_field_is_equal_to("capital", True),
        Filter.filter_where_field_is_greater_than_or_equal_to("population", 1_000_000),
    ])
).get_documents(on_cities)

Filters nest: an and_filter_with_filters inside an or_filter_with_filters, and the other way round.

Order and limit

cities \
    .query_where_field_is_equal_to("state", "CA") \
    .query_ordered_by_field("population", descending=True) \
    .query_limited_to(10) \
    .get_documents(on_cities)

# the last 3, in the query's order
cities.query_ordered_by_field("name").query_limited_to_last(3)
  • Ordering by a field leaves out the documents that do not have it.
  • A range filter (<, >, !=, not-in) and an order on a different field need a composite index. The query fails with FAILED_PRECONDITION, and the error's description holds a link that creates the index in the console.

Paging with cursors

Start or end at values of the ordered fields...

cities.query_ordered_by_field("population") \
    .query_starting_at_values([1_000_000]) \
    .query_ending_before_values([5_000_000])

...or at a document you read, which is how pages work:

class CityPages:
    PAGE = 25

    def __init__(self, db):
        self.query = db.collection_with_path("cities").query_ordered_by_field("population")
        self.last = None

    def next_page(self, on_page):
        query = self.query.query_limited_to(self.PAGE)
        if self.last is not None:
            query = query.query_starting_after_document(self.last)

        def on_snapshot(snapshot, error):
            if error is None and not snapshot.is_empty:
                self.last = snapshot[-1]          # the cursor for the next page
            on_page(snapshot, error)

        query.get_documents(on_snapshot)
Cursor Includes the cursor?
query_starting_at_values / query_starting_at_document Yes
query_starting_after_values / query_starting_after_document No
query_ending_at_values / query_ending_at_document Yes
query_ending_before_values / query_ending_before_document No

A document cursor must be a DocumentSnapshot from a callback: it carries the values of the ordered fields.

Collection group queries

Query every collection with the same ID, wherever it is in the database:

db.collection_group_with_id("landmarks") \
    .query_where_field_is_equal_to("type", "museum") \
    .get_documents(on_museums)

Pass only the collection ID, not a path. Collection group queries with filters need an index, and the security rules must allow them (match /{path=**}/landmarks/{id}).

Sub-collections

landmarks = db.collection_with_path("cities/SF/landmarks")
# the same:
landmarks = db.document_with_path("cities/SF").collection_with_path("landmarks")

landmarks.get_documents(on_landmarks)

Reading a document does not read its sub-collections.

Mistakes that would abort the app

The Firestore SDK checks a query as you build it, and raises an Objective-C exception on a mistake, which ends the app (Python cannot catch it). pyios-firebase makes the same checks first and raises ValueError (or TypeError) at the call that made the mistake:

Mistake Raised by
Two not-in filters, or not-in with in, array-contains-any or != (in the query, or inside an OR / AND Filter) The filter call
Two != filters The filter call
An empty in / not-in / array-contains-any list, or a str instead of a list The filter call
A limit below 1 (2,147,483,647 or more means no limit, as in the SDK) query_limited_to, query_limited_to_last
query_ordered_by_field after a start or end point query_ordered_by_field
More cursor values than query_ordered_by_field calls query_*_values
A cursor document that does not exist, lacks an ordered field, or has a server timestamp not written yet in it query_*_document
query_limited_to_last without an order get_documents, add_snapshot_listener

These checks follow the SDK's own rules, so a query the SDK accepts is never refused. A Query made from a native query (for example snapshot.query) is not checked: pyios-firebase does not know what it holds.

Too many in (30) or not-in (10) values are rejected by the server, not the SDK; pyios-firebase raises ValueError for those before sending too.