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

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

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

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
CollectionReference

Gets a CollectionReference to the collection that contains this document.

String

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

Int
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!

Extension functions

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

inline Flow<T?>

This function is deprecated. Migrate to use the KTX API from the main module: https://firebase.google.com/docs/android/kotlin-migration.

Flow<DocumentSnapshot>

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

Flow<DocumentSnapshot>

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 firestoreFirebaseFirestore!

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.

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
metadataChanges: MetadataChanges = MetadataChanges.EXCLUDE

controls metadata-only changes. Default: MetadataChanges.EXCLUDE