Query

overview

A query matches documents based on a set of criteria, and not based on a set of document references.

the result of a query: a query snapshot

The snapshot hosts a list of document snapshots (docs). The list is empty when no match occurs.

Otherwise, it contains only non empty snapshots, of type QueryDocumentSnapshot, which is DocumentSnapshot except that data() cannot be undefined.

querySnapshot.docs // list of document snapshots (QueryDocumentSnapshot)
querySnapshot.empty

docSnapshot.data() // DocumentData (not undefined)

const cats = querySnapshot.docs.map((docSnap) => docSnap.data())

a collection reference is a query

A collection ref can serve as a query, the one that targets all documents (get):

getDocs(colRef)
// getDocs(q)

colRef.get()
// q.get()

build a query

We always provide the collection reference. Then, we can:

• add value-based filters
• set the order
• limit the count

const q = query(colRef, where(..), where(..), orderBy(..), limit(..))
// const q = collection(..).where(..).orderBy(..).limit(..)

where filter: look for documents with a given value

We filter documents based on a value we want to find in a property. We request an exact value or one within a range. Depending on the data, we expect a single match or several.

Note: documents that do not possess the property at all are filtered out.

For example, we look for a document whose id is user.id:

where("id", "==", user.id)
// where(propertyName, operator, value)

We set the requirement for the value: exact match, being different, being smaller or larger, exact match with at least one value, or different from all values.

==
!=

<
<=
>
>=

"in" // the property is equal to either A, B or C
"not-in" // the property is different from A, B and C.

We can also ask the value to be included or excluded from the array if the property is an array.

"array-contains" // the array contains the value
"array-contains-any" // the array contains A, B or C..

order documents based on a field

We order documents based on (the value of) a field, in the ascending or descending order. If omitted, the order defaults to ascending.

orderBy(propertyName, orderDirection)
orderBy("postCount", "asc")
orderBy("postCount", "desc")

We can start from a given value, e.g. documents that have at least (or more than) 10 posts.

startAt(10)
startAfter(10)

pagination: cap the read, then read the next page

Get at most n documents:

limit(20)

To get the next page, we provide a cutoff document (snapshot), stored from the current batch: we then receive the document snapshots that starts after it:

query(colRef, startAfter(docSnapshot), limit(20))

run the query (get)

one time fetch

const qs = getDocs(query)
const qs = query.get()

real-time listener

Set up a real-time listener on the query: we receive a query snapshot:

const unsub = onSnapshot(query, (qs) => {
    const documents = qs.docs.map((docSnapshot) => docSnapshot.data())
    setMessages(documents)
})