Document

Document reference

The document reference identifies a document within the database, and embeds meta information.

We may find: the parent collection's reference, the document's id and the document's path as a string.

docRef.parent
docRef.id
docRef.path

use document reference: CRUD operations

We provide the document reference for CRUD operations:

• create the document, or override an existing one (upsert) - setDoc(ref, data)

• update an existing document (it errors if the document isn't found) - updateDoc(ref, data)

• read the document - getDoc(ref)

• delete the document - deleteDoc(ref)

build a document reference

The document's path identifies it uniquely. We provide the path as a single string or build it from string components.

const docRef = doc(db, "users", id) // string components
const docRef = doc(db, "users", "Nk....WQ")

const docRef = doc(db, "users/Nk....WQ") // single string
const docRef = doc(db, "users/" + id)

const docRef = collectionRef.doc("John") // admin sdk
const docRef = collectionRef.doc("NkJz11WQ")

We may alternatively provide the collectionRef and the document ID. If we want Firestore to generate the document ID on our behalf, we omit the ID. We receive the document's reference.

const docRef = doc(collectionRef, id)
const docRef = doc(collectionRef) // ID is generated by firestore

read document at reference

Since it's okay for the reference to point to a non-existing document, the read operation does not error if no document id found. Instead, it is a valid way to detect if a document at this path exists or not. The read functions return a Document snapshot, which may be empty.

getDoc(docRef)
docRef.get() // db.collection("messages").doc(id).get()

Document snapshot

The document snapshot is a wrapper that doesn't guarantee the document existence.

When we request a document, the SDK constructs a a wrapper (DocumentSnapshot) from the database's response. As a wrapper, it contains metadata and, if a document exists at this reference, it exposes the document too.

docSnapshot.exists()
docSnapshot.data() // undefined | DocumentData (or a more specific type)

docSnapshot.id // NkJz11WQ...7f
docSnapshot.ref // DocumentReference
docSnapshot.metadata // SnapshotMetadata

We may query a specific field:

docSnapshot.get("address.zipCode") // any

We may set up a subscription regarding a specific document reference to receive real-time snapshots on document change.

const unsub = onSnapshot(docRef, (docSnapshot) => {
    console.log("Current data: ", docSnapshot.data())
})