DocumentReference

public classDocumentReference

ADocumentReference refers to a document location in a Cloud Firestore database and can be used to write, read, or listen to the location. There may or may not exist a document at the referenced location. ADocumentReference can also be used to create aCollectionReference to a subcollection.

Subclassing Note: Cloud Firestore classes are not meant to be subclassed except for use in test mocks. Subclassing is not supported in production code and new SDK releases may break code that does so.

Summary

Public fields

finalFirebaseFirestore

Public methods

@NonNullListenerRegistration

Starts listening to the document referenced by thisDocumentReference.

@NonNullListenerRegistration

Starts listening to the document referenced by thisDocumentReference using an Activity-scoped listener.

@NonNullListenerRegistration

Starts listening to the document referenced by thisDocumentReference.

@NonNullListenerRegistration

Starts listening to the document referenced by thisDocumentReference with the given options.

@NonNullListenerRegistration

Starts listening to the document referenced by thisDocumentReference with the given options.

@NonNullListenerRegistration
addSnapshotListener(
    @NonNullActivity activity,
    @NonNullMetadataChanges metadataChanges,
    @NonNullEventListener<DocumentSnapshot> listener
)

Starts listening to the document referenced by thisDocumentReference with the given options using an Activity-scoped listener.

@NonNullListenerRegistration
addSnapshotListener(
    @NonNullExecutor executor,
    @NonNullMetadataChanges metadataChanges,
    @NonNullEventListener<DocumentSnapshot> listener
)

Starts listening to the document referenced by thisDocumentReference with the given options.

@NonNullCollectionReference
collection(@NonNullString collectionPath)

Gets aCollectionReference instance that refers to the subcollection at the specified path relative to this document.

@NonNullTask<Void>

Deletes the document referred to by thisDocumentReference.

boolean
@NonNullTask<DocumentSnapshot>
get()

Reads the document referenced by thisDocumentReference.

@NonNullTask<DocumentSnapshot>
get(@NonNullSource source)

Reads the document referenced by thisDocumentReference.

@NonNullFirebaseFirestore

Gets the Cloud Firestore instance associated with this document reference.

@NonNullString
@NonNullCollectionReference

Gets aCollectionReference to the collection that contains this document.

@NonNullString

Gets the path of this document (relative to the root of the database) as a slash-separated string.

int
@NonNullTask<Void>

Overwrites the document referred to by thisDocumentReference.

@NonNullTask<Void>
set(@NonNullObject data, @NonNullSetOptions options)

Writes to the document referred to by thisDocumentReference.

@NonNullTask<Void>

Updates fields in the document referred to by thisDocumentReference.

@NonNullTask<Void>
update(
    @NonNullString field,
    @NullableObject value,
    Object[] moreFieldsAndValues
)

Updates fields in the document referred to by thisDocumentReference.

@NonNullTask<Void>
update(
    @NonNullFieldPath fieldPath,
    @NullableObject value,
    Object[] moreFieldsAndValues
)

Updates fields in the document referred to by thisDocumentReference.

Extension functions

final @NonNullFlow<T>
<T extends Object>FirestoreKt.dataObjects(
    @NonNullDocumentReference receiver,
    @NonNullMetadataChanges metadataChanges
)

Starts listening to the document referenced by thisDocumentReference with the given options and emits its values converted to a POJO via aFlow.

final @NonNullFlow<@NonNullDocumentSnapshot>
FirestoreKt.snapshots(
    @NonNullDocumentReference receiver,
    @NonNullMetadataChanges metadataChanges
)

Starts listening to the document referenced by thisDocumentReference with the given options and emits its values via aFlow.

Public fields

firestore

public final FirebaseFirestore firestore

Public methods

addSnapshotListener

public @NonNullListenerRegistration addSnapshotListener(@NonNullEventListener<DocumentSnapshot> listener)

Starts listening to the document referenced by thisDocumentReference.

Parameters
@NonNullEventListener<DocumentSnapshot> listener

The event listener that will be called with the snapshots.

Returns
@NonNullListenerRegistration

A registration object that can be used to remove the listener.

addSnapshotListener

public @NonNullListenerRegistration addSnapshotListener(
    @NonNullActivity activity,
    @NonNullEventListener<DocumentSnapshot> listener
)

Starts listening to the document referenced by thisDocumentReference using an Activity-scoped listener.

