ADocumentReference refers to a document location in a Firestore databaseand can be used to write, read, or listen to the location. The document atthe referenced location may or may not exist. ADocumentReference canalso be used to create aCollectionReference to a subcollection.

Type parameters

  • T

Index

Constructors

Private constructor

Properties

firestore

firestore:Firestore

Thefirebase.firestore.Firestore the document is in.This is useful for performing transactions, for example.

id

id:string

The document's identifier within its collection.

parent

The Collection thisDocumentReference belongs to.

path

path:string

A string representing the path of the referenced document (relativeto the root of the database).

Methods

collection

delete

  • delete():Promise<void>

  • Deletes the document referred to by thisDocumentReference.

    ReturnsPromise<void>

    A Promise resolved once the document has been successfullydeleted from the backend (Note that it won't resolve while you'reoffline).

get

  • get(options?: GetOptions):Promise<DocumentSnapshot<T>>

  • Reads the document referred to by thisDocumentReference.

    Note: By default, get() attempts to provide up-to-date data when possibleby waiting for data from the server, but it may return cached data or failif you are offline and the server cannot be reached. This behavior can bealtered via theGetOptions parameter.

    Parameters

    • Optional options:GetOptions

      An object to configure the get behavior.

    ReturnsPromise<DocumentSnapshot<T>>

    A Promise resolved with a DocumentSnapshot containing thecurrent document contents.

isEqual

  • isEqual(other: DocumentReference<T>):boolean

  • Returns true if thisDocumentReference is equal to the provided one.

    Parameters

    Returnsboolean

    true if thisDocumentReference is equal to the provided one.

onSnapshot

  • onSnapshot(observer: {complete?:() =>void;error?:(error: FirestoreError) =>void;next?:(snapshot: DocumentSnapshot<T>) =>void }):() =>void

  • Attaches a listener for DocumentSnapshot events. You may either passindividualonNext andonError callbacks or pass a single observerobject withnext anderror callbacks.

    NOTE: Although anonCompletion callback can be provided, it willnever be called because the snapshot stream is never-ending.

    Parameters

    Returns() =>void

    An unsubscribe function that can be called to cancelthe snapshot listener.

      • ():void

      • Returnsvoid

  • onSnapshot(options: SnapshotListenOptions, observer: {complete?:() =>void;error?:(error: FirestoreError) =>void;next?:(snapshot: DocumentSnapshot<T>) =>void }):() =>void

  • Attaches a listener for DocumentSnapshot events. You may either passindividualonNext andonError callbacks or pass a single observerobject withnext anderror callbacks.

    NOTE: Although anonCompletion callback can be provided, it willnever be called because the snapshot stream is never-ending.

    Parameters

    Returns() =>void

    An unsubscribe function that can be called to cancelthe snapshot listener.

      • ():void

      • Returnsvoid

  • onSnapshot(onNext: (snapshot: DocumentSnapshot<T>) =>void, onError?: (error: FirestoreError) =>void, onCompletion?: () =>void):() =>void

  • Attaches a listener for DocumentSnapshot events. You may either passindividualonNext andonError callbacks or pass a single observerobject withnext anderror callbacks.

    NOTE: Although anonCompletion callback can be provided, it willnever be called because the snapshot stream is never-ending.

    Parameters

    • onNext:(snapshot:DocumentSnapshot<T>) =>void

      A callback to be called every time a newDocumentSnapshotis available.

    • Optional onError:(error:FirestoreError) =>void

      A callback to be called if the listen fails or iscancelled. No further callbacks will occur.

    • Optional onCompletion:() =>void
        • ():void

        • Returnsvoid

    Returns() =>void

    An unsubscribe function that can be called to cancelthe snapshot listener.

      • ():void

      • Returnsvoid

  • onSnapshot(options: SnapshotListenOptions, onNext: (snapshot: DocumentSnapshot<T>) =>void, onError?: (error: FirestoreError) =>void, onCompletion?: () =>void):() =>void

  • Attaches a listener for DocumentSnapshot events. You may either passindividualonNext andonError callbacks or pass a single observerobject withnext anderror callbacks.

    NOTE: Although anonCompletion callback can be provided, it willnever be called because the snapshot stream is never-ending.

    Parameters

    Returns() =>void

    An unsubscribe function that can be called to cancelthe snapshot listener.

      • ():void

      • Returnsvoid

set

  • set(data: Partial<T>, options: SetOptions):Promise<void>

  • Writes to the document referred to by thisDocumentReference. If thedocument does not yet exist, it will be created. If you passSetOptions, the provided data can be merged into an existing document.

    Parameters

    • data:Partial<T>

      A map of the fields and values for the document.

    • options:SetOptions

      An object to configure the set behavior.

    ReturnsPromise<void>

    A Promise resolved once the data has been successfully writtento the backend (Note that it won't resolve while you're offline).

  • set(data: T):Promise<void>

  • Writes to the document referred to by thisDocumentReference. If thedocument does not yet exist, it will be created. If you passSetOptions, the provided data can be merged into an existing document.

    Parameters

    • data:T

      A map of the fields and values for the document.

    ReturnsPromise<void>

    A Promise resolved once the data has been successfully writtento the backend (Note that it won't resolve while you're offline).

update

  • update(data: UpdateData):Promise<void>

  • Updates fields in the document referred to by thisDocumentReference.The update will fail if applied to a document that does not exist.

    Parameters

    • data:UpdateData

      An object containing the fields and values with which toupdate the document. Fields can contain dots to reference nested fieldswithin the document.

    ReturnsPromise<void>

    A Promise resolved once the data has been successfully writtento the backend (Note that it won't resolve while you're offline).

  • update(field: string |FieldPath, value: any, ...moreFieldsAndValues: any[]):Promise<void>

  • Updates fields in the document referred to by thisDocumentReference.The update will fail if applied to a document that does not exist.

    Nested fields can be updated by providing dot-separated field pathstrings or by providing FieldPath objects.

    Parameters

    • field:string |FieldPath

      The first field to update.

    • value:any

      The first value.

    • Rest...moreFieldsAndValues:any[]

      Additional key value pairs.

    ReturnsPromise<void>

    A Promise resolved once the data has been successfully writtento the backend (Note that it won't resolve while you're offline).

withConverter

  • withConverter(converter: null):DocumentReference<DocumentData>

  • Applies a custom data converter to this DocumentReference, allowing youto use your own custom model objects with Firestore. When you callset(), get(), etc. on the returned DocumentReference instance, theprovided converter will convert between Firestore data and your customtype U.

    Passing innull as the converter parameter removes the currentconverter.

    Parameters

    • converter:null

      Converts objects to and from Firestore. Passing innull removes the current converter.

    ReturnsDocumentReference<DocumentData>

    A DocumentReference that uses the provided converter.

  • withConverter<U>(converter: FirestoreDataConverter<U>):DocumentReference<U>

  • Applies a custom data converter to this DocumentReference, allowing youto use your own custom model objects with Firestore. When you callset(), get(), etc. on the returned DocumentReference instance, theprovided converter will convert between Firestore data and your customtype U.

    Passing innull as the converter parameter removes the currentconverter.

    Type parameters

    • U

    Parameters

    • converter:FirestoreDataConverter<U>

      Converts objects to and from Firestore. Passing innull removes the current converter.

    ReturnsDocumentReference<U>

    A DocumentReference that uses the provided converter.

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2022-07-27 UTC.