public class DocumentReference extends Object

A DocumentReference refers to a document location in a 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: 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.

Public Method Summary

ListenerRegistration
addSnapshotListener(Activity activity, MetadataChanges metadataChanges, EventListener<DocumentSnapshot> listener)
Starts listening to the document referenced by this DocumentReference with the given options using an Activity-scoped listener.
ListenerRegistration
addSnapshotListener(Executor executor, MetadataChanges metadataChanges, EventListener<DocumentSnapshot> listener)
Starts listening to the document referenced by this DocumentReference with the given options.
ListenerRegistration
addSnapshotListener(MetadataChanges metadataChanges, EventListener<DocumentSnapshot> listener)
Starts listening to the document referenced by this DocumentReference with the given options.
ListenerRegistration
addSnapshotListener(EventListener<DocumentSnapshot> listener)
Starts listening to the document referenced by this DocumentReference.
ListenerRegistration
addSnapshotListener(Executor executor, EventListener<DocumentSnapshot> listener)
Starts listening to the document referenced by this DocumentReference.
ListenerRegistration
addSnapshotListener(Activity activity, EventListener<DocumentSnapshot> listener)
Starts listening to the document referenced by this DocumentReference using an Activity-scoped listener.
CollectionReference
collection(String collectionPath)
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(Object o)
Task<DocumentSnapshot>
get()
Reads the document referenced by this DocumentReference.
Task<DocumentSnapshot>
get(Source source)
Reads the document referenced by this DocumentReference.
FirebaseFirestore
getFirestore()
Gets the Firestore instance associated with this document reference.
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(Object data)
Overwrites the document referred to by this DocumentReference.
Task<Void>
set(Object data, SetOptions options)
Writes to the document referred to by this DocumentReference.
Task<Void>
update(Map<String, Object> data)
Updates fields in the document referred to by this DocumentReference.
Task<Void>
update(String field, Object value, Object... moreFieldsAndValues)
Updates fields in the document referred to by this DocumentReference.
Task<Void>
update(FieldPath fieldPath, Object value, Object... moreFieldsAndValues)
Updates fields in the document referred to by this DocumentReference.

Inherited Method Summary

Public Methods

public ListenerRegistration addSnapshotListener (Activity activity, MetadataChanges metadataChanges, 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
activity The activity to scope the listener to.
metadataChanges Indicates whether metadata-only changes (i.e. only DocumentSnapshot.getMetadata() changed) should trigger snapshot events.
listener The event listener that will be called with the snapshots.
Returns
  • A registration object that can be used to remove the listener.

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

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

Parameters
executor The executor to use to call the listener.
metadataChanges Indicates whether metadata-only changes (i.e. only DocumentSnapshot.getMetadata() changed) should trigger snapshot events.
listener The event listener that will be called with the snapshots.
Returns
  • A registration object that can be used to remove the listener.

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

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

Parameters
metadataChanges Indicates whether metadata-only changes (i.e. only DocumentSnapshot.getMetadata() changed) should trigger snapshot events.
listener The event listener that will be called with the snapshots.
Returns
  • A registration object that can be used to remove the listener.

public ListenerRegistration addSnapshotListener (EventListener<DocumentSnapshot> listener)

Starts listening to the document referenced by this DocumentReference.

Parameters
listener The event listener that will be called with the snapshots.
Returns
  • A registration object that can be used to remove the listener.

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

Starts listening to the document referenced by this DocumentReference.

Parameters
executor The executor to use to call the listener.
listener The event listener that will be called with the snapshots.
Returns
  • A registration object that can be used to remove the listener.

public ListenerRegistration addSnapshotListener (Activity activity, 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
activity The activity to scope the listener to.
listener The event listener that will be called with the snapshots.
Returns
  • A registration object that can be used to remove the listener.

public CollectionReference collection (String collectionPath)

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

Parameters
collectionPath A slash-separated relative path to a subcollection.
Returns
  • The CollectionReference instance.

public Task<Void> delete ()

Deletes the document referred to by this DocumentReference.

Returns
  • A Task that will be resolved when the delete completes.

public boolean equals (Object o)

Parameters
o

public Task<DocumentSnapshot> get ()

Reads the document referenced by this DocumentReference.

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

public Task<DocumentSnapshot> get (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
source A value to configure the get behavior.
Returns
  • A Task that will be resolved with the contents of the Document at this DocumentReference.

public FirebaseFirestore getFirestore ()

Gets the Firestore instance associated with this document reference.

public String getId ()

public CollectionReference getParent ()

Gets a CollectionReference to the collection that contains this document.

Returns
  • The CollectionReference that contains this document.

public String getPath ()

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

Returns
  • The path of this document.

public int hashCode ()

public Task<Void> set (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
data The data to write to the document (e.g. a Map or a POJO containing the desired document contents).
Returns
  • A Task that will be resolved when the write finishes.

public Task<Void> set (Object data, 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
data The data to write to the document (e.g. a Map or a POJO containing the desired document contents).
options An object to configure the set behavior.
Returns
  • A Task that will be resolved when the write finishes.

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

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

Parameters
data A map of field / value pairs to update. Fields can contain dots to reference nested fields within the document.
Returns
  • A Task that will be resolved when the write finishes.

public Task<Void> update (String field, Object value, Object... moreFieldsAndValues)

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

Parameters
field The first field to update. Fields can contain dots to reference a nested field within the document.
value The first value
moreFieldsAndValues Additional field/value pairs.
Returns
  • A Task that will be resolved when the write finishes.

public Task<Void> update (FieldPath fieldPath, Object value, Object... moreFieldsAndValues)

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

Parameters
fieldPath The first field to update.
value The first value
moreFieldsAndValues Additional field/value pairs.
Returns
  • A Task that will be resolved when the write finishes.