firebase.firestore.DocumentReference

interface   static

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 The CollectionReference 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

firebase.firestore.GetOptions

An options object to configure how the data is retrieved.

Note: When using the default behavior, get() attempts to provide up-to-date data when possible by waiting for data from the server, but may return cached data or fail if you are offline and the server cannot be reached.

Value must not be null.
Returns

non-null Promise containing non-null firebase.firestore.DocumentSnapshot A promise that resolves with a DocumentSnapshot 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

firebase.firestore.SetOptions

An object to configure the set behavior. Pass {merge: true} to only replace the values specified in the data argument. Fields omitted will remain untouched.

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