Collection

Collection Reference

use a collection reference

We provide the collection reference to:

• fetch all documents - getDocs(colRef)

• build a query targeting that collection - query(colRef, filters..)

• receive an empty, preemptive, document reference, within that collection - doc(colRef)

• perform a reference-less document creation, delegating the document's id creation to firebase - addDoc(colRef, data). (it returns the reference)

We may also use it for the following operations:

• fetch a document: we provide the collection ref and the document's ID: getDoc(colRef, id)

A documentRef already encapsulates the collection reference information. As such, we don't need to provide both the collectionRef and the documentRef.

build a collection reference

Within a specific database, the path to the collection identifies the collection uniquely. If the collection lives at the top, aka is not a sub-collection, the path is the same as the collection name, for example "users"

We indicate the collection's path, either as

• a single string, with no starting slash for the root collection

• a sequence of string arguments with no slash.

const collectionRef = collection(db, "users")
const collectionRef = collection(db, "users/z83....xWx/custom_list")
const collectionRef = collection(db, "users", uid, "custom_list")

// firebase-admin/firestore
const collectionRef = db.collection("users")
const collectionRef = db.collection("users/z83....xWx/custom_list")

indicate type

The SDK cannot infer the type of the collection, aka the type of its documents. As such, we may provide it. We may also add the type of the document after being converted to a type to be used on the client, if we use a converter that changes its type. Otherwise, we provide twice the same type. If we use a converter, we don't to specify the type with as.

const playersColRef = collectionRef as CollectionReference<Player, Player>
const playersColRef = collectionRef as CollectionReference<Player, FirestorePlayer>
const playersColRef = collectionRef.withConverter(myConverter)

Firestore Converter

declare transform between firestore shape and client shape.

We may want to have a shape on the client that is distinct from the one in the database. For example:

• a property is a Timestamp in the database, but we want a Date on the client.
• We want to add client only properties, such as helper properties.

In this case, we want Firebase to transform the document when

• receiving it from Firestore (fromFirestore())
• sending it to Firestore (toFirestore())

We define a converter, made of two functions.

fromFirestore takes a query document snapshot.:

fromFirestore(snapshot: QueryDocumentSnapshot<FirestoreWorkout>): Workout{
		// transform to client shape
		const firestoreWorkout = snapshot.data()
		const workout = { ...firestoreItem, date: firestoreItem.date.toDate()}
     return workout
    }

toFirestore takes the local object.

toFirestore(workout: Workout) {
		// prepare the object for firestore
        	return { ...workout, date: Timestamp.fromDate(workout.date)}
    }

and put them in a data converter of type FirestoreDataConverter, which dictates both types, provided as type parameters following the shape of: FirestoreDataConverter<AppModel, DbModel>

const myConverter: FirestoreDataConverter<Workout, FirestoreWorkout> = {
    toFirestore() {},
    fromFirestore() {},
}

attach the converter to the collectionRef

We attach the converter with withConverter()

const collectionRef = collection(db, "users").withConverter(myConverter)

cloud functions may not use a converter

the Admin SDK does not provide withConverter()