DocumentReference

class

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

read-only

Firestore

The Firestore instance for the Firestore database (useful for performing transactions, etc.).

Example 

let collectionRef = firestore.collection('col');

collectionRef.add({foo: 'bar'}).then(documentReference => {
  let firestore = documentReference.firestore;
  console.log(`Root location for document is ${firestore.formattedName}`);
});

id

read-only

string

The last path element of the referenced document.

Example 

let collectionRef = firestore.collection('col');

collectionRef.add({foo: 'bar'}).then(documentReference => {
  console.log(`Added document with name '${documentReference.id}'`);
});

parent

read-only

CollectionReference

A reference to the collection to which this DocumentReference belongs.

Example 

let documentRef = firestore.doc('col/doc');
let collectionRef = documentRef.parent;

collectionRef.where('foo', '==', 'bar').get().then(results => {
  console.log(`Found ${results.size} matches in parent collection`);
}):

path

read-only

string

A string representing the path of the referenced document (relative to the root of the database).

Example 

let collectionRef = firestore.collection('col');

collectionRef.add({foo: 'bar'}).then(documentReference => {
  console.log(`Added document at '${documentReference.path}'`);
});

Methods

collection

collection(collectionPath) returns 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

CollectionReference 

A reference to the new subcollection.

Example 

let documentRef = firestore.doc('col/doc');
let subcollection = documentRef.collection('subcollection');
console.log(`Path to subcollection: ${subcollection.path}`);

create

create(data) returns Promise containing WriteResult

Create a document with the provided object values. This will fail the write if a document exists at its location.

Parameter

data

DocumentData

An object that contains the fields and data to serialize as the document.
Returns

Promise containing WriteResult 

A Promise that resolves with the write time of this create.

Example 

let documentRef = firestore.collection('col').doc();

documentRef.create({foo: 'bar'}).then((res) => {
  console.log(`Document created at ${res.updateTime}`);
}).catch((err) => {
  console.log(`Failed to create document: ${err}`);
});

delete

delete(precondition) returns Promise containing WriteResult

Deletes the document referred to by this DocumentReference.

A delete for a non-existing document is treated as a success (unless lastUptimeTime is provided).

Parameter

precondition

Optional

Precondition

A precondition to enforce for this delete.

Values in precondition have the following properties:

Parameter

lastUpdateTime

Optional

Timestamp

If set, enforces that the document was last updated at lastUpdateTime. Fails the delete if the document was last updated at a different time.
Returns

Promise containing WriteResult 

A Promise that resolves with the delete time.

Example 

let documentRef = firestore.doc('col/doc');

documentRef.delete().then(() => {
  console.log('Document successfully deleted.');
});

get

get() returns Promise containing DocumentSnapshot

Retrieve a document from the database. Fails the Promise if the document is not found.

Returns

Promise containing DocumentSnapshot 

A Promise resolved with a DocumentSnapshot for the retrieved document on success. For missing documents, DocumentSnapshot.exists will be false. If the get() fails for other reasons, the Promise will be rejected.

Example 

let documentRef = firestore.doc('col/doc');

documentRef.get().then(documentSnapshot => {
  if (documentSnapshot.exists) {
    console.log('Document retrieved successfully.');
  }
});

getCollections

getCollections() returns Promise containing Array of CollectionReference

Fetches the subcollections that are direct children of this document.

Returns

Promise containing Array of CollectionReference 

A Promise that resolves with an array of CollectionReferences.

Example 

let documentRef = firestore.doc('col/doc');

documentRef.getCollections().then(collections => {
  for (let collection of collections) {
    console.log(`Found subcollection with id: ${collection.id}`);
  }
});

isEqual

isEqual(other) returns boolean

Returns true if this DocumentReference is equal to the provided value.

Parameter

other

any type

The value to compare against.
Returns

boolean 

true if this DocumentReference is equal to the provided value.

onSnapshot

onSnapshot(onNext, onError) returns function()

Attaches a listener for DocumentSnapshot events.

Parameter

onNext

documentSnapshotCallback

A callback to be called every time a new DocumentSnapshot is available.

onError

Optional

errorCallback

A callback to be called if the listen fails or is cancelled. No further callbacks will occur. If unset, errors will be logged to the console.
Returns

function() 

An unsubscribe function that can be called to cancel the snapshot listener.

Example 

let documentRef = firestore.doc('col/doc');

let unsubscribe = documentRef.onSnapshot(documentSnapshot => {
  if (documentSnapshot.exists) {
    console.log(documentSnapshot.data());
  }
}, err => {
  console.log(`Encountered error: ${err}`);
});

// Remove this listener.
unsubscribe();

set

set(data, options) returns Promise containing WriteResult

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.

Parameter

data

DocumentData

A map of the fields and values for the document.

options

Optional

SetOptions

An object to configure the set behavior.

Values in options have the following properties:

Parameter

merge

Optional

boolean

If true, set() merges the values specified in its data argument. Fields omitted from this set() call remain untouched.

mergeFields

Optional

Array of (string or FieldPath)

If provided, set() only replaces the specified field paths. Any field path that is not specified is ignored and remains untouched.
Returns

Promise containing WriteResult 

A Promise that resolves with the write time of this set.

Example 

let documentRef = firestore.doc('col/doc');

documentRef.set({foo: 'bar'}).then(res => {
  console.log(`Document written at ${res.updateTime}`);
});

update

update(dataOrField, ...preconditionOrValues)

Updates fields in the document referred to by this DocumentReference. If the document doesn't yet exist, the update fails and the returned Promise will be rejected.

The update() method accepts either an object with field paths encoded as keys and field values encoded as values, or a variable number of arguments that alternate between field paths and field values.

A Precondition restricting this update can be specified as the last argument.

Parameter

dataOrField

(UpdateData, string, or FieldPath)

An object containing the fields and values with which to update the document or the path of the first field to update.

preconditionOrValues

(any type, string, FieldPath, or Precondition)

An alternating list of field paths and values to update or a Precondition to restrict this update.

Value may be repeated.
Returns

Promise. A Promise that resolves once the data has been successfully written to the backend.

Example 

let documentRef = firestore.doc('col/doc');

documentRef.update({foo: 'bar'}).then(res => {
  console.log(`Document updated at ${res.updateTime}`);
});