IMPORTANT: In July 2025, we stopped releasing new versions of KTX modules, and we removed the KTX libraries from the Firebase Android BoM (v34.0.0). If you use KTX APIs from the previously released KTX modules, we recommend that you migrate your app to use KTX APIs from the main modules instead. For details, see the FAQ about this initiative.

DocumentReference

public class DocumentReference

A DocumentReference 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. A DocumentReference can also be used to create a CollectionReference 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
`final FirebaseFirestore`	`firestore`

Public methods
`@NonNull ListenerRegistration`	`addSnapshotListener(@NonNull EventListener<DocumentSnapshot> listener)` Starts listening to the document referenced by this `DocumentReference`.
`@NonNull ListenerRegistration`	`addSnapshotListener( @NonNull Activity activity, @NonNull EventListener<DocumentSnapshot> listener )` Starts listening to the document referenced by this `DocumentReference` using an Activity-scoped listener.
`@NonNull ListenerRegistration`	`addSnapshotListener( @NonNull Executor executor, @NonNull EventListener<DocumentSnapshot> listener )` Starts listening to the document referenced by this `DocumentReference`.
`@NonNull ListenerRegistration`	`addSnapshotListener( @NonNull MetadataChanges metadataChanges, @NonNull EventListener<DocumentSnapshot> listener )` Starts listening to the document referenced by this `DocumentReference` with the given options.
`@NonNull ListenerRegistration`	`addSnapshotListener( @NonNull SnapshotListenOptions options, @NonNull EventListener<DocumentSnapshot> listener )` Starts listening to the document referenced by this `DocumentReference` with the given options.
`@NonNull ListenerRegistration`	`addSnapshotListener( @NonNull Activity activity, @NonNull MetadataChanges metadataChanges, @NonNull EventListener<DocumentSnapshot> listener )` Starts listening to the document referenced by this `DocumentReference` with the given options using an Activity-scoped listener.
`@NonNull ListenerRegistration`	`addSnapshotListener( @NonNull Executor executor, @NonNull MetadataChanges metadataChanges, @NonNull EventListener<DocumentSnapshot> listener )` Starts listening to the document referenced by this `DocumentReference` with the given options.
`@NonNull CollectionReference`	`collection(@NonNull String collectionPath)` Gets a `CollectionReference` instance that refers to the subcollection at the specified path relative to this document.
`@NonNull Task<Void>`	`delete()` Deletes the document referred to by this `DocumentReference`.
`boolean`	`equals(Object o)`
`@NonNull Task<DocumentSnapshot>`	`get()` Reads the document referenced by this `DocumentReference`.
`@NonNull Task<DocumentSnapshot>`	`get(@NonNull Source source)` Reads the document referenced by this `DocumentReference`.
`@NonNull FirebaseFirestore`	`getFirestore()` Gets the Cloud Firestore instance associated with this document reference.
`@NonNull String`	`getId()`
`@NonNull CollectionReference`	`getParent()` Gets a `CollectionReference` to the collection that contains this document.
`@NonNull String`	`getPath()` Gets the path of this document (relative to the root of the database) as a slash-separated string.
`int`	`hashCode()`
`@NonNull Task<Void>`	`set(@NonNull Object data)` Overwrites the document referred to by this `DocumentReference`.
`@NonNull Task<Void>`	`set(@NonNull Object data, @NonNull SetOptions options)` Writes to the document referred to by this `DocumentReference`.
`@NonNull Task<Void>`	`update(@NonNull Map<String, Object> data)` Updates fields in the document referred to by this `DocumentReference`.
`@NonNull Task<Void>`	`update( @NonNull String field, @Nullable Object value, Object[] moreFieldsAndValues )` Updates fields in the document referred to by this `DocumentReference`.
`@NonNull Task<Void>`	`update( @NonNull FieldPath fieldPath, @Nullable Object value, Object[] moreFieldsAndValues )` Updates fields in the document referred to by this `DocumentReference`.

Extension functions
`final @NonNull Flow<T>`	`<T extends Object> FirestoreKt.dataObjects( @NonNull DocumentReference receiver, @NonNull MetadataChanges metadataChanges )` Starts listening to the document referenced by this `DocumentReference` with the given options and emits its values converted to a POJO via a `Flow`.
`final @NonNull Flow<@NonNull DocumentSnapshot>`	`FirestoreKt.snapshots( @NonNull DocumentReference receiver, @NonNull MetadataChanges metadataChanges )` Starts listening to the document referenced by this `DocumentReference` with the given options and emits its values via a `Flow`.

