Document

Document reference

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

docRef.id // "Nk....WQ"
docRef.path // "users/Nk....WQ"
docRef.parent // colRef

use the document reference

We use the reference for most CRUD operations:

• read the document: getDoc

• update an existing document (it errors if the document doesn't exist): updateDoc

• delete the document: deleteDoc

• create the document, or override an existing one (upsert): setDoc

Note: addDoc() works without a document reference since it generates a new one on the fly.

build a document reference

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

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

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

Alternatively, we provide the collectionRef and the document ID, or only the collectionRef. In the latter case, the SDK generates a random ID.

const docRef = doc(collectionRef, id)
const docRef = doc(collectionRef) // random ID

read document at reference (get)

The get operation succeeds even when no document exists. We receive a Document snapshot which may be empty.

As such, checking the document existence requires to read inside the Document snapshot.

getDoc(docRef) // DocumentSnapshot
// docRef.get() // DocumentSnapshot

Document snapshot

The Document snapshot is a wrapper that doesn't guarantee the document existence. It exposes the document (or its absence) via a getter. The document's type is DocumentData or the more specific type we provided. It can also be undefined, unless it comes from a query (see Query)

Note: data() is a function because it accepts some configuration.

docSnapshot.exists()
docSnapshot.data() // DocumentData | undefined

It also exposes helpers and metadata.

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

Query a specific field

docSnapshot.get("address.zipCode") // low use

real-time listener on a single document

Set up a real-time listener on a (single) document reference:

const unsub = onSnapshot(docRef, (docSnapshot) => {
    docSnapshot.data() // DocumentData | undefined
})