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

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. If we omit the ID, the SDK generates a random one.

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

read document at reference (get)

The get operation succeeds even if no document exists: Checking for a document existence is a valid read.

The function returns a Document snapshot, which may be empty:

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. Unless we provide a more specific type, the document's type is DocumentData.

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

Set up a real-time listener on a document reference:

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