DocumentReference

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 functions
`ListenerRegistration`	`addSnapshotListener(listener: EventListener<DocumentSnapshot!>)` Starts listening to the document referenced by this `DocumentReference`.
`ListenerRegistration`	`addSnapshotListener( activity: Activity, listener: EventListener<DocumentSnapshot!> )` Starts listening to the document referenced by this `DocumentReference` using an Activity-scoped listener.
`ListenerRegistration`	`addSnapshotListener( executor: Executor, listener: EventListener<DocumentSnapshot!> )` Starts listening to the document referenced by this `DocumentReference`.
`ListenerRegistration`	`addSnapshotListener( metadataChanges: MetadataChanges, listener: EventListener<DocumentSnapshot!> )` Starts listening to the document referenced by this `DocumentReference` with the given options.
`ListenerRegistration`	`addSnapshotListener( options: SnapshotListenOptions, listener: EventListener<DocumentSnapshot!> )` Starts listening to the document referenced by this `DocumentReference` with the given options.
`ListenerRegistration`	`addSnapshotListener( activity: Activity, metadataChanges: MetadataChanges, listener: EventListener<DocumentSnapshot!> )` Starts listening to the document referenced by this `DocumentReference` with the given options using an Activity-scoped listener.
`ListenerRegistration`	`addSnapshotListener( executor: Executor, metadataChanges: MetadataChanges, listener: EventListener<DocumentSnapshot!> )` Starts listening to the document referenced by this `DocumentReference` with the given options.
`CollectionReference`	`collection(collectionPath: String)` Gets a `CollectionReference` instance that refers to the subcollection at the specified path relative to this document.
`Task<Void!>`	`delete()` Deletes the document referred to by this `DocumentReference`.
`Boolean`	`equals(o: Any!)`
`Task<DocumentSnapshot!>`	`get()` Reads the document referenced by this `DocumentReference`.
`Task<DocumentSnapshot!>`	`get(source: Source)` Reads the document referenced by this `DocumentReference`.
`String`	`getId()`
`CollectionReference`	`getParent()` Gets a `CollectionReference` to the collection that contains this document.
`String`	`getPath()` Gets the path of this document (relative to the root of the database) as a slash-separated string.
`Int`	`hashCode()`
`Task<Void!>`	`set(data: Any)` Overwrites the document referred to by this `DocumentReference`.
`Task<Void!>`	`set(data: Any, options: SetOptions)` Writes to the document referred to by this `DocumentReference`.
`Task<Void!>`	`update(data: (Mutable)Map<String!, Any!>)` Updates fields in the document referred to by this `DocumentReference`.
`Task<Void!>`	`update(field: String, value: Any?, moreFieldsAndValues: Array<Any!>!)` Updates fields in the document referred to by this `DocumentReference`.
`Task<Void!>`	`update(fieldPath: FieldPath, value: Any?, moreFieldsAndValues: Array<Any!>!)` Updates fields in the document referred to by this `DocumentReference`.

Public properties
`FirebaseFirestore!`	`firestore`

Extension functions
`inline Flow<T?>`	`<T : Any> DocumentReference.dataObjects(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`.
`inline Flow<T?>`	`<T : Any> DocumentReference.dataObjects(metadataChanges: MetadataChanges)` This function is deprecated. Migrate to use the KTX API from the main module: https://firebase.google.com/docs/android/kotlin-migration.
`Flow<DocumentSnapshot>`	`DocumentReference.snapshots(metadataChanges: MetadataChanges)` Starts listening to the document referenced by this `DocumentReference` with the given options and emits its values via a `Flow`.
`Flow<DocumentSnapshot>`	`DocumentReference.snapshots(metadataChanges: MetadataChanges)` This function is deprecated. com.google.firebase.fires

Public functions

addSnapshotListener

fun addSnapshotListener(listener: EventListener<DocumentSnapshot!>): ListenerRegistration

Starts listening to the document referenced by this DocumentReference.

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

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

addSnapshotListener

fun addSnapshotListener(
    activity: Activity,
    listener: EventListener<DocumentSnapshot!>
): ListenerRegistration

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

The listener will be automatically removed during onStop.

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

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

addSnapshotListener

fun addSnapshotListener(
    executor: Executor,
    listener: EventListener<DocumentSnapshot!>
): ListenerRegistration

Starts listening to the document referenced by this DocumentReference.

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

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

addSnapshotListener