Public fields

firestore

public final FirebaseFirestore firestore

Public methods

addSnapshotListener

public @NonNull ListenerRegistration addSnapshotListener(@NonNull EventListener<DocumentSnapshot> listener)

Starts listening to the document referenced by this DocumentReference.

Parameters
`@NonNull EventListener<DocumentSnapshot> listener`	The event listener that will be called with the snapshots.

Returns
`@NonNull ListenerRegistration`	A registration object that can be used to remove the listener.

addSnapshotListener

public @NonNull ListenerRegistration addSnapshotListener(
    @NonNull Activity activity,
    @NonNull EventListener<DocumentSnapshot> listener
)

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

The listener will be automatically removed during onStop.

Parameters
`@NonNull Activity activity`	The activity to scope the listener to.
`@NonNull EventListener<DocumentSnapshot> listener`	The event listener that will be called with the snapshots.

Returns
`@NonNull ListenerRegistration`	A registration object that can be used to remove the listener.

addSnapshotListener

public @NonNull ListenerRegistration addSnapshotListener(
    @NonNull Executor executor,
    @NonNull EventListener<DocumentSnapshot> listener
)

Starts listening to the document referenced by this DocumentReference.

Parameters
`@NonNull Executor executor`	The executor to use to call the listener.
`@NonNull EventListener<DocumentSnapshot> listener`	The event listener that will be called with the snapshots.

Returns
`@NonNull ListenerRegistration`	A registration object that can be used to remove the listener.

addSnapshotListener

public @NonNull ListenerRegistration addSnapshotListener(
    @NonNull MetadataChanges metadataChanges,
    @NonNull EventListener<DocumentSnapshot> listener
)

Starts listening to the document referenced by this DocumentReference with the given options.

Parameters
`@NonNull MetadataChanges metadataChanges`	Indicates whether metadata-only changes (specifically, only `DocumentSnapshot.getMetadata()` changed) should trigger snapshot events.
`@NonNull EventListener<DocumentSnapshot> listener`	The event listener that will be called with the snapshots.

Returns
`@NonNull ListenerRegistration`	A registration object that can be used to remove the listener.

addSnapshotListener

public @NonNull ListenerRegistration addSnapshotListener(
    @NonNull SnapshotListenOptions options,
    @NonNull EventListener<DocumentSnapshot> listener
)

Starts listening to the document referenced by this DocumentReference with the given options.