The listener will be automatically removed duringonStop.

Parameters
@NonNullActivity activity

The activity to scope the listener to.

@NonNullEventListener<DocumentSnapshot> listener

The event listener that will be called with the snapshots.

Returns
@NonNullListenerRegistration

A registration object that can be used to remove the listener.

addSnapshotListener

public @NonNullListenerRegistration addSnapshotListener(
    @NonNullExecutor executor,
    @NonNullEventListener<DocumentSnapshot> listener
)

Starts listening to the document referenced by thisDocumentReference.

Parameters
@NonNullExecutor executor

The executor to use to call the listener.

@NonNullEventListener<DocumentSnapshot> listener

The event listener that will be called with the snapshots.

Returns
@NonNullListenerRegistration

A registration object that can be used to remove the listener.

addSnapshotListener

public @NonNullListenerRegistration addSnapshotListener(
    @NonNullMetadataChanges metadataChanges,
    @NonNullEventListener<DocumentSnapshot> listener
)

Starts listening to the document referenced by thisDocumentReference with the given options.

Parameters
@NonNullMetadataChanges metadataChanges

Indicates whether metadata-only changes (specifically, only DocumentSnapshot.getMetadata() changed) should trigger snapshot events.

@NonNullEventListener<DocumentSnapshot> listener

The event listener that will be called with the snapshots.

Returns
@NonNullListenerRegistration

A registration object that can be used to remove the listener.

addSnapshotListener

public @NonNullListenerRegistration addSnapshotListener(
    @NonNullSnapshotListenOptions options,
    @NonNullEventListener<DocumentSnapshot> listener
)

Starts listening to the document referenced by thisDocumentReference with the given options.

Parameters
@NonNullSnapshotListenOptions options

Sets snapshot listener options, including whether metadata-only changes should trigger snapshot events, the source to listen to, the executor to use to call the listener, or the activity to scope the listener to.

@NonNullEventListener<DocumentSnapshot> listener

The event listener that will be called with the snapshots.

Returns
@NonNullListenerRegistration

A registration object that can be used to remove the listener.

addSnapshotListener

public @NonNullListenerRegistration addSnapshotListener(
    @NonNullActivity activity,
    @NonNullMetadataChanges metadataChanges,
    @NonNullEventListener<DocumentSnapshot> listener
)

Starts listening to the document referenced by thisDocumentReference with the given options using an Activity-scoped listener.

The listener will be automatically removed duringonStop.

Parameters
@NonNullActivity activity

The activity to scope the listener to.

@NonNullMetadataChanges metadataChanges

Indicates whether metadata-only changes (specifically, only DocumentSnapshot.getMetadata() changed) should trigger snapshot events.

@NonNullEventListener<DocumentSnapshot> listener

The event listener that will be called with the snapshots.

Returns
@NonNullListenerRegistration

A registration object that can be used to remove the listener.

addSnapshotListener

public @NonNullListenerRegistration addSnapshotListener(
    @NonNullExecutor executor,
    @NonNullMetadataChanges metadataChanges,
    @NonNullEventListener<DocumentSnapshot> listener
)

Starts listening to the document referenced by thisDocumentReference with the given options.

Parameters
@NonNullExecutor executor

The executor to use to call the listener.

@NonNullMetadataChanges metadataChanges

Indicates whether metadata-only changes (specifically, only DocumentSnapshot.getMetadata() changed) should trigger snapshot events.

@NonNullEventListener<DocumentSnapshot> listener

The event listener that will be called with the snapshots.

Returns
@NonNullListenerRegistration

A registration object that can be used to remove the listener.

collection

public @NonNullCollectionReference collection(@NonNullString collectionPath)

Gets aCollectionReference instance that refers to the subcollection at the specified path relative to this document.

Parameters
@NonNullString collectionPath

A slash-separated relative path to a subcollection.

Returns
@NonNullCollectionReference

TheCollectionReference instance.

delete

public @NonNullTask<Void> delete()

Deletes the document referred to by thisDocumentReference.

Returns
@NonNullTask<Void>

A Task that will be resolved when the delete completes.

equals

public boolean equals(Object o)

get

public @NonNullTask<DocumentSnapshot> get()

Reads the document referenced by thisDocumentReference.

Returns
@NonNullTask<DocumentSnapshot>