fun addSnapshotListener(
    metadataChanges: MetadataChanges,
    listener: EventListener<DocumentSnapshot!>
): ListenerRegistration

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

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

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

addSnapshotListener

fun addSnapshotListener(
    options: SnapshotListenOptions,
    listener: EventListener<DocumentSnapshot!>
): ListenerRegistration

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

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

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

addSnapshotListener

fun addSnapshotListener(
    activity: Activity,
    metadataChanges: MetadataChanges,
    listener: EventListener<DocumentSnapshot!>
): ListenerRegistration

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
`activity: Activity`	The activity to scope the listener to.
`metadataChanges: MetadataChanges`	Indicates whether metadata-only changes (specifically, only `DocumentSnapshot.getMetadata()` changed) should trigger snapshot events.
`listener: EventListener<DocumentSnapshot!>`	The event listener that will be called with the snapshots.

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

addSnapshotListener

fun addSnapshotListener(
    executor: Executor,
    metadataChanges: MetadataChanges,
    listener: EventListener<DocumentSnapshot!>
): ListenerRegistration

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

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

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

collection

fun collection(collectionPath: String): CollectionReference

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

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

Returns
`CollectionReference`	The `CollectionReference` instance.

delete

fun delete(): Task<Void!>

Deletes the document referred to by this DocumentReference.

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

equals

fun equals(o: Any!): Boolean

get

fun get(): Task<DocumentSnapshot!>

Reads the document referenced by this DocumentReference.

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

get

fun get(source: Source): Task<DocumentSnapshot!>

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
`source: Source`	A value to configure the get behavior.

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

getId

fun getId(): String

getParent

fun getParent(): CollectionReference

Gets a CollectionReference to the collection that contains this document.

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

getPath

fun getPath(): String

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

Returns
`String`	The path of this document.

hashCode

fun hashCode(): Int

set

fun set(data: Any): Task<Void!>

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
`data: Any`	The data to write to the document (like a Map or a POJO containing the desired document contents).

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

set

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

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

update

fun update(data: (Mutable)Map<String!, Any!>): Task<Void!>

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

Parameters
`data: (Mutable)Map<String!, Any!>`	A map of field / value pairs to update. Fields can contain dots to reference nested fields within the document.

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

update

fun update(field: String, value: Any?, moreFieldsAndValues: Array<Any!>!): Task<Void!>

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

Parameters
`field: String`	The first field to update. Fields can contain dots to reference a nested field within the document.
`value: Any?`	The first value
`moreFieldsAndValues: Array<Any!>!`	Additional field/value pairs.

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

update

fun update(fieldPath: FieldPath, value: Any?, moreFieldsAndValues: Array<Any!>!): Task<Void!>

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

Parameters
`fieldPath: FieldPath`	The first field to update.
`value: Any?`	The first value
`moreFieldsAndValues: Array<Any!>!`	Additional field/value pairs.

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

Public properties

firestore

val firestore: FirebaseFirestore!

Extension functions

dataObjects

inline fun <T : Any> DocumentReference.dataObjects(
    metadataChanges: MetadataChanges = MetadataChanges.EXCLUDE
): Flow<T?>

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 : Any>`	The type of the object to convert to.
`metadataChanges: MetadataChanges = MetadataChanges.EXCLUDE`	controls metadata-only changes. Default: `MetadataChanges.EXCLUDE`

dataObjects

inline fun <T : Any> DocumentReference.dataObjects(
    metadataChanges: MetadataChanges = MetadataChanges.EXCLUDE
): Flow<T?>

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 : Any>`	The type of the object to convert to.
`metadataChanges: MetadataChanges = MetadataChanges.EXCLUDE`	controls metadata-only changes. Default: `MetadataChanges.EXCLUDE`

snapshots

fun DocumentReference.snapshots(
    metadataChanges: MetadataChanges = MetadataChanges.EXCLUDE
): Flow<DocumentSnapshot>

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
`metadataChanges: MetadataChanges = MetadataChanges.EXCLUDE`	controls metadata-only changes. Default: `MetadataChanges.EXCLUDE`

snapshots

fun DocumentReference.snapshots(
    metadataChanges: MetadataChanges = MetadataChanges.EXCLUDE
): Flow<DocumentSnapshot>

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
`metadataChanges: MetadataChanges = MetadataChanges.EXCLUDE`	controls metadata-only changes. Default: `MetadataChanges.EXCLUDE`