A DocumentReference refers to a document location in a Firestore database and can be used to write, read, or listen to the location. The document at the referenced location may or may not exist. A DocumentReference can also be used to create a CollectionReference to a subcollection.

Type parameters

  • T

Index

Constructors

Properties

Methods

Constructors

Private constructor

Properties

firestore

firestore: Firestore

The firebase.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

parent: CollectionReference<T>

The Collection this DocumentReference belongs to.

path

path: string

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

Methods

collection

  • collection(collectionPath: string): CollectionReference<DocumentData>

  • Gets a CollectionReference instance that refers to the collection at the specified path.

    Parameters

    • collectionPath: string

      A slash-separated path to a collection.

    Returns CollectionReference<DocumentData>

    The CollectionReference instance.

delete

  • delete(): Promise<void>

  • Deletes the document referred to by this DocumentReference.

    Returns Promise<void>

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

get

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

  • Reads the document referred to by this DocumentReference.

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

    Parameters

    • Optional options: GetOptions

      An object to configure the get behavior.

    Returns Promise<DocumentSnapshot<T>>

    A Promise resolved with a DocumentSnapshot containing the current document contents.

isEqual

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

  • Returns true if this DocumentReference is equal to the provided one.

    Parameters

    Returns boolean

    true if this DocumentReference is equal to the provided one.

onSnapshot

  • onSnapshot(observer: object): function

  • Attaches a listener for DocumentSnapshot events. You may either pass individual onNext and onError callbacks or pass a single observer object with next and error callbacks.

    NOTE: Although an onCompletion callback can be provided, it will never be called because the snapshot stream is never-ending.

    Parameters

    • observer: object

      A single object containing next and error callbacks.

    Returns function

    An unsubscribe function that can be called to cancel the snapshot listener.

      • (): void

      • Returns void

  • onSnapshot(options: SnapshotListenOptions, observer: object): function

  • Attaches a listener for DocumentSnapshot events. You may either pass individual onNext and onError callbacks or pass a single observer object with next and error callbacks.

    NOTE: Although an onCompletion callback can be provided, it will never be called because the snapshot stream is never-ending.

    Parameters

    • options: SnapshotListenOptions

      Options controlling the listen behavior.

    • observer: object

      A single object containing next and error callbacks.

      • Optional complete?: function
          • (): void

          • Returns void

      • Optional error?: function
          • (error: Error): void

          • Parameters

            • error: Error

            Returns void

      • Optional next?: function

    Returns function

    An unsubscribe function that can be called to cancel the snapshot listener.

      • (): void

      • Returns void

  • onSnapshot(onNext: function, onError?: function, onCompletion?: function): function

  • Attaches a listener for DocumentSnapshot events. You may either pass individual onNext and onError callbacks or pass a single observer object with next and error callbacks.

    NOTE: Although an onCompletion callback can be provided, it will never be called because the snapshot stream is never-ending.

    Parameters

    • onNext: function

      A callback to be called every time a new DocumentSnapshot is available.

    • Optional onError: function

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

        • (error: Error): void

        • Parameters

          • error: Error

          Returns void

    • Optional onCompletion: function
        • (): void

        • Returns void

    Returns function

    An unsubscribe function that can be called to cancel the snapshot listener.

      • (): void

      • Returns void

  • onSnapshot(options: SnapshotListenOptions, onNext: function, onError?: function, onCompletion?: function): function

  • Attaches a listener for DocumentSnapshot events. You may either pass individual onNext and onError callbacks or pass a single observer object with next and error callbacks.

    NOTE: Although an onCompletion callback can be provided, it will never be called because the snapshot stream is never-ending.

    Parameters

    • options: SnapshotListenOptions

      Options controlling the listen behavior.

    • onNext: function

      A callback to be called every time a new DocumentSnapshot is available.

    • Optional onError: function

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

        • (error: Error): void

        • Parameters

          • error: Error

          Returns void

    • Optional onCompletion: function
        • (): void

        • Returns void

    Returns function

    An unsubscribe function that can be called to cancel the snapshot listener.

      • (): void

      • Returns void

set

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

  • Writes to the document referred to by this DocumentReference. If the document does not yet exist, it will be created. If you pass SetOptions, the provided data can be merged into an existing document.

    Parameters

    • data: T

      A map of the fields and values for the document.

    • Optional options: SetOptions

      An object to configure the set behavior.

    Returns Promise<void>

    A Promise resolved once the data has been successfully written to 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 this DocumentReference. 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 to update the document. Fields can contain dots to reference nested fields within the document.

    Returns Promise<void>

    A Promise resolved once the data has been successfully written to 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 this DocumentReference. The update will fail if applied to a document that does not exist.

    Nested fields can be updated by providing dot-separated field path strings 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.

    Returns Promise<void>

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

withConverter

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

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

    Type parameters

    • U

    Parameters

    Returns DocumentReference<U>

    A DocumentReference that uses the provided converter.