A Task that will be resolved with the contents of the Document at this DocumentReference.

get

public @NonNullTask<DocumentSnapshot> get(@NonNullSource source)

Reads the document referenced by thisDocumentReference.

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 theSource parameter.

Parameters
@NonNullSource source

A value to configure the get behavior.

Returns
@NonNullTask<DocumentSnapshot>

A Task that will be resolved with the contents of the Document at this DocumentReference.

getFirestore

public @NonNullFirebaseFirestore getFirestore()

Gets the Cloud Firestore instance associated with this document reference.

getId

public @NonNullString getId()

getParent

public @NonNullCollectionReference getParent()

Gets aCollectionReference to the collection that contains this document.

Returns
@NonNullCollectionReference

TheCollectionReference that contains this document.

getPath

public @NonNullString getPath()

Gets the path of this document (relative to the root of the database) as a slash-separated string.

Returns
@NonNullString

The path of this document.

hashCode

public int hashCode()

set

public @NonNullTask<Void> set(@NonNullObject data)

Overwrites the document referred to by thisDocumentReference. If the document does not yet exist, it will be created. If a document already exists, it will be overwritten.

Parameters
@NonNullObject data

The data to write to the document (like a Map or a POJO containing the desired document contents).

Returns
@NonNullTask<Void>

A Task that will be resolved when the write finishes.

set

public @NonNullTask<Void> set(@NonNullObject data, @NonNullSetOptions options)

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

Parameters
@NonNullObject data

The data to write to the document (like a Map or a POJO containing the desired document contents).

@NonNullSetOptions options

An object to configure the set behavior.

Returns
@NonNullTask<Void>

A Task that will be resolved when the write finishes.

update

public @NonNullTask<Void> update(@NonNullMap<String, Object> data)

Updates fields in the document referred to by thisDocumentReference. If no document exists yet, the update will fail.

Parameters
@NonNullMap<String, Object> data

A map of field / value pairs to update. Fields can contain dots to reference nested fields within the document.

Returns
@NonNullTask<Void>

A Task that will be resolved when the write finishes.

update

public @NonNullTask<Void> update(
    @NonNullString field,
    @NullableObject value,
    Object[] moreFieldsAndValues
)

Updates fields in the document referred to by thisDocumentReference. If no document exists yet, the update will fail.

Parameters
@NonNullString field

The first field to update. Fields can contain dots to reference a nested field within the document.

@NullableObject value

The first value

Object[] moreFieldsAndValues

Additional field/value pairs.

Returns
@NonNullTask<Void>

A Task that will be resolved when the write finishes.

update

public @NonNullTask<Void> update(
    @NonNullFieldPath fieldPath,
    @NullableObject value,
    Object[] moreFieldsAndValues
)

Updates fields in the document referred to by thisDocumentReference. If no document exists yet, the update will fail.

Parameters
@NonNullFieldPath fieldPath

The first field to update.

@NullableObject value

The first value

Object[] moreFieldsAndValues

Additional field/value pairs.

Returns
@NonNullTask<Void>

A Task that will be resolved when the write finishes.

Extension functions

FirestoreKt.dataObjects

public final @NonNullFlow<T> <T extends Object>FirestoreKt.dataObjects(
    @NonNullDocumentReference receiver,
    @NonNullMetadataChanges metadataChanges
)

Starts listening to the document referenced by thisDocumentReference with the given options and emits its values converted to a POJO via aFlow.

  • When the returned flow starts being collected, anEventListener will be attached.

  • When the flow completes, the listener will be removed.

Parameters
<T extends Object>

The type of the object to convert to.

@NonNullMetadataChanges metadataChanges

controls metadata-only changes. Default:MetadataChanges.EXCLUDE

FirestoreKt.snapshots

public final @NonNullFlow<@NonNullDocumentSnapshot> FirestoreKt.snapshots(
    @NonNullDocumentReference receiver,
    @NonNullMetadataChanges metadataChanges
)

Starts listening to the document referenced by thisDocumentReference with the given options and emits its values via aFlow.

  • When the returned flow starts being collected, anEventListener will be attached.

  • When the flow completes, the listener will be removed.

Parameters
@NonNullMetadataChanges metadataChanges

controls metadata-only changes. Default:MetadataChanges.EXCLUDE

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 2025-07-21 UTC.