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

Public methods
@NonNull ListenerRegistration

Starts listening to the document referenced by this DocumentReference.
@NonNull ListenerRegistration

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

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

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>

Deletes the document referred to by this DocumentReference.
boolean
@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

Gets the Cloud Firestore instance associated with this document reference.
@NonNull String
@NonNull CollectionReference

Gets a CollectionReference to the collection that contains this document.
@NonNull String

Gets the path of this document (relative to the root of the database) as a slash-separated string.
int
@NonNull Task<Void>

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>

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<T>
<T extends Object> FirestoreKt.dataObjects(
    @NonNull DocumentReference receiver,
    @NonNull MetadataChanges metadataChanges
)

This method is deprecated. Migrate to use the KTX API from the main module: https://firebase.google.com/docs/android/kotlin-migration.
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.
final @NonNull Flow<@NonNull DocumentSnapshot>
FirestoreKt.snapshots(
    @NonNull DocumentReference receiver,
    @NonNull MetadataChanges metadataChanges
)

This method is deprecated. com.google.firebase.fires

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

Deprecation Notice: The Kotlin extensions (KTX) APIs have been added to their respective main modules, and the Kotlin extension (KTX) APIs in com.google.firebase.firebase-database-ktx are now deprecated. As early as April 2024, we'll no longer release KTX modules. For details, see the FAQ about this initiative.

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

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.

Deprecation Notice: The Kotlin extensions (KTX) APIs have been added to their respective main modules, and the Kotlin extension (KTX) APIs in com.google.firebase.firebase-database-ktx are now deprecated. As early as April 2024, we'll no longer release KTX modules. For details, see the FAQ about this initiative.

Parameters
@NonNull MetadataChanges metadataChanges

controls metadata-only changes. Default: MetadataChanges.EXCLUDE