Document

Document reference

the document reference identifies a document within a collection, and embeds information about the parent collection.

parent is the the collection reference, id is the document's id. path is the document's absolute path as a string.

docRef.parent
docRef.id
docRed.path

uses: CRUD

We provide the document reference for CRUD operations:

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

• read the document - getDoc(ref)

• update the document - updateDoc(ref, data)

• delete the document - deleteDoc(ref)

compute a document reference

The path identifies the document uniquely. We provide it either as a single string or multiple strings.

We may provide the collectionRef and the document ID.

We may let Firestore creates the reference for us.

In some cases, we may provide only the parent collection's reference.

• compute a reference out of a path or ID.

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

const docRef = doc(db, "users", id) // collectionRef-less alternative
const docRef = doc(db, "users", "Nk....WQ")

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

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

read single document

at ref, or at id

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

Document snapshot

The document snapshot is a wrapper that does not guarantee the document existence.

When we request a document, we receive a snapshot, which may be empty in the sense of not containing data.

The snapshot still embeds metadata.

The data, if any, is accessible at snapshot.data(options). We may provide a config, though it's unneeded most of the time.

If the snapshot is empty, snapshot.data() returns undefined.

Besides, the term snapshot aims to stress that it's a static snapshot of the document rather than a live view over it.

We may subscribe to receive snapshots in realtime on document change.

work with the snapshot and the underlying document.

check document existence

docSnapshot.exists()

get the underlying document if it exists.

docSnapshot.data() // undefined if document doesn't exist
// typescript infered type: DocumentData | undefined

guard against document inexistence (redundant but needed by typescript).

if (!data) { .. }

we may typecast if collection didn't embed the type.

doc as FirestorePlanet

other props and methods

requested id, provided ref, resulting metadata.

docSnapshot.id
docSnapshot.ref
docSnapshot.metadata

get a single property directly through the document snapshot.

docSnapshot.get("phoneNumber")