firebase.firestore. DocumentReference
A DocumentReference
refers to a document location in a Firestore database and can be used to write, read, or listen to the location. The document at the referenced location may or may not exist. A DocumentReference
can also be used to create a CollectionReference
to a subcollection.
Properties
firestore
non-null firebase.firestore.Firestore
The firebase.firestore.Firestore the document is in. This is useful for performing transactions, for example.
id
string
The document's identifier within its collection.
parent
non-null firebase.firestore.CollectionReference
The Collection this DocumentReference
belongs to.
path
string
A string representing the path of the referenced document, relative to the root of the database.
Methods
collection
collection(collectionPath) returns firebase.firestore.CollectionReference
Gets a CollectionReference
instance that refers to the collection at the specified path.
Parameter |
|
---|---|
collectionPath |
string A slash-separated path to a collection. |
- Returns
-
non-null firebase.firestore.CollectionReference
TheCollectionReference
instance.
delete
delete() returns Promise containing void
Deletes the document referred to by this DocumentReference
.
- Returns
-
non-null Promise containing void
A promise that resolves once the document has been successfully deleted from the backend (Note that it won't resolve while you're offline).
get
get(options) returns Promise containing non-null firebase.firestore.DocumentSnapshot
Reads the document referred to by this DocumentReference
.
Parameter |
|
---|---|
options |
Optional An options object to configure how the data is retrieved. Note: When using the default behavior, Value must not be null. |
- Returns
-
non-null Promise containing non-null firebase.firestore.DocumentSnapshot
A promise that resolves with aDocumentSnapshot
containing the current document contents.
onSnapshot
onSnapshot(optionsOrObserverOrOnNext, observerOrOnNextOrOnError, onError) returns function()
Attaches a listener for DocumentSnapshot events. You may either pass individual onNext
and onError
callbacks or pass a single observer
object with next
and error
callbacks.
The listener can be cancelled by calling the function that is returned when onSnapshot
is called.
Parameter |
|
---|---|
optionsOrObserverOrOnNext |
(non-null firebase.firestore.SnapshotListenOptions, non-null Object, or function(non-null firebase.firestore.DocumentSnapshot)) This can be an observer object or an onNext function callback. It can also be an options object containing { includeMetadataChanges: true } to opt into events even when only metadata changed. |
observerOrOnNextOrOnError |
(non-null Object, function(non-null firebase.firestore.DocumentSnapshot), or function(non-null firebase.FirebaseError)) If you provided options, this will be an observer object or your onNext callback. Else, it is an optional onError callback. |
onError |
Optional function(non-null firebase.FirebaseError) If you didn't provide options and didn't use an observer object, this is the optional onError callback. |
- Returns
-
non-null function()
An unsubscribe function that can be called to cancel the snapshot listener.
set
set(data, options) returns Promise containing void
Writes to the document referred to by this DocumentReference
. If the document does not exist yet, it will be created. If you pass options, the provided data can be merged into the existing document.
Parameter |
|
---|---|
data |
Object An object of the fields and values for the document. Value must not be null. |
options |
Optional An object to configure the set behavior. Pass Value must not be null. |
- Returns
-
non-null Promise containing void
A promise that resolves once the data has been successfully written to the backend. (Note that it won't resolve while you're offline).
update
update(...var_args) returns Promise containing void
Updates fields in the document referred to by this DocumentReference
. The update will fail if applied to a document that does not exist.
Nested fields can be updated by providing dot-separated field path strings or by providing FieldPath objects.
Parameter |
|
---|---|
var_args |
any type Either an object containing all of the fields and values to update, or a series of arguments alternating between fields (as string or firebase.firestore.FieldPath objects) and values. Value may be repeated. |
- Returns
-
non-null Promise containing void
A promise that resolves once the data has been successfully written to the backend (Note that it won't resolve while you're offline).