Parameters
`@NonNull SnapshotListenOptions 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.
`@NonNull EventListener<DocumentSnapshot> listener`	The event listener that will be called with the snapshots.

Returns
`@NonNull ListenerRegistration`	A registration object that can be used to remove the listener.

addSnapshotListener

public @NonNull ListenerRegistration addSnapshotListener(
    @NonNull Activity activity,
    @NonNull MetadataChanges metadataChanges,
    @NonNull EventListener<DocumentSnapshot> listener
)

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

The listener will be automatically removed during onStop.

Parameters
`@NonNull Activity activity`	The activity to scope the listener to.
`@NonNull MetadataChanges metadataChanges`	Indicates whether metadata-only changes (specifically, only `DocumentSnapshot.getMetadata()` changed) should trigger snapshot events.
`@NonNull EventListener<DocumentSnapshot> listener`	The event listener that will be called with the snapshots.

Returns
`@NonNull ListenerRegistration`	A registration object that can be used to remove the listener.

addSnapshotListener

public @NonNull ListenerRegistration addSnapshotListener(
    @NonNull Executor executor,
    @NonNull MetadataChanges metadataChanges,
    @NonNull EventListener<DocumentSnapshot> listener
)

Starts listening to the document referenced by this DocumentReference with the given options.

Parameters
`@NonNull Executor executor`	The executor to use to call the listener.
`@NonNull MetadataChanges metadataChanges`	Indicates whether metadata-only changes (specifically, only `DocumentSnapshot.getMetadata()` changed) should trigger snapshot events.
`@NonNull EventListener<DocumentSnapshot> listener`	The event listener that will be called with the snapshots.

Returns
`@NonNull ListenerRegistration`	A registration object that can be used to remove the listener.

collection

public @NonNull CollectionReference collection(@NonNull String collectionPath)

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

Parameters
`@NonNull String collectionPath`	A slash-separated relative path to a subcollection.

Returns
`@NonNull CollectionReference`	The `CollectionReference` instance.

delete

public @NonNull Task<Void> delete()

Deletes the document referred to by this DocumentReference.

Returns
`@NonNull Task<Void>`	A Task that will be resolved when the delete completes.

equals

public boolean equals(Object o)

get

public @NonNull Task<DocumentSnapshot> get()

Reads the document referenced by this DocumentReference.

Returns
`@NonNull Task<DocumentSnapshot>`	A Task that will be resolved with the contents of the Document at this `DocumentReference`.

get

public @NonNull Task<DocumentSnapshot> get(@NonNull Source source)

Reads the document referenced by this DocumentReference.

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

Parameters
`@NonNull Source source`	A value to configure the get behavior.

Returns
`@NonNull Task<DocumentSnapshot>`	A Task that will be resolved with the contents of the Document at this `DocumentReference`.

getFirestore

public @NonNull FirebaseFirestore getFirestore()

Gets the Cloud Firestore instance associated with this document reference.

getId

public @NonNull String getId()

getParent

public @NonNull CollectionReference getParent()

Gets a CollectionReference to the collection that contains this document.

Returns
`@NonNull CollectionReference`	The `CollectionReference` that contains this document.

getPath

public @NonNull String getPath()

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

Returns
`@NonNull String`	The path of this document.

hashCode

public int hashCode()

set

public @NonNull Task<Void> set(@NonNull Object data)

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

Parameters
`@NonNull Object data`	The data to write to the document (like a Map or a POJO containing the desired document contents).

Returns
`@NonNull Task<Void>`	A Task that will be resolved when the write finishes.

set

public @NonNull Task<Void> set(@NonNull Object data, @NonNull SetOptions options)

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
`@NonNull Object data`	The data to write to the document (like a Map or a POJO containing the desired document contents).
`@NonNull SetOptions options`	An object to configure the set behavior.

Returns
`@NonNull Task<Void>`	A Task that will be resolved when the write finishes.

update

public @NonNull Task<Void> update(@NonNull Map<String, Object> data)

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

Parameters
`@NonNull Map<String, Object> data`	A map of field / value pairs to update. Fields can contain dots to reference nested fields within the document.

Returns
`@NonNull Task<Void>`	A Task that will be resolved when the write finishes.

update

public @NonNull Task<Void> update(
    @NonNull String field,
    @Nullable Object value,
    Object[] moreFieldsAndValues
)

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

Parameters
`@NonNull String field`	The first field to update. Fields can contain dots to reference a nested field within the document.
`@Nullable Object value`	The first value
`Object[] moreFieldsAndValues`	Additional field/value pairs.

Returns
`@NonNull Task<Void>`	A Task that will be resolved when the write finishes.

update

public @NonNull Task<Void> update(
    @NonNull FieldPath fieldPath,
    @Nullable Object value,
    Object[] moreFieldsAndValues
)

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

Parameters
`@NonNull FieldPath fieldPath`	The first field to update.
`@Nullable Object value`	The first value
`Object[] moreFieldsAndValues`	Additional field/value pairs.

Returns
`@NonNull Task<Void>`	A Task that will be resolved when the write finishes.

Extension functions

FirestoreKt.dataObjects

public final @NonNull Flow<T> <T extends Object> FirestoreKt.dataObjects(
    @NonNull DocumentReference receiver,
    @NonNull MetadataChanges metadataChanges
)

Starts listening to the document referenced by this DocumentReference with the given options and emits its values converted to a POJO via a Flow.

When the returned flow starts being collected, an EventListener will be attached.
When the flow completes, the listener will be removed.

Parameters
`<T extends Object>`	The type of the object to convert to.
`@NonNull MetadataChanges metadataChanges`	controls metadata-only changes. Default: `MetadataChanges.EXCLUDE`

FirestoreKt.snapshots

public final @NonNull Flow<@NonNull DocumentSnapshot> FirestoreKt.snapshots(
    @NonNull DocumentReference receiver,
    @NonNull MetadataChanges metadataChanges
)

Starts listening to the document referenced by this DocumentReference with the given options and emits its values via a Flow.

When the returned flow starts being collected, an EventListener will be attached.
When the flow completes, the listener will be removed.

Parameters
`@NonNull MetadataChanges metadataChanges`	controls metadata-only changes. Default: `MetadataChanges.EXCLUDE`